yera.config.storage.write

Persist edits to yera.toml and pyproject.toml while keeping human-oriented layout.

Why tomlkit (and not tomli + tomli-w, or tomllib + a writer)? Those paths parse TOML into a plain dict and write it back with a fresh serialiser. The whole file is re-emitted, so comments, spacing, and section order outside our edits are lost. That is especially bad for pyproject.toml, which people hand-edit and share with Ruff, Hatch, and so on.

tomlkit loads the file into a document — a structured representation that still carries the original layout. We only assign into the tables Yera cares about; the rest of the file is left as-is on save.

Public functions are the supported mutations. Private helpers load or save that document, ensure nested tables exist, and run a small mutator that returns whether anything changed worth writing to disk (so we skip useless rewrites where that matters).

Symbols

def delete_yera_toml — Remove the resolved ``yera.toml`` path; do nothing if it is already absent.
def remove_all_hubs — Clear every key under ``[hubs]`` (named hubs and ``default``).
def remove_all_models — Remove model entries from ``[models]``.
def remove_all_profiles — Clear every profile under ``[profiles.profiles]`` and unset ``default``.
def remove_all_providers — Clear every key under ``[providers]``.
def remove_from_pyproject_yera — Remove ``[tool.yera].`` when it exists.
def remove_from_pyproject_yera_overrides — Remove ``[tool.yera.overrides].`` when it exists.
def remove_hub_entry — Drop ``[hubs.]``; clear ``default`` too when it pointed at *name*.
def remove_model_from_universe — Remove one model entry from ``[[models.]]`` matching *model_id* and *connection*.
def remove_models_for_connection — Remove all model entries across all types for a specific provider connection.
def remove_profile — Drop ``[profiles.profiles.]``.
def remove_provider — Drop ``[providers.]`` and all its connections.
def remove_provider_connection — Drop ``[providers..connections.]``.
def write_hub_default — Set ``[hubs] default`` to *name* without removing existing ``[hubs.*]`` URL tables.
def write_hub_entry — Define or replace ``[hubs.]`` with the given *url*; other hub entries stay put.
def write_model_to_universe — Append or replace a model entry in ``[[models.]]`` in ``yera.toml``.
def write_models_to_universe — Write multiple model entries to yera.toml in a single file operation.
def write_profile — Write or replace ``[profiles.profiles.]`` in ``yera.toml``.
def write_profile_default — Set ``[profiles] default`` to *profile_name*.
def write_provider_connection — Define or replace ``[providers..connections.]`` with *connection_data*.
def write_pyproject_yera_cred_group — Set ``[tool.yera.overrides] cred-group`` to *name*; other ``pyproject.toml`` content stays intact.
def write_setting_to_yera_toml — Set ``[settings].`` to *value*; leave every other section of ``yera.toml`` as-is.
def write_to_pyproject_yera — Set ``[tool.yera].`` to *value*; all other ``pyproject.toml`` content stays intact.
def write_to_pyproject_yera_profile — Set ``[tool.yera.profiles] default`` to *profile_name* in ``pyproject.toml``.

delete_yera_toml

delete_yera_toml() → None

Remove the resolved yera.toml path; do nothing if it is already absent.

remove_all_hubs

remove_all_hubs() → None

Clear every key under [hubs] (named hubs and default).

Does not write when there is no hubs table, when hubs is not a TOML table, or when [hubs] is already empty—nothing to change on disk.

remove_all_models

remove_all_models(
    model_type: str | None = None,
) → None

Remove model entries from [models].

When model_type is given, clears only that type's array. When omitted, clears all type arrays entirely.

Does not write when there is no models table or the target is already empty.

Parameters

model_type
type: str | None = None

If set, remove only models of this type. If None, remove all models across all types.

remove_all_profiles

remove_all_profiles() → None

Clear every profile under [profiles.profiles] and unset default.

Does not write when there is no profiles table or it is already empty.

remove_all_providers

remove_all_providers() → None

Clear every key under [providers].

Does not write when there is no providers table or it is already empty.

remove_from_pyproject_yera

remove_from_pyproject_yera(
    key: str,
) → None

Remove [tool.yera].<key> when it exists.

Does not write the file when [tool] or [tool.yera] is absent, or when key is not present under [tool.yera], so the manifest is left unchanged.

Raises

PyprojectTomlNotFoundError

No writable pyproject.toml for this project.

remove_from_pyproject_yera_overrides

remove_from_pyproject_yera_overrides(
    key: str,
) → None

Remove [tool.yera.overrides].<key> when it exists.

Does not write when [tool], [tool.yera], or [tool.yera.overrides] is absent, or when key is not present. When the overrides table becomes empty after removal, drops the empty overrides table from [tool.yera].

Raises

PyprojectTomlNotFoundError

No writable pyproject.toml for this project.

remove_hub_entry

remove_hub_entry(
    name: str,
) → None

Drop [hubs.<name>]; clear default too when it pointed at name.

Does not write the file when there is no [hubs] table (nothing to change).

remove_model_from_universe

remove_model_from_universe(
    model_type: str,
    model_id: str,
    connection: str,
) → None

Remove one model entry from [[models.<type>]] matching model_id and connection.

Does not write when no matching entry exists.

Parameters

model_type
type: str

Model type key, e.g. "llm".

model_id
type: str

Yera-internal dot-delimited model id.

connection
type: str

Connection name the model was discovered under.

remove_models_for_connection

remove_models_for_connection(
    provider_type: str,
    connection_name: str,
) → None

Remove all model entries across all types for a specific provider connection.

Iterates every model type array in [models] and drops entries where both provider matches provider_type and connection matches connection_name. Does not write when nothing matches.

Parameters

provider_type
type: str

Provider type key, e.g. "aws".

connection_name
type: str

Connection name, e.g. "work".

remove_profile

remove_profile(
    profile_name: str,
) → None

Drop [profiles.profiles.<name>].

Clears default too when it pointed at profile_name. Does not write when the profile is absent.

Parameters

profile_name
type: str

Yera profile name to remove.

remove_provider

remove_provider(
    provider_type: str,
) → None

Drop [providers.<type>] and all its connections.

Does not write when the provider is absent.

Parameters

provider_type
type: str

Provider type key to remove, e.g. "aws".

remove_provider_connection

remove_provider_connection(
    provider_type: str,
    connection_name: str,
) → None

Drop [providers.<type>.connections.<name>].

Does not write when the provider or connection is absent.

Parameters

provider_type
type: str

Provider type key, e.g. "aws".

connection_name
type: str

Connection name to remove, e.g. "work".

write_hub_default

write_hub_default(
    name: str,
) → None

Set [hubs] default to name without removing existing [hubs.*] URL tables.

write_hub_entry

write_hub_entry(
    name: str,
    url: str,
) → None

Define or replace [hubs.<name>] with the given url; other hub entries stay put.

write_model_to_universe

write_model_to_universe(
    model: BaseModelConfig,
) → None

Append or replace a model entry in [[models.<type>]] in yera.toml.

Derives model type from model.type. If an entry with the same id and connection already exists it is replaced in-place; otherwise the entry is appended.

Parameters

model
type: BaseModelConfig

A validated model config object to write.

write_models_to_universe

write_models_to_universe(
    models: list[BaseModelConfig],
) → None

Write multiple model entries to yera.toml in a single file operation.

Parameters

models
type: list[BaseModelConfig]

List of validated model config objects to write.

write_profile

write_profile(
    profile: Profile,
) → None

Write or replace [profiles.profiles.<name>] in yera.toml.

Serialises the full profile — name, optional description, non-empty provider bindings, and non-empty model defaults — into a tomlkit table and assigns it under [profiles.profiles]. Creates the [profiles] and [profiles.profiles] tables if absent. Empty provider and model-default fields are omitted from the written entry.

Parameters

profile
type: Profile

Validated profile object to persist. The profile's name field is used as the table key.

write_profile_default

write_profile_default(
    profile_name: str,
) → None

Set [profiles] default to profile_name.

Parameters

profile_name
type: str

Yera profile name to set as default.

write_provider_connection

write_provider_connection(
    provider_type: str,
    connection_name: str,
    connection_data: dict[str, TomlValue],
) → None

Define or replace [providers.<type>.connections.<name>] with connection_data.

Creates the [providers], [providers.<type>], and [providers.<type>.connections] tables if absent.

Parameters

provider_type
type: str

Provider type key, e.g. "aws".

connection_name
type: str

Connection name, e.g. "work".

connection_data
type: dict[str, TomlValue]

Connection fields to write, e.g. {"region": "eu-west-1", "credentials": ["access_key_id"]}.

write_pyproject_yera_cred_group

write_pyproject_yera_cred_group(
    name: str,
) → None

Set [tool.yera.overrides] cred-group to name; other pyproject.toml content stays intact.

Creates [tool], [tool.yera], and [tool.yera.overrides] when missing. name is stripped of leading and trailing whitespace before writing.

Raises

PyprojectTomlNotFoundError

No writable pyproject.toml for this project.

TypeError

tool, tool.yera, or tool.yera.overrides exists but is not a table.

ValueError

name is empty or whitespace-only after stripping.

write_setting_to_yera_toml

write_setting_to_yera_toml(
    key: str,
    value: TomlValue,
) → None

Set [settings].<key> to value; leave every other section of yera.toml as-is.

write_to_pyproject_yera

write_to_pyproject_yera(
    key: str,
    value: TomlValue,
) → None

Set [tool.yera].<key> to value; all other pyproject.toml content stays intact.

Creates [tool] / [tool.yera] when missing.

Raises

PyprojectTomlNotFoundError

No writable pyproject.toml for this project.

TypeError

tool or tool.yera exists but is not a table (malformed file).

write_to_pyproject_yera_profile

write_to_pyproject_yera_profile(
    profile_name: str,
) → None

Set [tool.yera.profiles] default to profile_name in pyproject.toml.

Creates [tool], [tool.yera], and [tool.yera.profiles] if absent.

Parameters

profile_name
type: str

Yera profile name to set as the project-level active profile.

Raises

PyprojectTomlNotFoundError

No writable pyproject.toml for this project.