pydantic-settings-export 0.1.0__tar.gz

pydantic_settings_export-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jag_k
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydantic_settings_export-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.1
+Name: pydantic-settings-export
+Version: 0.1.0
+Summary: Export your Pydantic settings to a Markdown and .env.example files!
+Home-page: https://github.com/jag-k/pydantic-settings-export#readme
+License: MIT
+Author: Jag_k
+Author-email: jag-k@users.noreply.github.com
+Requires-Python: >=3.11,<4.0
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Dist: pydantic (>=2,<3)
+Requires-Dist: pydantic-settings (>=2,<3)
+Project-URL: Repository, https://github.com/jag-k/pydantic-settings-export
+Description-Content-Type: text/markdown
+
+# pydantic-settings-export
+
+[![PyPI version](https://img.shields.io/pypi/v/pydantic-settings-export?logo=pypi&label=pydantic-settings-export)](https://pypi.org/project/pydantic-settings-export/)
+
+*Export your Pydantic settings to a Markdown and .env.example files!*
+
+This package provides a way to use [pydantic](https://docs.pydantic.dev/) (and [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)) models to generate a Markdown file with the settings and their descriptions, and a `.env.example` file with the settings and their default values.
+
+## Installation
+
+```bash
+pip install pydantic-settings-export
+# or
+pipx install pydantic-settings-export  # for a global installation and using as a CLI
+```
+
+## Usage
+
+You can see the examples of usage this package in the [./docs/Configuration.md](./docs/Configuration.md) and [.env.example](./.env.example).
+
+### As code
+
+```python
+from pydantic import BaseSettings
+from pydantic_settings_export import Exporter, MarkdownSettings, Settings as PSESettings
+
+
+class Settings(BaseSettings):
+  my_setting: str = "default value"
+  another_setting: int = 42
+
+
+# Export the settings to a Markdown file `docs/Configuration.md` and `.env.example` file
+Exporter(
+  PSESettings(
+    markdown=MarkdownSettings(
+      save_dirs=["docs"],
+    ),
+  ),
+).run_all(Settings)
+```
+
+### As CLI
+
+```bash
+pydantic-settings-export --help
+```
+
+## Configuration
+
+You can add a `pydantic_settings_export` section to your `pyproject.toml` file to configure the exporter.
+
+```toml
+
+[tool.pydantic_settings_export]
+project_dir = "."
+default_settings = [
+  "pydantic_settings_export.settings:Settings",
+]
+dotenv = { "name" = ".env.example" }
+
+[tool.pydantic_settings_export.markdown]
+name = "Configuration.md"
+save_dirs = [
+  "docs",
+  "wiki",
+]
+```
+
+## Todo
+
+- [ ] Add tests
+- [ ] Add more configuration options
+- [ ] Add more output formats
+  - [ ] TOML (and `pyproject.toml`)
+  - [ ] JSON
+  - [ ] YAML
+
+
+## License
+
+[MIT](./LICENCE)
+

pydantic_settings_export-0.1.0/README.md

@@ -0,0 +1,82 @@
+# pydantic-settings-export
+
+[![PyPI version](https://img.shields.io/pypi/v/pydantic-settings-export?logo=pypi&label=pydantic-settings-export)](https://pypi.org/project/pydantic-settings-export/)
+
+*Export your Pydantic settings to a Markdown and .env.example files!*
+
+This package provides a way to use [pydantic](https://docs.pydantic.dev/) (and [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)) models to generate a Markdown file with the settings and their descriptions, and a `.env.example` file with the settings and their default values.
+
+## Installation
+
+```bash
+pip install pydantic-settings-export
+# or
+pipx install pydantic-settings-export  # for a global installation and using as a CLI
+```
+
+## Usage
+
+You can see the examples of usage this package in the [./docs/Configuration.md](./docs/Configuration.md) and [.env.example](./.env.example).
+
+### As code
+
+```python
+from pydantic import BaseSettings
+from pydantic_settings_export import Exporter, MarkdownSettings, Settings as PSESettings
+
+
+class Settings(BaseSettings):
+  my_setting: str = "default value"
+  another_setting: int = 42
+
+
+# Export the settings to a Markdown file `docs/Configuration.md` and `.env.example` file
+Exporter(
+  PSESettings(
+    markdown=MarkdownSettings(
+      save_dirs=["docs"],
+    ),
+  ),
+).run_all(Settings)
+```
+
+### As CLI
+
+```bash
+pydantic-settings-export --help
+```
+
+## Configuration
+
+You can add a `pydantic_settings_export` section to your `pyproject.toml` file to configure the exporter.
+
+```toml
+
+[tool.pydantic_settings_export]
+project_dir = "."
+default_settings = [
+  "pydantic_settings_export.settings:Settings",
+]
+dotenv = { "name" = ".env.example" }
+
+[tool.pydantic_settings_export.markdown]
+name = "Configuration.md"
+save_dirs = [
+  "docs",
+  "wiki",
+]
+```
+
+## Todo
+
+- [ ] Add tests
+- [ ] Add more configuration options
+- [ ] Add more output formats
+  - [ ] TOML (and `pyproject.toml`)
+  - [ ] JSON
+  - [ ] YAML
+
+
+## License
+
+[MIT](./LICENCE)

pydantic_settings_export-0.1.0/pydantic_settings_export/__init__.py

@@ -0,0 +1,7 @@
+from .constants import *
+from .exporter import *
+from .generators import *
+from .models import *
+from .settings import *
+from .utils import *
+from .version import __version__, __version_tuple__

pydantic_settings_export-0.1.0/pydantic_settings_export/cli.py

@@ -0,0 +1,111 @@
+import argparse
+
+from collections.abc import Sequence
+from inspect import isclass
+from pathlib import Path
+from typing import Any
+
+from pydantic_settings import BaseSettings
+
+from pydantic_settings_export.exporter import Exporter
+from pydantic_settings_export.generators import ALL_GENERATORS, AbstractGenerator
+from pydantic_settings_export.settings import Settings
+from pydantic_settings_export.utils import ObjectImportAction
+from pydantic_settings_export.version import __version__
+
+
+CDW = Path.cwd()
+
+
+class SettingsAction(ObjectImportAction):
+    """The settings action."""
+
+    @staticmethod
+    def callback(obj: Any) -> type[BaseSettings]:
+        """Check if the object is a settings class."""
+        if isclass(obj) and issubclass(obj, BaseSettings):
+            return obj
+        elif not isclass(obj) and isinstance(obj, BaseSettings):
+            return obj.__class__
+        raise ValueError(f"The {obj!r} is not a settings class.")
+
+
+class GeneratorAction(ObjectImportAction):
+    """The generator action."""
+
+    @staticmethod
+    def callback(obj: Any) -> type[AbstractGenerator]:
+        """Check if the object is a settings class."""
+        if isclass(obj) and issubclass(obj, AbstractGenerator):
+            return obj
+        elif not isclass(obj) and isinstance(obj, AbstractGenerator):
+            return obj.__class__
+        raise ValueError(f"The {obj!r} is not a generator class.")
+
+
+def dir_type(path: str) -> Path:
+    """Check if the path is a directory."""
+    p = Path(path).resolve().absolute()
+    if p.is_dir():
+        return p
+    raise argparse.ArgumentTypeError(f"The {path} is not a directory.")
+
+
+parser = argparse.ArgumentParser(
+    description="Export pydantic settings to a file",
+)
+parser.add_argument(
+    "--version",
+    "-v",
+    action="version",
+    version=f"pydantic-settings-export {__version__}",
+)
+
+parser.add_argument(
+    "--project-dir",
+    "-d",
+    default=CDW,
+    type=dir_type,
+    help="The project directory. (default: current directory)",
+)
+parser.add_argument(
+    "--config-file",
+    "-c",
+    default=CDW / "pyproject.toml",
+    type=argparse.FileType("rb"),
+    help="Path to `pyproject.toml` file. (default: ./pyproject.toml)",
+)
+parser.add_argument(
+    "--generator",
+    "-g",
+    default=ALL_GENERATORS,
+    action=GeneratorAction,
+    help=f"The generator class or object to use. (default: [{', '.join(g.__name__ for g in ALL_GENERATORS)}])",
+)
+parser.add_argument(
+    "settings",
+    nargs="*",
+    action=SettingsAction,
+    help="The settings classes or objects to export.",
+)
+
+
+def main(parse_args: Sequence[str] | None = None):  # noqa: D103
+    args = parser.parse_args(parse_args)
+    s = Settings.from_pyproject(args.config_file)
+
+    s.project_dir = args.project_dir
+    s.generators = args.generator
+    settings = s.default_settings or args.settings
+    if not settings:
+        parser.exit(0, parser.format_help())
+
+    result = Exporter(s).run_all(*settings)
+    if result:
+        files = "\n".join(f"- {r}" for r in result)
+        parser.exit(0, f"Generated files ({len(result)}): \n{files}\n")
+    parser.exit(0, "No files generated.\n")
+
+
+if __name__ == "__main__":
+    main()

pydantic_settings_export-0.1.0/pydantic_settings_export/constants.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+from typing import Annotated
+
+from pydantic import BeforeValidator, SecretStr
+
+
+__all__ = (
+    "StrAsPath",
+    "FIELD_TYPE_MAP",
+)
+
+StrAsPath = Annotated[Path, BeforeValidator(lambda v: Path(v))]
+
+FIELD_TYPE_MAP = {
+    SecretStr: "string",
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+    None: "null",
+}

pydantic_settings_export-0.1.0/pydantic_settings_export/exporter.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+from pydantic_settings_export.generators import AbstractGenerator
+from pydantic_settings_export.models import SettingsInfoModel
+from pydantic_settings_export.settings import Settings
+
+
+__all__ = ("Exporter",)
+
+
+class Exporter:
+    """The exporter for pydantic settings."""
+
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        generators: list[type[AbstractGenerator]] | None = None,
+    ) -> None:
+        self.settings: Settings = settings or Settings.from_pyproject()
+        self.generators: list[type[AbstractGenerator]] = settings.generators if generators is None else generators
+
+    def run_all(self, *settings: BaseSettings | type[BaseSettings]) -> list[Path]:
+        """Run all generators for the given settings.
+
+        :param settings: The settings to generate documentation for.
+        :return: The paths to generated documentations.
+        """
+        settings_infos: list[SettingsInfoModel] = [
+            SettingsInfoModel.from_settings_model(s, self.settings) for s in settings
+        ]
+
+        return [
+            # Run all generators for each setting info
+            path
+            for generator in self.generators
+            for path in generator.run(self.settings, *settings_infos)
+        ]

pydantic_settings_export-0.1.0/pydantic_settings_export/generators/__init__.py

@@ -0,0 +1,6 @@
+from .abstract import *
+from .dotenv import *
+from .markdown import *
+
+
+ALL_GENERATORS: list[type[AbstractGenerator]] = [DotEnvGenerator, MarkdownGenerator]

pydantic_settings_export-0.1.0/pydantic_settings_export/generators/abstract.py

@@ -0,0 +1,58 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from pydantic_settings_export.models import SettingsInfoModel
+from pydantic_settings_export.settings import Settings
+
+
+__all__ = ("AbstractGenerator",)
+
+
+class AbstractGenerator(ABC):
+    """The abstract class for the configuration file generator."""
+
+    def __init__(self, settings: Settings) -> None:
+        """Initialize the AbstractGenerator.
+
+        :param settings: The settings for the generator.
+        """
+        self.settings = settings
+
+    @abstractmethod
+    def generate_single(self, settings_info: SettingsInfoModel, level: int = 1) -> str:
+        """Generate the configuration file content.
+
+        :param settings_info: The settings class to generate documentation for.
+        :param level: The level of nesting. Used for indentation.
+        :return: The generated documentation.
+        """
+        raise NotImplementedError
+
+    def generate(self, *settings_infos: SettingsInfoModel) -> str:
+        """Generate the configuration file content.
+
+        :param settings_infos: The settings info classes to generate documentation for.
+        :return: The generated documentation.
+        """
+        return "\n\n".join(self.generate_single(s).strip() for s in settings_infos).strip() + "\n"
+
+    @abstractmethod
+    def write_to_files(self, generated_result: str) -> list[Path]:
+        """Write the generated content to files.
+
+        :param generated_result: The result to write to files.
+        :return: The list of file paths written to.
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def run(cls, settings: Settings, settings_info: SettingsInfoModel) -> list[Path]:
+        """Run the generator.
+
+        :param settings: The settings for the generator.
+        :param settings_info: The settings info to generate documentation for.
+        :return: The list of file paths written to.
+        """
+        generator = cls(settings)
+        result = generator.generate(settings_info)
+        return generator.write_to_files(result)

pydantic_settings_export-0.1.0/pydantic_settings_export/generators/dotenv.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from pydantic_settings_export.models import SettingsInfoModel
+
+from .abstract import AbstractGenerator
+
+
+__all__ = ("DotEnvGenerator",)
+
+
+class DotEnvGenerator(AbstractGenerator):
+    """The .env example generator."""
+
+    def write_to_files(self, generated_result: str) -> list[Path]:
+        """Write the generated content to files.
+
+        :param generated_result: The result to write to files.
+        :return: The list of file paths written to.
+        """
+        file_path = self.settings.project_dir / self.settings.dotenv.name
+        file_path.write_text(generated_result)
+        return [file_path]
+
+    def generate_single(self, settings_info: SettingsInfoModel, level=1) -> str:
+        """Generate a .env example for a pydantic settings class.
+
+        :param level: The level of nesting. Used for indentation.
+        :param settings_info: The settings class to generate a .env example for.
+        :return: The generated .env example.
+        """
+        result = f"### {settings_info.name}\n\n"
+        for field in settings_info.fields:
+            field_name = f"{settings_info.env_prefix}{field.name.upper()}"
+            field_string = f"{field_name}={field.default}\n"
+
+            if not field.is_required:
+                field_string = f"# {field_string}"
+            result += field_string
+
+        result = result.strip() + "\n\n"
+
+        for child in settings_info.child_settings:
+            result += self.generate_single(child)
+
+        return result

pydantic_settings_export-0.1.0/pydantic_settings_export/generators/markdown.py

@@ -0,0 +1,87 @@
+from pathlib import Path
+from typing import TypedDict
+
+from pydantic_settings_export.models import SettingsInfoModel
+from pydantic_settings_export.utils import make_pretty_md_table_from_dict
+
+from .abstract import AbstractGenerator
+
+
+__all__ = ("MarkdownGenerator",)
+
+
+class TableRowDict(TypedDict):
+    """The table row dictionary."""
+
+    Name: str
+    Type: str
+    Default: str
+    Description: str
+    Example: str | None
+
+
+class MarkdownGenerator(AbstractGenerator):
+    """The Markdown configuration file generator."""
+
+    def generate_single(self, settings_info: SettingsInfoModel, level: int = 1) -> str:  # noqa: C901
+        """Generate Markdown documentation for a pydantic settings class.
+
+        :param settings_info: The settings class to generate documentation for.
+        :param level: The level of nesting. Used for indentation.
+        :return: The generated documentation.
+        """
+        docs = ("\n\n" + settings_info.docs).rstrip()
+
+        # Generate header
+        result = f"{'#' * level} {settings_info.name}{docs}\n\n"
+
+        # Add environment prefix if it exists
+        if settings_info.env_prefix:
+            result += f"**Environment Prefix**: `{settings_info.env_prefix}`\n\n"
+
+        # Generate fields
+        rows: list[TableRowDict] = [
+            TableRowDict(
+                Name=f"`{settings_info.env_prefix}{field.name.upper()}`",
+                Type=f"`{field.type}`",
+                Default=f"`{field.default}`" if not field.is_required else "*required*",
+                Description=field.description,
+                Example=f"`{field.example}`" if field.example else None,
+            )
+            for field in settings_info.fields
+        ]
+
+        if rows:
+            result += make_pretty_md_table_from_dict(rows) + "\n\n"
+
+        # Generate child settings
+        result += "\n\n".join(self.generate_single(child, level + 1).strip() for child in settings_info.child_settings)
+
+        return result
+
+    def generate(self, *settings_infos: SettingsInfoModel) -> str:
+        """Generate Markdown documentation for a pydantic settings class.
+
+        :param settings_infos: The settings class to generate documentation for.
+        :return: The generated documentation.
+        """
+        return (
+            "# Configuration\n\n"
+            "Here you can find all available configuration options using ENV variables.\n\n"
+            + "\n\n".join(self.generate_single(s, 2).strip() for s in settings_infos)
+        ).strip() + "\n"
+
+    def write_to_files(self, generated_result: str) -> list[Path]:
+        """Write the generated content to files.
+
+        :param generated_result: The result to write to files.
+        :return: The list of file paths written to.
+        """
+        file_paths = []
+        for d in self.settings.markdown.save_dirs:
+            d = d.absolute().resolve()
+            d.mkdir(parents=True, exist_ok=True)
+            p = d / self.settings.markdown.name
+            file_paths.append(p)
+            p.write_text(generated_result)
+        return file_paths

pydantic_settings_export-0.1.0/pydantic_settings_export/models.py

@@ -0,0 +1,165 @@
+from inspect import getdoc, isclass
+from pathlib import Path
+from types import UnionType
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticSerializationError, PydanticUndefined
+from pydantic_settings import BaseSettings
+
+from pydantic_settings_export.constants import FIELD_TYPE_MAP
+from pydantic_settings_export.settings import Settings
+
+
+__all__ = (
+    "FieldInfoModel",
+    "SettingsInfoModel",
+)
+
+
+class FieldInfoModel(BaseModel):
+    """Info about the field of the settings model."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = Field(..., description="The name of the field.")
+    type: str = Field(..., description="The type of the field.")
+    default: str | None = Field(
+        None,
+        description="The default value of the field.",
+        validate_default=False,
+    )
+    description: str | None = Field(None, description="The description of the field.")
+    example: str | None = Field(None, description="The example of the field.")
+    alias: str | None = Field(None, description="The alias of the field.")
+
+    @property
+    def is_required(self) -> bool:
+        """Check if the field is required."""
+        return self.default is PydanticUndefined
+
+    @staticmethod
+    def create_default(field: FieldInfo, global_settings: Settings | None = None) -> str | None:
+        """Make default value for the field.
+
+        :param field: The field info to generate default value for.
+        :param global_settings: The global settings.
+        :return: The default value for the field as string, or None if there is no default value.
+        """
+        default: object | PydanticUndefined = field.default
+
+        if default is PydanticUndefined and field.default_factory:
+            default = field.default_factory()
+
+        if (
+            # if we need to replace absolute paths
+            global_settings
+            and global_settings.relative_to.replace_abs_paths
+            # Check if default is a Path and is absolute
+            and isinstance(default, Path)
+            and default.is_absolute()
+        ):
+            # Make the default path relative to the global_settings
+            default = Path(global_settings.relative_to.alias) / default.relative_to(global_settings.project_dir)
+
+        if default is PydanticUndefined:
+            return None
+        try:
+            return TypeAdapter(field.annotation).dump_json(default).decode()
+        except PydanticSerializationError:
+            return str(default)
+
+    @classmethod
+    def from_settings_field(
+        cls,
+        name: str,
+        field: FieldInfo,
+        global_settings: Settings | None = None,
+    ) -> Self:
+        """Generate FieldInfoModel using name and field.
+
+        :param name: The name of the field.
+        :param field: The field info to generate FieldInfoModel from.
+        :param global_settings: The global settings.
+        :return: Instance of FieldInfoModel.
+        """
+        # Parse the annotation of the field
+        annotation = field.annotation
+
+        if isinstance(annotation, UnionType):
+            args = list(filter(bool, getattr(annotation, "__args__", [])))
+            annotation = args[0] if args else None
+
+        # Get the name from the alias if it exists
+        name: str = field.alias or name
+        # Get the type from the FIELD_TYPE_MAP if it exists
+        type_: str = FIELD_TYPE_MAP.get(annotation, annotation.__name__ if annotation else "any")
+        # Get the default value from the field if it exists
+        default = cls.create_default(field, global_settings)
+        # Get the description from the field if it exists
+        description: str | None = field.description or None
+        # Get the example from the field if it exists
+        example: str | None = str(field.examples[0]) if field.examples else default
+
+        return cls(
+            name=name,
+            type=type_,
+            default=default,
+            description=description,
+            example=example,
+            alias=field.alias,
+        )
+
+
+class SettingsInfoModel(BaseModel):
+    """Info about the settings model."""
+
+    name: str = Field(..., description="The name of the settings model.")
+    docs: str = Field("", description="The documentation of the settings model.")
+    env_prefix: str = Field("", description="The prefix of the environment variables.")
+    fields: list[FieldInfoModel] = Field(default_factory=list, description="The fields of the settings model.")
+    child_settings: list["SettingsInfoModel"] = Field(
+        default_factory=list, description="The child settings of the settings model."
+    )
+
+    @classmethod
+    def from_settings_model(
+        cls,
+        settings: BaseSettings | type[BaseSettings],
+        global_settings: Settings | None = None,
+    ) -> Self:
+        """Generate SettingsInfoModel using a settings model.
+
+        :param settings: The settings model to generate SettingsInfoModel from.
+        :param global_settings: The global settings.
+        :return: Instance of SettingsInfoModel.
+        """
+        conf = settings.model_config
+        fields_info = settings.model_fields
+
+        child_settings = []
+        fields = []
+        for name, field_info in fields_info.items():
+            if global_settings and global_settings.respect_exclude and field_info.exclude:
+                continue
+            annotation = field_info.annotation
+            if isclass(annotation) and issubclass(annotation, BaseSettings):
+                child_settings.append(cls.from_settings_model(annotation, global_settings=global_settings))
+                continue
+            fields.append(FieldInfoModel.from_settings_field(name, field_info, global_settings))
+
+        return cls(
+            name=(
+                # Get the title from the settings model if it exists
+                conf.get("title", None)
+                # Otherwise, get the name from the settings model if it exists
+                or getattr(settings, "__name__", None)
+                # Otherwise, get the class name from the settings model
+                or str(settings.__class__.__name__)
+            ),
+            docs=(getdoc(settings) or "").strip(),
+            env_prefix=conf.get("env_prefix", ""),
+            fields=fields,
+            child_settings=child_settings,
+        )

pydantic_settings_export-0.1.0/pydantic_settings_export/settings.py

@@ -0,0 +1,122 @@
+from pathlib import Path
+from typing import TYPE_CHECKING, Self
+
+from pydantic import Field, ImportString
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from pydantic_settings_export.constants import StrAsPath
+from pydantic_settings_export.utils import get_config_from_pyproject_toml
+
+
+if TYPE_CHECKING:
+    from pydantic_settings_export.generators.abstract import AbstractGenerator  # noqa: F401
+
+__all__ = (
+    "MarkdownSettings",
+    "DotEnvSettings",
+    "RelativeToSettings",
+    "Settings",
+)
+
+
+class RelativeToSettings(BaseSettings):
+    """Settings for the relative directory."""
+
+    model_config = SettingsConfigDict(
+        title="Relative Directory Settings",
+        env_prefix="RELATIVE_TO_",
+    )
+
+    replace_abs_paths: bool = Field(True, description="Replace absolute paths with relative path to project root.")
+    alias: str = Field("<project_dir>", description="The alias for the relative directory.")
+
+
+class MarkdownSettings(BaseSettings):
+    """Settings for the markdown file."""
+
+    model_config = SettingsConfigDict(
+        title="Configuration File Settings",
+        env_prefix="CONFIG_FILE_",
+    )
+
+    enabled: bool = Field(True, description="Enable the configuration file generation.")
+    name: str = Field("Configuration.md", description="The name of the configuration file.")
+
+    save_dirs: list[StrAsPath] = Field(
+        default_factory=list, description="The directories to save configuration files to."
+    )
+
+    def __bool__(self) -> bool:
+        """Check if the configuration file is set."""
+        return self.enabled and bool(self.save_dirs)
+
+
+class DotEnvSettings(BaseSettings):
+    """Settings for the .env file."""
+
+    model_config = SettingsConfigDict(
+        title=".env File Settings",
+        env_prefix="DOTENV_",
+    )
+
+    name: str = Field(".env.example", description="The name of the .env file.")
+
+
+class Settings(BaseSettings):
+    """Global settings for pydantic_settings_export."""
+
+    model_config = SettingsConfigDict(
+        title="Global Settings",
+        env_prefix="PYDANTIC_SETTINGS_EXPORT_",
+        plugin_settings={
+            "pyproject_toml": {
+                "package_name": "pydantic_settings_export",
+            }
+        },
+    )
+
+    default_settings: list[ImportString] = Field(
+        default_factory=list,
+        description="The default settings to use. The settings are applied in the order they are listed.",
+    )
+
+    project_dir: Path = Field(
+        Path.cwd(),
+        description="The project directory. Used for relative paths in the configuration file and .env file.",
+    )
+
+    relative_to: RelativeToSettings = Field(
+        default_factory=RelativeToSettings,
+        description="The relative directory settings.",
+    )
+    markdown: MarkdownSettings = Field(
+        default_factory=MarkdownSettings,
+        description="The configuration of markdown file settings.",
+    )
+    dotenv: DotEnvSettings = Field(
+        default_factory=DotEnvSettings,
+        description="The .env file settings.",
+    )
+
+    respect_exclude: bool = Field(
+        True,
+        description="Respect the exclude attribute in the fields.",
+    )
+
+    generators: list = Field(  # type: list[type[AbstractGenerator]]
+        default_factory=list,
+        description="The list of generators to use.",
+        exclude=True,
+    )
+
+    @classmethod
+    def from_pyproject(cls, base_path: Path | None = None) -> Self:
+        """Load settings from the pyproject.toml file.
+
+        :param base_path: The base path to search for the pyproject.toml file, or this file itself.
+        The current working directory is used by default.
+        :return: The loaded settings.
+        """
+        config = get_config_from_pyproject_toml(cls, base_path)
+        config.setdefault("project_dir", str(base_path.parent))
+        return cls(**config)

pydantic_settings_export-0.1.0/pydantic_settings_export/utils.py

@@ -0,0 +1,177 @@
+import argparse
+import importlib
+import sys
+import tomllib
+
+from pathlib import Path
+from typing import Any
+
+
+__all__ = (
+    "find_pyproject_toml",
+    "make_pretty_md_table",
+    "make_pretty_md_table_from_dict",
+)
+
+from pydantic_settings import BaseSettings
+
+
+def make_pretty_md_table(header: list[str], rows: list[list[str]]) -> str:  # noqa: C901
+    """Make a pretty Markdown table with column alignment.
+
+    :param header: The header of the table.
+    :param rows: The rows of the table.
+    :return: The prettied Markdown table.
+    """
+    col_sizes = [len(h) for h in header]
+    for row in rows:
+        for i, cell in enumerate(row):
+            if cell is None:
+                cell = ""
+            col_sizes[i] = max(col_sizes[i], len(cell))
+
+    result = "|"
+    for i, h in enumerate(header):
+        result += f" {h}{' ' * (col_sizes[i] - len(h))} |"
+    result += "\n|"
+    for i, _ in enumerate(header):
+        result += f"{'-' * (col_sizes[i] + 2)}|"
+    for row in rows:
+        result += "\n|"
+        for i, cell in enumerate(row):
+            if cell is None:
+                cell = ""
+            result += f" {cell}{' ' * (col_sizes[i] - len(cell))} |"
+    return result
+
+
+def make_pretty_md_table_from_dict(data: list[dict[str, str | None]]) -> str:
+    """Make a pretty Markdown table with column alignment from a list of dictionaries.
+
+    :param data: The rows of the table as dictionaries.
+    :return: The prettied Markdown table.
+    """
+    # Save unique keys from all rows and save order
+    header: list[str] = list(
+        {
+            # We need only key
+            key: 0
+            for row in data
+            for key in row.keys()
+        }.keys(),
+    )
+    rows = [[row.get(key, None) or "" for key in header] for row in data]
+    return make_pretty_md_table(header, rows)
+
+
+def find_pyproject_toml(search_from: Path | None = None) -> Path | None:
+    """Find the pyproject.toml file in the current working directory or its parents.
+
+    :param search_from: The directory to start searching from.
+    :return: The path to the pyproject.toml file or None if it wasn't found.
+    """
+    if not search_from:
+        search_from = Path.cwd()
+    for parent in (search_from, *search_from.parents):
+        pyproject_toml = parent / "pyproject.toml"
+        if pyproject_toml.is_file():
+            return pyproject_toml
+    return None
+
+
+def get_tool_name(settings: type[BaseSettings]) -> str | None:
+    """Get the tool name from the settings.
+
+    :param settings: The settings class to get the tool name from.
+    :return: The tool name.
+    """
+    return settings.model_config.get("plugin_settings", {}).get("pyproject_toml", {}).get("package_name", None)
+
+
+def get_config_from_pyproject_toml(settings: type[BaseSettings], base_path: Path | None = None) -> dict:
+    """Get the configuration from the pyproject.toml file.
+
+    :param base_path: The base path to search for the pyproject.toml file, or this file itself.
+        The current working directory is used by default.
+    :param settings: The settings class to create the settings from.
+    :return: The created settings.
+    """
+    tool_name = get_tool_name(settings)
+
+    if not tool_name:
+        raise ValueError("The tool name is not set in the settings.")
+
+    if not base_path:
+        base_path = Path.cwd()
+
+    if not base_path.is_file():
+        base_path = find_pyproject_toml(base_path)
+
+    if not base_path:
+        raise FileNotFoundError("The pyproject.toml file was not found.")
+
+    with open(base_path, "rb") as file:
+        data = tomllib.load(file)
+
+    return data.get("tool", {}).get(tool_name, {})
+
+
+class ObjectImportAction(argparse.Action):
+    """Import the object from the module."""
+
+    @staticmethod
+    def callback(obj: Any) -> Any:
+        """Check if the object is a settings class."""
+        return obj
+
+    @staticmethod
+    def import_obj(value: str) -> Any:
+        """Import the object from the module.
+
+        :param value: The value in the format 'module:class'.
+        :raise ValueError: If the value is not in the format 'module:class'.
+        :raise ValueError: If the class is not in the module.
+        :raise ModuleNotFoundError: If the module is not found.
+        :return: The imported object.
+        """
+        try:
+            module_name, class_name = value.rsplit(":", 1)
+        except ValueError:
+            raise ValueError(f"The {value!r} is not in the format 'module:class'.") from None
+
+        module = importlib.import_module(module_name)
+
+        obj = getattr(module, class_name, None)
+        if obj is None:
+            raise ValueError(f"The {class_name!r} is not in the module {module_name!r}.")
+        return obj
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: list[str],
+        option_string: str | None = None,
+    ) -> None:
+        """Import the object from the module."""
+        # Add the project directory to the sys.path
+        sys.path.insert(0, str(namespace.project_dir))
+        importlib.invalidate_caches()
+
+        if isinstance(values, str):
+            values = [values]
+
+        result = getattr(namespace, self.dest, [])
+
+        # Reset the default value
+        if result == self.default:
+            result = []
+
+        for value in values:
+            try:
+                result.append(self.callback(self.import_obj(value)))
+            except (ValueError, ModuleNotFoundError) as e:
+                parser.print_usage(sys.stderr)
+                parser.exit(2, f"{parser.prog}: error: {argparse.ArgumentError(self, str(e))}\n")
+
+        setattr(namespace, self.dest, result)

pydantic_settings_export-0.1.0/pydantic_settings_export/version.py

@@ -0,0 +1,3 @@
+# These version placeholders will be replaced later during substitution.
+__version__ = "0.1.0"
+__version_tuple__ = (0, 1, 0)

pydantic_settings_export-0.1.0/pyproject.toml

@@ -0,0 +1,149 @@
+[tool.poetry]
+name = "pydantic-settings-export"
+version = "0.1.0"
+description = "Export your Pydantic settings to a Markdown and .env.example files!"
+authors = ["Jag_k <jag-k@users.noreply.github.com>"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Documentation",
+    "Topic :: Utilities",
+    "Environment :: Console",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+
+]
+readme = "README.md"
+license = "MIT"
+repository = "https://github.com/jag-k/pydantic-settings-export"
+homepage = "https://github.com/jag-k/pydantic-settings-export#readme"
+packages = [
+    { include = "pydantic_settings_export", from = "." },
+]
+
+[tool.poetry.scripts]
+pydantic-settings-export = "pydantic_settings_export.cli:main"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pydantic = "^2"
+pydantic-settings = "^2"
+
+
+[tool.poetry.group.dev.dependencies]
+ruff = "*"
+ruff-lsp = "*"
+pre-commit = "*"
+ssort = "^0.13.0"
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+style = "semver"
+
+[tool.poetry-dynamic-versioning.substitution]
+files = [
+    "pydantic_settings_export/version.py",
+]
+
+[tool.poetry-dynamic-versioning.files."pydantic_settings_export/version.py"]
+persistent-substitution = true
+initial-content = """
+# These version placeholders will be replaced later during substitution.
+__version__ = "0.0.0"
+__version_tuple__ = (0, 0, 0)
+"""
+
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"
+
+
+# https://docs.astral.sh/ruff/
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+extend-exclude = [
+    ".idea",
+    ".vscode",
+    ".fleet",
+]
+
+# https://docs.astral.sh/ruff/settings/#lint
+[tool.ruff.lint]
+ignore-init-module-imports = true
+select = [
+    'F', # flake8
+    'I', # isort
+    'B', # flake8-bugbear
+    'D', # pydocstyle
+    'W', # pycodestyle (warnings)
+    'E', # pycodestyle (errors)
+    'N', # pep8-naming
+    'PT', # flake8-pytest-style
+    'C90', # mccabe
+]
+ignore = [
+    'B012', # {name} inside finally blocks cause exceptions to be silenced
+    'D100', # Missing docstring in public module
+    'D104', # Missing docstring in public package
+    'D105', # Missing docstring in magic method
+    'D106', # Missing docstring in public nested class
+    'D107', # Missing docstring in __init__
+    'D203', # 1 blank line required before class docstring
+    'D401', # First line of docstring should be in imperative mood: "{first_line}"
+    'D404', # First word of the docstring should not be "This"
+    'D207', # Docstring is under-indented
+    'D208', # Docstring is over-indented
+]
+
+
+
+# https://docs.astral.sh/ruff/settings/#extend-per-file-ignores
+[tool.ruff.lint.extend-per-file-ignores]
+'__init__.py' = [
+    'F401', # {name} imported but unused; consider using importlib.util.find_spec to test for availability
+    'F403', # from {name} import * used; unable to detect undefined names
+    'F405', # {name} may be undefined, or defined from star imports
+]
+
+# https://docs.astral.sh/ruff/settings/#lintpydocstyle
+[tool.ruff.lint.pydocstyle]
+convention = 'pep257'
+
+
+# https://docs.astral.sh/ruff/settings/#lintmccabe
+[tool.ruff.lint.mccabe]
+max-complexity = 6
+
+# https://docs.astral.sh/ruff/settings/#lintisort
+[tool.ruff.lint.isort]
+section-order = [
+    'future',
+    'standard-library',
+    'third-party',
+    'first-party',
+    'local-folder',
+]
+known-first-party = ["pydantic_settings_export"]
+lines-after-imports = 2
+lines-between-types = 1
+
+# https://github.com/jag-k/pydantic-settings-export
+[tool.pydantic_settings_export]
+project_dir = "."
+default_settings = [
+    "pydantic_settings_export.settings:Settings",
+]
+dotenv = {"name" = ".env.example"}
+
+[tool.pydantic_settings_export.markdown]
+name = "Configuration.md"
+save_dirs = [
+    "docs",
+    "wiki",
+]