Library

Configuration file parsing and validation.

macprefs.config.read_config(config_file: Path | None = None) → dict[str, Any]

Read and validate the configuration file.

Returns:

Parsed configuration, or an empty dict if no file was found.

Return type:

dict[str, Any]

Raises:

ConfigTypeError – If the configuration structure is invalid.

Constants.

macprefs.constants.GLOBAL_DOMAIN_ARG = '-globalDomain'

Global domain argument for the defaults command.

macprefs.constants.MAX_CONCURRENT_EXPORT_TASKS = 40

Maximum number of concurrent export tasks.

Exceptions.

exception macprefs.exceptions.ConfigTypeError(key: str, expected_type: str)

Configuration error.

exception macprefs.exceptions.PropertyListConversionError(filename: str | None = None)

Exception raised when a property list conversion fails.

Convert a property list dictionary to defaults write commands.

macprefs.plist2defaults.plist_to_defaults_commands(domain: str, root: PlistRoot, key_filter: collections.abc.Callable[[str, str], bool] | None = None, *, invert_filters: bool = False) → Iterator[str]

Given a macprefs.typing.PlistRoot, generate defaults write commands.

Parameters:
domain : str

The preferences domain.

root : PlistRoot

The root of the preferences dictionary.

key_filter : Callable[[str, str], bool] | None

A function that takes a domain and key and returns True if the key should be ignored.

invert_filters : bool

If True, invert the key filter.

Yields:

str – Lines for output into a shell script.

Processing utilities.

macprefs.processing.make_key_filter(bad_keys_re_addendum: Iterable[str] | None = None, bad_keys_addendum: Mapping[str, set[str]] | None = None, *, reset_re: bool = False, reset_bad_keys: bool = False) → collections.abc.Callable[[str, str], bool]

Create a function to filter out ignored keys.

Returns:

Predicate that returns True when a key should be ignored.

Return type:

Callable[[str, str], bool]

macprefs.processing.remove_data_fields(root: PlistRoot) → PlistRoot

Clean up data fields from a macprefs.typing.PlistRoot.

Returns:

The mapping with data fields removed.

Return type:

PlistRoot

macprefs.processing.remove_data_fields_list(pl_list: PlistList) → PlistList

Clean up data fields from a macprefs.typing.PlistList.

Returns:

The list with data fields removed.

Return type:

PlistList

Utility functions.

async macprefs.utils.defaults_export(domain: str, repo_prefs_dir: Path) → tuple[str, PlistRoot]

Export a domain using the defaults command.

Returns:

The domain name and parsed plist contents. Values may be empty if export failed.

Return type:

tuple[str, PlistRoot]

async macprefs.utils.generate_domains(bad_domains_addendum: Iterable[str], bad_domain_prefixes_addendum: Iterable[str], *, reset_domains: bool = False, reset_prefixes: bool = False) → AsyncIterator[str]

Generate the list of domains to export.

Yields:

str – The domain name.

async macprefs.utils.git(cmd: Iterable[str], work_tree: Path, git_dir: Path | None = None, ssh_key: str | None = None) → sp.Process

Run a Git command.

Returns:

The subprocess handle after the command completes successfully.

Return type:

subprocess.Process

Raises:

  • CalledProcessError – If the command exits with a non-zero status.

  • RuntimeError – If the subprocess is missing expected pipes or state.

async macprefs.utils.install_job(output_dir: Path, deploy_key: Path | None = None) → int

Install a launchd job to run macprefs.

Returns:

0 if launchctl load and start succeeded, otherwise 1.

Return type:

int

Raises:

RuntimeError – If the prefs-export subprocess has no stdout pipe.

async macprefs.utils.is_git_installed() → bool

Check if Git is installed.

Returns:

True if the git executable is on PATH.

Return type:

bool

async macprefs.utils.prefs_export(out_dir: Path, config: dict[str, Any] | None = None, deploy_key: Path | None = None, *, commit: bool = False) → None

Export filtered preferences to a directory.

Also writes scripts exec-defaults.sh and rejected-defaults.sh to the output directory, both of which contain defaults commands to set preferences equivalent to the exported property list files.

Raises:

PropertyListConversionError – If any plutil command fails.

async macprefs.utils.setup_output_directory(out_dir: Path) → tuple[Path, Path]

Set up the output directory and the Preferences subdirectory.

Returns:

The output directory and the Preferences subdirectory paths.

Return type:

tuple[Path, Path]