Metadata-Version: 2.4
Name: kadi-fsspec
Version: 0.1.0
Summary: An fsspec-compatible filesystem implementation for kadi4mat collections, records and files.
Author: Matthias Volk
Author-email: Matthias Volk <matthias.volk@gfz.de>
License-Expression: EUPL-1.2
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: fsspec>=2026.7.0
Requires-Dist: kadi-apy>=0.51.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 GFZ Helmholtz Centre for Geosciences

SPDX-License-Identifier: EUPL-1.2
-->

# kadi-fsspec

Expose a kadi4mat collection as [fsspec](https://filesystem-spec.readthedocs.io/en/latest/#) filesystem. Collections and records are represented as directories. Files attached to records are represented as files.

The [kadi-apy](https://kadi-apy.readthedocs.io/en/stable/) library is used, in particular all API calls go through a [`KadiManager`](https://kadi-apy.readthedocs.io/en/stable/usage/lib.html#kadimanager) instance.

## Usage

### General

Basic usage, assuming you have a `.kadiconfig` file (e.g. because you have previously used `kadi-apy`):
```python
from kadi_fsspec import KadiFileSystem

root_collection_identifier = "@root-collection"

fs = KadiFileSystem(root_collection_identifier)
```

Alternatively, pass an instance of [`KadiManager`](https://kadi-apy.readthedocs.io/en/stable/usage/lib.html#kadimanager) or options to create one, for example:
```python
from kadi_fsspec import KadiFileSystem
from kadi_apy import KadiManager

root_collection_identifier = "@root-collection"

manager = KadiManager(
    host="https://kadi4mat.iam.kit.edu/",
    pat="<your-kadi-access-token>",
)

fs = KadiFileSystem(root_collection_identifier, kadi_manager=manager)
```

### Inside marimo

The original motivation for this package was to allow users of [marimo](https://docs.marimo.io/) to browse a kadi4mat collection from inside a notebook.
If you add a cell with the code shown above, marimo should autodetect the instance of `fsspec.AbstractFileSystem` and a file tree should appear in the "Remote Storage" section of the "Files" tab of the left sidebar.

### Other usage

The package registers the `kadi://` protocol in `fsspec`, so you can also get an instance of a `KadiFileSystem` filesystem or open a file via the `fsspec` API:
```python
# Instance of KadiFileSystem
fs = fsspec.filesystem("kadi", root_collection_identifier="@root-collection")

# Open files directly
with fsspec.open("kadi:///some-collection/some-record/some-file.txt", "rb", root_collection_identifier="@root-collection") as f:
    print(f.read().decode())

```

## Status

- [x] Listing records and collections as directories
- [x] Read and download files
- [x] Create new records (parent collection must exist)
- [x] Write to existing files
- [x] Create new files (parent record must exist)
- [ ] Partial reads, streaming

## License and Copyright

Copyright GFZ Helmholtz Centre for Geosciences. `kadi-fsspec` is licensed under EUPL-1.2.
