Configuration

Configuration centers around the ixmp4.conf.settings.Settings class. When instantiated, this class will read environment variables and .env files to populate the object. Any value can be overridden by passing the appropriate constructor argument:

from ixmp4.conf.settings import Settings
from ixmp4 import Platform

settings = Settings(manager_url="https://custom.manager.ece.iiasa.ac.at")

# use custom manager url for a single platform
mp = Platform(settings=settings)

Two nested settings classes ixmp4.conf.settings.ClientSettings and ixmp4.conf.settings.ServerSettings are used to configure the ixmp4.transport.HttpxTransport and ixmp4.server.Ixmp4Server classes respectively,

For the convenience, a local .env file can be used to configure the settings object:

IXMP4_MODE=development
IXMP4_STORAGE_DIRECTORY=~/.local/share/ixmp4/
IXMP4_MANAGER_URL=https://api.manager.ece.iiasa.ac.at/v1/

# Server Settings
IXMP4_SERVER__MANAGER_URL=https://api.manager.ece.iiasa.ac.at/v1/
IXMP4_SERVER__TOML_PLATFORMS=/custom/path/to/platforms.toml
IXMP4_SERVER__SECRET_HS256=changeme
IXMP4_SERVER__MAX_PAGE_SIZE=10000
IXMP4_SERVER__DEFAULT_PAGE_SIZE=5000

# Client Settings
IXMP4_CLIENT__DEFAULT_UPLOAD_CHUNK_SIZE=10000
IXMP4_CLIENT__CONCURRENCY=2
IXMP4_CLIENT__RETRIES=3
IXMP4_CLIENT__TIMEOUT=30
IXMP4_CLIENT__SECRET_HS256=changeme

Submodules

ixmp4.conf.credentials module

class ixmp4.conf.credentials.CredentialsDict

Bases: TypedDict

username: str

password: str

class ixmp4.conf.credentials.Credentials(toml_file: Path)

Bases: object

credentials: dict[str, CredentialsDict]

load() → None

dump() → None

get(key: str) → CredentialsDict | None

set(key: str, username: str, password: str) → None

clear(key: str) → None

ixmp4.conf.platforms module

ixmp4.conf.platforms.resolve_dsn_env_tokens(dsn: str) → str: Replace {env:VAR_NAME} placeholders with environment variable values.

class ixmp4.conf.platforms.PlatformConnectionInfo(*args, **kwargs)

Bases: Protocol

id: int

name: str

slug: str

access_group: int

management_group: int

accessibility: str

dsn: str

url: Any

class ixmp4.conf.platforms.PlatformConnections

Bases: ABC

abstractmethod list_platforms() → list[PlatformConnectionInfo]

abstractmethod get_platform(name: str) → PlatformConnectionInfo

class ixmp4.conf.platforms.TomlPlatform(*, id: int = -1, name: str, slug: str, access_group: int = -1, management_group: int = -1, accessibility: str = 'PUBLIC', dsn: str, url: str | None = None)

Bases: BaseModel

id: int

name: str

slug: str

access_group: int

management_group: int

accessibility: str

dsn: str

url: str | None

model_config = {'from_attributes': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ixmp4.conf.platforms.TomlPlatforms(toml_file: Path)

Bases: PlatformConnections

platforms: dict[str, TomlPlatform]

load() → None

dump() → None

list_platforms() → list[TomlPlatform]

get_platform(name: str) → TomlPlatform

add_platform(name: str, dsn: str) → None

remove_platform(name: str) → None

class ixmp4.conf.platforms.ManagerPlatforms(manager_client: ManagerClient)

Bases: PlatformConnections

manager_client: ManagerClient

list_platforms() → list[Ixmp4Instance]

get_platform(name: str) → Ixmp4Instance

ixmp4.conf.settings module

class ixmp4.conf.settings.ClientSettings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_prefix_target: EnvPrefixTarget | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None, _cli_shortcuts: Mapping[str, str | list[str]] | None = None, _secrets_dir: PathType | None = None, _build_sources: tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None = None, *, default_upload_chunk_size: int = 10000, concurrency: Annotated[int, Le(le=4)] = 2, retries: int = 3, timeout: int = 30, secret_hs256: SecretStr | None = None)

Bases: BaseSettings

default_upload_chunk_size: int

concurrency: int

retries: int

timeout: int

secret_hs256: SecretStr | None

model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'env_prefix_target': 'variable', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Bases: BaseSettings

manager_url: HttpUrl | None

toml_platforms: Path | None

secret_hs256: SecretStr | None

max_page_size: int

default_page_size: int

setup() → ServerSettings

get_self_signed_auth(secret_hs256: SecretStr) → SelfSignedAuth

get_manager_client(manager_url: HttpUrl, secret_hs256: SecretStr) → ManagerClient

get_toml_platforms() → TomlPlatforms | None

model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': '', 'env_prefix_target': 'variable', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ixmp4.conf.settings.Settings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_prefix_target: EnvPrefixTarget | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None, _cli_settings_source: CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None, _cli_shortcuts: Mapping[str, str | list[str]] | None = None, _secrets_dir: PathType | None = None, _build_sources: tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None = None, *, mode: Literal['production', 'development', 'debug'] = 'production', storage_directory: Path = PosixPath('~/.local/share/ixmp4'), manager_url: HttpUrl = HttpUrl('https://api.manager.ece.iiasa.ac.at/v1'), server: ServerSettings = ServerSettings(manager_url=None, toml_platforms=None, secret_hs256=None, max_page_size=10000, default_page_size=5000), client: ClientSettings = ClientSettings(default_upload_chunk_size=10000, concurrency=2, retries=3, timeout=30, secret_hs256=None), **values: Any)

Bases: BaseSettings

mode: Literal['production', 'development', 'debug']

storage_directory: Path

manager_url: HttpUrl

server: ServerSettings

client: ClientSettings

model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': '.env', 'env_file_encoding': 'utf-8', 'env_ignore_empty': False, 'env_nested_delimiter': '__', 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': 'ixmp4_', 'env_prefix_target': 'variable', 'extra': 'allow', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

setup() → Settings

is_in_interactive_mode() → bool

get_credentials_path() → Path

get_credentials() → Credentials

get_toml_platforms_path() → Path

get_toml_platforms() → TomlPlatforms

setup_directories() → None

classmethod validate_storage_dir(v: Path) → Path

load_logging_config(config: str) → Any

configure_logging(config: str) → None

get_database_dir() → Path: Returns the path to the local sqlite database directory.

get_database_path(name: str) → Path: Returns a Path object for a given sqlite database name. Does not check whether or not the file actually exists.

get_client_auth(credentials: CredentialsDict | None) → ManagerAuth | SelfSignedAuth | None

get_self_signed_auth(secret_hs256: SecretStr) → SelfSignedAuth

get_manager_auth(manager_url: HttpUrl, credentials: CredentialsDict) → ManagerAuth | None

get_manager_client(credentials: str = 'default') → ManagerClient

get_manager_platforms(credentials: str = 'default') → ManagerPlatforms