Typings

These typed dictionaries describe cihai’s public configuration shape. They are useful when annotating code that builds or validates a cihai.types.ConfigDict.

Typings for cihai.

This is meant to be imported from inside typing.TYPE_CHECKING so it does not require typing_extensions at runtime:

>>> from typing import TYPE_CHECKING
>>> if TYPE_CHECKING:
...     from .types import DirsConfigDict
>>> def my_fn(dir_config: "DirsConfigDict") -> None:
...     pass

class cihai.types.RawPluginConfigDict

class

class

class cihai.types.RawPluginConfigDict

Bases: TypedDict

Barebones plugin config dictionary.

class cihai.types.RawDirsConfigDict

class

class

class cihai.types.RawDirsConfigDict

Bases: TypedDict

Raw directory config dictionary.

Values may be str templates holding XDG placeholders such as {user_cache_dir}, environment variables, or a tilde; cihai.config.expand_config() resolves them to pathlib.Path.

cache

attribute

attribute

cache

Cache directory, defaulting to the XDG user cache directory.

Type:

str | pathlib.Path

log

attribute

attribute

log

Log directory, defaulting to the XDG user log directory.

Type:

str | pathlib.Path

data

attribute

attribute

data

Persistent data directory, home to the SQLite database in the default config, defaulting to the XDG user data directory.

Type:

str | pathlib.Path

class cihai.types.DirsConfigDict

class

class

class cihai.types.DirsConfigDict

Bases: TypedDict

Directory config dictionary.

Resolved counterpart of RawDirsConfigDict: templates, environment variables, and tildes are already expanded.

cache

attribute

attribute

cache

Cache directory, defaulting to the XDG user cache directory.

Type:

pathlib.Path

log

attribute

attribute

log

Log directory, defaulting to the XDG user log directory.

Type:

pathlib.Path

data

attribute

attribute

data

Persistent data directory, home to the SQLite database in the default config, defaulting to the XDG user data directory.

Type:

pathlib.Path

class cihai.types.RawDatabaseConfigDict

class

class

class cihai.types.RawDatabaseConfigDict

Bases: TypedDict

Raw database config dictionary.

url

attribute

attribute

url

SQLAlchemy database URL, handed to sqlalchemy.create_engine() by cihai.db.Database. Before cihai.config.expand_config() runs it may carry XDG placeholders, as the default sqlite:///{user_data_dir}/cihai.db does.

Type:

str

class cihai.types.RawConfigDict

class

class

class cihai.types.RawConfigDict

Bases: TypedDict

Raw, unresolved configuration dictionary.

Shape a caller passes to cihai.core.Cihai, before it is merged over cihai.constants.DEFAULT_CONFIG and its templates expanded.

plugins

attribute

attribute

plugins

Dataset plugins, keyed by the namespace of the dataset they extend. Omitted when no dataset carries plugins.

Type:

NotRequired[dict[str, RawPluginConfigDict]]

datasets

attribute

attribute

datasets

Datasets to bootstrap, keyed by the attribute namespace they are bound to on the cihai.core.Cihai object. A value is either a dotted import path resolved through cihai.utils.import_string() or a cihai.extend.Dataset subclass.

Type:

dict[str, str | Dataset]

database

attribute

attribute

database

Database connection settings.

Type:

RawDatabaseConfigDict

dirs

attribute

attribute

dirs

Cache, log, and data directories.

Type:

RawDirsConfigDict

debug

attribute

attribute

debug

Debug flag, False in the default config.

Type:

bool

class cihai.types.ConfigDict

class

class

class cihai.types.ConfigDict

Bases: TypedDict

Cihai Configuration dictionary.

Shape of cihai.core.Cihai.config: user input merged over cihai.constants.DEFAULT_CONFIG with templates expanded, so every key is present.

plugins

attribute

attribute

plugins

Dataset plugins, keyed by the namespace of the dataset they extend. An empty mapping when no dataset carries plugins.

Type:

dict[str, RawPluginConfigDict]

datasets

attribute

attribute

datasets

Datasets to bootstrap, keyed by the attribute namespace they are bound to on the cihai.core.Cihai object. A value is either a dotted import path resolved through cihai.utils.import_string() or a cihai.extend.Dataset subclass.

Type:

dict[str, str | Dataset]

database

attribute

attribute

database

Database connection settings.

Type:

RawDatabaseConfigDict

dirs

attribute

attribute

dirs

Cache, log, and data directories.

Type:

RawDirsConfigDict

debug

attribute

attribute

debug

Debug flag, False in the default config.

Type:

bool