Migration notes¶
Migration and deprecation notes for unihan-etl are here, see Changelog as well.
Welcome on board! 👋
📌 For safety, always pin the package
📖 Check the migration notes (You are here)
📣 If you feel something got deprecated and it interrupted you - past, present, or future - voice your opinion on the tracker.
We want to make unihan-etl fun, reliable, and useful for users.
API changes can be painful.
If we can do something to draw the sting, we’ll do it. We’re taking a balanced approach. That’s why these notes are here!
(Please pin the package. 🙏)
Next release¶
Notes on the upcoming release will be added here
unihan-etl 0.40.0 (2026-01-24)¶
CLI now requires explicit subcommand (#344)¶
The CLI has been redesigned with a subcommand architecture. Running unihan-etl without arguments now displays help instead of immediately running the ETL export process.
Quick migration¶
Before 0.39.1, running the bare command would download and export UNIHAN data:
$ unihan-etl
From 0.40.0+, use the export subcommand explicitly:
$ unihan-etl export
Command mapping¶
Before 0.39.1 |
From 0.39.1+ |
Description |
|---|---|---|
|
|
Export UNIHAN data |
|
|
Export as JSON |
|
|
Export specific fields |
New subcommands¶
The new architecture adds dedicated subcommands for common tasks:
List available UNIHAN fields:
$ unihan-etl fields
List available source files:
$ unihan-etl files
Download without exporting:
$ unihan-etl download
Search for a character:
$ unihan-etl search 好
Scripts and automation¶
If you have scripts that invoke unihan-etl directly, update them to use unihan-etl export:
Before:
#!/bin/bash
unihan-etl -F json -f kDefinition,kMandarin > unihan.json
After:
#!/bin/bash
unihan-etl export -F json -f kDefinition,kMandarin > unihan.json
Python API unchanged¶
The Python API remains unchanged. If you use unihan-etl as a library, no changes are needed:
>>> from unihan_etl.core import Packager
>>> from unihan_etl.options import Options
>>> packager = Packager(Options(fields=['kDefinition']))
>>> packager.download()
>>> data = packager.export()
unihan-etl 0.22.0 (2023-06-17)¶
Move unihan_etl.process to unihan_etl.core (#284)¶
Before 0.22.0:
from unihan_etl.process import Packager
From 0.22.0+:
>>> from unihan_etl.core import Packager
Options is now a dataclass object (#280)¶
A typed, autocomplete-friendly :obj:dataclasses.dataclass object is now used for the unihan_etl options object.
Before 0.22.0:
from unihan_etl.process import Packager
packager = Packager({
'fields': ['kDefinition']
})
From 0.22.0+ (also note above):
>>> from unihan_etl.core import Packager
>>> from unihan_etl.options import Options
>>> packager = Packager(Options(
... fields=['kDefinition']
... ))