Config reader - vcspull._internal.config_reader

Warning

Be careful with these! Internal APIs are not covered by version policies. They can break or be removed between minor versions!

If you need an internal API stabilized please file an issue.

vcspull._internal.config_reader.config_format_from_path(path)
function[source]

Return config format inferred from a path or symlink target.

The visible path remains the config identity, but symlinks may point at a differently named target. When the target advertises a supported config suffix, prefer that format; otherwise fall back to the visible path suffix.

Parameters:

path (pathlib.Path) – Path to inspect.

Returns:

"json" or "yaml" when a supported suffix is found, otherwise None.

Return type:

FormatLiteral | None

Examples

>>> config_format_from_path(pathlib.Path("config.yaml"))
'yaml'
>>> import tempfile
>>> with tempfile.TemporaryDirectory() as tmp:
...     root = pathlib.Path(tmp)
...     target = root / "config.json"
...     _ = target.write_text("{}", encoding="utf-8")
...     link = root / ".vcspull.yaml"
...     link.symlink_to(target)
...     config_format_from_path(link)
'json'
class vcspull._internal.config_reader.ConfigReader
class[source]

Bases: object

Parse string data (YAML and JSON) into a dictionary.

>>> cfg = ConfigReader({ "session_name": "my session" })
>>> cfg.dump("yaml")
'session_name: my session\n'
>>> cfg.dump("json")
'{\n  "session_name": "my session"\n}'
__init__(content)
method[source]
Parameters:

content (RawConfigData)

Return type:

None

static _load(fmt, content)
staticmethod method[source]

Load raw config data and directly return it.

>>> ConfigReader._load("json", '{ "session_name": "my session" }')
{'session_name': 'my session'}

>>> ConfigReader._load("yaml", 'session_name: my session')
{'session_name': 'my session'}
Parameters:

  • fmt (FormatLiteral)

  • content (str)

Return type:

dict[str, Any]

classmethod load(fmt, content)
classmethod method[source]

Load raw config data into a ConfigReader instance (to dump later).

>>> cfg = ConfigReader.load("json", '{ "session_name": "my session" }')
>>> cfg
<vcspull._internal.config_reader.ConfigReader object at ...>
>>> cfg.content
{'session_name': 'my session'}

>>> cfg = ConfigReader.load("yaml", 'session_name: my session')
>>> cfg
<vcspull._internal.config_reader.ConfigReader object at ...>
>>> cfg.content
{'session_name': 'my session'}
Parameters:

  • fmt (FormatLiteral)

  • content (str)

Return type:

ConfigReader

classmethod _from_file(path)
classmethod method[source]

Load data from file path directly to dictionary.

YAML file

For demonstration only, create a YAML file:

>>> yaml_file = tmp_path / 'my_config.yaml'
>>> yaml_file.write_text('session_name: my session', encoding='utf-8')
24

Read YAML file:

>>> ConfigReader._from_file(yaml_file)
{'session_name': 'my session'}

JSON file

For demonstration only, create a JSON file:

>>> json_file = tmp_path / 'my_config.json'
>>> json_file.write_text('{"session_name": "my session"}', encoding='utf-8')
30

Read JSON file:

>>> ConfigReader._from_file(json_file)
{'session_name': 'my session'}
Parameters:

path (Path)

Return type:

dict[str, Any]

classmethod from_file(path)
classmethod method[source]

Load data from file path.

YAML file

For demonstration only, create a YAML file:

>>> yaml_file = tmp_path / 'my_config.yaml'
>>> yaml_file.write_text('session_name: my session', encoding='utf-8')
24

Read YAML file:

>>> cfg = ConfigReader.from_file(yaml_file)
>>> cfg
<vcspull._internal.config_reader.ConfigReader object at ...>

>>> cfg.content
{'session_name': 'my session'}

JSON file

For demonstration only, create a JSON file:

>>> json_file = tmp_path / 'my_config.json'
>>> json_file.write_text('{"session_name": "my session"}', encoding='utf-8')
30

Read JSON file:

>>> cfg = ConfigReader.from_file(json_file)
>>> cfg
<vcspull._internal.config_reader.ConfigReader object at ...>

>>> cfg.content
{'session_name': 'my session'}
Parameters:

path (Path)

Return type:

ConfigReader

static _dump(fmt, content, indent=2, **kwargs)
staticmethod method[source]

Dump directly.

>>> ConfigReader._dump("yaml", { "session_name": "my session" })
'session_name: my session\n'

>>> ConfigReader._dump("json", { "session_name": "my session" })
'{\n  "session_name": "my session"\n}'
Parameters:

  • fmt (FormatLiteral)

  • content (RawConfigData)

  • indent (int)

  • kwargs (Any)

Return type:

str

dump(fmt, indent=2, **kwargs)
method[source]

Dump via ConfigReader instance.

>>> cfg = ConfigReader({ "session_name": "my session" })
>>> cfg.dump("yaml")
'session_name: my session\n'
>>> cfg.dump("json")
'{\n  "session_name": "my session"\n}'
Parameters:

  • fmt (FormatLiteral)

  • indent (int)

  • kwargs (Any)

Return type:

str

class vcspull._internal.config_reader._DuplicateTrackingSafeLoader
class[source]

Bases: SafeLoader

SafeLoader that records duplicate top-level keys.

Notes

PyYAML constructs sequence (list) items AFTER exiting parent mappings, so simple depth-counting doesn’t work for nested structures. Instead, we explicitly track the root mapping node and only consider keys as top-level if they’re direct children of that root node.

__init__(stream)
method[source]

Initialize the scanner.

Parameters:

stream (str)

Return type:

None

yaml_constructors = {'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:int': <function SafeConstructor.construct_yaml_int>, 'tag:yaml.org,2002:map': <function _duplicate_tracking_construct_mapping>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:omap': <function SafeConstructor.construct_yaml_omap>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function SafeConstructor.construct_yaml_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:str': <function SafeConstructor.construct_yaml_str>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>, None: <function SafeConstructor.construct_undefined>}
attribute
vcspull._internal.config_reader._duplicate_tracking_construct_mapping(loader, node, deep=False)
function[source]
Parameters:
Return type:

dict[Any, Any]

class vcspull._internal.config_reader.DuplicateAwareConfigReader
class[source]

Bases: ConfigReader

ConfigReader that tracks duplicate top-level YAML sections.

__init__(content, *, duplicate_sections=None, top_level_items=None)
method[source]
Parameters:
Return type:

None

property duplicate_sections: dict[str, list[Any]]
property

Mapping of top-level keys to the list of duplicated values.

property top_level_items: list[tuple[str, Any]]
property

Ordered list of top-level items, including duplicates.

classmethod _load_yaml_with_duplicates(content)
classmethod method[source]
Parameters:

content (str)

Return type:

tuple[dict[str, Any], dict[str, list[Any]], list[tuple[str, Any]]]

classmethod _load_from_path(path)
classmethod method[source]
Parameters:

path (Path)

Return type:

tuple[dict[str, Any], dict[str, list[Any]], list[tuple[str, Any]]]

classmethod from_file(path)
classmethod method[source]

Load data from file path.

YAML file

For demonstration only, create a YAML file:

>>> yaml_file = tmp_path / 'my_config.yaml'
>>> yaml_file.write_text('session_name: my session', encoding='utf-8')
24

Read YAML file:

>>> cfg = ConfigReader.from_file(yaml_file)
>>> cfg
<vcspull._internal.config_reader.ConfigReader object at ...>

>>> cfg.content
{'session_name': 'my session'}

JSON file

For demonstration only, create a JSON file:

>>> json_file = tmp_path / 'my_config.json'
>>> json_file.write_text('{"session_name": "my session"}', encoding='utf-8')
30

Read JSON file:

>>> cfg = ConfigReader.from_file(json_file)
>>> cfg
<vcspull._internal.config_reader.ConfigReader object at ...>

>>> cfg.content
{'session_name': 'my session'}
Parameters:

path (Path)

Return type:

DuplicateAwareConfigReader

classmethod _from_file(path)
classmethod method[source]

Load data from file path directly to dictionary.

YAML file

For demonstration only, create a YAML file:

>>> yaml_file = tmp_path / 'my_config.yaml'
>>> yaml_file.write_text('session_name: my session', encoding='utf-8')
24

Read YAML file:

>>> ConfigReader._from_file(yaml_file)
{'session_name': 'my session'}

JSON file

For demonstration only, create a JSON file:

>>> json_file = tmp_path / 'my_config.json'
>>> json_file.write_text('{"session_name": "my session"}', encoding='utf-8')
30

Read JSON file:

>>> ConfigReader._from_file(json_file)
{'session_name': 'my session'}
Parameters:

path (Path)

Return type:

dict[str, Any]

classmethod load_with_duplicates(path)
classmethod method[source]
Parameters:

path (Path)

Return type:

tuple[dict[str, Any], dict[str, list[Any]], list[tuple[str, Any]]]