From 52ed7929ba49487e9c2accd1b84f215e7147bb00 Mon Sep 17 00:00:00 2001 From: Eduard Trott Date: Mon, 26 Aug 2024 12:09:08 +0200 Subject: [PATCH] Add documentation for the extra module --- yamx/extra/README.md | 103 ++++++++++++++++++++++++++++++++++++++ yamx/extra/__init__.py | 8 +++ yamx/{ => extra}/extra.py | 92 ---------------------------------- 3 files changed, 111 insertions(+), 92 deletions(-) create mode 100644 yamx/extra/README.md create mode 100644 yamx/extra/__init__.py rename yamx/{ => extra}/extra.py (83%) diff --git a/yamx/extra/README.md b/yamx/extra/README.md new file mode 100644 index 0000000..4c8b211 --- /dev/null +++ b/yamx/extra/README.md @@ -0,0 +1,103 @@ +## Logical Sorting + +To apply logical sorting to your YAML file, you can use the function `sort_logical(obj, config)`. The config parameter in this function is defined by SORT_CONFIG, which determines the sorting order for keys and values within the YAML content. By using SORT_CONFIG, you can ensure your YAML data is organized according to specific rules and preferences. + +### Structure of SORT_CONFIG + +- **Keys**: The keys in `SORT_CONFIG` are tuples that represent the path to a key in the YAML file. For example, a key like `("key1", "key2")` targets a nested key `key2` under `key1`. + +- **Values**: The values are dictionaries that define the sorting order for either dictionaries or lists located under the specified key path. + +### Sorting Dictionaries + +For dictionary elements, the `key_order` specifies the order in which keys should appear. + +#### Example 1: Sorting Dictionary Keys + +Given the configuration: +```python +SORT_CONFIG = { + ("key1", "key2"): { + "key_order": ["key3", "key4"] + } +} +``` + +The resulting YAML configuration will sort the keys `key3` and `key4` under `key1 > key2`: + +```yaml +key1: + key2: + key3: ... + key4: ... +``` + +### Sorting Lists + +Lists are denoted by the `[]` symbol in the key tuple, indicating that the sorting rules apply to a list under the specified path. + +#### Example 2: Sorting Lists + +Given the configuration: +```python +SORT_CONFIG = { + ("key1", "[]"): { + "key_order": ["key3", "key4"] + } +} +``` + +The resulting YAML configuration will sort dictionary items inside a list under `key1` by the keys `key3` and `key4`: + +```yaml +key1: + - key3: ... + key4: ... +``` + +### Advanced Sorting for Lists + +For sorting list elements, use `item_order` to define the sorting criteria. The `item_order` can contain strings or tuples, where tuples represent nested keys within dictionary elements. + +#### Example 3: Advanced Sorting for Lists + +Given the configuration: +```python +SORT_CONFIG = { + ("key1",): { + "item_order": [ + {"key": "key2"}, + {"key": ("key3", "value")} + ] + } +} +``` + +Here, items under the list at `key1` will be sorted: +1. First by the value of `key2`. +2. Then by the value under `key2 > value`. + +The resulting YAML configuration will look like: + +```yaml +key1: + - key2: 1 + key3: + value: 3 + - key2: 1 + key3: + value: 4 + - key2: 2 + key3: + value: 1 + - key2: 2 + key3: + value: 2 +``` + +### Special Notes + +- If a dictionary is represented by a toggled group, the first key of the "if" body is used to represent the order of the entire group. +- `item_order` is used exclusively for defining the order of items in a list, allowing for complex nested sorting based on multiple criteria. + +By configuring `SORT_CONFIG` appropriately, you can ensure your YAML files are consistently and predictably ordered according to your specific needs. diff --git a/yamx/extra/__init__.py b/yamx/extra/__init__.py new file mode 100644 index 0000000..89349fe --- /dev/null +++ b/yamx/extra/__init__.py @@ -0,0 +1,8 @@ +from yamx.extra.extra import ( + ResolvingContext, + extract_toggles, + resolve_toggles, + sort_logical, +) + +__all__ = ["resolve_toggles", "extract_toggles", "ResolvingContext", "sort_logical"] diff --git a/yamx/extra.py b/yamx/extra/extra.py similarity index 83% rename from yamx/extra.py rename to yamx/extra/extra.py index 38b5699..a80df1b 100644 --- a/yamx/extra.py +++ b/yamx/extra/extra.py @@ -179,98 +179,6 @@ def resolve_condition( return bool(strtobool(resolved)) -########################################################### -# SORT_CONFIG explained # -########################################################### -# SORT_CONFIG is a dictionary that defines the sorting order for the keys in the YAML file. -# -# The keys in the dictionary are tuples that represent the path to the key in the YAML file. -# e.g. {("key1", "key2",): ...} -# -# The value is another dictionary that defines the sorting order for dictionary or list under -# the key. -# if element under given key represents a dictionary -# "key_order" key is used to define the order of keys in the dictionary. -# -# EXAMPLE 1 -# -# if SORT_CONFIG is {("key1", "key2",): {"key_order": ["key3", "key4"]}} -# final config will have the order according to the key_order list: -# { -# "key1": { -# "key2": { -# "key3": ..., -# "key4": ... -# } -# } -# } - -# list object can be denoted by "[]" symbol in the key tuple -# -# EXAMPLE 2 -# -# if SORT_CONFIG is {("key1", "[]"): {"key_order": ["key3", "key4"]}} -# final config will have the order according to the key_order list: -# { -# "key1": [ -# { -# "key3": ..., -# "key4": ... -# } -# ] -# } - -# NOTE: if dictionary is represented by toggled group - first key of "if" body is used to -# represent the order of the whole group - -# if element in json file that is being sorted under given key represents a list -# "item_order" key is used to define the order of items in the list. -# "item_order" list can contain strings or tuples. If tuple is used, it represents a key in -# the dictionary. - -# -# EXAMPLE 3 -# -# if SORT_CONFIG is -# { -# ("key1",): { -# "item_order": [ -# { -# "key": "key3" -# }, -# { -# "key": ("key4", "value") -# } -# ] -# } -# } -# the logic behind the definition is following: -# - sort items in the list under key "key1" -# - first sort by "key3" -# - then sort by "value" of "key4" -# final config will have the order according to the item_order list: -# { -# "key1": [ -# { -# "key2": 1, -# "key3": {"value": 3} -# }, -# { -# "key2": 1, -# "key3": {"value": 4} -# }, -# { -# "key2": 2, -# "key3": {"value": 1} -# }, -# { -# "key2": 2, -# "key3": {"value": 2} -# }, -# ] -# } - - def sort_logical(obj: Any, config: dict) -> Any: """Perform logical sorting based on the provided structure""" if isinstance(obj, ConditionalData):