Quickstart¶

cihai is designed to work out-of-the-box without configuration.

Installation¶

$ pip install --user cihai

First lookup¶

Most projects start with cihai.core.Cihai, bootstrap the unihan dataset once, then query it with lookup_char() or reverse_char().

This script is also tested by tests/test_examples.py.

#!/usr/bin/env python
"""Demonstrate basic case of Cihai's python API with UNIHAN."""

from __future__ import annotations

import logging

from cihai.core import Cihai

log = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO, format="%(message)s")


def run(unihan_options: dict[str, object] | None = None) -> None:
    """Initialize Cihai with UNIHAN (automatically initialized implicitly)."""
    if unihan_options is None:
        unihan_options = {}
    c = Cihai()

    if not c.unihan.is_bootstrapped:  # download and install Unihan to db
        c.unihan.bootstrap(unihan_options)

    query = c.unihan.lookup_char("㐭")
    glyph = query.first()

    assert glyph is not None
    log.info(f"lookup for 㐭: {glyph.kDefinition}")

    query = c.unihan.reverse_char("granary")
    log.info(
        'matches for "granary": {} '.format(", ".join([glph.char for glph in query])),
    )


if __name__ == "__main__":
    run()

Developmental releases¶

New versions of cihai are published to PyPI as alpha, beta, or release candidates. Identifiers like a1, b1, and rc1 mark alpha, beta, and release candidates, respectively.

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__)"

Configuration¶

By default, cihai requires no configuration. The defaults file locations are XDG Base Directory for the users’ system, as well as SQLite to store, seek, and retrieve data.

You can override cihai’s default storage and file directories via a config file.

The default configuration is at cihai.constants.DEFAULT_CONFIG.

Database configuration accepts any SQLAlchemy Database URLs. If you’re using a DB other than SQLite, such as Postgres, be sure to install the requisite driver, such as psycopg.

Advanced Config¶

cihai is designed to allow you to incrementally override settings to your liking.

Internally, the config is parsed through cihai.config.expand_config(). This will replace environment variables, XDG variables and tildes. You can also enter absolute paths.

Environmental variables require a dollar sign added to them, e.g. ${ENVVAR}. XDG variables such as user_cache_dir, user_config_dir, user_data_dir, user_log_dir, site_config_dir, site_data_dir are done via curly brackets only. E.g. {site_config_dir}. Tildes are just replaced.

database:
  url: '${DATABASE_URL}'
dirs:
  data: '{user_data_dir}/mydata'
  cache: '~/cache/cihai'
  logs: '$ENVVAR/logs'

In the example above, Heroku’s DATABASE_URL is replaced as an environmental variable. The XDG variable for user_data_dir is combined with mydata/, which makes the data stored deeper. The environmental variable $ENVVAR is also replaced.

You may point to a custom config with cihai.core.Cihai.from_file().

You can also override bootstrapping settings. Pass a unihan_options dictionary to bootstrap(); the dictionary is passed to unihan-etl’s unihan_etl.core.Packager option param, which is then merged on top of unihan-etl’s default settings:

The source value can also point to a local path. You can use fields or input_files to narrow the imported UNIHAN data.

unihan_options:
   source: 'https://custom-mirror.com/Unihan.zip'
   work_dir: '/path/to/unzip/files'
   zip_path: '/path/to/store/Unihan.zip'
   fields: ['kDefinition']
   input_files: ['Unihan_Readings.txt']

See Configure Storage for a tested configuration-file example.