| Name | polli-typus JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Taxonomic types, projections and async taxonomy services for Polli-Labs. |
| upload_time | 2025-08-09 02:38:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
ecology
pydantic
sqlalchemy
taxonomy
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Typus
**Shared taxonomy & geo‑temporal types for the Polli‑Labs ecological stack**
Typus centralises every domain object that the rest of our platform —
`linnaeus`, `pollinalysis-server`, dashboards … — needs: taxon records,
clades, hierarchical classification results, projection helpers and async
database services. Anything that speaks taxonomy imports **Typus** and stays DRY.
---
## Features
* **Wide ancestry view** – `expanded_taxa` ORM exposes each rank (L10 → L70)
on a single row for constant‑time lineage queries.
* **Async services** – `PostgresTaxonomyService` (ltree) &
`SQLiteTaxonomyService` (fixture) share one interface.
* **Pydantic v2 models** – `Taxon`, `Clade`,
`HierarchicalClassificationResult`, all JSON‑Schema‑exportable.
* **Projection utils** – lat/lon ↔ unit‑sphere, cyclical‑time features,
multi‑scale elevation sinusoids.
* **Optional drivers only when you need them** – install
`polli-typus[postgres]` or `[sqlite]`; core install stays lightweight.
* **Offline SQLite loader** – `typus-load-sqlite` CLI builds and caches the offline dataset
---
## Requirements
* Python **≥ 3.10**
---
## Installation
### Core (no DB drivers)
```bash
uv pip install polli-typus # import typus
```
### With Postgres backend
```bash
uv pip install "polli-typus[postgres]" # adds asyncpg
```
### With SQLite only (CI, offline, sandboxes)
```bash
uv pip install "polli-typus[sqlite]"
```
### Development / tests / lint
```bash
uv pip install -e ".[dev,sqlite]" # pytest, pytest-asyncio, ruff, pre-commit, aiosqlite …
```
Install with plain pip:
```bash
pip install -e ".[dev,sqlite]"
```
---
## Quick start
```python
from typus import PostgresTaxonomyService, RankLevel, latlon_to_unit_sphere
svc = PostgresTaxonomyService("postgresql+asyncpg://user:pw@host/db")
bee = await svc.get_taxon(630955) # Anthophila
print(bee.scientific_name, bee.rank_level) # Anthophila RankLevel.L32
print(latlon_to_unit_sphere(31.5, -110.4)) # → x, y, z on S²
```
### Offline mode (SQLite fixture)
```python
from pathlib import Path
from typus.services import SQLiteTaxonomyService, load_expanded_taxa
db = Path("expanded_taxa.sqlite")
load_expanded_taxa(db) # downloads if missing
svc = SQLiteTaxonomyService(db)
```
```bash
typus-load-sqlite --sqlite expanded_taxa.sqlite
```
---
## Developer guide
* **Lint & tests (one‑liner)**
```bash
ruff check . && ruff format . && pytest -q
```
* **Format whole repo**
```bash
ruff format .
```
* **JSON Schemas** – `python -m typus.export_schemas` → `typus/schemas/`
* **SQLite fixture** – `python scripts/gen_fixture_sqlite.py`
* **Pre‑commit hooks** – `pre-commit install`
---
## Publishing (maintainers)
See `build/typus_publish.md` for tag → TestPyPI → PyPI workflow.
---
## License
MIT © 2025 Polli Labs
Raw data
{
"_id": null,
"home_page": null,
"name": "polli-typus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ecology, pydantic, sqlalchemy, taxonomy",
"author": null,
"author_email": "Polli-Labs <caleb@polli.ai>",
"download_url": null,
"platform": null,
"description": "\n\n# Typus\n\n**Shared taxonomy & geo\u2011temporal types for the Polli\u2011Labs ecological stack**\n\nTypus centralises every domain object that the rest of our platform \u2014\n`linnaeus`, `pollinalysis-server`, dashboards \u2026 \u2014 needs: taxon records,\nclades, hierarchical classification results, projection helpers and async\ndatabase services. Anything that speaks taxonomy imports **Typus** and stays DRY.\n\n---\n\n## Features\n\n* **Wide ancestry view** \u2013 `expanded_taxa` ORM exposes each rank (L10\u202f\u2192\u202fL70)\n on a single row for constant\u2011time lineage queries.\n* **Async services** \u2013 `PostgresTaxonomyService` (ltree) &\n `SQLiteTaxonomyService` (fixture) share one interface.\n* **Pydantic\u00a0v2 models** \u2013 `Taxon`, `Clade`,\n `HierarchicalClassificationResult`, all JSON\u2011Schema\u2011exportable.\n* **Projection utils** \u2013 lat/lon \u2194 unit\u2011sphere, cyclical\u2011time features,\n multi\u2011scale elevation sinusoids.\n* **Optional drivers only when you need them** \u2013 install\n `polli-typus[postgres]` or `[sqlite]`; core install stays lightweight.\n* **Offline SQLite loader** \u2013 `typus-load-sqlite` CLI builds and caches the offline dataset\n\n---\n\n## Requirements\n\n* Python **\u2265\u202f3.10**\n\n---\n\n## Installation\n\n### Core (no DB drivers)\n\n```bash\nuv pip install polli-typus # import typus\n```\n\n### With Postgres backend\n\n```bash\nuv pip install \"polli-typus[postgres]\" # adds asyncpg\n```\n\n### With SQLite only (CI, offline, sandboxes)\n\n```bash\nuv pip install \"polli-typus[sqlite]\"\n```\n\n### Development / tests / lint\n\n```bash\nuv pip install -e \".[dev,sqlite]\" # pytest, pytest-asyncio, ruff, pre-commit, aiosqlite \u2026\n```\n\nInstall with plain pip:\n\n```bash\npip install -e \".[dev,sqlite]\"\n```\n\n---\n\n## Quick start\n\n```python\nfrom typus import PostgresTaxonomyService, RankLevel, latlon_to_unit_sphere\n\nsvc = PostgresTaxonomyService(\"postgresql+asyncpg://user:pw@host/db\")\nbee = await svc.get_taxon(630955) # Anthophila\nprint(bee.scientific_name, bee.rank_level) # Anthophila RankLevel.L32\n\nprint(latlon_to_unit_sphere(31.5, -110.4)) # \u2192 x, y, z on S\u00b2\n```\n\n### Offline mode (SQLite fixture)\n\n```python\nfrom pathlib import Path\nfrom typus.services import SQLiteTaxonomyService, load_expanded_taxa\n\ndb = Path(\"expanded_taxa.sqlite\")\nload_expanded_taxa(db) # downloads if missing\nsvc = SQLiteTaxonomyService(db)\n```\n```bash\ntypus-load-sqlite --sqlite expanded_taxa.sqlite\n```\n\n---\n\n## Developer guide\n\n* **Lint & tests (one\u2011liner)**\n\n ```bash\n ruff check . && ruff format . && pytest -q\n ```\n\n* **Format whole repo**\n\n ```bash\n ruff format .\n ```\n\n* **JSON Schemas** \u2013 `python -m typus.export_schemas` \u2192 `typus/schemas/`\n\n* **SQLite fixture** \u2013 `python scripts/gen_fixture_sqlite.py`\n\n* **Pre\u2011commit hooks** \u2013 `pre-commit install`\n\n---\n\n## Publishing (maintainers)\n\nSee `build/typus_publish.md` for tag \u2192 TestPyPI \u2192 PyPI workflow.\n\n---\n\n## License\n\nMIT \u00a9\u00a02025\u00a0Polli\u00a0Labs\n",
"bugtrack_url": null,
"license": null,
"summary": "Taxonomic types, projections and async taxonomy services for Polli-Labs.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/polli-labs/typus",
"Issues": "https://github.com/polli-labs/typus/issues"
},
"split_keywords": [
"ecology",
" pydantic",
" sqlalchemy",
" taxonomy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9b7197d7d008b8f09efe30c739022e0e4de77aed30c996293d055d11315458d4",
"md5": "c6a33529b59ec1d3708104c3525c1db6",
"sha256": "054f8f47de5ee9a6c0d8cfd13a338e864c7dcb5d5c845d677f7ea70a1a652b47"
},
"downloads": -1,
"filename": "polli_typus-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6a33529b59ec1d3708104c3525c1db6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 41546,
"upload_time": "2025-08-09T02:38:26",
"upload_time_iso_8601": "2025-08-09T02:38:26.389286Z",
"url": "https://files.pythonhosted.org/packages/9b/71/97d7d008b8f09efe30c739022e0e4de77aed30c996293d055d11315458d4/polli_typus-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 02:38:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "polli-labs",
"github_project": "typus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "polli-typus"
}
