Add documentation for the extra module

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.

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"]

yamx/extra.py → 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):