PanGBank-api 0.1.1__tar.gz

pangbank_api-0.1.1/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: PanGBank-api
+Version: 0.1.1
+Summary: Source code to PanGBank API
+Author: Jean Mainguy
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi[all]>=0.115.8
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: typer>=0.15.1
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: packaging>=24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: requests>=2.32.3; extra == "dev"
+Requires-Dist: httpx>=0.28.1; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: flake8>=7.1.2; extra == "dev"
+Requires-Dist: alembic>=1.13.1; extra == "dev"
+
+# PanGBank API
+
+This repository contains the API used to manage the **PanGBank** database, which stores collections of pangenomes built with [**PPanGGOLiN**](https://github.com/labgem/PPanGGOLiN).
+
+The API is built with [**FastAPI**](https://fastapi.tiangolo.com) and uses [**SQLModel**](https://sqlmodel.tiangolo.com) as its ORM.
+It provides a RESTful interface for querying and exploring pangenome collections. Alongside the API, a command-line tool `pangbank_db` is included to manage the database.
+
+## 🚀 Installation
+
+### Local API Setup
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://github.com/labgem/PanGBank-api.git
+   cd PanGBank-api
+   ```
+
+2. **Create a virtual environment and install dependencies**:
+
+   ```bash
+   python -m venv venv
+   source venv/bin/activate
+   pip install .
+   ```
+
+3. **Run the API in development mode**:
+
+   ```bash
+   export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+   export PANGBANK_DATA_DIR="<path/to/pangenome_directory>"
+   fastapi dev pangbank_api/main.py
+   ```
+
+> `PANGBANK_DB_PATH` is the path to your SQLite database file.
+> `PANGBANK_DATA_DIR` is the root directory containing your pangenome data and mash files.
+
+
+## 🛠️ Managing the Database with `pangbank_db`
+
+All CLI commands require the `PANGBANK_DB_PATH` environment variable to be set.
+
+```bash
+export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+```
+
+
+### Add a Collection Release
+
+To add a new collection of pangenomes in the database, use:
+
+```bash
+pangbank_db add-collection-release <collection_release.json>
+```
+> [!NOTE]
+> This command requires two environment variables:
+>
+> ```bash
+> export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+> export PANGBANK_DATA_DIR="<root/path/serving/pangenomes>"
+> ```
+  
+
+<details>
+
+
+<summary>JSON Schema Example</summary>
+
+
+
+```jsonc
+{
+  "collection": {
+    "name": "GTDB_all_sampled",
+    "description": "GTDB all is a collection of pangenomes made of GTDB species that have at least 15 genomes."
+  },
+  "release": {
+    "version": "1.0.0",
+    "ppanggolin_version": "2.2.4",
+    "pangbank_wf_version": "0.0.2",
+    "pangenomes_directory": "GTDB_refseq/release_v1.0.0/data/pangenomes/", // relative to PANGBANK_DATA_DIR
+    "release_note": "",
+    "date": "2025-07-10",
+    "mash_sketch": "GTDB_refseq/release_v1.0.0/data/mash_sketch/families_persistent_all.msh", // relative to PANGBANK_DATA_DIR
+    "mash_version": "2.3"
+  },
+  "taxonomy": {
+    "name": "GTDB",
+    "version": "10-RS226",
+    "ranks": "Domain; Phylum; Class; Order; Family; Genus; Species",
+    "file": "/absolute/path/to/taxonomy.tsv"
+  },
+  "genome_sources": [
+    {
+      "name": "RefSeq",
+      "file": "/absolute/path/to/genomes.tsv",
+      "version": "",
+      "description": "",
+      "source": "",
+      "url": ""
+    }
+  ],
+  "genome_metadata_sources": [
+    {
+      "name": "GTDB 10-RS226 metadata",
+      "description": "Metadata collected from GTDB. Some columns have been filtered out.",
+      "url": "https://data.ace.uq.edu.au/public/gtdb/data/releases/release226/226.0/",
+      "strain_attribute": "ncbi_strain_identifiers",
+      "organism_name_attribute": "ncbi_organism_name",
+      "file": "/absolute/path/to/metadata.tsv"
+    }
+  ]
+}
+```
+
+#### Note
+* Paths for `pangenomes_directory` and `mash_sketch` must be **relative to `PANGBANK_DATA_DIR`**.
+* Paths for `taxonomy.file`, `genome_sources[*].file`, and `genome_metadata_sources[*].file` must be **absolute file paths**.
+
+</details>
+
+
+### List Existing Collections
+
+```bash
+pangbank_db list-collection
+```
+
+### Delete a Collection Release
+
+```bash
+pangbank_db delete-collection <collection_name> --release-version <version>
+```
+
+
+## 🗃️ Database Migrations with Alembic
+
+We use [Alembic](https://alembic.sqlalchemy.org/) to manage schema changes in the PanGBank database.
+
+
+#### Create a new migration
+
+Generate a migration after updating your SQLModel models (e.g., adding or changing columns):
+
+```bash
+alembic revision --autogenerate -m "Describe your change here"
+```
+
+#### Apply migrations to the database
+
+This applies all pending migrations:
+
+```bash
+alembic upgrade head
+```
+
+#### Roll back the last migration (use with caution)
+
+If something went wrong, you can revert the last migration:
+
+```bash
+alembic downgrade -1
+```
+
+Or go back to the base (empty schema):
+
+```bash
+alembic downgrade base
+```
+
+> [!NOTE]
+> * The SQLite database path is defined in `config.py` via the `pangbank_db_path` setting (`PANGBANK_DB_PATH` env var).
+>* Alembic is configured to read this dynamically, so no need to change `alembic.ini`.
+
+
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature-name`).
+3. Commit your changes (`git commit -m 'Add new feature'`).
+4. Push to the branch (`git push origin feature-name`).
+5. Open a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For any inquiries or issues, open an issue on the [GitHub repository](https://github.com/labgem/PanGBank-API/issues).

pangbank_api-0.1.1/PanGBank_api.egg-info/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: PanGBank-api
+Version: 0.1.1
+Summary: Source code to PanGBank API
+Author: Jean Mainguy
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi[all]>=0.115.8
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: typer>=0.15.1
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: packaging>=24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: requests>=2.32.3; extra == "dev"
+Requires-Dist: httpx>=0.28.1; extra == "dev"
+Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
+Requires-Dist: flake8>=7.1.2; extra == "dev"
+Requires-Dist: alembic>=1.13.1; extra == "dev"
+
+# PanGBank API
+
+This repository contains the API used to manage the **PanGBank** database, which stores collections of pangenomes built with [**PPanGGOLiN**](https://github.com/labgem/PPanGGOLiN).
+
+The API is built with [**FastAPI**](https://fastapi.tiangolo.com) and uses [**SQLModel**](https://sqlmodel.tiangolo.com) as its ORM.
+It provides a RESTful interface for querying and exploring pangenome collections. Alongside the API, a command-line tool `pangbank_db` is included to manage the database.
+
+## 🚀 Installation
+
+### Local API Setup
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://github.com/labgem/PanGBank-api.git
+   cd PanGBank-api
+   ```
+
+2. **Create a virtual environment and install dependencies**:
+
+   ```bash
+   python -m venv venv
+   source venv/bin/activate
+   pip install .
+   ```
+
+3. **Run the API in development mode**:
+
+   ```bash
+   export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+   export PANGBANK_DATA_DIR="<path/to/pangenome_directory>"
+   fastapi dev pangbank_api/main.py
+   ```
+
+> `PANGBANK_DB_PATH` is the path to your SQLite database file.
+> `PANGBANK_DATA_DIR` is the root directory containing your pangenome data and mash files.
+
+
+## 🛠️ Managing the Database with `pangbank_db`
+
+All CLI commands require the `PANGBANK_DB_PATH` environment variable to be set.
+
+```bash
+export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+```
+
+
+### Add a Collection Release
+
+To add a new collection of pangenomes in the database, use:
+
+```bash
+pangbank_db add-collection-release <collection_release.json>
+```
+> [!NOTE]
+> This command requires two environment variables:
+>
+> ```bash
+> export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+> export PANGBANK_DATA_DIR="<root/path/serving/pangenomes>"
+> ```
+  
+
+<details>
+
+
+<summary>JSON Schema Example</summary>
+
+
+
+```jsonc
+{
+  "collection": {
+    "name": "GTDB_all_sampled",
+    "description": "GTDB all is a collection of pangenomes made of GTDB species that have at least 15 genomes."
+  },
+  "release": {
+    "version": "1.0.0",
+    "ppanggolin_version": "2.2.4",
+    "pangbank_wf_version": "0.0.2",
+    "pangenomes_directory": "GTDB_refseq/release_v1.0.0/data/pangenomes/", // relative to PANGBANK_DATA_DIR
+    "release_note": "",
+    "date": "2025-07-10",
+    "mash_sketch": "GTDB_refseq/release_v1.0.0/data/mash_sketch/families_persistent_all.msh", // relative to PANGBANK_DATA_DIR
+    "mash_version": "2.3"
+  },
+  "taxonomy": {
+    "name": "GTDB",
+    "version": "10-RS226",
+    "ranks": "Domain; Phylum; Class; Order; Family; Genus; Species",
+    "file": "/absolute/path/to/taxonomy.tsv"
+  },
+  "genome_sources": [
+    {
+      "name": "RefSeq",
+      "file": "/absolute/path/to/genomes.tsv",
+      "version": "",
+      "description": "",
+      "source": "",
+      "url": ""
+    }
+  ],
+  "genome_metadata_sources": [
+    {
+      "name": "GTDB 10-RS226 metadata",
+      "description": "Metadata collected from GTDB. Some columns have been filtered out.",
+      "url": "https://data.ace.uq.edu.au/public/gtdb/data/releases/release226/226.0/",
+      "strain_attribute": "ncbi_strain_identifiers",
+      "organism_name_attribute": "ncbi_organism_name",
+      "file": "/absolute/path/to/metadata.tsv"
+    }
+  ]
+}
+```
+
+#### Note
+* Paths for `pangenomes_directory` and `mash_sketch` must be **relative to `PANGBANK_DATA_DIR`**.
+* Paths for `taxonomy.file`, `genome_sources[*].file`, and `genome_metadata_sources[*].file` must be **absolute file paths**.
+
+</details>
+
+
+### List Existing Collections
+
+```bash
+pangbank_db list-collection
+```
+
+### Delete a Collection Release
+
+```bash
+pangbank_db delete-collection <collection_name> --release-version <version>
+```
+
+
+## 🗃️ Database Migrations with Alembic
+
+We use [Alembic](https://alembic.sqlalchemy.org/) to manage schema changes in the PanGBank database.
+
+
+#### Create a new migration
+
+Generate a migration after updating your SQLModel models (e.g., adding or changing columns):
+
+```bash
+alembic revision --autogenerate -m "Describe your change here"
+```
+
+#### Apply migrations to the database
+
+This applies all pending migrations:
+
+```bash
+alembic upgrade head
+```
+
+#### Roll back the last migration (use with caution)
+
+If something went wrong, you can revert the last migration:
+
+```bash
+alembic downgrade -1
+```
+
+Or go back to the base (empty schema):
+
+```bash
+alembic downgrade base
+```
+
+> [!NOTE]
+> * The SQLite database path is defined in `config.py` via the `pangbank_db_path` setting (`PANGBANK_DB_PATH` env var).
+>* Alembic is configured to read this dynamically, so no need to change `alembic.ini`.
+
+
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature-name`).
+3. Commit your changes (`git commit -m 'Add new feature'`).
+4. Push to the branch (`git push origin feature-name`).
+5. Open a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For any inquiries or issues, open an issue on the [GitHub repository](https://github.com/labgem/PanGBank-API/issues).

pangbank_api-0.1.1/PanGBank_api.egg-info/SOURCES.txt

@@ -0,0 +1,31 @@
+README.md
+pyproject.toml
+PanGBank_api.egg-info/PKG-INFO
+PanGBank_api.egg-info/SOURCES.txt
+PanGBank_api.egg-info/dependency_links.txt
+PanGBank_api.egg-info/entry_points.txt
+PanGBank_api.egg-info/requires.txt
+PanGBank_api.egg-info/top_level.txt
+pangbank_api/__init__.py
+pangbank_api/config.py
+pangbank_api/database.py
+pangbank_api/dependencies.py
+pangbank_api/main.py
+pangbank_api/models.py
+pangbank_api/crud/__init__.py
+pangbank_api/crud/collections.py
+pangbank_api/crud/common.py
+pangbank_api/crud/genomes.py
+pangbank_api/crud/pangenomes.py
+pangbank_api/manage_db/__init__.py
+pangbank_api/manage_db/collections.py
+pangbank_api/manage_db/genome_metadata.py
+pangbank_api/manage_db/genomes.py
+pangbank_api/manage_db/input_models.py
+pangbank_api/manage_db/pangbank_db.py
+pangbank_api/manage_db/taxonomy.py
+pangbank_api/manage_db/utils.py
+pangbank_api/routers/__init__.py
+pangbank_api/routers/collections.py
+pangbank_api/routers/genomes.py
+pangbank_api/routers/pangenomes.py

pangbank_api-0.1.1/PanGBank_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pangbank_api-0.1.1/PanGBank_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pangbank_db = pangbank_api.manage_db.pangbank_db:cli

pangbank_api-0.1.1/PanGBank_api.egg-info/requires.txt

@@ -0,0 +1,13 @@
+fastapi[all]>=0.115.8
+sqlmodel>=0.0.22
+typer>=0.15.1
+pyyaml>=6.0.2
+packaging>=24
+
+[dev]
+pytest>=8.3.4
+requests>=2.32.3
+httpx>=0.28.1
+pytest-cov>=6.0.0
+flake8>=7.1.2
+alembic>=1.13.1

pangbank_api-0.1.1/PanGBank_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+pangbank_api

pangbank_api-0.1.1/README.md

@@ -0,0 +1,191 @@
+# PanGBank API
+
+This repository contains the API used to manage the **PanGBank** database, which stores collections of pangenomes built with [**PPanGGOLiN**](https://github.com/labgem/PPanGGOLiN).
+
+The API is built with [**FastAPI**](https://fastapi.tiangolo.com) and uses [**SQLModel**](https://sqlmodel.tiangolo.com) as its ORM.
+It provides a RESTful interface for querying and exploring pangenome collections. Alongside the API, a command-line tool `pangbank_db` is included to manage the database.
+
+## 🚀 Installation
+
+### Local API Setup
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone https://github.com/labgem/PanGBank-api.git
+   cd PanGBank-api
+   ```
+
+2. **Create a virtual environment and install dependencies**:
+
+   ```bash
+   python -m venv venv
+   source venv/bin/activate
+   pip install .
+   ```
+
+3. **Run the API in development mode**:
+
+   ```bash
+   export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+   export PANGBANK_DATA_DIR="<path/to/pangenome_directory>"
+   fastapi dev pangbank_api/main.py
+   ```
+
+> `PANGBANK_DB_PATH` is the path to your SQLite database file.
+> `PANGBANK_DATA_DIR` is the root directory containing your pangenome data and mash files.
+
+
+## 🛠️ Managing the Database with `pangbank_db`
+
+All CLI commands require the `PANGBANK_DB_PATH` environment variable to be set.
+
+```bash
+export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+```
+
+
+### Add a Collection Release
+
+To add a new collection of pangenomes in the database, use:
+
+```bash
+pangbank_db add-collection-release <collection_release.json>
+```
+> [!NOTE]
+> This command requires two environment variables:
+>
+> ```bash
+> export PANGBANK_DB_PATH="<path/to/database.sqlite>"
+> export PANGBANK_DATA_DIR="<root/path/serving/pangenomes>"
+> ```
+  
+
+<details>
+
+
+<summary>JSON Schema Example</summary>
+
+
+
+```jsonc
+{
+  "collection": {
+    "name": "GTDB_all_sampled",
+    "description": "GTDB all is a collection of pangenomes made of GTDB species that have at least 15 genomes."
+  },
+  "release": {
+    "version": "1.0.0",
+    "ppanggolin_version": "2.2.4",
+    "pangbank_wf_version": "0.0.2",
+    "pangenomes_directory": "GTDB_refseq/release_v1.0.0/data/pangenomes/", // relative to PANGBANK_DATA_DIR
+    "release_note": "",
+    "date": "2025-07-10",
+    "mash_sketch": "GTDB_refseq/release_v1.0.0/data/mash_sketch/families_persistent_all.msh", // relative to PANGBANK_DATA_DIR
+    "mash_version": "2.3"
+  },
+  "taxonomy": {
+    "name": "GTDB",
+    "version": "10-RS226",
+    "ranks": "Domain; Phylum; Class; Order; Family; Genus; Species",
+    "file": "/absolute/path/to/taxonomy.tsv"
+  },
+  "genome_sources": [
+    {
+      "name": "RefSeq",
+      "file": "/absolute/path/to/genomes.tsv",
+      "version": "",
+      "description": "",
+      "source": "",
+      "url": ""
+    }
+  ],
+  "genome_metadata_sources": [
+    {
+      "name": "GTDB 10-RS226 metadata",
+      "description": "Metadata collected from GTDB. Some columns have been filtered out.",
+      "url": "https://data.ace.uq.edu.au/public/gtdb/data/releases/release226/226.0/",
+      "strain_attribute": "ncbi_strain_identifiers",
+      "organism_name_attribute": "ncbi_organism_name",
+      "file": "/absolute/path/to/metadata.tsv"
+    }
+  ]
+}
+```
+
+#### Note
+* Paths for `pangenomes_directory` and `mash_sketch` must be **relative to `PANGBANK_DATA_DIR`**.
+* Paths for `taxonomy.file`, `genome_sources[*].file`, and `genome_metadata_sources[*].file` must be **absolute file paths**.
+
+</details>
+
+
+### List Existing Collections
+
+```bash
+pangbank_db list-collection
+```
+
+### Delete a Collection Release
+
+```bash
+pangbank_db delete-collection <collection_name> --release-version <version>
+```
+
+
+## 🗃️ Database Migrations with Alembic
+
+We use [Alembic](https://alembic.sqlalchemy.org/) to manage schema changes in the PanGBank database.
+
+
+#### Create a new migration
+
+Generate a migration after updating your SQLModel models (e.g., adding or changing columns):
+
+```bash
+alembic revision --autogenerate -m "Describe your change here"
+```
+
+#### Apply migrations to the database
+
+This applies all pending migrations:
+
+```bash
+alembic upgrade head
+```
+
+#### Roll back the last migration (use with caution)
+
+If something went wrong, you can revert the last migration:
+
+```bash
+alembic downgrade -1
+```
+
+Or go back to the base (empty schema):
+
+```bash
+alembic downgrade base
+```
+
+> [!NOTE]
+> * The SQLite database path is defined in `config.py` via the `pangbank_db_path` setting (`PANGBANK_DB_PATH` env var).
+>* Alembic is configured to read this dynamically, so no need to change `alembic.ini`.
+
+
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch (`git checkout -b feature-name`).
+3. Commit your changes (`git commit -m 'Add new feature'`).
+4. Push to the branch (`git push origin feature-name`).
+5. Open a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For any inquiries or issues, open an issue on the [GitHub repository](https://github.com/labgem/PanGBank-API/issues).

pangbank_api-0.1.1/pangbank_api/config.py

@@ -0,0 +1,21 @@
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+from pathlib import Path
+from typing import Annotated
+from fastapi import Depends
+
+
+class Settings(BaseSettings):
+    pangbank_db_path: Path = Path("database/database.db")
+    pangbank_data_dir: Path = Path("data/")
+    pangbank_origins: str = (
+        "http://localhost:3000"  # list of origins separated by semicolon
+    )
+
+
+@lru_cache
+def get_settings():
+    return Settings()
+
+
+SettingsDep = Annotated[Settings, Depends(get_settings)]