inference-model 2.0.12__py3-none-any.whl

inference_model/utils/documentation_helper/exporters/__init__.py

@@ -0,0 +1,176 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List, Type
+
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+
+from inference_model.utils.documentation_helper.model import (
+    LeaveSetting,
+    NestingSetting,
+    RootSetting,
+)
+
+
+class ExporterBase(BaseModel, ABC):
+    """
+    A Base class to create setting exporters for different formats from.
+    """
+
+    root_setting: RootSetting
+
+    def __init__(
+        self,
+        setting_cls: Type[BaseSettings],
+        cls: Type[RootSetting] = RootSetting,
+        **kwargs
+    ) -> None:
+        """
+        Initialize the object.
+
+        :param setting_cls: Each setting exporter requires a setting class to export from.
+        :param cls:
+            In case we would want to use a custom cls, we can pass it here.
+            RootSetting should be fine in most cases though.
+        """
+        super().__init__(root_setting=cls(setting_cls=setting_cls), **kwargs)
+
+    @staticmethod
+    def _header_translation_dict() -> Dict[str, str]:
+        """
+        Return a dictionary to translate the pydantic-parameters to the values that should be used in the export.
+
+        This method may be overridden to create custom naming.
+        It is provided, however, to allow different formats to be similar in naming,
+        thus, providing a naming-convention.
+        :return:
+            A Dictionary with the translation.
+            The key is the pydantic-parameter, the value is the export-parameter.
+        """
+        return {
+            "full_env_name": "Environment Variable",
+            "description": "Description",
+            "default": "Default Value",
+            "annotation_string": "Type",
+            "required": "required",
+        }
+
+    def _max_leave_param_length(
+        self, leave_settings: List[LeaveSetting], include_header_length: bool
+    ) -> Dict[str, int]:
+        """
+        Calculate the maximum length of each parameter in the leave_settings.
+
+        Some exporters may want to have a fixed width for each column.
+        This is a helper-function to calculate the length of those columns.
+        :param leave_settings: A list of leave-settings to calculate the maximum length of each parameter from.
+        :param include_header_length: Weather to include the header length in the calculation.
+        :return:
+            A dictionary with the maximum length of each parameter.
+            The key is the pydantic-parameter, the value is the maximum length.
+        """
+        if not include_header_length:
+            max_lengths: Dict[str, int] = {
+                "full_env_name": 0,
+                "description": 0,
+                "default": 0,
+                "annotation_string": 0,
+                "required": 0,
+            }
+        else:
+            max_lengths: Dict[str, int] = {
+                param: len(header)
+                for param, header in self._header_translation_dict().items()
+            }
+
+        for leave_setting in leave_settings:
+            for parameter, max_length in max_lengths.items():
+                length: int = len(str(getattr(leave_setting, parameter)))
+                if length > max_length:
+                    max_lengths[parameter] = length
+
+        return max_lengths
+
+    @abstractmethod
+    def _export_leaves_to_string(self, leave_settings: List[LeaveSetting]) -> str:
+        """
+        Export the leave-settings to a string.
+
+        This method should be implemented by the child-class, since it is format-specific.
+        :param leave_settings: A list of leave-settings to export.
+        :return: The exported string.
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def _export_nesting_header_to_string(self, nesting_setting: NestingSetting) -> str:
+        """
+        Export the flat nesting-settings to a string.
+
+        This method will only export the header, description, etc., but NOT sub-settings!
+        This method should be implemented by the child-class, since it is format-specific.
+        :param nesting_setting: The nesting-setting to export.
+        :return: The exported string.
+        """
+        raise NotImplementedError()
+
+    def _export_full_nesting_to_string(self, nesting_setting: NestingSetting) -> str:
+        """
+        Export the full nesting-settings to a string.
+
+        This method will only export the header, description, etc., AND sub-settings!
+
+        This method may be overridden to create custom naming.
+        It is provided, however, to allow different formats to be similar in naming,
+        thus, providing a naming-convention.
+
+        Generally, A nested setting is exported by exporting:
+        - Header, description, etc. by calling _export_nesting_header_to_string.
+        - Leaves-settings by calling _export_leaves_to_string.
+        - Nesting-settings by calling _export_full_nesting_to_string.
+
+        :param nesting_setting: The nesting-setting to export.
+        :return: The exported string.
+        """
+        string: str = self._export_nesting_header_to_string(
+            nesting_setting=nesting_setting
+        )
+        string += self._export_leaves_to_string(
+            leave_settings=list(nesting_setting.sub_leave_settings)
+        )
+        for sub_nesting_setting in nesting_setting.sub_nesting_settings:
+            string += self._export_full_nesting_to_string(
+                nesting_setting=sub_nesting_setting
+            )
+        return string
+
+    def export(self) -> str:
+        """
+        Export the settings to a string.
+
+        :return: The exported string.
+        """
+        export: str = (
+            self._export_full_nesting_to_string(
+                nesting_setting=self.root_setting
+            ).strip()
+            + "\n"
+        )
+
+        return "\n".join([line.rstrip() for line in export.split("\n")])
+
+    def __str__(self) -> str:
+        """
+        Return the exported string.
+
+        :return: The exported string.
+        """
+        return self.export()
+
+    def save(self, filename: str) -> None:
+        """
+        Save the exported string to a file.
+
+        :param filename: The filename to save the exported string to.
+        """
+        with open(filename, "w") as f:
+            f.write(str(self))

inference_model/utils/documentation_helper/exporters/collapsible_markdown_exporter.py

@@ -0,0 +1,49 @@
+from typing import List
+
+from inference_model.utils.documentation_helper.exporters.markdown_exporter import (
+    MarkdownExporter,
+)
+from inference_model.utils.documentation_helper.model import LeaveSetting
+
+
+class CollapsibleMarkdownExporter(MarkdownExporter):
+    """
+    Another Markdown format.
+
+    Leaves are collapsible Headers to make documentations with long descriptions more readable.
+    """
+
+    def _export_leaves_to_string(self, leave_settings: List[LeaveSetting]) -> str:
+        """
+        Overwrite the method to export the leaves in a collapsible format.
+
+        :param leave_settings: The list of leave-settings to export.
+        :return: The string representation of the leave-settings.
+        """
+        export_strings: List[str] = []
+        for leave_setting in leave_settings:
+            export_string: str = "<details>\n"
+            export_string += f"    <summary>{leave_setting.full_env_name}</summary>\n"
+            export_string += "    <table>\n"
+
+            for param, header in self._header_translation_dict().items():
+                if param == "description" or param == "full_env_name":
+                    # Skipping those, since they are already contained elsewhere.
+                    continue
+
+                export_string += "        <tr>\n"
+                export_string += f"            <td>{header}</td>\n"
+                export_string += (
+                    f"            <td>{getattr(leave_setting, param)}</td>\n"
+                )
+                export_string += "        </tr>\n"
+
+            export_string += "    </table>\n"
+            if leave_setting.description:
+                export_string += f"    {leave_setting.description}\n"
+            export_string += "</details>"
+            export_string += "\n\n"
+
+            export_strings.append(export_string)
+
+        return "".join(export_strings)

inference_model/utils/documentation_helper/exporters/markdown_exporter.py

@@ -0,0 +1,77 @@
+from typing import Dict, List
+
+from inference_model.utils.documentation_helper.exporters import ExporterBase
+from inference_model.utils.documentation_helper.model import (
+    LeaveSetting,
+    NestingSetting,
+)
+
+
+class MarkdownExporter(ExporterBase):
+    """
+    A class to export the settings to a Markdown format.
+    """
+
+    def _export_leaves_to_string(self, leave_settings: List[LeaveSetting]) -> str:
+        """
+        Export the leave-settings to a string as a Markdown table.
+
+        :param leave_settings: A list of leave-settings to export.
+        :return: The exported string
+        """
+        # We want the table to be formatted properly. This includes that the columns have a fixed width.
+        # Each column may have a different width, but the width of each column should be the same for each row.
+        # We calculate the maximum length of each column and use this to format the table.
+        max_param_lengths: Dict[str, int] = self._max_leave_param_length(
+            leave_settings=leave_settings, include_header_length=True
+        )
+
+        # We are building the header of the table.
+        header: str = " | ".join(
+            [
+                self._header_translation_dict().get(param).ljust(length)
+                for param, length in max_param_lengths.items()
+            ]
+        )
+        header = f"| {header} |"
+
+        # The header is separated from the rows by a seperator.
+        seperator: str = "|".join(
+            "-" * (length + 2) for length in max_param_lengths.values()
+        )
+        seperator = f"|{seperator}|"
+
+        # We are building the rows of the table.
+        rows: List[str] = [
+            " | ".join(
+                [
+                    str(getattr(leave_setting, param)).ljust(length)
+                    for param, length in max_param_lengths.items()
+                ]
+            )
+            for leave_setting in leave_settings
+        ]
+        rows = [f"| {row} |" for row in rows]
+
+        # finally we join the header, seperator and rows to a single string
+        return "\n".join([header, seperator] + rows) + "\n\n"
+
+    def _export_nesting_header_to_string(self, nesting_setting: NestingSetting) -> str:
+        """
+        Export the flat nesting-settings to a string (as a markdown header with some text).
+
+        This method will only export the header, description, etc., but NOT sub-settings!
+        :param nesting_setting: The nesting-setting to export.
+        :return: The exported string.
+        """
+        # Create a new Markdown header.
+        expected_string: str = (
+            "#" * (nesting_setting.nesting_count + 1)
+            + f" {nesting_setting.full_env_name}\n\n"
+        )
+
+        # Optionally add the description if given.
+        if nesting_setting.description:
+            expected_string += f"{nesting_setting.description}\n\n"
+
+        return expected_string

inference_model/utils/documentation_helper/model.py

@@ -0,0 +1,353 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Iterator, Optional, Type
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
+from pydantic_settings import BaseSettings
+
+
+class Setting(BaseModel, ABC):
+    """
+    All information regarding a settings-parameter.
+    """
+
+    prefix_: Optional[str]
+    setting_name: str
+    root_model_config: Dict[str, Any]
+    nesting_count: int
+
+    def __init__(
+        self,
+        prefix: Optional[str],
+        setting_name: str,
+        root_model_config: Dict[str, Any],
+        nesting_count: int,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize the setting.
+
+        :param prefix: The prefix of the setting including suffixed nested-delimiter.
+        :param setting_name: The name of the setting excluding the prefix or nested-delimiter.
+        :param root_model_config:
+            The model config as defined in RootSetting, since model_config gets passed down the tree.
+        :param nesting_count: The nesting count of the setting. Root=0, Nesting=1, ..., Leave=n.
+        """
+        if prefix is None and nesting_count != 0:
+            raise ValueError("prefix is None but nesting_count is not 0")
+        if root_model_config.get("env_nested_delimiter") is None:
+            raise ValueError("env_nested_delimiter is not set in model_config")
+        if setting_name is None:
+            raise ValueError("setting_name is empty")
+
+        super().__init__(
+            prefix_=prefix,
+            setting_name=setting_name,
+            root_model_config=root_model_config,
+            nesting_count=nesting_count,
+            **kwargs,
+        )
+
+    @property
+    def env_nested_delimiter(self) -> str:
+        """
+        Return the env_nested_delimiter of the current setting.
+
+        When configuring the settings using environment-variable, we need to know the delimiter.
+        :return: The env_nested_delimiter of the current setting.
+        """
+        return self.root_model_config.get("env_nested_delimiter")
+
+    @property
+    def prefix(self) -> str:
+        """
+        Return the full prefix of the current setting.
+
+        The prefix is the full path to the current setting, including all parent settings.
+        The prefix will be upper-cased, when it is not case-sensitive.
+        :return: The full prefix of the current setting.
+        """
+        if self.prefix_ is None:
+            return ""
+
+        # At the root level, the env-prefix, will not be suffixed with the nested-delimiter.
+        # Since the env-prefix will be the setting-name at nesting_count 0,
+        # and the prefix_ at nesting_count 1, we need to skip adding nested-delimiter at nesting_count 0 and 1.
+        if self.nesting_count > 1:
+            prefix: str = f"{self.prefix_}{self.env_nested_delimiter}"
+        else:
+            prefix: str = self.prefix_
+
+        if self.root_model_config.get("case_sensitive"):
+            return prefix
+        else:
+            return prefix.upper()
+
+    @property
+    def full_env_name(self) -> str:
+        """
+        Return the full_env_name of the current setting including all parent prefixes, delimiter and setting_name.
+
+        The full_env_name will be upper-cased, when it is not case-sensitive.
+        :return: The full_env_name of the current setting.
+        """
+        full_env_name: str = f"{self.prefix}{self.setting_name}"
+        if self.root_model_config.get("case_sensitive"):
+            return full_env_name
+        else:
+            return full_env_name.upper()
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """
+        Return the description of the current setting.
+
+        The description is the description of the current setting.
+        :return: The description of the current setting.
+        """
+        raise NotImplementedError()
+
+    @classmethod
+    def is_nesting(cls) -> bool:
+        """
+        Determine if this setting could contain sub-settings.
+
+        Note: An empty BaseSetting will not contain any sub-settings, yet it will be considered nesting.
+        This is intentional.
+        :return: True if there could be a sub-settings, False otherwise.
+        """
+        return issubclass(cls, NestingSetting)
+
+
+class LeaveSetting(Setting):
+    """
+    A LeaveSetting, which is a setting that does not contain other settings (is a leave).
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    field_info: FieldInfo
+
+    def __init__(
+        self,
+        prefix: Optional[str],
+        setting_name: str,
+        root_model_config: Dict[str, Any],
+        nesting_count: int,
+        field_info: FieldInfo,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize the leave-setting.
+
+        :param prefix: The prefix of the setting including suffixed nested-delimiter.
+        :param setting_name: The name of the setting excluding the prefix or nested-delimiter.
+        :param root_model_config:
+            The model config as defined in RootSetting, since model_config gets passed down the tree.
+        :param nesting_count: The nesting count of the setting. Root=0, Nesting=1, ..., Leave=n.
+        :param field_info: The field-info-object from pydantic containing further information of the setting.
+        """
+        super().__init__(
+            prefix=prefix,
+            root_model_config=root_model_config,
+            setting_name=setting_name,
+            nesting_count=nesting_count,
+            field_info=field_info,
+            **kwargs,
+        )
+
+    @property
+    def description(self) -> str:
+        """
+        Return the description of the current setting.
+
+        The description is the description of the current setting.
+        :return: The description of the current setting.
+        """
+        return (self.field_info.description or "").strip()
+
+    @property
+    def annotation(self) -> Type[Any]:
+        """
+        Return the annotation of the current setting.
+
+        The annotation is the type of the current setting.
+        :return: The annotation of the current setting.
+        """
+        return self.field_info.annotation
+
+    @property
+    def annotation_string(self) -> str:
+        """
+        Return a string-representation fo the annotation.
+
+        :return: The string-representation of the annotation.
+        """
+        return (
+            str(self.annotation)
+            .replace("typing.", "")
+            .replace("class ", "")
+            .replace("'", "")
+            .replace("<", "")
+            .replace(">", "")
+        ).strip()
+
+    @property
+    def required(self) -> bool:
+        """
+        Return if the setting is required.
+
+        :return: True if the setting is required, False otherwise
+        """
+        return self.field_info.is_required()
+
+    @property
+    def default(self) -> str:
+        """
+        Return the default value of the setting.
+
+        :return: The default value of the setting.
+        """
+        if self.field_info.default != PydanticUndefined:
+            return str(self.field_info.default)
+        elif self.field_info.default_factory:
+            return "Created by a default-factory."
+        else:
+            return "---"
+
+
+class NestingSetting(Setting):
+    """
+    ANestingSetting, which is a setting that contains other settings (is nesting).
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    field_infos: Dict[str, FieldInfo]
+    description_: str
+
+    def __init__(
+        self,
+        prefix: Optional[str],
+        setting_name: str,
+        root_model_config: Dict[str, Any],
+        nesting_count: int,
+        field_infos: Dict[str, FieldInfo],
+        description: str,
+        **kwargs,
+    ) -> None:
+        """
+        Initialize the nesting-setting.
+
+        :param prefix: The prefix of the setting including suffixed nested-delimiter.
+        :param setting_name: The name of the setting excluding the prefix or nested-delimiter.
+        :param root_model_config:
+            The model config as defined in RootSetting, since model_config gets passed down the tree.
+        :param nesting_count: The nesting count of the setting. Root=0, Nesting=1, ..., Leave=n.
+        :param field_infos: The field-infos of the sub-settings.
+        :param description: The description of the nesting-setting.
+        """
+        super().__init__(
+            prefix=prefix,
+            setting_name=setting_name,
+            root_model_config=root_model_config,
+            nesting_count=nesting_count,
+            field_infos=field_infos,
+            description_=description,
+            **kwargs,
+        )
+
+    @property
+    def description(self) -> str:
+        """
+        Return the description of the current setting.
+
+        :return: The description of the current setting.
+        """
+        return self.description_.strip()
+
+    @property
+    def sub_leave_settings(self) -> Iterator[LeaveSetting]:
+        """
+        Return the sub-settings of the current setting (only leave settings).
+
+        This is a generator. When you want to make length-checks or reuse the iterator,
+        use list(setting.nested_settings) to make it a list.
+        :return: The sub-settings of the current setting (only leave settings).
+        """
+        for field_name, field in self.field_infos.items():
+            if issubclass(type(field.annotation), type) and issubclass(
+                field.annotation, BaseSettings
+            ):
+                continue
+            yield LeaveSetting(
+                prefix=self.full_env_name,
+                root_model_config=self.root_model_config,
+                field_info=field,
+                setting_name=field_name,
+                nesting_count=self.nesting_count + 1,
+            )
+
+    @property
+    def sub_nesting_settings(self) -> Iterator["NestingSetting"]:
+        """
+        Return the sub-settings of the current setting (only nesting settings).
+
+        This is a generator. When you want to make length-checks or reuse the iterator,
+        use list(setting.nested_settings) to make it a list.
+        :return: The sub-settings of the current setting (only nesting settings).
+        """
+        for field_name, field in self.field_infos.items():
+            if not (
+                issubclass(type(field.annotation), type)
+                and issubclass(field.annotation, BaseSettings)
+            ):
+                continue
+            yield NestingSetting(
+                prefix=self.full_env_name,
+                root_model_config=self.root_model_config,
+                field_infos=field.annotation.model_fields,
+                setting_name=field_name,
+                nesting_count=self.nesting_count + 1,
+                # A nested-setting may get a description by the class-docstring, or by the field-description.
+                # We will combine both, if they are not empty.
+                description=f"{(field.description or '').strip()}\n\n"
+                f"{(field.annotation.__doc__ or '').strip()}".strip(),
+            )
+
+    @property
+    def sub_settings(self) -> Iterator[Setting]:
+        """
+        Return the sub-settings of the current setting (all settings).
+
+        This is a generator. When you want to make length-checks or reuse the iterator,
+        use list(setting.nested_settings) to make it a list.
+        :return: The sub-settings of the current setting (all settings).
+        """
+        for sub_setting in self.sub_leave_settings:
+            yield sub_setting
+        for sub_setting in self.sub_nesting_settings:
+            yield sub_setting
+
+
+class RootSetting(NestingSetting):
+    """
+    The root-setting, which is the entry-point for the settings-configuration.
+    """
+
+    def __init__(self, setting_cls: Type[BaseSettings]) -> None:
+        """
+        Initialize the root-setting.
+
+        :param setting_cls: The class of the root-setting. Must be a child of BaseSetting.
+        """
+        super().__init__(
+            prefix=None,
+            setting_name=setting_cls.model_config.get("env_prefix"),
+            root_model_config=setting_cls.model_config,
+            nesting_count=0,
+            field_infos=setting_cls.model_fields,
+            description=setting_cls.__doc__ or "",
+        )