ubuntu-bio 0.1.0__tar.gz

ubuntu_bio-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Lint, Type Check & Test Suite
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint with Ruff
+        run: uv run ruff check .
+
+      - name: Check formatting with Ruff
+        run: uv run ruff format --check .
+
+      - name: Type check with Mypy
+        run: uv run mypy src tests
+
+      - name: Run Pytest test suite
+        run: uv run pytest --cov=src --cov-report=xml

ubuntu_bio-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/ubuntu-bio/
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing (OIDC)
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run test suite verification
+        run: uv run pytest
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          # If using OIDC Trusted Publishing, no token is needed.
+          # If using an API token, set the secret PYPI_API_TOKEN in GitHub repository settings.
+          password: ${{ secrets.PYPI_API_TOKEN }}

ubuntu_bio-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing & linting
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# OS artifacts
+.DS_Store

ubuntu_bio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UbuntuBio Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ubuntu_bio-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: ubuntu-bio
+Version: 0.1.0
+Summary: Official Python client and CLI for UbuntuBio - African Bioinformatics Data Hub
+Author-email: UbuntuBio Community <dev@ubuntubio.org>
+License: MIT
+License-File: LICENSE
+Keywords: africa,bioinformatics,datasets,genomics,open-science,openxet
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.12.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.3; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12.20240917; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ubuntu-bio
+
+[![PyPI version](https://img.shields.io/pypi/v/ubuntu-bio.svg?color=blue)](https://pypi.org/project/ubuntu-bio/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ubuntu-bio.svg)](https://pypi.org/project/ubuntu-bio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Sredeemer/ubuntu-bio-pypi/actions/workflows/ci.yml/badge.svg)](https://github.com/Sredeemer/ubuntu-bio-pypi/actions/workflows/ci.yml)
+
+The official Python client and command-line interface (`ubio`) for **UbuntuBio** — the African Bioinformatics Data Hub.
+
+`ubuntu-bio` enables researchers across the African continent and globally to publish, discover, stream, and version bioinformatics datasets (pathogen genomics, AMR surveillance, agriculture, biodiversity, and metagenomics) with chunk-level deduplication and Git versioning.
+
+---
+
+## Key Features
+
+- **Researcher Identity & Namespaces**: Seamless ORCID-authenticated login via browser loopback or RFC 8628 device flow with personal namespace resolution (`@username/dataset-name`).
+- **Genomic Deduplication**: Powered by OpenXet Content-Addressed Storage (CAS) using 64 KiB Content-Defined Chunking (CDC) and Blake3 Merkle trees—identical sequence chunks are stored only once.
+- **Git Versioning**: Every dataset is backed by standard Git commit histories, tags, and branches.
+- **Metadata Standards & Data Governance**: Built-in MIxS checklist validation and African Union ISO-3166 country code verification. Non-human genomics strictly enforced in v1.
+- **Dual Interface**: Full-featured command-line interface (`ubio` or `ubuntu-bio`) and ergonomic Python SDK (`import ubuntu_bio as ub`).
+
+---
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install ubuntu-bio
+```
+
+Or using `uv`:
+
+```bash
+uv add ubuntu-bio
+```
+
+---
+
+## CLI Quickstart
+
+The package installs two identical CLI entrypoints: `ubio` and `ubuntu-bio`.
+
+### 1. Authenticate with ORCID
+Connect your ORCID iD. Opens an interactive browser authorization or falls back to an RFC 8628 device verification code:
+
+```bash
+ubio login
+```
+
+Verify your authenticated researcher profile:
+
+```bash
+ubio whoami
+```
+
+```text
+✓ Authenticated with UbuntuBio Hub
+  Name:       Dr. Ada Lovelace
+  Username:   @ada-lovelace
+  ORCID:      0000-0002-1825-0097
+  Role:       researcher
+  Server:     https://hub.ubuntubio.org
+```
+
+### 2. Create a Dataset Repository
+Create a new dataset repository. If you provide a bare slug, `ubio` automatically prefixes your verified researcher handle:
+
+```bash
+# Automatically creates @ada-lovelace/lassa-surveillance-2024
+ubio create lassa-surveillance-2024 --domain virus --access public
+
+# Or specify an institutional / organization namespace
+ubio create pasteur-dakar/lassa-2024 --domain virus --access public
+```
+
+Supported biological domains:
+`bacteria`, `virus`, `parasite`, `fungus`, `plant`, `animal`, `vector`, `metagenome`, `environmental`.
+
+### 3. Upload Datasets
+Upload an entire directory of sequences, alignments, and metadata:
+
+```bash
+ubio upload lassa-surveillance-2024 ./my-data --message "Initial release of Lineage II FASTA assemblies"
+```
+
+### 4. Search Public Datasets
+Search the catalog using full-text search across pathogen titles, descriptions, and AU member states:
+
+```bash
+# Search for cholera surveillance in Kenya
+ubio search "cholera" --country KE
+
+# Search for antimicrobial resistance studies
+ubio search "antimicrobial resistance" --domain bacteria
+```
+
+### 5. Download Datasets & Remote Files
+Download a snapshot of a dataset repository:
+
+```bash
+ubio download lassa-surveillance-2024 --output-dir ./local-data
+```
+
+Download external assets listed in a `remote_files.tsv` manifest with parallel MD5 verification:
+
+```bash
+ubio download-remote ./remote_files.tsv --output-dir ./downloads --workers 8
+```
+
+---
+
+## Python SDK Quickstart
+
+Use `ubuntu_bio` directly in your Python analysis pipelines and Jupyter notebooks:
+
+```python
+import ubuntu_bio as ub
+
+# 1. Authenticate (using a Personal Access Token or environment variable)
+ub.login(token="ubp_your_personal_access_token")
+
+# 2. Check profile
+profile = ub.whoami()
+print(f"Logged in as: @{profile.get('username')}")
+
+# 3. Create a repository
+repo = ub.create_repo(
+    repo_id="lassa-surveillance-2024",
+    domain="virus",
+    access="public",
+    description="Lassa virus genomic surveillance in West Africa",
+)
+
+# 4. Upload an entire folder of genomic files
+ub.upload_folder(
+    repo_id="lassa-surveillance-2024",
+    folder_path="./data",
+    message="Add consensus FASTA and GFF annotations",
+)
+
+# 5. Download a single file or complete snapshot
+fasta_path = ub.download_file("pasteur-dakar/cholera-2024", "assemblies/sample_01.fasta")
+dataset_dir = ub.snapshot_download("pasteur-dakar/cholera-2024", revision="main")
+```
+
+---
+
+## Configuration & Environment Variables
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `UBUNTUBIO_SERVER_URL` | UbuntuBio Hub API server URL | `https://hub.ubuntubio.org` |
+| `UBUNTUBIO_API_TOKEN` | Personal Access Token (`ubp_...`) for non-interactive environments / CI | `None` |
+| `UBUNTUBIO_CONFIG_DIR` | Directory storing local credentials cache | `~/.config/ubuntubio` |
+
+---
+
+## Security & Biological Data Ethics
+
+- **Non-Human Data Only**: In compliance with UbuntuBio v1 data governance rules, human genomic data (NCBI Taxon ID 9606) is strictly prohibited.
+- **African Union Member States**: Metadata validation strictly enforces the 54 AU member state ISO-3166-1 alpha-2 country codes.
+- **Token Security**: Tokens are stored locally with restrictive file permissions (`0600`) and validated via short-lived cryptographic tokens against the Hub.
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE).

ubuntu_bio-0.1.0/README.md

@@ -0,0 +1,169 @@
+# ubuntu-bio
+
+[![PyPI version](https://img.shields.io/pypi/v/ubuntu-bio.svg?color=blue)](https://pypi.org/project/ubuntu-bio/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ubuntu-bio.svg)](https://pypi.org/project/ubuntu-bio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Sredeemer/ubuntu-bio-pypi/actions/workflows/ci.yml/badge.svg)](https://github.com/Sredeemer/ubuntu-bio-pypi/actions/workflows/ci.yml)
+
+The official Python client and command-line interface (`ubio`) for **UbuntuBio** — the African Bioinformatics Data Hub.
+
+`ubuntu-bio` enables researchers across the African continent and globally to publish, discover, stream, and version bioinformatics datasets (pathogen genomics, AMR surveillance, agriculture, biodiversity, and metagenomics) with chunk-level deduplication and Git versioning.
+
+---
+
+## Key Features
+
+- **Researcher Identity & Namespaces**: Seamless ORCID-authenticated login via browser loopback or RFC 8628 device flow with personal namespace resolution (`@username/dataset-name`).
+- **Genomic Deduplication**: Powered by OpenXet Content-Addressed Storage (CAS) using 64 KiB Content-Defined Chunking (CDC) and Blake3 Merkle trees—identical sequence chunks are stored only once.
+- **Git Versioning**: Every dataset is backed by standard Git commit histories, tags, and branches.
+- **Metadata Standards & Data Governance**: Built-in MIxS checklist validation and African Union ISO-3166 country code verification. Non-human genomics strictly enforced in v1.
+- **Dual Interface**: Full-featured command-line interface (`ubio` or `ubuntu-bio`) and ergonomic Python SDK (`import ubuntu_bio as ub`).
+
+---
+
+## Installation
+
+Install using `pip`:
+
+```bash
+pip install ubuntu-bio
+```
+
+Or using `uv`:
+
+```bash
+uv add ubuntu-bio
+```
+
+---
+
+## CLI Quickstart
+
+The package installs two identical CLI entrypoints: `ubio` and `ubuntu-bio`.
+
+### 1. Authenticate with ORCID
+Connect your ORCID iD. Opens an interactive browser authorization or falls back to an RFC 8628 device verification code:
+
+```bash
+ubio login
+```
+
+Verify your authenticated researcher profile:
+
+```bash
+ubio whoami
+```
+
+```text
+✓ Authenticated with UbuntuBio Hub
+  Name:       Dr. Ada Lovelace
+  Username:   @ada-lovelace
+  ORCID:      0000-0002-1825-0097
+  Role:       researcher
+  Server:     https://hub.ubuntubio.org
+```
+
+### 2. Create a Dataset Repository
+Create a new dataset repository. If you provide a bare slug, `ubio` automatically prefixes your verified researcher handle:
+
+```bash
+# Automatically creates @ada-lovelace/lassa-surveillance-2024
+ubio create lassa-surveillance-2024 --domain virus --access public
+
+# Or specify an institutional / organization namespace
+ubio create pasteur-dakar/lassa-2024 --domain virus --access public
+```
+
+Supported biological domains:
+`bacteria`, `virus`, `parasite`, `fungus`, `plant`, `animal`, `vector`, `metagenome`, `environmental`.
+
+### 3. Upload Datasets
+Upload an entire directory of sequences, alignments, and metadata:
+
+```bash
+ubio upload lassa-surveillance-2024 ./my-data --message "Initial release of Lineage II FASTA assemblies"
+```
+
+### 4. Search Public Datasets
+Search the catalog using full-text search across pathogen titles, descriptions, and AU member states:
+
+```bash
+# Search for cholera surveillance in Kenya
+ubio search "cholera" --country KE
+
+# Search for antimicrobial resistance studies
+ubio search "antimicrobial resistance" --domain bacteria
+```
+
+### 5. Download Datasets & Remote Files
+Download a snapshot of a dataset repository:
+
+```bash
+ubio download lassa-surveillance-2024 --output-dir ./local-data
+```
+
+Download external assets listed in a `remote_files.tsv` manifest with parallel MD5 verification:
+
+```bash
+ubio download-remote ./remote_files.tsv --output-dir ./downloads --workers 8
+```
+
+---
+
+## Python SDK Quickstart
+
+Use `ubuntu_bio` directly in your Python analysis pipelines and Jupyter notebooks:
+
+```python
+import ubuntu_bio as ub
+
+# 1. Authenticate (using a Personal Access Token or environment variable)
+ub.login(token="ubp_your_personal_access_token")
+
+# 2. Check profile
+profile = ub.whoami()
+print(f"Logged in as: @{profile.get('username')}")
+
+# 3. Create a repository
+repo = ub.create_repo(
+    repo_id="lassa-surveillance-2024",
+    domain="virus",
+    access="public",
+    description="Lassa virus genomic surveillance in West Africa",
+)
+
+# 4. Upload an entire folder of genomic files
+ub.upload_folder(
+    repo_id="lassa-surveillance-2024",
+    folder_path="./data",
+    message="Add consensus FASTA and GFF annotations",
+)
+
+# 5. Download a single file or complete snapshot
+fasta_path = ub.download_file("pasteur-dakar/cholera-2024", "assemblies/sample_01.fasta")
+dataset_dir = ub.snapshot_download("pasteur-dakar/cholera-2024", revision="main")
+```
+
+---
+
+## Configuration & Environment Variables
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `UBUNTUBIO_SERVER_URL` | UbuntuBio Hub API server URL | `https://hub.ubuntubio.org` |
+| `UBUNTUBIO_API_TOKEN` | Personal Access Token (`ubp_...`) for non-interactive environments / CI | `None` |
+| `UBUNTUBIO_CONFIG_DIR` | Directory storing local credentials cache | `~/.config/ubuntubio` |
+
+---
+
+## Security & Biological Data Ethics
+
+- **Non-Human Data Only**: In compliance with UbuntuBio v1 data governance rules, human genomic data (NCBI Taxon ID 9606) is strictly prohibited.
+- **African Union Member States**: Metadata validation strictly enforces the 54 AU member state ISO-3166-1 alpha-2 country codes.
+- **Token Security**: Tokens are stored locally with restrictive file permissions (`0600`) and validated via short-lived cryptographic tokens against the Hub.
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE).

ubuntu_bio-0.1.0/pyproject.toml

@@ -0,0 +1,119 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ubuntu-bio"
+version = "0.1.0"
+description = "Official Python client and CLI for UbuntuBio - African Bioinformatics Data Hub"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+    { name = "UbuntuBio Community", email = "dev@ubuntubio.org" }
+]
+keywords = [
+    "bioinformatics",
+    "africa",
+    "genomics",
+    "datasets",
+    "open-science",
+    "openxet",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "httpx>=0.27.2",
+    "typer>=0.12.5",
+    "rich>=13.9.0",
+    "pydantic>=2.9.0",
+    "pyyaml>=6.0.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.3",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.7.0",
+    "mypy>=1.13.0",
+    "types-pyyaml>=6.0.12.20240917",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.3",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.7.0",
+    "mypy>=1.13.0",
+    "types-pyyaml>=6.0.12.20240917",
+]
+
+
+[project.scripts]
+ubio = "ubuntu_bio.cli:main"
+ubuntu-bio = "ubuntu_bio.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ubuntu_bio", "src/ubuntubio"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+    "S",    # flake8-bandit
+    "C4",   # flake8-comprehensions
+    "SIM",  # flake8-simplify
+    "RUF",  # Ruff-specific rules
+]
+ignore = [
+    "S101", # Allow assert in tests
+    "S105", # Possible hardcoded password
+    "S106", # Possible hardcoded password
+    "S603", # Subprocess calls
+    "S607", # Partial executable paths
+    "B008", # Function call in argument defaults
+    "S324", # MD5 used for remote_files.tsv checksums
+    "SIM117", # Allow nested with statements in tests
+]
+
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+show_error_codes = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --strict-markers"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

ubuntu_bio-0.1.0/src/ubuntu_bio/__init__.py

@@ -0,0 +1,56 @@
+"""UbuntuBio Python Client Library (ubuntu-bio).
+
+African Bioinformatics Data Hub client for discovering, downloading,
+publishing, and versioning genomic datasets.
+"""
+
+from __future__ import annotations
+
+from ubuntu_bio.auth import login, logout, poll_device_token, request_device_code, whoami
+from ubuntu_bio.config import get_cache_dir, get_config_dir, get_hub_url
+from ubuntu_bio.download import download_file, download_remote_files, snapshot_download
+from ubuntu_bio.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ClientValidationError,
+    DownloadError,
+    RepositoryAlreadyExistsError,
+    RepositoryNotFoundError,
+    UbuntuBioError,
+    UploadError,
+)
+from ubuntu_bio.hub import create_repo, get_commits, get_repo, get_tree, list_repos
+from ubuntu_bio.search import search
+from ubuntu_bio.upload import upload_file, upload_folder
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthenticationError",
+    "AuthorizationError",
+    "ClientValidationError",
+    "DownloadError",
+    "RepositoryAlreadyExistsError",
+    "RepositoryNotFoundError",
+    "UbuntuBioError",
+    "UploadError",
+    "create_repo",
+    "download_file",
+    "download_remote_files",
+    "get_cache_dir",
+    "get_commits",
+    "get_config_dir",
+    "get_hub_url",
+    "get_repo",
+    "get_tree",
+    "list_repos",
+    "login",
+    "logout",
+    "poll_device_token",
+    "request_device_code",
+    "search",
+    "snapshot_download",
+    "upload_file",
+    "upload_folder",
+    "whoami",
+]