# Bootstrap - unihan_db.bootstrap
Source: https://unihan-db.git-pull.com/api/bootstrap/

# Bootstrap - `unihan_db.bootstrap`

```{module} unihan_db

```

```{eval-rst}
.. automodule:: unihan_db.bootstrap
   :members:
   :undoc-members:
   :show-inheritance:
```

---

# Importing - unihan_db.importer
Source: https://unihan-db.git-pull.com/api/importer/

# Importing - `unihan_db.importer`

```{module} unihan_db

```

```{eval-rst}
.. automodule:: unihan_db.importer
   :members:
   :undoc-members:
   :show-inheritance:
```

---

# API Reference
Source: https://unihan-db.git-pull.com/api/

(api)=

# API Reference

```{module} unihan_db

```

:::{warning}
Be careful with these! APIs are **not** covered considered stable pre-1.0. They can break or be removed between minor versions!

If you need an internal API stabilized please [file an issue](https://github.com/cihai/unihan-db/issues).
:::

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Bootstrap
:link: bootstrap
:link-type: doc
Data download, session helpers, and ETL options.
:::

:::{grid-item-card} Importer
:link: importer
:link-type: doc
Transform normalized UNIHAN records into ORM objects.
:::

:::{grid-item-card} Tables
:link: tables
:link-type: doc
SQLAlchemy ORM models for UNIHAN data.
:::

::::

```{toctree}
:caption: API
:maxdepth: 1
:hidden:

bootstrap
importer
tables
```

---

# Tables - unihan_db.tables
Source: https://unihan-db.git-pull.com/api/tables/

# Tables - `unihan_db.tables`

```{module} unihan_db

```

```{eval-rst}
.. automodule:: unihan_db.tables
   :members:
   :undoc-members:
   :show-inheritance:
```

---

# Changelog
Source: https://unihan-db.git-pull.com/history/

(history)=

```{include} ../CHANGES

```

---

# unihan-db
Source: https://unihan-db.git-pull.com/

(index)=

# unihan-db

SQLAlchemy models for the [UNIHAN](https://www.unicode.org/charts/unihan.html) CJK character database.
unihan-db provides the schema and ORM layer. For the ETL pipeline, see [unihan-etl](https://unihan-etl.git-pull.com/). For end-user character lookups, see [cihai](https://cihai.git-pull.com/).

::::{grid} 1 2 3 3
:gutter: 2 2 3 3

:::{grid-item-card} Quickstart
:link: quickstart
:link-type: doc
Install and load UNIHAN data in 5 minutes.
:::

:::{grid-item-card} Models & Bootstrap
:link: api/index
:link-type: doc
Table models, bootstrap loader, and data importer.
:::

:::{grid-item-card} Contributing
:link: project/index
:link-type: doc
Development setup, code style, release process.
:::

::::

## Install

```console
$ pip install unihan-db
```

```console
$ uv add unihan-db
```

## At a glance

```python
from sqlalchemy import create_engine
from sqlalchemy.orm import Session

from unihan_db.bootstrap import bootstrap_unihan
from unihan_db.tables import Base, Unhn

engine = create_engine("sqlite:///unihan.db")

# Step 1: Create the schema
Base.metadata.create_all(engine)

# Step 2: Bootstrap data from the Unicode consortium
bootstrap_unihan(engine)

# Step 3: Query characters
with Session(engine) as session:
    char = session.query(Unhn).filter_by(char="\u597D").first()
    if char:
        print(char.char, char.ucn)
```

See [Quickstart](quickstart.md) for the full setup, including bootstrapping
data from the Unicode consortium.

```{toctree}
:hidden:

quickstart
api/index
project/index
history
GitHub <https://github.com/cihai/unihan-db>
```

---

# Code style
Source: https://unihan-db.git-pull.com/project/code-style/

(code-style)=

# Code style

## Linting and formatting

unihan-db uses [ruff](https://github.com/astral-sh/ruff) for linting and formatting.

Lint the codebase:

```console
$ uv run ruff check . --fix --show-fixes
```

Format the codebase:

```console
$ uv run ruff format .
```

## Type checking

[mypy](https://github.com/python/mypy) is configured in strict mode.

```console
$ uv run mypy src tests
```

## Conventions

- `from __future__ import annotations` in every module.
- Namespace imports for stdlib: `import typing as t`.
- NumPy-style docstrings.
- See `[tool.ruff]` in `pyproject.toml` for the full rule set.

---

# Contributing
Source: https://unihan-db.git-pull.com/project/contributing/

(contributing)=

# Contributing

## Development setup

Install the package in editable mode with dev dependencies:

```console
$ uv pip install --editable . -G dev
```

Run the tests:

```console
$ uv run pytest
```

## cihai contributing guide

unihan-db follows the cihai organization's contributing conventions.
See the [cihai contributing guide](https://cihai.git-pull.com/project/contributing/) for
full details on submitting patches, writing tests, and code review workflow.

---

# Project
Source: https://unihan-db.git-pull.com/project/

(project)=

# Project

Information for contributors and maintainers.

::::{grid} 1 1 2 2
:gutter: 2 2 3 3

:::{grid-item-card} Contributing
:link: contributing
:link-type: doc
Development setup and how to get involved.
:::

:::{grid-item-card} Code Style
:link: code-style
:link-type: doc
Ruff, mypy, and import conventions.
:::

:::{grid-item-card} Releasing
:link: releasing
:link-type: doc
Release checklist and version policy.
:::

::::

```{toctree}
:hidden:

contributing
code-style
releasing
```

---

# Releasing
Source: https://unihan-db.git-pull.com/project/releasing/

(releasing)=

# Releasing

## Version policy

unihan-db is pre-1.0. APIs may change between minor versions.

## Release checklist

1. Update `CHANGES` with the new version and today's date.

2. Bump the version in `src/unihan_db/__about__.py` and `pyproject.toml`.

3. Commit and tag:

   ```console
   $ git tag v0.XX.0
   ```

4. Push the tag:

   ```console
   $ git push --tags
   ```

## Publishing

Releases are published to PyPI via GitHub Actions using
[trusted publishing (OIDC)](https://docs.pypi.org/trusted-publishers/).
Pushing a version tag triggers the publish workflow automatically.

---

# Quickstart
Source: https://unihan-db.git-pull.com/quickstart/

(quickstart)=

# Quickstart

## Installation

Assure you have at least python **>= 3.7**.

Using [pip]:

```console
$ pip install unihan-db
```

Inside a project managed by [uv]:

```console
$ uv add unihan-db
```

Run code without installing by using [uvx]:

```console
$ uvx --from unihan-db python -c "import unihan_db.bootstrap as bootstrap; print(bootstrap.TABLE_NAME)"
```

Install into an isolated environment with [pipx] (exposes the `unihan-etl` CLI from dependencies):

```console
$ pipx install 'unihan-db' --include-deps
```

You can upgrade to the latest release with:

```console
$ pip install --upgrade unihan-db
```

(developmental-releases)=

### Developmental releases

New versions of unihan-db are published to PyPI as alpha, beta, or release candidates. In their
versions you will see notification like `a1`, `b1`, and `rc1`, respectively. `1.10.0b4` would mean
the 4th beta release of `1.10.0` before general availability.

- [pip]\:

  ```console
  $ pip install --upgrade --pre unihan-db
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@next 'unihan-db' --pip-args '\--pre' --include-deps --force
  // Provides the unihan-etl CLI from the dependency set.
  ```

- [uv]:

  ```console
  $ uv add unihan-db --prerelease allow
  ```

- [uvx]:

  ```console
  $ uvx --from 'unihan-db' --prerelease allow python -c "import unihan_db.bootstrap as bootstrap; print(bootstrap.TABLE_NAME)"
  ```

via trunk (can break easily):

- [pip]\:

  ```console
  $ pip install -e git+https://github.com/cihai/unihan-db.git#egg=unihan-db
  ```

- [uv]:

  ```console
  $ uv add git+https://github.com/cihai/unihan-db.git#egg=unihan-db
  ```

- [pipx]\:

  ```console
  $ pipx install --suffix=@master 'unihan-db @ git+https://github.com/cihai/unihan-db.git@master' --include-deps --force
  ```

[pip]: https://pip.pypa.io/en/stable/
[pipx]: https://pypa.github.io/pipx/docs/
[uv]: https://docs.astral.sh/uv/
[uvx]: https://docs.astral.sh/uv/guides/tools/

## Usage

```{literalinclude} ../examples/01_bootstrap.py
:language: python
```

## Pythonics

:::{seealso}

{ref}`unihan-db's API documentation <api>`.

---