keshe/.venv/Lib/site-packages/faker/sphinx/documentor.py

# coding=utf-8
import importlib
import inspect
import os

from pathlib import Path

from faker.config import AVAILABLE_LOCALES
from faker.config import PROVIDERS as STANDARD_PROVIDER_NAMES
from faker.providers import BaseProvider

if os.environ.get("READTHEDOCS", False):
    version = os.environ["READTHEDOCS_VERSION"]
    HOME = Path("/home/docs/checkouts/readthedocs.org/user_builds/faker/checkouts") / version
    DOCS_ROOT = HOME / "docs"
else:
    DOCS_ROOT = Path(__file__).resolve().parents[2] / "docs"

SECTION_ADORNMENTS = "#*=-~"

PROVIDER_AUTODOC_TEMPLATE = """
.. autoclass:: {provider_class}
   :members: {provider_methods}
   :undoc-members:
   :show-inheritance:

"""

BASE_PROVIDER_METHOD_NAMES = [
    name for name, method in inspect.getmembers(BaseProvider, inspect.isfunction) if not name.startswith("_")
]


def _get_provider_methods(provider_class):
    try:
        provider_module_name, obj_name = provider_class.rsplit(".", 1)
        provider_module = importlib.import_module(provider_module_name)
        provider = getattr(provider_module, obj_name, None)
    except (ModuleNotFoundError, AttributeError):
        return ""
    else:
        return ", ".join(
            [
                name
                for name, method in inspect.getmembers(provider, inspect.isfunction)
                if not name.startswith("_") and name not in BASE_PROVIDER_METHOD_NAMES
            ]
        )


def _get_localized_provider_info(locale):
    info = []
    for provider_name in STANDARD_PROVIDER_NAMES:
        try:
            locale_module_path = f"{provider_name}.{locale}"
            locale_module = importlib.import_module(locale_module_path)
            provider = getattr(locale_module, "Provider")
        except (ModuleNotFoundError, AttributeError):
            continue
        else:
            provider_class = f"{provider.__module__}.Provider"
            info.append((provider_class, provider_name))
    return info


def _write(fh, s):
    return fh.write(s.encode("utf-8"))


def _hide_edit_on_github(fh):
    _write(fh, ":github_url: hide\n\n")


def _write_title(fh, title, level=1):
    if not isinstance(level, int) or level < 1 or level > 5:
        raise ValueError("`level` must be an integer from 1 to 5")
    if level <= 2:
        _write(fh, SECTION_ADORNMENTS[level - 1] * len(title))
        _write(fh, "\n")
    _write(fh, f"{title}\n")
    _write(fh, SECTION_ADORNMENTS[level - 1] * len(title))
    _write(fh, "\n\n")


def _write_includes(fh):
    _write(fh, ".. include:: ../includes/substitutions.rst")
    _write(fh, "\n\n")


def _write_standard_provider_index():
    with (DOCS_ROOT / "providers.rst").open("wb") as fh:
        _hide_edit_on_github(fh)
        _write_title(fh, "Standard Providers")
        _write(fh, ".. toctree::\n")
        _write(fh, "   :maxdepth: 2\n\n")
        _write(fh, "   providers/baseprovider\n")
        for provider_name in STANDARD_PROVIDER_NAMES:
            _write(fh, f"   providers/{provider_name}\n")


def _write_base_provider_docs():
    (DOCS_ROOT / "providers").mkdir(parents=True, exist_ok=True)
    with (DOCS_ROOT / "providers" / "baseprovider.rst").open("wb") as fh:
        _hide_edit_on_github(fh)
        _write_title(fh, "``faker.providers``")
        _write_includes(fh)
        _write(
            fh,
            PROVIDER_AUTODOC_TEMPLATE.format(
                provider_class="faker.providers.BaseProvider",
                provider_methods=",".join(BASE_PROVIDER_METHOD_NAMES),
            ),
        )


def _write_standard_provider_docs():
    (DOCS_ROOT / "providers").mkdir(parents=True, exist_ok=True)
    for provider_name in STANDARD_PROVIDER_NAMES:
        with (DOCS_ROOT / "providers" / f"{provider_name}.rst").open("wb") as fh:
            provider_class = f"{provider_name}.Provider"
            provider_methods = _get_provider_methods(provider_class)
            _hide_edit_on_github(fh)
            _write_title(fh, f"``{provider_name}``")
            _write_includes(fh)
            _write(
                fh,
                PROVIDER_AUTODOC_TEMPLATE.format(
                    provider_class=provider_class,
                    provider_methods=provider_methods,
                ),
            )


def _write_localized_provider_index():
    with (DOCS_ROOT / "locales.rst").open("wb") as fh:
        _hide_edit_on_github(fh)
        _write_title(fh, "Localized Providers")
        _write(fh, ".. toctree::\n")
        _write(fh, "   :maxdepth: 2\n\n")
        for locale in AVAILABLE_LOCALES:
            _write(fh, f"   locales/{locale}\n")


def _write_localized_provider_docs():
    (DOCS_ROOT / "locales").mkdir(parents=True, exist_ok=True)
    for locale in AVAILABLE_LOCALES:
        info = _get_localized_provider_info(locale)
        with (DOCS_ROOT / "locales" / "{}.rst".format(locale)).open("wb") as fh:
            _hide_edit_on_github(fh)
            _write_title(fh, f"Locale {locale}")
            _write_includes(fh)
            for provider_class, standard_provider_name in info:
                provider_methods = _get_provider_methods(provider_class)
                _write_title(fh, f"``{standard_provider_name}``", level=2)
                _write(
                    fh,
                    PROVIDER_AUTODOC_TEMPLATE.format(
                        provider_class=provider_class,
                        provider_methods=provider_methods,
                    ),
                )


def write_provider_docs():
    DOCS_ROOT.mkdir(parents=True, exist_ok=True)
    _write_standard_provider_index()
    _write_base_provider_docs()
    _write_standard_provider_docs()
    _write_localized_provider_index()
    _write_localized_provider_docs()