Metadata-Version: 2.5
Name: galaxy-fsspec
Version: 0.1.0
Summary: An fsspec filesystem for Galaxy histories, datasets, and collections.
Project-URL: Homepage, https://github.com/galaxyproject/galaxy-fsspec
Project-URL: Issues, https://github.com/galaxyproject/galaxy-fsspec/issues
Author: galaxy-fsspec contributors
License-Expression: MIT
License-File: LICENSE
Keywords: bioblend,filesystem,fsspec,galaxy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: bioblend>=0.22.0
Requires-Dist: fsspec>=2024.1.0
Requires-Dist: requests>=2.31
Provides-Extra: async
Requires-Dist: fsspec>=2024.1.0; extra == 'async'
Description-Content-Type: text/markdown

# galaxy-fsspec

An [`fsspec`](https://filesystem-spec.readthedocs.io/) filesystem that exposes a
Galaxy account as a virtual, read-only directory tree.

```
galaxy://
├── histories/
│   └── <history>/                 (created / last_modified exposed via info())
│       ├── <dataset>              (files)
│       └── <collection>/          (list, paired, list:paired, nested ...)
│           └── ...                (collections nest as folders of folders)
└── libraries/
    └── <library>/
        ├── <dataset>
        └── <folder>/
            └── ...
```

Datasets are streamed as files; collections (including nested collections)
appear as directories.

## Install

```bash
uv pip install galaxy-fsspec
```

Because the protocol is registered via the `fsspec.specs` entry point,
`fsspec.filesystem("galaxy")` and `fsspec.open("galaxy://...")` work without
any extra imports.

## Configure

The filesystem reads two environment variables:

| Variable                  | Default              | Purpose                          |
| ------------------------- | -------------------- | -------------------------------- |
| `GALAXY_URL`              | `https://usegalaxy.org` | Galaxy server URL             |
| `GALAXY_USER_API_KEY`     | *(required)*         | User API key                     |

Optional:

| Variable                       | Default | Purpose                                       |
| ------------------------------ | ------- | --------------------------------------------- |
| `GALAXY_FSSPEC_SHOW_HID_IN_NAMES` | unset   | `true` prefixes entries with their `hid` (`1-my-dataset`) |

You can also pass arguments explicitly:

```python
import fsspec
fs = fsspec.filesystem("galaxy", url="https://my.galaxy.org", api_key="...", show_hid_in_names=True)
```

## Usage

```python
import fsspec

fs = fsspec.filesystem("galaxy")

# List histories.
for h in fs.ls("histories", detail=True):
    print(h["name"])

# Timestamps (created / last_modified) are fetched lazily via info().
for h in fs.ls("histories", detail=True):
    info = fs.info(h["name"])
    print(info["name"], info["created"], info["last_modified"])

# Walk a history's contents — datasets are files, collections are folders.
print(fs.ls("histories/My History"))

# Read a dataset (range-aware streaming via Galaxy's display endpoint).
with fs.open("histories/My History/my-paired/forward/R1.fastq", "rb") as f:
    print(f.read(64))
```

`show_hid_in_names=True` renders history entries as Galaxy does in its UI:

```
histories/My History/1-my-uploaded-dataset
histories/My History/30-my result
histories/My History/5-mycollection/1-forward
```

## Scope

Read-only for now: histories, datasets, and (nested) collections. Writes,
uploads, and library browsing are not yet supported.
