taxdumpy 0.1.1__tar.gz

taxdumpy-0.1.1/.gitignore

@@ -0,0 +1,212 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# More
+.DS_Store
+CLAUDE.md
+.claude

taxdumpy-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Omega HH
+
+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.

taxdumpy-0.1.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: taxdumpy
+Version: 0.1.1
+Summary: Python package for efficiently parsing NCBI's taxdump database
+Project-URL: Documentation, https://github.com/omegahh/taxdumpy
+Project-URL: Issues, https://github.com/omegahh/taxdumpy/issues
+Project-URL: Source, https://github.com/omegahh/taxdumpy
+Author-email: Omega HH <omeganju@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Omega HH
+        
+        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.
+License-File: LICENSE
+Keywords: NCBI,metagenomics,taxonomy,tree-of-life
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: rapidfuzz
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Taxdumpy 🧬
+
+#### NCBI Taxonomy Toolkit for Python
+
+*A high-performance parser for NCBI Taxonomy databases with lineage resolution and taxonomy search*
+
+![](https://img.shields.io/badge/license-MIT-blue.svg)
+![](https://img.shields.io/badge/python-3.10+-blue.svg)
+![](https://img.shields.io/pypi/v/taxdumpy?color=green)
+
+## Features
+
+- **Blazing Fast Parsing**  
+  Optimized loading of NCBI taxdump files (`nodes.dmp`, `names.dmp`, etc.) with optional pickle caching
+
+- **Comprehensive Taxon Operations**  
+  - TaxID validation and lineage tracing
+  - Scientific name resolution
+  - Rank-based filtering (species → kingdom)
+  - Merged/deleted node handling
+
+- **Fuzzy Search**  
+  Rapid approximate name matching using `rapidfuzz` (supports misspellings)
+
+- **Memory Efficient**  
+  Lazy loading and optimized data structures for large taxonomies
+
+## Installation
+
+```bash
+pip install taxdumpy
+```
+
+Or from source:
+```bash
+git clone https://github.com/yourusername/taxdumpy.git
+cd taxdumpy
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from taxdumpy import TaxDb, Taxon
+
+# Initialize database (auto-downloads if needed)
+taxdb = TaxDb("/path/to/taxdump")
+
+# Create taxon object
+human = Taxon(9606, taxdb)  # Homo sapiens
+
+# Access lineage
+print(human.name_lineage)
+# ['Homo sapiens', 'Homo', 'Hominidae', ..., 'cellular organisms']
+
+# Search organisms
+taxdb._rapid_fuzz("Influenza", limit=5)
+```
+
+## Command Line Interface
+
+```bash
+# Cache full database
+taxdumpy cache -d /path/to/taxdump
+
+# Search organism
+taxdumpy search --fast "Escherichia coli"
+
+# Trace lineage
+taxdumpy lineage --fast 511145  # E. coli K-12
+```
+
+## Database Setup
+
+1. Download NCBI taxdump:  
+   ```bash
+   mkdir -p ~/.taxonkit
+   wget ftp://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz -P ~/.taxonkit
+   tar -xzf ~/.taxonkit/taxdump.tar.gz -C ~/.taxonkit
+   ```
+
+2. (Optional) Create optimized cache:  
+   ```bash
+   taxdumpy cache -d ~/.taxonkit
+   ```
+
+## Advanced Usage
+
+### Custom Caching
+```python
+# Fast cache with specific taxids
+with open("important_taxids.txt", "w") as f:
+    f.write("\n".join(["9606", "511145"]))
+    
+# CLI
+taxdumpy fast-cache -d ~/.taxonkit -f important_taxids.txt
+```
+
+### API Reference
+```python
+class Taxon:
+    """Represents a taxonomic unit"""
+    
+    @property
+    def lineage(self) -> List[Node]: ...
+    @property
+    def rank_lineage(self) -> List[str]: ...
+    @property
+    def is_legacy(self) -> bool: ...
+```
+
+## Performance Tips
+
+- Use `fast=True` when loading for ~3x speedup (requires pre-caching)
+- For batch processing, reuse `TaxDb` instances
+- Set `TAXDB_PATH` environment variable to avoid path repetition
+
+## Contributing
+
+PRs welcome! Please:
+1. Format with `black`
+2. Include type hints
+3. Add tests under `/tests`
+
+## License
+
+MIT © 2025 [Omega HH](https://github.com/omegahh)

taxdumpy-0.1.1/README.md

@@ -0,0 +1,127 @@
+# Taxdumpy 🧬
+
+#### NCBI Taxonomy Toolkit for Python
+
+*A high-performance parser for NCBI Taxonomy databases with lineage resolution and taxonomy search*
+
+![](https://img.shields.io/badge/license-MIT-blue.svg)
+![](https://img.shields.io/badge/python-3.10+-blue.svg)
+![](https://img.shields.io/pypi/v/taxdumpy?color=green)
+
+## Features
+
+- **Blazing Fast Parsing**  
+  Optimized loading of NCBI taxdump files (`nodes.dmp`, `names.dmp`, etc.) with optional pickle caching
+
+- **Comprehensive Taxon Operations**  
+  - TaxID validation and lineage tracing
+  - Scientific name resolution
+  - Rank-based filtering (species → kingdom)
+  - Merged/deleted node handling
+
+- **Fuzzy Search**  
+  Rapid approximate name matching using `rapidfuzz` (supports misspellings)
+
+- **Memory Efficient**  
+  Lazy loading and optimized data structures for large taxonomies
+
+## Installation
+
+```bash
+pip install taxdumpy
+```
+
+Or from source:
+```bash
+git clone https://github.com/yourusername/taxdumpy.git
+cd taxdumpy
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from taxdumpy import TaxDb, Taxon
+
+# Initialize database (auto-downloads if needed)
+taxdb = TaxDb("/path/to/taxdump")
+
+# Create taxon object
+human = Taxon(9606, taxdb)  # Homo sapiens
+
+# Access lineage
+print(human.name_lineage)
+# ['Homo sapiens', 'Homo', 'Hominidae', ..., 'cellular organisms']
+
+# Search organisms
+taxdb._rapid_fuzz("Influenza", limit=5)
+```
+
+## Command Line Interface
+
+```bash
+# Cache full database
+taxdumpy cache -d /path/to/taxdump
+
+# Search organism
+taxdumpy search --fast "Escherichia coli"
+
+# Trace lineage
+taxdumpy lineage --fast 511145  # E. coli K-12
+```
+
+## Database Setup
+
+1. Download NCBI taxdump:  
+   ```bash
+   mkdir -p ~/.taxonkit
+   wget ftp://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz -P ~/.taxonkit
+   tar -xzf ~/.taxonkit/taxdump.tar.gz -C ~/.taxonkit
+   ```
+
+2. (Optional) Create optimized cache:  
+   ```bash
+   taxdumpy cache -d ~/.taxonkit
+   ```
+
+## Advanced Usage
+
+### Custom Caching
+```python
+# Fast cache with specific taxids
+with open("important_taxids.txt", "w") as f:
+    f.write("\n".join(["9606", "511145"]))
+    
+# CLI
+taxdumpy fast-cache -d ~/.taxonkit -f important_taxids.txt
+```
+
+### API Reference
+```python
+class Taxon:
+    """Represents a taxonomic unit"""
+    
+    @property
+    def lineage(self) -> List[Node]: ...
+    @property
+    def rank_lineage(self) -> List[str]: ...
+    @property
+    def is_legacy(self) -> bool: ...
+```
+
+## Performance Tips
+
+- Use `fast=True` when loading for ~3x speedup (requires pre-caching)
+- For batch processing, reuse `TaxDb` instances
+- Set `TAXDB_PATH` environment variable to avoid path repetition
+
+## Contributing
+
+PRs welcome! Please:
+1. Format with `black`
+2. Include type hints
+3. Add tests under `/tests`
+
+## License
+
+MIT © 2025 [Omega HH](https://github.com/omegahh)

taxdumpy-0.1.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taxdumpy"
+description = "Python package for efficiently parsing NCBI's taxdump database"
+authors = [
+	{name = "Omega HH", email = "omeganju@gmail.com"}
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+	"Programming Language :: Python",
+	"Programming Language :: Python :: 3.10",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"License :: OSI Approved :: MIT License",
+	"Operating System :: OS Independent",
+]
+license = {file = "LICENSE"}
+keywords = [
+	"metagenomics",
+	"taxonomy",
+	"tree-of-life",
+	"NCBI"
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+	"rapidfuzz",
+	"tqdm"
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+dev = ["black", "pytest", "build"]
+
+[project.urls]
+Documentation = "https://github.com/omegahh/taxdumpy"
+Issues = "https://github.com/omegahh/taxdumpy/issues"
+Source = "https://github.com/omegahh/taxdumpy"
+
+[project.scripts]
+taxdumpy = "taxdumpy.__main__:main"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.version]
+path = "src/taxdumpy/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/taxdumpy"]

taxdumpy-0.1.1/src/taxdumpy/__init__.py

@@ -0,0 +1,19 @@
+"""Taxdumpy: A Python package for parsing NCBI taxdump database and resolving taxonomy lineage.
+"""
+
+__version__ = "0.1.1"
+
+from taxdumpy.taxdb import TaxDb, TaxDbError, TaxidError
+from taxdumpy.taxon import Taxon
+from taxdumpy.functions import upper_rank_id
+
+__all__ = [
+        # Exceptions
+        "TaxDbError",
+        "TaxidError",
+        # Data classes
+        "TaxDb",
+        "Taxon",
+        # utilities
+        "upper_rank_id"
+        ]

taxdumpy-0.1.1/src/taxdumpy/__main__.py

@@ -0,0 +1,8 @@
+"""Taxdumpy main entry point.
+"""
+
+import sys
+from taxdumpy.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

taxdumpy-0.1.1/src/taxdumpy/ansi.py

@@ -0,0 +1,5 @@
+
+b_str = lambda x: f"\033[1m{x}\033[0m" # Bold
+u_str = lambda x: f"\033[1;4m{x}\033[0m"  # UnderLine
+r_str = lambda x: f"\033[1;31m{x}\033[0m" # Red
+m_color = lambda m: f"\033[1;31m{m.group(0)}\033[0m"

taxdumpy-0.1.1/src/taxdumpy/basic.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+
+@dataclass
+class Node:
+    __slots__ = ("taxid","parent","rank","name","equal","acronym","legacy","division")
+    taxid:    int
+    parent:   int
+    rank:     str
+    name:     str
+    equal:    str|None
+    acronym:  str|None
+    division: str
+
+class TaxDbError(Exception):
+    pass
+
+class TaxidError(Exception):
+    pass
+
+class TaxRankError(Exception):
+    pass

taxdumpy-0.1.1/src/taxdumpy/cli.py

@@ -0,0 +1,104 @@
+"""Taxdumpy command-line interface
+"""
+
+import os
+import sys
+import pickle
+import argparse
+
+from tqdm import tqdm
+from pathlib import Path
+from typing import Optional, List
+
+from taxdumpy.taxdb import TaxDb
+from taxdumpy.taxsqlite import TaxSQLite
+from taxdumpy.taxon import Taxon
+from taxdumpy.ansi  import u_str
+
+def _params_parser():
+    TAXDB_PATH = os.environ.get("TAXDB_PATH", Path.home() / ".taxonkit")
+    parser = argparse.ArgumentParser(description="Toolkit for parsing NCBI taxonomy and resolving taxon lineage")
+    sub_parsers = parser.add_subparsers(dest='command')
+
+    cache_parser = sub_parsers.add_parser('cache')
+    cache_parser.add_argument('-d', dest='taxdb', help=f'path of upzipped taxonomy database, default: {TAXDB_PATH}', default=TAXDB_PATH)
+    cache_parser.add_argument('-f', dest='taxidf', help=f"If specified, cache a tiny version of TaxDb which only contains taxids in the given file.")
+
+    trace_parser = sub_parsers.add_parser('lineage')
+    trace_parser.add_argument('-d', dest='taxdb', help=f'path of upzipped taxonomy database, default: {TAXDB_PATH}', default=TAXDB_PATH)
+    trace_parser.add_argument("--fast", action="store_true")
+    trace_parser.add_argument("taxid", help=f"NCBI taxonomy id", type=int)
+
+    sname_parser = sub_parsers.add_parser('search')
+    sname_parser.add_argument('-d', dest='taxdb', help=f'path of upzipped taxonomy database, default: {TAXDB_PATH}', default=TAXDB_PATH)
+    sname_parser.add_argument("--fast", action="store_true")
+    sname_parser.add_argument("keyword", help=f"organism name", type=str)
+
+    return parser
+
+# Main Entry Point
+def main(args: Optional[List[str]] = None) -> int:
+    parsed_args = _params_parser().parse_args(args)
+    taxdb_path  = Path(parsed_args.taxdb)
+    if not taxdb_path.is_dir():
+        print(f"Input Path {taxdb_path=} is not exist. aborting!")
+        return 1
+
+    if parsed_args.command == 'cache':
+        sqlite_file = taxdb_path / "taxdump.sqlite"
+        sqlite_file.unlink(missing_ok=True)
+        TAXSQL = TaxSQLite(taxdb_path)
+        print(TAXSQL)
+        if not parsed_args.taxidf:
+            pickle_file = taxdb_path / "taxdump.pickle"
+            pickle_file.unlink(missing_ok=True)
+            TAXDB = TaxDb(taxdb_path)
+            TAXDB.dump_taxdump()
+        else:
+            taxid_file = Path(parsed_args.taxidf)
+            assert taxid_file.is_file(), FileExistsError(f"Input file {u_str(taxid_file)} is not found")
+            try:
+                with open(taxid_file, 'r') as fin:
+                    all_taxids = [int(line.strip()) for line in fin]
+            except Exception as e:
+                print(f"Error in parsing taxid file:\n\t{u_str(taxid_file)}")
+                raise e
+            all_taxids = frozenset(all_taxids)
+            print(f"Loaded {len(all_taxids):,} taxids...")
+
+            pickle_file = taxdb_path / "taxdump_fast.pickle"
+            pickle_file.unlink(missing_ok=True)
+            TAXDB = TaxDb(taxdb_path)
+            print(f"Loading the full version of TAXDB, which contains {len(TAXDB):,} taxids.")
+            kept_taxids = []
+            for taxid in tqdm(TAXDB._taxid2nodes.keys(), ncols=120):
+                taxon = Taxon(taxid, TAXDB)
+                for lineage_taxid in taxon.taxid_lineage:
+                    if lineage_taxid in all_taxids:
+                        kept_taxids.extend(taxon.taxid_lineage)
+                        break
+            kept_taxids = frozenset(kept_taxids)
+            print(f"Number of kept taxids: {len(kept_taxids):,}")
+            kept_taxid2nodes = {k: v for k,v in TAXDB._taxid2nodes.items() if k in kept_taxids}
+            print(f"Writing to {u_str(pickle_file)}")
+            with open(pickle_file, 'wb') as fout:
+                pickle.dump([kept_taxid2nodes,
+                             TAXDB._old2news,
+                             TAXDB.delnodes], fout, protocol=pickle.HIGHEST_PROTOCOL)
+            print(f"Fast Taxdump dumped!")
+
+    elif parsed_args.command == 'lineage':
+        TAXDB = TaxSQLite(taxdb_path)
+        taxid = parsed_args.taxid
+        taxon = Taxon(taxid, TAXDB)
+        print(taxon.__repr__())
+
+    elif parsed_args.command == 'search':
+        TAXDB = TaxSQLite(taxdb_path)
+        keyword = parsed_args.keyword
+        TAXDB.fuzzy_search(kw=keyword)
+
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

taxdumpy-0.1.1/src/taxdumpy/functions.py

@@ -0,0 +1,48 @@
+"""
+Description: Functions for Taxdumpy
+Author: Hao Hong (omeganju@gmail.com)
+Created: 2025-07-06 17:07:57
+"""
+
+from typing import Literal
+
+from taxdumpy.basic import TaxRankError
+from taxdumpy.taxon import Taxon
+from taxdumpy.taxdb import TaxDb
+# from taxdumpy.taxsqlite import TaxSQLite
+
+RANKNAMES  = ["species", "genus", "family", "order", "class", "phylum", "superkingdom", "realm"]
+RANK2LEVEL = {k: i for i,k in enumerate(RANKNAMES)}
+LEVEL2RANK = {i: k for i,k in enumerate(RANKNAMES)}
+def upper_rank_id(tax:  Taxon,
+                  taxdb: TaxDb,
+                  rank: Literal["species", "genus", "family", "order",
+                                "class", "phylum", "superkingdom", "realm"],
+                  ) -> int:
+    curr_rank = tax.rank
+    if curr_rank not in RANKNAMES:
+        raise TaxRankError(f"TAXID={tax.taxid} ({curr_rank=}) is a non-canonical phylogenetic rank")
+    assert rank in RANKNAMES, TaxRankError(f"{rank=} is a non-canonical phylogenetic rank")
+    # and check rank levels
+    curr_level = RANK2LEVEL[curr_rank]
+    high_level = RANK2LEVEL[rank]
+    if high_level <= curr_level:
+        raise RuntimeError(f"{rank=} is in lower/equal level than {curr_rank=} in phylogenetic tree")
+    # Get upper rank iteratively
+    if rank in tax.rank_lineage:
+        return tax.taxid_lineage[tax.rank_lineage.index(rank)]
+    elif f"sub{rank}" in tax.rank_lineage:
+        return tax.taxid_lineage[tax.rank_lineage.index(f"sub{rank}")]
+    else:
+        # neither rank nor sub-rank in the lineage
+        temp_level = high_level
+        temp_rank  = LEVEL2RANK[temp_level]
+        while temp_level > curr_level:
+            temp_level -= 1
+            temp_rank = LEVEL2RANK[temp_level]
+            if temp_rank in tax.rank_lineage:
+                break;
+        jump_taxid = tax.taxid_lineage[tax.rank_lineage.index(temp_rank)]
+        for _ in range(high_level - temp_level):
+            jump_taxid = Taxon(jump_taxid, taxdb).parent
+        return jump_taxid

taxdumpy-0.1.1/src/taxdumpy/taxdb.py

@@ -0,0 +1,171 @@
+"""
+Description: NCBI Taxonomy toolkit for parsing database, display taxid, show-lineage, etc,.
+Author: Hao Hong (omeganju@gmail.com)
+Created: 2025-06-30 19:51:00
+"""
+
+import re
+import pickle
+
+from pathlib   import Path
+from functools import cached_property
+
+from rapidfuzz import process, fuzz
+
+from taxdumpy.basic import Node, TaxDbError, TaxidError
+from taxdumpy.ansi  import u_str, m_color
+
+
+class TaxDb:
+    """
+    Create an object of the TaxDb class.
+    """
+    def __init__(self, taxdump_dir: Path|str, fast: bool = False) -> None:
+        self._taxdump_dir = Path(taxdump_dir).resolve()
+        self._fast = fast
+
+        self._taxdbf = [self._taxdump_dir / 'merged.dmp',
+                        self._taxdump_dir / 'delnodes.dmp',
+                        self._taxdump_dir / 'division.dmp',
+                        self._taxdump_dir / 'nodes.dmp',
+                        self._taxdump_dir / 'names.dmp'
+                        ]
+        self._mrgef, self._delnf, self._divsf, self._nodef, self._namef = self._taxdbf
+        self._pickle = self._taxdump_dir / ('taxdump_fast.pickle' if fast else 'taxdump.pickle')
+
+        self._taxid2nodes, self._old2news, self._delnodes = self._load_taxdump()
+
+    def _check_taxdump(self):
+        if not (self._pickle.is_file() or all([f.is_file() for f in self._taxdbf])):
+            raise TaxDbError("required taxdump files are incomplete")
+
+    def __repr__(self):
+        return f"Taxdump (Dict) Database from {u_str(self._taxdump_dir)}"
+
+    def __len__(self) -> int:
+        return len(self._taxid2nodes)
+
+    def _load_taxdump(self):
+        if self._pickle.is_file():
+            with open(self._pickle, 'rb') as fin:
+                taxid2nodes, old2news, del_taxids = pickle.load(fin)
+        else:
+            taxid2nodes, old2news, del_taxids = self._import_nodes()
+
+        return taxid2nodes, old2news, del_taxids
+
+    @cached_property
+    def all_names(self) -> list[str]:
+        return [node.name for node in self._taxid2nodes.values()]
+
+    @cached_property
+    def name2taxid(self) -> dict[str, int]:
+        return {node.name:taxid for taxid,node in self._taxid2nodes.items()}
+
+    @property
+    def delnodes(self) -> set[int]:
+        return self._delnodes
+
+    @cached_property
+    def max_taxid_strlen(self) -> int:
+        return len(str(max(list(self._taxid2nodes.keys()))))
+
+    @cached_property
+    def max_rank_strlen(self) -> int:
+        return max(set([len(n.rank) for n in self._taxid2nodes.values()]))
+
+    def _import_merged(self) -> dict[int, int]:
+        old2new = {}
+        with open(self._mrgef, "r") as f:
+            for L in f:
+                old, new = L.split('\t')[0], L.split('\t')[2]
+                old2new[int(old)] = int(new)
+        return old2new
+
+    def _import_divcodes(self) -> dict[int, str]:
+        div2codes = {}
+        with open(self._divsf, 'r') as f:
+            for L in f:
+                div, code = L.split('\t')[0], L.split('\t')[2]
+                div2codes[int(div)] = code
+        return div2codes
+
+    def _import_delnodes(self) -> set[int]:
+        del_taxids = set()
+        with open(self._delnf, 'r') as f:
+            for L in f:
+                del_taxids.add(int(L.split('\t')[0]))
+        return del_taxids
+
+    def _import_names(self) -> tuple[dict, dict, dict]:
+        sci_names, eq_names, acr_names = {}, {}, {}
+        with open(self._namef, "r") as f:
+            for L in f:
+                sp = L.split('\t')
+                tid = int(sp[0]); name = sp[2]; clas = sp[6]
+                if clas == "scientific name":
+                    sci_names[tid] = name
+                elif clas == "equivalent name":
+                    eq_names.setdefault(tid, []).append(name)
+                elif clas == "acronym":
+                    acr_names.setdefault(tid, []).append(name)
+        return sci_names, eq_names, acr_names
+
+    def _import_nodes(self) -> tuple[dict[int, Node], dict[int, int], set[int]]:
+        old2news   = self._import_merged()
+        div2codes  = self._import_divcodes()
+        del_taxids = self._import_delnodes()
+        old_taxids = set(old2news.keys())
+        sci_names, eq_names, acr_names = self._import_names()
+        taxid2nodes  = {}
+        with open(self._nodef, "r") as f:
+            for line in f:
+                line   = line.split('\t')
+                taxid  = int(line[0])
+                parent = int(line[2])
+                rank   = line[4]
+                divid  = int(line[8])
+
+                node   = Node(
+                        taxid   = taxid,
+                        parent  = old2news[parent] if parent in old_taxids else parent,
+                        rank    = rank,
+                        name    = sci_names[taxid],
+                        equal   = "|".join(eq_names[taxid])  if taxid in eq_names.keys()  else None,
+                        acronym = "|".join(acr_names[taxid]) if taxid in acr_names.keys() else None,
+                        division=div2codes[divid]
+                        )
+
+                taxid2nodes[taxid] = node
+        # Finished import all current taxid nodes, extending old_taxids (for compact)
+        cur_taxids = set(taxid2nodes.keys())
+        assert not old_taxids.intersection(cur_taxids), TaxDbError("current taxids have legacy taxids")
+
+        return taxid2nodes, old2news, del_taxids
+
+    def dump_taxdump(self):
+        print(f"Writing to {self._pickle}")
+        with open(self._pickle, 'wb') as fout:
+            pickle.dump([self._taxid2nodes,
+                         self._old2news,
+                         self.delnodes], fout, protocol=pickle.HIGHEST_PROTOCOL)
+        print(f"Taxdump dumped!")
+
+    def get_node(self, taxid: int) -> Node:
+        if taxid in self._old2news:
+            taxid = self._old2news[taxid]
+
+        if taxid in self.delnodes:
+            raise TaxidError(f"{taxid=} is a deleted taxonomy identifier")
+        try:
+            return self._taxid2nodes[taxid]
+        except KeyError:
+            raise TaxidError(f"{taxid=} is not a valid taxonomy identifier")
+
+    def fuzzy_search(self, kw: str, limit: int = 10):
+        results = process.extract(kw, self.all_names, scorer=fuzz.WRatio, limit=limit)
+        for name, _, _ in results:
+            tid  = self.name2taxid[name]
+            node = self.get_node(tid)
+            col  = re.sub(kw, m_color, name, flags=re.IGNORECASE)
+            print(f"{tid:<{self.max_taxid_strlen}}\t{node.rank:<{self.max_rank_strlen}}\t{col}")

taxdumpy-0.1.1/src/taxdumpy/taxon.py

@@ -0,0 +1,116 @@
+"""
+Description: NCBI Taxonomy toolkit for parsing database, display taxid, show-lineage, etc,.
+Author: Hao Hong (omeganju@gmail.com)
+Created: 2025-06-30 19:51:00
+"""
+
+from taxdumpy.ansi      import b_str, r_str
+from taxdumpy.taxdb     import TaxDb
+from taxdumpy.taxsqlite import Node, TaxSQLite
+
+class Taxon:
+    """
+    Create an object of the Taxon class.
+    """
+    # @line_profiler.profile
+    def __init__(self, taxid: int, taxdb: TaxDb|TaxSQLite):
+        # taxid, taxonomy node, and lineage
+        self._taxid   = taxid
+        self._node    = taxdb.get_node(taxid)
+        self._lineage = self._find_lineage(taxdb)
+
+    @property
+    def taxid(self) -> int:
+        return self._taxid
+
+    @property
+    def node(self) -> Node:
+        return self._node
+
+    @property
+    def lineage(self) -> list[Node]:
+        return self._lineage
+
+    # other infered taxon attributes
+    @property
+    def update_taxid(self) -> int:
+        return self.node.taxid
+
+    @property
+    def name(self) -> str:
+        return self.node.name
+
+    @property
+    def rank(self) -> str:
+        return self.node.rank
+
+    @property
+    def parent(self) -> int:
+        return self.node.parent
+
+    @property
+    def acronym(self) -> str|None:
+        return self.node.acronym
+
+    @property
+    def division(self) -> str:
+        return self.node.division
+
+    @property
+    def is_legacy(self) -> bool:
+        return self.taxid != self.node.taxid
+
+    @property
+    def has_species_level(self) -> bool:
+        return "species" in self.rank_lineage
+
+    @property
+    def species_taxid(self) -> int:
+        return self.taxid_lineage[self.rank_lineage.index("species")] if self.has_species_level else 0
+
+    @property
+    def taxid_lineage(self) -> list[int]:
+        return [node.taxid for node in self.lineage]
+
+    @property
+    def rank_lineage(self) -> list[str]:
+        return [node.rank for node in self.lineage]
+
+    @property
+    def name_lineage(self) -> list[str]:
+        return [node.name for node in self.lineage]
+
+    @property
+    def _max_tlen(self) -> int:
+        return max([len(str(t)) for t in self.taxid_lineage])
+
+    @property
+    def _max_rlen(self) -> int:
+        return max([len(r) for r in self.rank_lineage])
+
+    def __repr__(self):
+        lineage_str_list = []
+        for t, r, n in zip(self.taxid_lineage, self.rank_lineage, self.name_lineage):
+            current_str = f"{t:<{self._max_tlen}}\t{r:<{self._max_rlen}}\t{n}"
+            if t == self.node.taxid:
+                if self.acronym:
+                    current_str += f" ({self.acronym})"
+                if self.is_legacy:
+                    current_str += r_str(f" <- [{self.taxid} has been merged!]")
+                current_str = b_str(current_str)
+            lineage_str_list.append(current_str)
+        return "\n".join(reversed(lineage_str_list))
+
+    def __str__(self):
+        print_str = f"{self.update_taxid:<10}\t{self.rank}\t{self.name}"
+        if self.is_legacy:
+            print_str += r_str(f" <- [{self.taxid} has been merged!]")
+        return print_str
+
+    def _find_lineage(self, taxdb: TaxDb|TaxSQLite) -> list[Node]:
+        lineage = [self.node]
+        current_taxid = lineage[-1].taxid
+        while lineage[-1].parent != current_taxid:
+            current_taxid = lineage[-1].parent
+            lineage.append(taxdb.get_node(current_taxid))
+        return lineage

taxdumpy-0.1.1/src/taxdumpy/taxsqlite.py

@@ -0,0 +1,252 @@
+"""
+Description: NCBI Taxonomy toolkit for parsing database, and build up a SQLite database, etc,.
+Author: Hao Hong (omeganju@gmail.com)
+Created: 2025-06-30 19:51:00
+"""
+
+import re
+import sqlite3
+
+from pathlib   import Path
+from rapidfuzz import process, fuzz
+from functools import cached_property
+
+from taxdumpy.ansi  import u_str, m_color
+from taxdumpy.basic import Node, TaxidError
+
+
+class TaxSQLite:
+    """
+    Create an object of the TaxDb class.
+    """
+    def __init__(self, taxdump_dir: Path|str):
+        self._taxdump_dir = Path(taxdump_dir).resolve()
+
+        self._db_path = self._taxdump_dir / "taxdump.sqlite"
+
+        # open a sqlite connection, and use row_factory for element access, r['name'] for example
+        self._conn = sqlite3.connect(self._db_path)
+        self._conn.row_factory = sqlite3.Row
+        if not self._check_tables():
+            self._build_database()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if hasattr(self, '_conn'):
+            self._conn.close()
+
+    def close(self):
+        """Close SQLite connection"""
+        if hasattr(self, '_conn'):
+            self._conn.close()
+
+    def _check_tables(self) -> bool:
+        c = self._conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' and name='nodes'")
+        return c.fetchone() is not None
+
+    def __repr__(self):
+        repr_str = f"Taxdump (SQLite) Database from {u_str(self._taxdump_dir)}\n"
+        nodes_num = self._conn.execute("SELECT COUNT(*) FROM nodes").fetchone()[0]
+        repr_str += f"\tImported nodes: {nodes_num:,}\n"
+        merged_num = self._conn.execute("SELECT COUNT(*) FROM merged").fetchone()[0]
+        repr_str += f"\tLegacy nodes:   {merged_num:,}\n"
+        delete_num = len(self.delnodes)
+        repr_str += f"\tDeleted nodes:  {delete_num:,}"
+        return repr_str
+
+    def _build_database(self):
+        try:
+            print("Build up TAXDUMP SQLite Database...")
+            c = self._conn.cursor()
+            # 1) Create Tables
+            c.executescript(
+                    """
+                    CREATE TABLE nodes (
+                        taxid    INTEGER PRIMARY KEY,
+                        parent   INTEGER NOT NULL,
+                        rank     TEXT    NOT NULL,
+                        division TEXT    NOT NULL
+                        );
+                    CREATE TABLE names (
+                        taxid      INTEGER NOT NULL,
+                        name       TEXT    NOT NULL,
+                        name_class TEXT    NOT NULL,
+                        PRIMARY KEY (taxid, name_class, name)
+                        );
+                    CREATE TABLE merged (
+                        oldtid INTEGER PRIMARY KEY,
+                        newtid INTEGER NOT NULL
+                        );
+                    CREATE INDEX idx_names_name        ON names(name);
+                    CREATE INDEX idx_names_taxid       ON names(taxid);
+                    CREATE INDEX idx_names_taxid_class ON names(taxid, name_class);
+                    CREATE INDEX idx_nodes_parent ON nodes(parent);
+                    """
+                    )
+
+            # 2) Parsing merged.dmp, division.dmp, delnodes.dmp, names.dmp
+            old2new   = self._import_merged()
+            div2code  = self._import_divcodes()
+            sci_names, eq_names, acr_names = self._import_names()
+
+            # 3) Insert Nodes
+            rows_nodes = []
+            with open(self._taxdump_dir / "nodes.dmp", 'r') as f:
+                for line in f:
+                    cols   = line.split('\t')
+                    taxid  = int(cols[0])
+                    parent = int(cols[2])
+                    parent = old2new[parent] if parent in old2new else parent
+                    rank   = cols[4]
+                    divc   = div2code[int(cols[8])]
+                    rows_nodes.append((taxid, parent, rank, divc))
+            c.executemany(
+                    "INSERT INTO nodes VALUES (?,?,?,?)", rows_nodes
+                    )
+
+            # 4) Insert Names
+            rows_names = []
+            for taxid, nm in sci_names.items():
+                rows_names.append((taxid, nm, "scientific"))
+            for taxid, lst in eq_names.items():
+                for nm in lst:
+                    rows_names.append((taxid, nm, "equivalent"))
+            for taxid, lst in acr_names.items():
+                for nm in lst:
+                    rows_names.append((taxid, nm, "acronym"))
+            c.executemany(
+                    "INSERT INTO names VALUES (?,?,?)",
+                    rows_names
+                    )
+
+            # 5) Insert Legacy Taxids
+            rows_legacy = [(old,new) for old,new in old2new.items()]
+            c.executemany("INSERT INTO merged VALUES (?,?)", rows_legacy)
+            self._conn.commit()
+        except Exception:
+            self._conn.rollback()
+            raise
+
+    @cached_property
+    def all_names(self) -> list[str]:
+        # Loading all scientific names
+        all_names = [
+                row["name"]
+                for row in self._conn.execute(
+                    "SELECT name FROM names WHERE name_class='scientific'")
+                ]
+        return all_names
+
+    @cached_property
+    def name2taxid(self) -> dict[str, int]:
+        # create name->taxid map
+        name2taxid = {
+                row["name"]: row["taxid"]
+                for row in self._conn.execute(
+                    "SELECT taxid,name FROM names WHERE name_class='scientific'"
+                    )
+                }
+        return name2taxid
+
+    @cached_property
+    def delnodes(self) -> set[int]:
+        return self._import_delnodes()
+
+    @cached_property
+    def max_taxid_strlen(self) -> int:
+        max_taxid = self._conn.execute(
+                "SELECT MAX(taxid) AS max_taxid FROM nodes"
+                ).fetchone()["max_taxid"]
+        return len(str(max_taxid))
+
+    @cached_property
+    def max_rank_strlen(self) -> int:
+        row = self._conn.execute(
+                "SELECT MAX(LENGTH(rank)) FROM nodes"
+                ).fetchone()
+        return row[0]
+
+    def _import_merged(self) -> dict[int,int]:
+        old2new = {}
+        with open(self._taxdump_dir / "merged.dmp", 'r') as f:
+            for line in f:
+                parts = line.split('\t')
+                old2new[int(parts[0])] = int(parts[2])
+        return old2new
+
+    def _import_divcodes(self) -> dict[int,str]:
+        div2codes = {}
+        with open(self._taxdump_dir / "division.dmp", 'r') as f:
+            for L in f:
+                div, code = L.split('\t')[0], L.split('\t')[2]
+                div2codes[int(div)] = code
+        return div2codes
+
+    def _import_delnodes(self) -> set[int]:
+        s = set()
+        with open(self._taxdump_dir / "delnodes.dmp", 'r') as f:
+            for L in f:
+                s.add(int(L.split('\t')[0]))
+        return s
+
+    def _import_names(self):
+        sci_names, eq_names, acr_names = {}, {}, {}
+        with open(self._taxdump_dir / "names.dmp", 'r') as f:
+            for L in f:
+                sp = L.split('\t')
+                tid = int(sp[0]); name = sp[2]; clas = sp[6]
+                if clas == "scientific name":
+                    sci_names[tid] = name
+                elif clas == "equivalent name":
+                    eq_names.setdefault(tid, []).append(name)
+                elif clas == "acronym":
+                    acr_names.setdefault(tid, []).append(name)
+        return sci_names, eq_names, acr_names
+
+    def get_node(self, taxid: int) -> Node:
+        r1 = self._conn.execute(
+                "SELECT newtid FROM merged WHERE oldtid=?", (taxid,)
+                ).fetchone()
+        if r1:
+            taxid = r1['newtid']
+
+        r = self._conn.execute(
+                "SELECT * FROM nodes WHERE taxid=?", (taxid,)
+                ).fetchone()
+        if not r:
+            if taxid in self.delnodes:
+                raise TaxidError(f"{taxid=} is a deleted taxonomy identifier")
+            else:
+                raise TaxidError(f"{taxid=} is a wrong taxonomy identifier")
+
+        name = self._conn.execute(
+                "SELECT name FROM names WHERE taxid=? AND name_class='scientific'", (taxid,)
+                ).fetchone()["name"]
+        eqv  = self._conn.execute(
+                "SELECT group_concat(name,'|') AS a FROM names WHERE taxid=? AND name_class='equivalent'",
+                (taxid,)
+                ).fetchone()["a"]
+        acr  = self._conn.execute(
+                "SELECT group_concat(name,'|') AS a FROM names WHERE taxid=? AND name_class='acronym'",
+                (taxid,)
+                ).fetchone()["a"]
+        return Node(
+                taxid    = r["taxid"],
+                parent   = r["parent"],
+                rank     = r["rank"],
+                name     = name,
+                equal    = eqv,
+                acronym  = acr,
+                division = r["division"]
+                )
+
+    def fuzzy_search(self, kw: str, limit: int = 10):
+        results = process.extract(kw, self.all_names, scorer=fuzz.WRatio, limit=limit)
+        for name, _, _ in results:
+            tid  = self.name2taxid[name]
+            node = self.get_node(tid)
+            col  = re.sub(kw, m_color, name, flags=re.IGNORECASE)
+            print(f"{tid:<{self.max_taxid_strlen}}\t{node.rank:<{self.max_rank_strlen}}\t{col}")