vcspull fmt - vcspull.cli.fmt

Format vcspull configuration files.

class vcspull.cli.fmt.FmtAction

Bases: Enum

Action resolved for each repo entry during vcspull fmt.

NORMALIZE = 'normalize'

NO_CHANGE = 'no_change'

SKIP_PINNED = 'skip_pinned'

vcspull.cli.fmt.create_fmt_subparser(parser)

Create vcspull fmt argument subparser.

Return type:

None

Parameters:

parser (ArgumentParser)

vcspull.cli.fmt.normalize_repo_config(repo_data)

Normalize repository configuration to verbose format.

Return type:

dict[str, Any]

Parameters:

repo_data (Any) – Repository configuration (string URL or dict)

Returns:

Normalized repository configuration with ‘repo’ key

Return type:

dict

Examples

String entries are wrapped:

>>> from vcspull.cli.fmt import normalize_repo_config
>>> normalize_repo_config("git+https://example.com/r.git")
{'repo': 'git+https://example.com/r.git'}

Dict with url key is normalized to repo:

>>> normalize_repo_config({"url": "git+https://example.com/r.git"})
{'repo': 'git+https://example.com/r.git'}

Dict already using repo key passes through unchanged:

>>> normalize_repo_config({"repo": "git+https://example.com/r.git"})
{'repo': 'git+https://example.com/r.git'}

When both url and repo keys are present, both are preserved (deduplication is left to the caller):

>>> normalize_repo_config({"url": "git+https://example.com/u.git", "repo": "git+https://example.com/r.git"})
{'url': 'git+https://example.com/u.git', 'repo': 'git+https://example.com/r.git'}

vcspull.cli.fmt._classify_fmt_action(repo_data)

Classify the fmt action for a single repository entry.

Returns the action and the (possibly normalized) data so that callers do not need to call normalize_repo_config() a second time.

Return type:

tuple[FmtAction, Any]

Parameters:

repo_data (Any) – Repository configuration value (string, dict, or other).

Returns:

The resolved action and the resulting repo data. For NORMALIZE the second element is the normalized dict; for NO_CHANGE and SKIP_PINNED it is the original repo_data.

Return type:

tuple[FmtAction, Any]

Examples

String entries need normalization:

>>> _classify_fmt_action("git+ssh://x")
(<FmtAction.NORMALIZE: 'normalize'>, {'repo': 'git+ssh://x'})

Dict with url key needs normalization:

>>> _classify_fmt_action({"url": "git+ssh://x"})
(<FmtAction.NORMALIZE: 'normalize'>, {'repo': 'git+ssh://x'})

Already normalized dict:

>>> _classify_fmt_action({"repo": "git+ssh://x"})
(<FmtAction.NO_CHANGE: 'no_change'>, {'repo': 'git+ssh://x'})

Pinned entry is preserved verbatim:

>>> pinned = {"repo": "git+ssh://x", "options": {"pin": True}}
>>> action, data = _classify_fmt_action(pinned)
>>> action
<FmtAction.SKIP_PINNED: 'skip_pinned'>
>>> data == pinned
True
>>> entry = {"repo": "git+ssh://x", "options": {"pin": {"fmt": True}}}
>>> _classify_fmt_action(entry)[0]
<FmtAction.SKIP_PINNED: 'skip_pinned'>

Pinned for import only — fmt still normalizes:

>>> entry = {"url": "git+ssh://x", "options": {"pin": {"import": True}}}
>>> action, data = _classify_fmt_action(entry)
>>> action
<FmtAction.NORMALIZE: 'normalize'>
>>> data["repo"]
'git+ssh://x'

vcspull.cli.fmt.format_config(config_data)

Format vcspull configuration for consistency.

Return type:

tuple[dict[str, Any], int]

Parameters:

config_data (dict) – Raw configuration data

Returns:

Formatted configuration and count of changes made

Return type:

tuple[dict, int]

vcspull.cli.fmt.format_single_config(config_file_path, write, *, merge_roots)

Format a single vcspull configuration file.

Return type:

bool

Parameters:

• config_file_path (pathlib.Path) – Path to config file

• write (bool) – Whether to write changes back to file

• merge_roots (bool) – Merge duplicate workspace roots when True (default behavior)

Returns:

True if formatting was successful, False otherwise

Return type:

bool

vcspull.cli.fmt.format_config_file(config_file_path_str, write, format_all=False, *, merge_roots=True)

Format vcspull configuration file(s).

Return type:

None

Parameters:

• config_file_path_str (str | None) – Path to config file, or None to use default

• write (bool) – Whether to write changes back to file

• format_all (bool) – If True, format all discovered config files

• merge_roots (bool) – Merge duplicate workspace roots when True (default)