Legacy v1 API reference

The functions below exist for v1 compatibility and migration. Functions marked as deprecated emit DeprecationWarning; new code should use upref.ConfigStore and upref.collect(). See Migrating from Upref v1 for the transition guide.

File and raw-value helpers

Provide temporary v1 compatibility and explicit migration helpers.

Upref v1 mixed interactive field descriptions with persisted values and kept all files below a shared .upref data directory. The v2 API separates those concerns. This module preserves the historical call signatures during the v2 series while directing new code toward upref.ConfigStore and upref.collect().

Every historical package-level wrapper emits DeprecationWarning. Pure conversion helpers remain available for migration tooling but are not part of the recommended v2 workflow.

upref.legacy.load_conf(filename)

Load a YAML mapping through the deprecated path-oriented v1 API.

Deprecated since version 2.0: Use ConfigStore.load for managed per-application configuration files.

Parameters:

filename (str | PathLike[str]) – File path to expand, resolve, and read.

Returns:

A detached validated configuration, or an empty dictionary when the file does not exist or is empty.

Raises:

ConfigReadError – If filename is invalid or cannot be resolved, or an existing file cannot be read.
ConfigFormatError – If its YAML or configuration values are invalid.

Return type:

upref.legacy.save_conf(conf, filename)

Save a YAML mapping through the deprecated path-oriented v1 API.

Deprecated since version 2.0: Use ConfigStore.save.

Parameters:

conf (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Complete configuration mapping to validate and persist.
filename (str | PathLike[str]) – Destination path to expand and resolve.

Returns:

A detached normalized copy of the saved mapping.

Raises:

ConfigFormatError – If conf contains unsupported data.
ConfigWriteError – If the destination cannot be written atomically.

Return type:

upref.legacy.upref_filename(name)

Return the historical .upref/<name>.conf location.

Deprecated since version 2.0: Use ConfigStore.path.

Parameters:: name (str) – Legacy preference name without a suffix.
Returns:: The absolute legacy filename as a string.
Raises:: ConfigPathError – If name is empty, reserved, or unsafe.
Return type:: str

upref.legacy.current_upref(name)

Load a descriptor or raw mapping from the historical v1 location.

Deprecated since version 2.0: Use ConfigStore.load or explicitly migrate the file with upref.ConfigStore.import_legacy().

Parameters:

name (str) – Legacy preference name without the .conf suffix.

Returns:

The detached stored mapping, or an empty dictionary when absent.

Raises:

ConfigPathError – If name is unsafe.
ConfigReadError – If the file cannot be read.
ConfigFormatError – If the file contains invalid configuration data.

Return type:

upref.legacy.load_data(name, default_data=None)

Load raw v1 data and optionally merge application defaults.

Deprecated since version 2.0: Use ConfigStore.load.

Parameters:

name (str) – Legacy preference name without the .conf suffix.
default_data (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]] | None) – Optional fallback values. Stored values take precedence and nested mappings merge recursively.

Returns:

A detached resolved configuration.

Raises:

ConfigPathError – If name is unsafe.
ConfigReadError – If the stored file cannot be read.
ConfigFormatError – If defaults or stored values are invalid.

Return type:

upref.legacy.save_data(data, name)

Save raw values in the historical v1 location.

Deprecated since version 2.0: Use ConfigStore.save.

Parameters:

data (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Complete raw configuration mapping.
name (str) – Legacy preference name without the .conf suffix.

Returns:

A detached normalized copy of data.

Raises:

ConfigPathError – If name is unsafe.
ConfigFormatError – If data is invalid.
ConfigWriteError – If the file cannot be persisted.

Return type:

Descriptor and merge helpers

upref.legacy.default_conf()

Return detached GUI defaults formerly stored in default.conf.

Returns:: A new descriptor mapping that callers may mutate safely.
Return type:: dict[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]

Note

This helper exists for direct v1-module compatibility. New prompt front ends define their own presentation defaults.

upref.legacy.dict_merge(dct, merge_dct, add_keys=True)

Merge two mappings with the corrected alias-free v2 implementation.

Parameters:

dct (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Base mapping copied into the result.
merge_dct (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Higher-priority mapping merged over dct.
add_keys (bool) – Include keys not already present in dct when true.

Returns:

A detached recursively merged mapping.

Raises:

ConfigFormatError – If either input violates the configuration model.

Return type:

upref.legacy.conv_raw_to_description(data)

Wrap raw values in the descriptor format used by Upref v1.

Parameters:: data (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Raw configuration values keyed by preference name.
Returns:: A detached mapping where each value is stored below "value".
Raises:: ConfigFormatError – If data is not a supported configuration.
Return type:: dict[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]

upref.legacy.conv_description_to_raw(data_description)

Extract raw values from a v1 descriptor mapping.

Metadata keys beginning or ending with __ and descriptors without a value member are omitted.

Parameters:: data_description (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Historical descriptor mapping.
Returns:: A detached mapping of preference names to raw values.
Raises:: ConfigFormatError – If the descriptor tree contains unsupported data.
Return type:: dict[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]

upref.legacy.all_values_are_set(data_description)

Return whether every non-metadata descriptor contains a usable value.

A descriptor is incomplete when it is not a mapping, lacks value, or stores None or an empty string. Falsey non-string values such as False and 0 are complete.

Parameters:: data_description (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Historical descriptor mapping to inspect.
Returns:: True when all preference descriptors are complete.
Raises:: ConfigFormatError – If the descriptor tree itself is invalid.
Return type:: bool

Interactive compatibility helpers

upref.legacy.get_pref(data_description, name, interface='gui', force_renew=False, mandatory=True)

Collect v1 descriptor values through the separated v2 prompt layer.

A v1 password descriptor requests masked presentation from the selected interface, but accepted values are saved as readable plain-text YAML.

Deprecated since version 2.0: Define upref.Field objects, call upref.collect(), and persist the returned raw values with upref.ConfigStore.

Parameters:

data_description (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Historical mapping of preference descriptors.
name (str) – Legacy preference filename stem.
interface (str) – "gui" or "tty" prompt implementation.
force_renew (bool) – Ask for every field even when saved values are complete.
mandatory (bool) – When false, extract currently stored descriptor values without prompting or applying data_description.

Returns:

A detached mapping of collected raw values.

Raises:

ConfigPathError – If name is unsafe.
ConfigReadError – If existing preferences cannot be read.
ConfigFormatError – If descriptors or saved data are invalid.
PromptCancelled – If the user cancels collection.
PromptUnavailableError – If the selected front end is unavailable.
ConfigWriteError – If collected descriptor values cannot be persisted.
ValueError – If interface is unsupported.
Exception – Unexpected front-end errors propagate unchanged.

Return type:

upref.legacy.set_pref(data, name, data_description=None)

Update values stored in a historical v1 descriptor file.

Deprecated since version 2.0: Use ConfigStore.update for raw v2 values.

Parameters:

data (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]]) – Raw preference values to wrap and replace.
name (str) – Legacy preference filename stem.
data_description (Mapping[str, bool | int | float | str | None | list[bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | None | list[ConfigValue] | dict[str, ConfigValue]]] | None) – Optional descriptor base. When omitted, the current legacy file is loaded first.

Raises:

ConfigPathError – If name is unsafe.
ConfigReadError – If the current descriptor file cannot be read.
ConfigFormatError – If descriptions or values are invalid.
ConfigWriteError – If the updated file cannot be persisted.

Return type:

None

upref.legacy.remove_pref(name)

Delete a historical v1 preference file if it exists.

Deprecated since version 2.0: Use ConfigStore.delete.

Parameters:

name (str) – Legacy preference filename stem.

Raises:

ConfigPathError – If name is unsafe.
ConfigWriteError – If an existing file cannot be deleted.

Return type:

None

Explicit migration function

Most applications should call upref.ConfigStore.import_legacy(). The function below is the underlying compatibility entry point.

upref.legacy.import_legacy(store, name, *, overwrite=False, legacy_directory=None)

Import one v1 file into store while leaving the source untouched.

Documents recognized by the structural descriptor heuristic are converted to raw values; other mappings retain their shape. A raw document whose fields resemble descriptors is therefore ambiguous. The target is written only after the source has been parsed and normalized successfully.

The source and target identity check prevents self-overwrite. The separate target-existence check and save are not locked, so concurrent migrations require external coordination.

Parameters:

store (ConfigStore) – Destination v2 store.
name (str) – Legacy preference filename stem.
overwrite (bool) – Permit replacing an existing v2 destination.
legacy_directory (str | PathLike[str] | None) – Absolute override for the legacy source directory.

Returns:

A detached copy of the values written to store.

Raises:

ConfigPathError – If the source name or directory is unsafe.
ConfigReadError – If the source cannot be read or the target path cannot be inspected.
ConfigFormatError – If the source contains invalid YAML or values.
MigrationError – If source and target are the same file, the source is missing, the target already exists without overwrite, or the destination store reports an Upref persistence error.

Return type:

Config