Changelog¶
To install the unreleased unihan-db version, see developmental releases.
pip:
$ pip install --user --upgrade --pre unihan-db
pipx:
$ pipx install --suffix=@next 'unihan-db' --pip-args '\--pre' --include-deps --force
This installs the unihan-etl command-line tools from the dependency set. With
the suffix shown above, run unihan-etl@next.
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)"
unihan-db 0.21.x (unreleased)¶
Notes on the upcoming release will go here.
unihan-db 0.21.x is the May 2026 documentation and dependency refresh. It
reshapes the docs around the Library Skeleton pattern, moves the site onto the
shared gp-sphinx platform, and adopts the Vite-backed gp-furo-theme asset
pipeline. Runtime data loading remains centered on bootstrap_unihan()
and Unhn; the upstream unihan-etl dependency moves
to the current 0.41 line.
Breaking changes¶
unihan-etl CLI requires explicit subcommands (#358)¶
Users who run the unihan-etl command directly from unihan-db’s dependency set
must use the explicit upstream subcommand syntax introduced in unihan-etl
0.40.
Before:
$ unihan-etl
After:
$ unihan-etl export
Python callers using bootstrap_data() or
bootstrap_unihan() continue to use the same
unihan-db bootstrap APIs.
Dependencies¶
Current unihan-etl import pipeline (#358)¶
Minimum unihan-etl~=0.41.0 (was ~=0.39.1). The bump keeps
bootstrap_data() aligned with the maintained ETL
package while preserving the import-facing modules used by unihan-db.
What’s new¶
Library Skeleton documentation (#360)¶
The docs are now organized around a composed homepage, a compact API index, and
a project/ section for contribution, code-style, and release guidance. The
homepage explains unihan-db’s place in the cihai stack: unihan-db provides the
schema and ORM layer, unihan-etl handles the ETL pipeline, and cihai is the
end-user lookup layer.
The new page structure gives readers a quicker path from installation to the
core workflow: create the SQLAlchemy schema, bootstrap UNIHAN data, and query
Unhn rows. See Quickstart,
API Reference, and Project.
API pages with richer object presentation (#362, #363)¶
The API reference now uses the gp-sphinx autodoc style layer: card-style Python signatures, badges, object cross-references, and cleaner field-list rendering. The split API pages for Bootstrap - unihan_db.bootstrap, Importing - unihan_db.importer, and Tables - unihan_db.tables remain the canonical entry points.
The gp-sphinx 0.0.1a8 adoption also picks up the argparse-domain and CSS namespace consolidation work from the shared platform. For unihan-db, the main result is simpler dependency management and a docs stack that matches sibling projects.
gp-furo-theme and Vite-built docs assets (#364)¶
The docs theme now renders through gp-furo-theme, a Tailwind v4 port of Furo,
with sphinx-vite-builder owning theme asset builds. Published wheels carry
pre-built CSS and JavaScript, so downstream docs builds can install the theme
without rebuilding the frontend assets locally.
The same branch retired the old gp-sphinx-vite references from this project.
The final dependency pins have since followed the shared workspace to
gp-sphinx==0.0.1a17 and sphinx-autodoc-api-style==0.0.1a17.
Fixes¶
Source links use the package version¶
unihan_db.__version__ is now exported from unihan_db.__about__, allowing the
gp-sphinx linkcode helper to build version-aware source links instead of broken
blob/v/... URLs.
unihan-db 0.20.1 (2026-03-21)¶
unihan-db 0.20.1 is a small maintenance release for the SQLAlchemy model layer. It keeps the polymorphic table mappings compatible with stricter Ruff linting without changing the database schema or query behavior.
Development¶
SQLAlchemy mapper configuration avoids builtin-shadowing lint (#357)¶
The polymorphic base models in Tables - unihan_db.tables now use SQLAlchemy’s string
attribute form for polymorphic_on, e.g. "polymorphic_on": "type". That
removes the bare class-scope reference to Python’s type builtin that triggered
Ruff A003.
The change deliberately avoids a schema rename, # noqa comments, and
project-wide lint suppression. SQLAlchemy resolves the string attribute name at
mapper configuration time, so the ORM behavior stays equivalent.
unihan-db 0.20.0 (2026-01-24)¶
unihan-db 0.20.0 refreshes the release pipeline and project command surface. It
moves package publishing to PyPI Trusted Publisher, adopts just as the
developer command runner, and follows the maintained unihan-etl 0.39 release
line.
Dependencies¶
Current unihan-etl 0.39 line (#354)¶
Minimum unihan-etl~=0.39.1 (was ~=0.38.0). This keeps unihan-db aligned
with the trusted-publishing release of the ETL package and its Unicode data
updates.
Development¶
PyPI Trusted Publisher release flow (#352)¶
Release publishing now uses PyPI Trusted Publisher instead of long-lived upload credentials. That reduces secret handling in CI and matches the release infrastructure used across the cihai and git-pull package family.
Makefile commands moved to just (#353)¶
Development commands moved from Makefile to justfile. The public docs now
refer to just test, just ruff, just mypy, and just build-docs as the
standard local workflow.
The documentation deployment path also moved to AWS OIDC authentication and the AWS CLI, removing another long-lived secret from the docs pipeline.
unihan-db 0.19.0 (2025-11-01)¶
unihan-db 0.19.0 updates the supported Python and ETL floors for the next maintenance cycle. It drops Python 3.9, adds Python 3.14 to the test matrix, and makes deferred annotations the project-wide default.
Breaking changes¶
Python 3.10 is now the minimum (#351)¶
Python 3.9 support was dropped after its upstream end-of-life window. The supported range is now Python 3.10 and newer, still below Python 4.
Current unihan-etl 0.38 line¶
Minimum unihan-etl~=0.38.0 (was ~=0.37.0). The dependency bump keeps the
database loader on the maintained ETL series.
Development¶
Python 3.14 enters the test matrix (#350)¶
CI now exercises Python 3.14 so compatibility issues are caught before the next stable Python release.
Deferred annotations across the codebase (#348)¶
Modules now use from __future__ import annotations, and Ruff’s pyupgrade
annotation rules are enabled. This reduces runtime annotation work and keeps
type syntax consistent across the project.
unihan-db 0.18.0 (2024-12-21)¶
unihan-db 0.18.0 is a maintenance-only compatibility release. It raises the
Python and unihan-etl floors and applies an aggressive automated Ruff cleanup
for the Python 3.9 era.
Breaking changes¶
Python 3.9 is now the minimum (#347)¶
Python 3.8 support was dropped after its October 2024 end-of-life date. This and later releases require Python 3.9 or newer.
Current unihan-etl 0.37 line (#347)¶
Minimum unihan-etl~=0.37.0. This dependency floor matches the Python 3.9
minimum used by the upstream ETL package.
Development¶
Ruff cleanup pass (#347)¶
The release applies Ruff v0.8-era automated lint and formatting fixes across the codebase. The intent was mechanical cleanup only, not a user-facing API change.
unihan-db 0.17.0 (2024-11-26)¶
unihan-db 0.17.0 moves the project tooling from Poetry-era packaging to the current uv and hatchling workflow. It is maintenance-only for library users, but it changes how contributors install, build, and lock the project.
Development¶
Project management moved from Poetry to uv (#344)¶
uv is now the package and environment manager for the project. Dependency groups and lockfile operations follow uv’s workflow instead of Poetry’s.
Build backend moved from Poetry to hatchling (#344)¶
The package build backend moved from Poetry to hatchling. This aligns unihan-db with the packaging backend used by sibling projects.
unihan-db 0.16.0 (2024-11-25)¶
unihan-db 0.16.0 updates the project for UNIHAN Revision 37. The release tracks the upstream data-format changes from Unicode and updates the ETL dependency that parses those fields.
Breaking changes¶
UNIHAN Revision 37 data changes (#345)¶
Minimum unihan-etl~=0.35.0 (was ~=0.34.0). Revision 37 adds support for
double and triple apostrophes in kRSUnicode simplified radicals.
Revision 37 also removes the old kFrequency field. The changelog intentionally
keeps this as a field-name note rather than an API link because the field is no
longer part of the current documented surface.
Documentation¶
Plain links are linkified¶
Links that previously rendered as bare text now become clickable in the docs.
unihan-db 0.15.0 (2024-04-01)¶
unihan-db 0.15.0 is the UNIHAN Revision 35 release. It also tightens the project’s linting and begins the package-management migration work that later settled on uv and hatchling.
Breaking changes¶
UNIHAN Revision 35 data changes (#330)¶
Minimum unihan-etl~=0.34.0 (was ~=0.27.0). Revision 35 brings the loader up
to the current Unicode data shape at the time of release.
Several older fields were removed upstream across Unicode 12.0.0, 13.0.0, and
15.1.0, including kHKSCS, kIRGDaiKanwaZiten, kKPS0, kKPS1, kKSC0,
kKSC1, kRSKangXi, kRSJapanese, kRSKanWa, kRSKorean, and
kDefaultSortKey. These are documented as historical field names, not linked
as current APIs.
Development¶
uv migration work begins (#344)¶
Project management starts moving from Poetry to uv. The complete contributor workflow consolidation appears in the later 0.17.0 maintenance release.
Ruff linting becomes stricter (#331, #332, #333)¶
The release adopts a broader Ruff rule set, moves formatting to ruff format,
and applies an automated cleanup pass. New rule families include
flake8-commas, flake8-builtins, and flake8-errmsg.
unihan-db 0.14.0 (2023-12-10)¶
unihan-db 0.14.0 fixes several import and model-conversion bugs and makes the example bootstrap path part of the test suite. It is the release that turned the examples and API docs into stronger regression coverage for real user workflows.
Fixes¶
as_dict() works on model rows again (#325)¶
The SQLAlchemy mapper event wiring for add_to_dict()
was fixed, restoring row.as_dict() on Unhn rows.
This makes the object-to-dictionary helper path usable again after the mapper
callback regression.
Importer field parsing fixes (#327)¶
import_char() received fixes for several structured
UNIHAN fields, including kXHC1983, kHanyuPinyin, kHanyuPinlu, and
kCCCII.
kRSUnicode double apostrophes parse correctly¶
Minimum unihan-etl~=0.30.1 (was ~=0.30.0post0). The upstream patch fixes
kRSUnicode records that include double apostrophes.
Documentation¶
API docs split into focused pages (#322, #328)¶
The API reference now has separate pages for bootstrap helpers, importer helpers, and SQLAlchemy tables. The release also adds docstrings across functions, methods, classes, and packages so those pages are more useful.
Development¶
Examples are now tested (#324)¶
The examples/ bootstrap script runs under pytest, covering the same sample
workflow shown in documentation: build the schema, import fixture data, and
query rows.
Documentation and CI linting tightened (#322)¶
Ruff gained pydocstyle coverage, and CodeQL moved from a custom advanced configuration file to GitHub’s default setup.
unihan-db 0.13.0 (2023-11-19)¶
unihan-db 0.13.0 focuses on packaging, formatting, and test configuration. It
moves pytest configuration into pyproject.toml, updates the ETL dependency,
and replaces Black formatting with Ruff’s formatter.
Dependencies¶
Current unihan-etl 0.29 line¶
Minimum unihan-etl~=0.29.0 (was ~=0.28.0). The dependency bump keeps the
database loader aligned with upstream parser fixes.
Development¶
Test and packaging configuration consolidated (#318)¶
pytest configuration now lives in pyproject.toml, and Python 3.12 is listed
in the package classifiers.
Development dependencies use Poetry groups¶
The project stops modeling development dependencies as extras and uses Poetry’s dependency-group structure instead, matching Poetry’s own guidance.
Formatting moved from Black to Ruff (#321)¶
ruff format replaces Black while preserving the same broad formatting style
and reducing the toolchain.
eradicate was removed from Ruff checks¶
The ERA rule family had too many false positives for this project and was
removed from the lint set.
unihan-db 0.12.0 (2023-07-18)¶
unihan-db 0.12.0 follows the upstream ETL fixture work and applies another code quality pass. The main user-facing impact is more reliable local tests around cached UNIHAN data.
Dependencies¶
unihan-etl fixture improvements (#317)¶
Minimum unihan-etl~=0.27.0 (was ~=0.25.0). The intermediate 0.26 line added
cached UNIHAN data support for the pytest plugin, and 0.27 fixed plugin data
locations.
Development¶
Ruff code quality fixes (#316)¶
The release applies another batch of Ruff-driven code quality cleanup.
unihan-db 0.11.0 (2023-07-01)¶
unihan-db 0.11.0 is a maintenance-only release. It tightens Ruff checks and follows the upstream ETL package to its next code-quality release.
Dependencies¶
Current unihan-etl 0.25 line¶
Minimum unihan-etl~=0.25.0 (was ~=0.24.0). The upstream release improves
its own Ruff strictness.
Development¶
Ruff checks are stricter (#315)¶
The project enables more Ruff code-quality rules for future changes.
unihan-db 0.10.0 (2023-06-24)¶
unihan-db 0.10.0 is a maintenance-only dependency refresh. It follows several
unihan-etl releases that improved configuration, typing, and regex-related
warnings.
Dependencies¶
Current unihan-etl 0.24 line (#314)¶
Minimum unihan-etl~=0.24.0 (was ~=0.19.1). The upstream path includes
configurable application directories for tests, dataclass-based configuration,
Python 3.7 removal, normalized typing imports, and the zhon 2.0 dependency
update.
unihan-db 0.9.0 (2023-06-10)¶
unihan-db 0.9.0 is the SQLAlchemy 2 and strict-typing modernization release. It raises the project above Python 3.7 and makes future ORM refactors safer.
Breaking changes¶
SQLAlchemy 2 is now required (#311)¶
Minimum SQLAlchemy>=2. The project now uses SQLAlchemy 2’s ORM and Core
typing improvements, including better mypy support when working with mapped
entities.
See SQLAlchemy’s 2.0 migration guide and What’s new in SQLAlchemy 2.0 for upstream migration details.
Python 3.8 is now the minimum (#309)¶
Python 3.7 support was dropped after its upstream end-of-life date. Python 3.8
also provides standard-library typing features such as TypedDict and
Protocol.
Development¶
Strict mypy checking (#311)¶
The project moved to strict mypy validation. This improves editor feedback and keeps ORM and importer refactors constrained by typed contracts.
unihan-db 0.8.0 (2023-05-13)¶
unihan-db 0.8.0 is a maintenance-only tooling release. It marks the final Python 3.7-compatible line and consolidates formatting, import sorting, and linting under Ruff.
Breaking changes¶
Final Python 3.7 release¶
This is the last release line intended for Python 3.7 users.
Development¶
Ruff replaces the older lint and format stack¶
Ruff now handles formatting, import sorting, and linting, replacing isort, flake8, and flake8 plugins for this project.
Poetry 1.5 is used for project management¶
The contributor toolchain follows Poetry 1.5 for this release line.
unihan-db 0.7.2 (2023-05-13)¶
unihan-db 0.7.2 is a small dependency release. It updates the ETL package for a typing fix in a shared helper.
Dependencies¶
unihan-etl 0.18.2¶
Minimum unihan-etl~=0.18.2 (was ~=0.18.1). The upstream release updates
typing for merge_dict.
unihan-db 0.7.1 (2022-10-01)¶
unihan-db 0.7.1 refreshes packaging and CI after the gp-libs documentation
migration. It also starts trusting the typed upstream unihan-etl package in
mypy.
Dependencies¶
unihan-etl 0.18.1¶
Minimum unihan-etl~=0.18.1. This upstream release adds the missing PyYAML
dependency.
Development¶
CI and Poetry updates (#305)¶
The release job is split so normal CI no longer pulls the PyPI upload image, CodeQL configuration is cleaned up, and Poetry moves from 1.1 to 1.2.
mypy now checks unihan-etl¶
The local mypy configuration stops ignoring unihan-etl, which is typed by
this release line.
unihan-db 0.7.0 (2022-09-11)¶
unihan-db 0.7.0 is a maintenance release for linting and documentation. It adds more static-analysis plugins and moves docs rendering onto the gp-libs Sphinx helper stack used by sibling projects.
Development¶
More flake8 checks (#300, #301)¶
The project adds flake8-bugbear and flake8-comprehensions to catch more
common Python mistakes.
Documentation¶
gp-libs Sphinx helpers (#303)¶
The changelog now renders with issue-linking support, the API table of contents uses the gp-libs autodoc fix, and documentation doctests run through the gp-libs docutils pytest integration.
unihan-db 0.6.0 (2022-08-21)¶
unihan-db 0.6.0 is an internal dependency refresh for the ETL layer. It pulls in
upstream cache controls, typing work, and documentation fixes from
unihan-etl.
Dependencies¶
unihan-etl 0.17.2¶
Minimum unihan-etl~=0.17.2 (was ~=0.16.0). The upstream release sequence
adds a cache/no-cache option, type annotations, follow-up annotation bug fixes,
and changelog issue-linking documentation updates.
unihan-db 0.5.0 (2022-08-20)¶
unihan-db 0.5.0 is a compatibility cleanup release across the cihai projects.
It removes the last Python 2 compatibility leftovers and relies on the shared
helper from unihan-etl.
Breaking changes¶
Python 2 compatibility cleanup (#299)¶
Python 2 support had already ended in 0.2.0. This release removes the duplicate
local merge_dict() helper and imports the maintained implementation from
unihan_etl instead.
Minimum unihan-etl~=0.15.0 is required to avoid old compatibility imports in
the dependency chain.
unihan-db 0.4.0 (2022-08-16)¶
unihan-db 0.4.0 modernizes the supported Python range and contributor checks. It adds Python 3.10 support, drops Python 3.6, and introduces doctest and mypy validation.
Breaking changes¶
Python support window updated (#292)¶
Python 3.6 support was dropped and Python 3.10 support was added.
Development¶
Static checks and doctests (#297)¶
The project adds initial doctest support, initial mypy validation, a
tmpdir-to-tmp_path test migration, and pyupgrade cleanup for Python 3.7+.
Poetry and CI cache updates (#274, #292, #297)¶
Poetry moves to the 1.1 line, CI uses the Poetry installer, and
actions/setup-python caching improves dependency install time for tests and
docs.
Documentation¶
Furo documentation theme¶
The docs move to the Furo theme.
unihan-db 0.3.0 (2021-06-15)¶
unihan-db 0.3.0 converts the project documentation to Markdown. This was a documentation-format release rather than a runtime feature release.
Documentation¶
Markdown documentation (#269)¶
The documentation source moved to Markdown.
unihan-db 0.2.0 (2021-06-15)¶
unihan-db 0.2.0 completes the Python 3 transition. It drops old Python versions, removes now-unneeded compatibility imports, and refreshes development metadata.
Breaking changes¶
Python 2.7 and 3.5 were dropped (#267)¶
The project no longer supports Python 2.7 or Python 3.5. Unused __future__
imports and old compatibility modesets were removed.
Development¶
Tooling metadata refresh¶
The release updates Black to 21.6b0 and refreshes trove classifiers for Python 3.9.
unihan-db 0.1.0 (2020-08-09)¶
unihan-db 0.1.0 is the first substantial package release. It introduces the modern packaging and documentation shape, speeds up initial data import, and adds the zero-config SQLite database path that remains central to the library.
What’s new¶
Zero-config SQLite database¶
The package can create a default SQLite database under the user’s XDG data directory via the application-directory helpers. This gives applications a working database path without requiring their own configuration first.
Faster initial import and broader field support¶
Initial data import was sped up, and support for more UNIHAN fields was added.
The release also raised the unihan-etl dependency to 0.9.5 and loosened
version constraints where appropriate.
Documentation¶
Documentation overhaul (#262)¶
The docs moved to a self-hosted site with icons, metadata, and publishing documentation.
Development¶
Poetry packaging and GitHub Actions (#261, #262, #263)¶
The project moved from Pipfile-based development to Poetry packaging, added
package project_urls, and replaced Travis CI with GitHub Actions.
unihan-db 0.0.0 (2017-05-29)¶
unihan-db 0.0.0 was the initial repository commit. It did not have a PyPI release.