Quickstart¶
unihan-db turns UNIHAN into local SQLAlchemy
tables. For the common path, create a session with
unihan_db.bootstrap.get_session(), load the data once with
unihan_db.bootstrap.bootstrap_unihan(), and query
unihan_db.tables.Unhn or its related tables. The first bootstrap
downloads and imports the archive; after that, your queries use local SQLite.
Installation¶
Use Python >=3.10,<4.0.
Using pip:
$ pip install unihan-db
Inside a project managed by uv:
$ uv add unihan-db
Run code without installing by using uvx:
$ uvx --from unihan-db python -c "import unihan_db.bootstrap as bootstrap; print(bootstrap.TABLE_NAME)"
Install into an isolated environment with pipx:
$ pipx install 'unihan-db' --include-deps
The dependency set includes the unihan-etl CLI.
You can upgrade to the latest release with:
$ pip install --upgrade unihan-db
Usage¶
The example creates a session, runs the bootstrap, queries a random
Unhn row, and shows both
unihan_db.bootstrap.to_dict() and the row’s injected to_dict() helper.
For the API details behind those helpers, see
unihan-db’s API documentation.
#!/usr/bin/env python
"""Example for bootstrapping UNIHAN DB."""
from __future__ import annotations
import logging
import pprint
from sqlalchemy.sql.expression import func
from unihan_db import bootstrap
from unihan_db.tables import Unhn
log = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO, format="%(message)s")
def run(unihan_options: dict[str, object] | None = None) -> None:
"""Initialize Unihan DB via ``bootstrap_unihan()``."""
session = bootstrap.get_session()
bootstrap.bootstrap_unihan(session, unihan_options)
random_row_query = session.query(Unhn).order_by(func.random()).limit(1)
assert random_row_query is not None
random_row = random_row_query.first()
log.info(pprint.pformat(bootstrap.to_dict(random_row)))
assert random_row is not None
log.info(pprint.pformat(random_row.to_dict())) # type:ignore
if __name__ == "__main__":
run()
Developmental releases¶
New versions of unihan-db are published to PyPI as alpha, beta, or release
candidates. Version suffixes such as a1, b1, and rc1 mark those
pre-release stages; 1.10.0b4 is the fourth beta before general availability.
pip:
$ pip install --upgrade --pre unihan-db
pipx:
$ pipx install --suffix=@next 'unihan-db' --pip-args '\--pre' --include-deps --force
This also installs the unihan-etl CLI from the dependency set.
uv:
$ uv add unihan-db --prerelease allow
uvx:
$ uvx --from 'unihan-db' --prerelease allow python -c "import unihan_db.bootstrap as bootstrap; print(bootstrap.TABLE_NAME)"
Install from unreleased master only when you need a change that is not on
PyPI yet. This follows the current development branch, so APIs and behavior
can change before the next release: