# Migration notes

Migration and deprecation notes for unihan-etl are here, see {ref}`history` as well.

```{admonition} Welcome on board! 👋
1. 📌 For safety, **always** pin the package
2. 📖 Check the migration notes _(You are here)_
3. 📣 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. 🙏)

   [tracker]: https://github.com/cihai/unihan-etl/discussions
```

## Next release

_Notes on the upcoming release will be added here_

<!-- Maintainers, insert migration notes for the next release 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:

```console
$ unihan-etl
```

From 0.40.0+, use the `export` subcommand explicitly:

```console
$ unihan-etl export
```

#### Command mapping

| Before 0.39.1 | From 0.39.1+ | Description |
|---------------|--------------|-------------|
| `unihan-etl` | `unihan-etl export` | Export UNIHAN data |
| `unihan-etl -F json` | `unihan-etl export -F json` | Export as JSON |
| `unihan-etl -f kDefinition` | `unihan-etl export -f kDefinition` | Export specific fields |

#### New subcommands

The new architecture adds dedicated subcommands for common tasks:

List available UNIHAN fields:

```console
$ unihan-etl fields
```

List available source files:

```console
$ unihan-etl files
```

Download without exporting:

```console
$ unihan-etl download
```

Search for a character:

```console
$ unihan-etl search 好
```

#### Scripts and automation

If you have scripts that invoke `unihan-etl` directly, update them to use `unihan-etl export`:

Before:

```bash
#!/bin/bash
unihan-etl -F json -f kDefinition,kMandarin > unihan.json
```

After:

```bash
#!/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:

```python
>>> 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:

```python
from unihan_etl.process import Packager
```

From 0.22.0+:

```python
>>> 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:

```python
from unihan_etl.process import Packager

packager = Packager({
    'fields': ['kDefinition']
})
```

From 0.22.0+ (also note above):

```python
>>> from unihan_etl.core import Packager
>>> from unihan_etl.options import Options
>>> packager = Packager(Options(
...     fields=['kDefinition']
... ))
```

<!--
# vim: set filetype=markdown:
-->
