Fix/stuff

.github/workflows/test.yml

@@ -17,10 +17,11 @@ jobs:
     strategy:
       matrix:
         python:
-          - "3.8"
           - "3.9"
           - "3.10"
           - "3.11"
+          - "3.12"
+          - "3.13"
     steps:
       - name: Check out code
         uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4

.pre-commit-config.yaml

@@ -50,5 +50,3 @@ repos:
     rev: v1.11.2
     hooks:
       - id: mypy
-        additional_dependencies:
-          - types-PyYAML

aar_doc/core.py

@@ -11,7 +11,14 @@
 
 import jinja2
 import typer
-import yaml
+
+from ruamel.yaml import YAML, YAMLError
+
+yaml = YAML()
+yaml.indent(mapping=2, sequence=2, offset=2)
+yaml.version = "1.1"
+yaml.encoding = "utf-8"
+yaml.allow_unicode = True
 
 
 class OutputMode(Enum):
@@ -26,7 +33,7 @@ class OutputMode(Enum):
 def parse_config(
     ctx: typer.Context,
     config_file: pathlib.Path,
-):
+) -> None:
     """
     Parses the configuration file
     """
@@ -38,7 +45,7 @@ def parse_config(
     if config_file_full_path.exists():
         try:
             with open(config_file_full_path, "r", encoding="utf-8") as f:
-                content = yaml.safe_load(f)
+                content = yaml.load(f)
 
                 ctx.default_map = ctx.default_map or {}
                 ctx.default_map.update(content)
@@ -58,8 +65,8 @@ def parse_meta(ctx: typer.Context) -> tuple[dict, dict]:
         argument_specs_yml: pathlib.Path = list(meta.glob("argument_specs.y*ml"))[0]
         with open(argument_specs_yml, "r", encoding="utf-8") as f:
             try:
-                argument_specs = yaml.safe_load(f)
-            except yaml.YAMLError:
+                argument_specs = yaml.load(f)
+            except YAMLError:
                 typer.echo("Not a valid YAML file: meta/argument_specs.y[a]ml")
             try:
                 argument_specs = argument_specs.get("argument_specs", {})
@@ -76,8 +83,8 @@ def parse_meta(ctx: typer.Context) -> tuple[dict, dict]:
 
     with open(main_yml, "r", encoding="utf-8") as f:
         try:
-            main = yaml.safe_load(f)
-        except yaml.YAMLError as exc:
+            main = yaml.load(f)
+        except YAMLError as exc:
             typer.echo("Not a valid YAML file: meta/main.y[a]ml")
             raise typer.Exit(1) from exc
         if not argument_specs:
@@ -104,7 +111,7 @@ def parse_collection(ctx: typer.Context) -> dict:
         galaxy_yml = galaxy_files[0]
 
         with open(galaxy_yml, "r", encoding="utf-8") as f:
-            collection = yaml.safe_load(f)
+            collection = yaml.load(f)
 
         return collection
     return {}
@@ -171,7 +178,7 @@ def parse_options(ctx: typer.Context) -> dict:
                 details["display_required"] = (
                     "yes" if details.get("required", False) else "no"
                 )
-                description = details["description"]
+                description = details["description"] if "description" in details else ""
                 details["display_description"] = (
                     (
                         description
@@ -181,40 +188,41 @@ def parse_options(ctx: typer.Context) -> dict:
                     .replace("\n", " ")
                     .strip()
                 )
-                details["display_type"] = details.get("type", "str")
-                details["display_default"] = ""
-                if details["display_type"] == "bool":
-                    details["display_default"] = (
-                        "true" if details.get("default", False) else "false"
-                    )
-                elif details["display_type"] == "list":
-                    if default := details.get("default", None):
-                        details["display_default"] = json.dumps(default)
-                    if "elements" in details:
-                        if (details["elements"] == "dict") and ("options" in details):
-                            details["display_type"] = (
-                                f"list of dicts of '{option}' options"
-                            )
-                        else:
-                            details["display_type"] = (
-                                "list of '" + details["elements"] + "'"
-                            )
-                elif details["display_type"] == "dict":
-                    if default := details.get("default", None):
-                        details["display_default"] = json.dumps(default)
+
+                display_type = details.get("type", "str")
+
+                if display_type == "list":
+                    elements = details.get("elements", "")
+                    if elements == "dict" and "options" in details:
+                        display_type = f"list of dicts of '{option}' options"
+                    else:
+                        display_type = f"list of '{elements}'"
+                elif display_type == "dict":
                     if "options" in details:
-                        details["display_type"] = f"dict of '{option}' options"
-                elif details["display_type"] == "str":
-                    try:
-                        details["display_default"] = details.get("default", "").strip()
-                    except AttributeError as exc:
-                        typer.echo(
-                            f"The default value of the argument {option} "
-                            f"is of type {type(details.get('default')).__name__}, need str",
+                        display_type = f"dict of '{option}' options"
+
+                details["display_type"] = display_type
+
+                if "default" in details:
+                    default_value = details.get("default", "")
+                    details["display_default"] = str(default_value).strip()
+
+                    if display_type in ["list", "dict"]:
+                        details["display_default"] = (
+                            json.dumps(default_value) if default_value else ""
                         )
-                        raise typer.Exit(code=1) from exc
+
+                    elif display_type == "str":
+                        if not isinstance(default_value, str):
+                            typer.echo(
+                                f"The default value of the argument {option} "
+                                f"is of type {type(default_value).__name__}, need str",
+                            )
+                            raise typer.Exit(1)
+
                 else:
-                    details["display_default"] = str(details.get("default", "")).strip()
+                    details["display_default"] = ""
+
         entrypoint_options[entrypoint] = gathered_options
 
     return entrypoint_options

aar_doc/defaults.py

@@ -8,7 +8,7 @@
 from dataclasses import dataclass, field
 from os import linesep
 from pathlib import Path
-from typing import Any
+from typing import Any, Union
 
 from ruamel.yaml import YAML
 from ruamel.yaml.comments import CommentedMap
@@ -28,7 +28,7 @@ class RoleDefault:
 
     name: str
     value: Any
-    description: str
+    description: Union[str, list[str]]
 
 
 @dataclass
@@ -56,15 +56,14 @@ def add_default(
         self,
         name: str,
         value: Any,
-        description: str = "No description provided.",
+        description: Union[str, list],
     ) -> None:
         """Add a default.
 
         Args:
             name (str): Variable name of the default.
             value (Any): Value of the default.
             description (str, optional): Description of the default.
-            Defaults to "No description provided.".
         """
         if isinstance(value, str):
             value = value.strip()
@@ -87,10 +86,18 @@ def to_commented_map(self) -> CommentedMap:
                 if "\n" in value:
                     value = LiteralScalarString(value)
             commented_defaults[role_default.name] = value
-            commented_defaults.yaml_set_comment_before_after_key(
-                role_default.name,
-                role_default.description,
+            description_items = (
+                role_default.description
+                if isinstance(role_default.description, list)
+                else [role_default.description]
             )
+
+            for description_item in description_items:
+                commented_defaults.yaml_set_comment_before_after_key(
+                    key=role_default.name,
+                    before=description_item,
+                )
+
         return commented_defaults
 
 
@@ -102,7 +109,7 @@ def generate_commented_defaults(
     defaults_manager = RoleDefaultsManager(overwrite_duplicate_defaults)
 
     for entry_point in argument_spec_data:
-        options = argument_spec_data.get(entry_point, {}).get("options")
+        options: dict[str, Any] = argument_spec_data.get(entry_point, {}).get("options")
         if not options:
             continue
         for name, spec in options.items():

pyproject.toml

@@ -13,7 +13,6 @@ documentation = "https://github.com/telekom-mms/aar_doc/"
 python = "^3.9"
 click = "^8.1.3"
 Jinja2 = "^3.1.2"
-PyYAML = "^6.0"
 typer = "^0.12.0"
 ruamel-yaml = "^0.18.6"
 
@@ -22,7 +21,6 @@ black = "^24.0.0"
 mypy = "^1.0.0"
 pytest = "^8.0.0"
 pytest-cov = "^5.0.0"
-types-PyYAML = "^6.0.12"
 isort = "^5.10.1"
 
 [tool.poetry.scripts]
@@ -31,7 +29,6 @@ aar-doc = "aar_doc.cli:app"
 [tool.poetry.group.dev.dependencies]
 pylint = "^3.3.1"
 pre-commit = "^4.0.0"
-types-pyyaml = "^6.0.12.20240917"
 
 [tool.pytest.ini_options]
 addopts = [

tests/fixtures/roles/extended/README.md

@@ -67,8 +67,8 @@ The list entry point for the extended role.
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | list_int | A list of ints | list of 'int' | no | [1, 2, 3] |
-| list_str | A list of strings | list of 'str' | no | ["foo", "bar", "baz"] |
-| list_dict | A list of dicts | list of 'dict' | no | [{"dict": {"foo": "bar"}}, {"dict": {"one": 1, "two": 2}}] |
+| list_str | A list of strings | list of 'str' | no | ['foo', 'bar', 'baz'] |
+| list_dict | A list of dicts | list of 'dict' | no | [{'dict': {'foo': 'bar'}}, {'dict': {'one': 1, 'two': 2}}] |
 
 
 
@@ -112,10 +112,10 @@ The bool entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
-| bool_true | A true boolean value | bool | no | true |
-| bool_false | A false boolean value | bool | no | false |
-| bool_yes | A truthy boolean value | bool | no | true |
-| bool_no | A falsy boolean value | bool | no | false |
+| bool_true | A true boolean value | bool | no | True |
+| bool_false | A false boolean value | bool | no | False |
+| bool_yes | A truthy boolean value | bool | no | yes |
+| bool_no | A falsy boolean value | bool | no | no |
 
 
 

tests/fixtures/roles/generate_defaults/defaults/main.yml

@@ -21,6 +21,7 @@ generate_defaults_truthy_false_string: 'false'
 # A umask string value
 generate_defaults_umask: '0755'
 # A list value
+# with a list description with a rather long description, maybe too long.
 generate_defaults_list:
   - value1
   - value2
@@ -32,6 +33,7 @@ generate_defaults_dict:
   value3: third value
 # A string value that can be overwritten
 generate_defaults_overwrite: original value
+generate_defaults_no_description: foo
 # A multiline string value
 generate_defaults_str_multiline: |-
   This is a multi line string.

tests/fixtures/roles/generate_defaults/defaults/overwrite.yml

@@ -21,6 +21,7 @@ generate_defaults_truthy_false_string: 'false'
 # A umask string value
 generate_defaults_umask: '0755'
 # A list value
+# with a list description with a rather long description, maybe too long.
 generate_defaults_list:
   - value1
   - value2
@@ -32,6 +33,7 @@ generate_defaults_dict:
   value3: third value
 # A string value that was overwritten
 generate_defaults_overwrite: overwritten value
+generate_defaults_no_description: foo
 # A multiline string value
 generate_defaults_str_multiline: |-
   This is a multi line string.

tests/fixtures/roles/generate_defaults/meta/argument_specs.yml

@@ -49,7 +49,9 @@ argument_specs:
           - value1
           - value2
           - value3
-        description: A list value
+        description:
+          - A list value
+          - with a list description with a rather long description, maybe too long.
       generate_defaults_dict:
         type: dict
         default:
@@ -65,6 +67,10 @@ argument_specs:
         type: str
         required: true
         description: An option without a default
+      generate_defaults_no_description:
+        type: str
+        required: true
+        default: "foo"
   alternate:
     short_description: The alternate entry point for the defaults role.
     options:

tests/fixtures/roles/meta_main_yaml/README.md

@@ -57,8 +57,8 @@ The list entry point for the extended role.
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | list_int | A list of ints | list of 'int' | no | [1, 2, 3] |
-| list_str | A list of strings | list of 'str' | no | ["foo", "bar", "baz"] |
-| list_dict | A list of dicts | list of 'dict' | no | [{"dict": {"foo": "bar"}}, {"dict": {"one": 1, "two": 2}}] |
+| list_str | A list of strings | list of 'str' | no | ['foo', 'bar', 'baz'] |
+| list_dict | A list of dicts | list of 'dict' | no | [{'dict': {'foo': 'bar'}}, {'dict': {'one': 1, 'two': 2}}] |
 
 
 
@@ -102,10 +102,10 @@ The bool entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
-| bool_true | A true boolean value | bool | no | true |
-| bool_false | A false boolean value | bool | no | false |
-| bool_yes | A truthy boolean value | bool | no | true |
-| bool_no | A falsy boolean value | bool | no | false |
+| bool_true | A true boolean value | bool | no | True |
+| bool_false | A false boolean value | bool | no | False |
+| bool_yes | A truthy boolean value | bool | no | yes |
+| bool_no | A falsy boolean value | bool | no | no |