Changelog

You can test the unpublished version of cihai before it’s released. See developmental releases.

pip:

$ pip install --user --upgrade --pre cihai

pipx:

$ pipx run --pip-args '\--pre' --spec 'cihai' python -c "import cihai; print(cihai.__version__)"

uv:

$ uv add cihai --prerelease allow

uvx:

$ uvx --from 'cihai' --prerelease allow python -c "import cihai; print(cihai.__version__)"

cihai 0.37.x (unreleased)

Notes on the upcoming release will go here.

cihai 0.37.x is a documentation and data-dependency refresh for the library. The cihai.core.Cihai runtime API stays stable, while the docs move onto the shared gp-sphinx platform, gain a clearer Library Skeleton structure, and fix several long-standing Sphinx warnings. The release also accepts the newer unihan-etl line used by the current UNIHAN tooling.

Breaking changes

Minimum unihan-etl>=0.41.0 (was >=0.39.1) (#393)

cihai now depends on unihan-etl~=0.41.0, up from the 0.39.1 line. No cihai code changes were needed for the bump: the unihan-etl 0.40.0 CLI subcommand redesign and 0.41.0 documentation updates do not change the programmatic API cihai uses to bootstrap UNIHAN data.

See the upstream unihan-etl 0.41.0 release notes for the CLI documentation improvements that shipped there.

What’s new

Documentation reorganized around everyday library tasks (#394)

The docs site now follows the Library Skeleton pattern: the homepage is a real entry point instead of a README dump, and the main routes are grouped around quickstart, topics, API reference, datasets, internals, and project documentation. Readers looking for lookup examples, configuration, extension points, or release workflow no longer need to infer the site structure from a flat list of pages.

The restructure also keeps archival design notes under Design and Planning, moves user-oriented guides under Topics, and separates unstable internals under Internals. Old documentation URLs are redirected where the page move would otherwise break external links.

Smoother docs frontend for repeated navigation (#392)

The docs frontend received the typography and page-load improvements first proven in tmuxp: self-hosted IBM Plex fonts, preload hints, fallback font metrics, fixed image and badge dimensions, and SPA-like navigation for internal links. The result is a calmer docs site with less layout shift, fewer full-page reloads, and smoother transitions between pages.

The local implementation later moved into the shared gp-sphinx package stack, so cihai benefits from the same frontend work without continuing to carry the one-off Sphinx extension, templates, and static assets in this repository.

API reference gets structured autodoc presentation (#396)

The API reference now uses the gp-sphinx autodoc presentation layer for card-style signatures, type and modifier badges, richer Python-object cross-references, and more legible parameter and field-list rendering. Pages such as Core - cihai.core, Extending - cihai.extend, and UNIHAN - cihai.data.unihan are easier to scan while still linking to the same underlying public API objects.

This release enables sphinx-autodoc-api-style explicitly and keeps the docs dependency pins aligned with the gp-sphinx workspace releases that supply the shared badge, layout, typehint, font, and theme surfaces.

Fixes

Sphinx warning cleanup for public docs and API docstrings (#397)

Several pre-existing docs issues are fixed so the generated site loses broken links and noisy warnings that obscured real failures. The cihai.core.Cihai docstring no longer carries numeric footnote references that Napoleon splits across fragments, no longer embeds a literalinclude path that resolves from the wrong page, and no longer duplicates the documented config attribute.

The docs tree also routes the internal API landing page through Internal API, resolves CJK through the glossary domain, repairs the internationalization link in the glossary, and aligns the cihai.conversion label with the module name used by the public docs.

Documentation

Shared gp-sphinx platform replaces local docs plumbing (#395)

cihai now builds docs through the published gp-sphinx package stack. docs/conf.py delegates common theme, extension, font, copybutton, redirection, and linkcode behavior to merge_sphinx_config(), and the repository no longer carries the local sphinx_fonts extension, custom Furo templates, project sidebar JavaScript, or tests for those removed docs-only modules.

The migration makes cihai’s docs configuration smaller and keeps the site aligned with the same documentation platform used by sibling projects.

gp-sphinx docs stack refreshed through 0.0.1a17 (#398, #399)

The docs dependency stack was updated across the gp-sphinx 0.0.1a8 and 0.0.1a16 release lines, then pinned to the current 0.0.1a17 workspace packages. The important user-visible pieces are the argparse domain and namespaced CSS cleanup from 0.0.1a8, plus the gp-furo-theme and sphinx-vite-builder consolidation from 0.0.1a16.

gp-furo-theme is a Tailwind v4 port of Furo, and sphinx-vite-builder owns the Vite asset pipeline so published wheels ship with the static theme assets already built. The final 0.0.1a17 pin picks up the expanded default font preloads for headings, italic body text, and bold inline code.

cihai 0.36.1 (2026-01-24)

cihai 0.36.1 is a maintenance release for release infrastructure and the UNIHAN dependency line. It keeps the library API steady while moving PyPI publishing to Trusted Publisher and keeping the packaged UNIHAN tooling current.

Breaking changes

Minimum unihan-etl>=0.39.1 (was >=0.38.0) (#389)

The unihan-etl dependency moved from 0.38.0 to 0.39.1. Downstream projects that pin cihai and unihan-etl together should allow the newer compatible release line.

Development

Makefile tasks moved to just (#388)

Development and documentation commands moved from Makefile recipes to justfile recipes. Contributor documentation now points to just commands for tests, linting, typing, and docs builds.

PyPI and docs publishing use identity-based credentials (#387)

PyPI publishing migrated to Trusted Publisher, and docs deployment moved to AWS OIDC authentication with the AWS CLI. Release jobs no longer need long-lived upload credentials for those paths.

cihai 0.36.0 (2025-11-01)

cihai 0.36.0 raises the supported Python floor and keeps the project ready for newer Python runtimes. It also refreshes UNIHAN compatibility through unihan-etl and updates typing style for deferred annotation evaluation.

Breaking changes

Python 3.10 is now the minimum (#386)

Python 3.9 support was dropped. The new minimum supported Python version is 3.10, matching Python 3.9’s end-of-life status on October 31, 2025.

See also:

Minimum unihan-etl>=0.38.0 (was >=0.37.0)

The UNIHAN dependency line moved from 0.37.0 to 0.38.0.

Development

Python 3.14 added to the test matrix (#385)

The project test matrix now includes Python 3.14 so compatibility issues are caught before users reach that runtime.

Deferred annotations adopted across the codebase (#383)

Modules now use from __future__ import annotations to avoid eager annotation resolution at runtime. Ruff rules for PEP 585 and PEP 604 typing syntax were enabled at the same time so future annotations stay modern and consistent.

See PEP 563 for the deferred annotation behavior this prepares for.

cihai 0.35.0 (2024-12-21)

cihai 0.35.0 is a maintenance release for the supported Python and UNIHAN dependency floors. No user-facing lookup features or bug fixes ship in this release.

Breaking changes

Python 3.9 is now the minimum (#382)

Python 3.8 support was dropped after its October 7, 2024 end-of-life. The minimum supported Python version for cihai became 3.9.

Minimum unihan-etl>=0.37.0 (#382)

The unihan-etl dependency moved to the 0.37.0 line, matching the new Python 3.9 floor.

Development

Ruff applied broad automated cleanup (#382)

The codebase was reformatted and lint-fixed with Ruff 0.8.4, including preview and unsafe automated fixes for the Python 3.9 code line.

$ ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes

$ ruff format .

cihai 0.34.0 (2024-11-26)

cihai 0.34.0 modernizes packaging and project management. Poetry was replaced by uv for day-to-day dependency management, and hatchling became the build backend.

Breaking changes

Project management moved from Poetry to uv (#380)

uv is the project and package manager used by the repository. Development documentation and local commands were updated around uv workflows.

Build backend moved from Poetry to hatchling (#380)

The package build system moved from poetry to hatchling, following the modern Python packaging split between project management and build backend.

Development

UNIHAN Revision 37 data cleanup

kFrequency was removed following UNIHAN Revision 37.

See also:

Ruff f-string cleanup (#371)

Ruff 0.4.2 automated more string-formatting cleanups across the codebase.

cihai 0.33.0 (2024-04-06)

cihai 0.33.0 is a maintenance-only release for documentation and lint cleanup. It does not add lookup features or bug fixes.

Documentation

Links that were previously plain text in the docs are now automatically linkified.

Development

Ruff automated cleanup (#369)

Ruff 0.3.4 was applied with broad automated fixes, including preview and unsafe fixes, followed by formatting.

cihai 0.32.0 (2024-04-01)

cihai 0.32.0 is a maintenance-only release for dependency updates and Ruff command changes. It does not add lookup features or bug fixes.

Development

The release updates unihan-etl from 0.30.1 to 0.34.0, Poetry from 1.7.1 to 1.8.2, and Ruff from 0.2.2 to 0.3.0. CI now uses ruff check . for linting.

See the Ruff 0.3.0 changelog for the upstream linting changes.

cihai 0.31.0 (2024-02-09)

cihai 0.31.0 brings the packaged UNIHAN data line forward to Unicode 15.1.0 and keeps the project lint rules stricter. It also splits the API reference into smaller pages for easier browsing.

What’s new

UNIHAN compatibility updated to 15.1.0 (#366)

UNIHAN compatibility moved from 11.0.0 to 15.1.0, released September 1, 2023 as revision 35. The unihan-etl dependency also moved from 0.29.0 through 0.30.1 to 0.33.1, including the kRSUnicode double-apostrophe fix.

Documentation

API reference split into multiple pages (#363)

The API docs now use separate pages by module instead of one large API document.

Development

Ruff lint coverage strengthened (#367)

Ruff now enforces additional rule families from flake8-commas, flake8-builtins, and flake8-errmsg.

cihai 0.30.0 (2023-12-09)

cihai 0.30.0 fixes two conversion helper failures and expands documentation coverage for public objects. It also simplifies CodeQL configuration.

Fixes

Documentation

Functions, methods, classes, and packages received docstrings so the API reference is more complete (#361).

Development

CodeQL moved from an advanced configuration file to GitHub’s default, and Ruff gained the pydocstyle rule set (#361).

cihai 0.29.0 (2023-11-19)

cihai 0.29.0 is a packaging and development-tooling maintenance release. It does not add lookup features or library bug fixes.

Packaging

Pytest configuration moved into pyproject.toml (#357), Python 3.12 Trove classifiers were added, and development dependencies were moved from extras into Poetry dependency groups to match Poetry’s supported model.

GitHub Actions dependencies were refreshed to reduce workflow warnings, including dorny/paths-filter from 2.7.0 to 2.11.1.

Development

unihan-etl moved from 0.28.0 to 0.29.0, Poetry moved from 1.6.1 to 1.7.0, and formatting moved from Black to ruff format (#360). The Ruff ERA / eradicate rule family was removed because it produced too many false positives to trust.

cihai 0.28.0 (2023-07-22)

cihai 0.28.0 is a maintenance-only release. It updates unihan-etl from 0.27.0 to 0.28.0, picking up pytest fixture renamings without adding cihai lookup features or bug fixes.

cihai 0.27.0 (2023-07-18)

cihai 0.27.0 fixes test failures caused by upstream fixture movement and refreshes the UNIHAN dependency line.

Fixes

The CI test breakage was resolved (#355). unihan-etl moved from 0.25.0 through 0.26.0 to 0.27.0, bringing the pytest plugin with cached UNIHAN data and later fixture fixes.

Development

Ruff-based code quality cleanup continued (#354).

cihai 0.26.0 (2023-07-01)

cihai 0.26.0 is a maintenance-only release. Ruff gained additional rules and related fixes (#353), and unihan-etl moved from 0.24.0 to 0.25.0 for typing-related updates.

cihai 0.25.0 (2023-06-24)

cihai 0.25.0 is a maintenance-only release. unihan-etl moved from 0.23.1 to 0.24.0 (#352), which updates the zhon subdependency from 1.1.5 to 2.0.0 and fixes pytest warnings related to regular expressions.

See the zhon 2.0 release notes.

cihai 0.24.0 (2023-06-24)

cihai 0.24.0 is a maintenance-only release. unihan-etl moved from 0.22.1 to 0.23.0 (#351), adding configurable application directories that are especially useful for test isolation.

cihai 0.23.0 (2023-06-19)

cihai 0.23.0 is a maintenance-only release. unihan-etl moved from 0.21.1 to 0.22.1 (#348), bringing dataclass-based configuration in the upstream data tooling.

cihai 0.22.1 (2023-06-18)

cihai 0.22.1 fixes the upstream UNIHAN output file extension issue by moving unihan-etl from 0.21.0 to 0.21.1.

cihai 0.22.0 (2023-06-18)

cihai 0.22.0 is a maintenance-only release for upstream internal updates. unihan-etl moved from 0.19.2 to 0.20.0, dropping Python 3.7 and normalizing typing imports, then to 0.21.0, which moved paths to pathlib.

cihai 0.21.0 (2023-06-03)

cihai 0.21.0 moves the database layer to SQLAlchemy 2.0. It also continues the test-suite migration from legacy pytest path objects to standard library paths.

Breaking changes

SQLAlchemy 2.0 is now required (#340)

Downstream packages now need SQLAlchemy 2.0 at minimum. The upgrade brings built-in typing improvements for mypy and allows SQLAlchemy Core APIs to be used against ORM entities.

See also:

Development

Tests moved from pytest’s tmp_dir / py.path.local style to tmp_path / pathlib.Path (#346). Unnecessary use of typing_extensions.TypedDict was removed where the standard library type is available; NotRequired still uses typing_extensions until the minimum Python version supports PEP 655 directly.

cihai 0.20.0 (2023-05-29)

cihai 0.20.0 drops Python 3.7 and tightens the type-checking baseline for future maintenance.

Breaking changes

Python 3.7 support removed (#343)

Python 3.7 support was dropped ahead of its June 27, 2023 end-of-life. Python 3.8 includes standard-library support for TypedDict and Protocol, reducing the need for compatibility imports.

Development

Strict mypy typing adopted (#324)

The project moved to strict mypy typing. The goal is safer future refactoring and better downstream editor completions.

See mypy --strict.

cihai 0.19.0 (2023-05-28)

cihai 0.19.0 is a maintenance-only release that consolidates linting and formatting around Ruff.

Development

Ruff replaces isort, flake8, and related flake8 plugins for formatting, import sorting, and linting. The release also updates Poetry from 1.4.0 to 1.5.0 and unihan-etl from 0.18.2 to 0.19.1.

See Ruff and the Poetry 1.5.0 release notes.

cihai 0.18.3 (2023-05-13)

cihai 0.18.3 is a maintenance-only release. It bumps unihan-etl from 0.18.1 to 0.18.2 for a merge_dict typing update and applies flake8 cleanup.

cihai 0.18.2 (2022-10-02)

cihai 0.18.2 is a maintenance-only release. It bumps unihan-etl from 0.18.0 to 0.18.1 for packaging updates and temporarily pins importlib_metadata<5 while internal dependency compatibility is settled.

cihai 0.18.1 (2022-10-01)

cihai 0.18.1 fixes packaging by adding the missing PyYAML dependency.

cihai 0.18.0 (2022-10-01)

cihai 0.18.0 removes the old kaptan configuration path.

Breaking changes

The kaptan dependency was removed (#334), and .ini configuration files are no longer supported. Use YAML or JSON configuration files with cihai.core.Cihai.from_file().

cihai 0.17.1 (2022-10-01)

cihai 0.17.1 is an infrastructure release. CI became faster by moving release publishing to a separate job, avoiding the PyPI upload image on normal runs, and cleaning up CodeQL configuration (#333). Poetry also moved from the 1.1.x line to the 1.2.x line.

cihai 0.17.0 (2022-09-11)

cihai 0.17.0 is a maintenance-only release for repository layout, linting, and documentation infrastructure.

Development

The package moved to a src/ layout (#331), and the lint stack gained flake8-bugbear (#328) and flake8-comprehensions (#329).

Documentation

The changelog is rendered with linkify_issues (#330, superseding #327). The docs also fixed table-of-contents rendering with sphinx_toctree_autodoc_fix and began testing documentation doctests with pytest_doctest_docutils, built on doctest_docutils.

cihai 0.16.0 (2022-08-21)

cihai 0.16.0 is internal maintenance for type annotations across the cihai projects. It updates unihan-etl from 0.16.0 to 0.17.2, covering --no-cache / cache support, strict mypy typing, fixes from the first annotation pass, and docs changelog issue-linking updates.

cihai 0.15.0 (2022-08-20)

cihai 0.15.0 changes how the command-line application is installed.

Breaking changes

The CLI is again installed through the separate cihai-cli package, rather than through the cihai[cli] extra. This makes deploying and pinning cihai and cihai-cli less laborious.

Before cihai 0.15.0:

$ pip install cihai[cli]

After cihai 0.15.0:

$ pip install cihai-cli

See cihai #326 and cihai-cli #279.

cihai 0.14.1 (2022-08-20)

cihai 0.14.1 bumps the cihai-cli dependency to 0.10.0. The release keeps the library and CLI paired while leaving room to revisit whether the library package should become more explicitly lib-only later.

cihai 0.14.0 (2022-08-20)

cihai 0.14.0 removes the old Python 2 compatibility layer.

Breaking changes

Python 2 compatibility modules and imports were removed. Python 2.x had already been officially dropped in cihai 0.11.0 via #325; this release removes the leftover compatibility code paths.

import_string() and ImportStringError were updated from Werkzeug, merge_dict now comes from unihan_etl, and unihan-etl>=0.15.0 is required to avoid future compatibility imports from that dependency.

cihai 0.13.0 (2022-08-16)

cihai 0.13.0 updates Python version compatibility and adds the first round of static typing and doctest infrastructure.

Compatibility

Python 3.10 support was added and Python 3.6 support was removed (#317).

Development

Poetry moved to the 1.1 line, CI was updated to use the Poetry 1.1.12 installer path, and dependency caching improved through actions/setup-python (#296, #317, #323). Initial doctest support and initial mypy validation were added (#323), and obsolete pre-commit configuration was removed.

Documentation

The docs gained development workflow docs that apply across the cihai project family.

cihai 0.12.0 (2021-06-16)

cihai 0.12.0 converts the changelog and related release notes to Markdown (#291).

cihai 0.11.1 (2021-06-15)

cihai 0.11.1 fixes the cihai-cli and SQLAlchemy dependency versions.

cihai 0.11.0 (2021-06-15)

cihai 0.11.0 removes the legacy Python 2.7 and Python 3.5 support line. It updates Black to 21.6b0, updates Trove classifiers for Python 3.9, moves unihan-etl to 0.12.0, removes unused modesets, and drops compatibility imports that only existed for the removed Python versions (#288).

cihai 0.10.0 (2020-08-09)

cihai 0.10.0 modernizes packaging, docs hosting, CI, and plugin-system infrastructure.

Packaging

The cihai-cli version constraint was removed to satisfy pip’s 2020 resolver behavior. See pip’s resolver documentation.

Packaging and publishing moved to Poetry (#285), following the earlier move from Pipfile to Poetry (#283).

Documentation and CI

The docs are self-hosted with updated metadata and icons (#284), Travis CI moved to GitHub Actions (#284), and Makefiles were overhauled. Plugin and extension-system infrastructure also improved.

cihai 0.9.0p1 (2019-08-18)

cihai 0.9.0p1 repins the requirements/cli.txt dependency again.

cihai 0.9.0p0 (2019-08-18)

cihai 0.9.0p0 repins the requirements/cli.txt dependency.

cihai 0.9.0 (2019-08-18)

cihai 0.9.0 is the final release of the 0.9 series. From this release line, cihai-cli is installed with the cihai[cli] extra. The prerelease entries below carry the detailed migration and refactor notes.

cihai 0.9.0a4 (2019-08-17)

cihai 0.9.0a4 adds project_urls, keeps collections imports compatible across Python 2 and 3, updates pytest to 5.1.0, and applies linting fixes.

cihai 0.9.0a (2018-09-07)

cihai 0.9.0a is a major internal refactor of the package layout and UNIHAN dataset model.

What’s new

The package now exposes cihai.__version__ without requiring access to __about__, source links appear on API pages, and __github__ is available in package metadata. DEFAULT_CONFIG moved to constants.py, the UNIHAN module moved into cihai/unihan/, and UNIHAN is treated as a dataset.

Cihai() automatically includes the UNIHAN dataset by default. Historical code could opt out with Cihai(unihan=False). Examples are tested so API-breaking changes are caught when documentation examples need updates.

Development

The release updates pytest to 3.8.0, Sphinx to 1.7.9, and renames older internal modules from _util to _utils and _conf to _config.

cihai 0.8.1 (2018-07-21)

cihai 0.8.1 loosens kaptan and related dependency constraints to avoid downstream entanglement with PyYAML and cihai-cli. It also updates Sphinx, releases, and the Pipfile lock state.

cihai 0.8.0 (2018-06-23)

cihai 0.8.0 refreshes the UNIHAN data toolchain and modernizes the documentation style.

Development

unihan-etl moved from 0.9.0 to 0.9.5. Base dependencies moved to SQLAlchemy 1.2.8 and kaptan 0.5.9, while developer dependencies such as isort, flake8, vulture, Sphinx, alagitpull, releases, and pytest were updated.

Documentation and licensing

Documentation moved to NumPy-style docstrings with sphinxcontrib-napoleon. The license changed from New BSD to MIT, and all future commits and contributions are licensed to the cihai software foundation, including commits by Tony Narlock.

cihai 0.7.4 (2017-05-26)

cihai 0.7.4 bumps unihan-tabular from 0.8.1 to unihan-etl 0.9.0.

cihai 0.7.3 (2017-05-20)

cihai 0.7.3 updates unihan-tabular to 0.7.3, adding kJa and fixing kCompatibilityVariant.

cihai 0.7.2 (2017-05-20)

cihai 0.7.2 adds support for character lookup and reverse lookup, with code examples in the historical examples/ directory.

cihai 0.7.1 (2017-05-20)

cihai 0.7.1 updates the README and removes the unused CLI module.

cihai 0.7.0 (2017-05-20)

cihai 0.7.0 splits CLI functionality into cihai-cli and updates package classifiers and metadata.

cihai 0.6.1 (2017-05-17)

cihai 0.6.1 adds initial reverse-lookup support and emits CLI output as basic YAML.

cihai 0.6.0 (2017-05-17)

cihai 0.6.0 adds logging configuration support through options and the CLI, and converts print-based diagnostics to logging.

cihai 0.5.1 (2017-05-17)

cihai 0.5.1 fixes the Python 2 CLI path.

cihai 0.5.0 (2017-05-17)

cihai 0.5.0 removes the singleton metadata object and automatically bootstraps UNIHAN on first use.

cihai 0.4.2 (2017-05-16)

cihai 0.4.2 loads default configuration from an internal dictionary.

cihai 0.4.1 (2017-05-16)

cihai 0.4.1 updates MANIFEST.in.

cihai 0.4.0 (2017-05-16)

cihai 0.4.0 is the first release with the core database-backed lookup shape that later releases build on.

What’s new

Database schemas are reflected automatically and exposed through the main cihai object. The CLI uses click, cihai info <char> supports initial character lookups, and UNIHAN bootstraps into cihai by default through the historical unihan-tabular project (#3).

Development

The release drops Python 3.3 and 3.4 support (#4), adds initial XDG base-directory support (#4), moves tests to pytest functions and fixtures, removes an unused UNIHAN test module, sorts imports, moves the default config from cihai/config.yml to conf/default.yml, splits configuration functionality into cihai.conf, expands configuration variables for replacements, tildes, environment variables, and XDG paths, and documents CLI usage with sphinx-argparse.

cihai 0.3.0 (2017-04-16)

cihai 0.3.0 reboots the project under the cihai name.

What’s new

The package metadata moved to __about__.py, README links were updated to HTTPS, Travis tested through Python 3.6, and PyPy support was added. The release also modernized the root and docs Makefiles, moved requirements into the requirements/ folder, updated the Sphinx theme to Alabaster with a new logo, enabled Coveralls, locked base dependencies, added development dependencies for isort, vulture, and flake8, and renamed cihai.cihai to cihai.core.