serena.util.yaml

serena.util.yaml#

Source code: serena/util/yaml.py

class YamlCommentNormalisation(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)[source]#

Bases: Enum

Defines a normalisation to be applied to the comment representation in a ruamel CommentedMap.

Note that even though a YAML document may seem to consistently contain, for example, leading comments before a key only, ruamel may still parse some comments as trailing comments of the previous key or as document-level comments. The normalisations define ways to adjust the comment representation accordingly, clearly associating comments with the keys they belong to.

NONE = 'none'#

No comment normalisation is performed. Comments are kept as parsed by ruamel.yaml.

LEADING = 'leading'#

Document is assumed to have leading comments only, i.e. comments before keys, only full-line comments. This normalisation achieves that comments are properly associated with keys as leading comments.

LEADING_WITH_CONVERSION_FROM_TRAILING = 'leading_with_conversion_from_trailing'#

Document is assumed to have a mixture of leading comments (before keys) and trailing comments (after values), only full-line comments. This normalisation achieves that all comments are converted to leading comments and properly associated with keys.

load_yaml(path, comment_normalisation=YamlCommentNormalisation.NONE)[source]#
Parameters:

  • path (str) – the path to the YAML file to load

  • comment_normalisation (YamlCommentNormalisation) – the comment normalisation to apply after loading

Returns:

the loaded commented map

Return type:

CommentedMap

normalise_yaml_comments(commented_map, comment_normalisation)[source]#

Applies the given comment normalisation to the given commented map in-place.

Parameters:

  • commented_map (CommentedMap) – the commented map whose comments are to be normalised

  • comment_normalisation (YamlCommentNormalisation) – the comment normalisation to apply

Return type:

None

transfer_yaml_comments_by_index(
source,
target,
indices,
forced_update_keys=(),
force_update_all=False,
)[source]#
Parameters:

  • source (CommentedMap) – the source, from which to transfer missing comments

  • target (CommentedMap) – the target map, whose comments will be updated

  • indices (list[int]) – list of comment indices to transfer

  • forced_update_keys (Sequence[str]) – keys for which comments are always transferred, even if present in target

  • force_update_all (bool) – if True, comments are transferred for all keys, even if present in target

Return type:

None

transfer_yaml_comments(
source,
target,
comment_normalisation,
forced_update_keys=(),
force_update_all=False,
)[source]#

Transfers missing comments from source to target YAML.

Parameters:

  • source (CommentedMap) – the source, from which to transfer missing comments

  • target (CommentedMap) – the target map, whose comments will be updated.

  • comment_normalisation (YamlCommentNormalisation) – the comment normalisation to assume; if NONE, no comments are transferred

  • forced_update_keys (Sequence[str]) – keys for which comments are always transferred, even if present in target

  • force_update_all (bool) – if True, comments are transferred for all keys, even if present in target

Return type:

None