"""
This type stub file was generated by pyright.
"""

from pathlib import Path
from typing import TYPE_CHECKING
from typing import AnyStr
from typing import Literal

from jinja2 import Environment

"""Rendering utilities for the OZI project templates.
"""
if TYPE_CHECKING:
    ...

def find_user_template(target: str, file: str, fix: str) -> str | None:
    """Find a user-defined project template file e.g. :file:`{target}/templates/{fix}/{file}`.

    :param target: path to an OZI project directory
    :type target: Path
    :param file: filename
    :type file: str
    :param fix: template directory fix path
    :type fix: str
    :return: a user-defined template as a string
    :rtype: str | None
    """

def map_to_template(
    fix: (
        Literal[
            'child', 'github_workflows', 'root', 'source', 'subprojects', 'templates', 'test'
        ]
        | AnyStr
    ),
    filename: str,
) -> str:
    """Map an appropriate template for an ozi-fix mode and filename.

    .. versionadded:: 1.5

    :param fix: ozi-fix mode setting
    :type fix: AnyStr
    :param filename: name with file extension
    :type filename: str
    :return: template path
    :rtype: str
    """

def build_file(
    env: Environment,
    fix: (
        Literal[
            'child', 'github_workflows', 'root', 'source', 'subprojects', 'templates', 'test'
        ]
        | AnyStr
    ),
    path: Path,
    user_template: str | None,
    **kwargs: str
) -> None:
    """Render project file based on OZI templates.

    .. versionadded:: 1.5

    :param env: rendering environment
    :type env: Environment
    :param fix: ozi-fix setting
    :type fix: AnyStr
    :param path: full path of file to be rendered
    :type path: Path
    :param user_template: path to a user template to extend
    :type user_template: str | None
    """

def build_child(env: Environment, parent: str, child: Path) -> None:
    """Add a child directory to a parent in an existing OZI-style project.

    :param env: the OZI project file rendering environment
    :type env: jinja2.Environment
    :param parent: existing directory name in project
    :type parent: str
    :param child: path to a new child directory
    :type child: Path
    """

class RenderedContent:
    def __init__(
        self,
        env: Environment,
        target: Path,
        name: str,
        ci_provider: str,
        readme_type: str,
        update_wrapfile: bool,
    ) -> None:
        """OZI new project content to render.

        .. versionadded:: 1.15.2

        :param target: project root path
        :type target: Path
        :param name: project name
        :type name: str
        :param ci_provider: :term:`CI` provider setting
        :type ci_provider: str
        :param readme_type: the README file extension
        :type readme_type: str
        """

    def render(self) -> None:
        """Render the project."""

def render_ci_files_set_user(env: Environment, target: Path, ci_provider: str) -> str:
    """Render :term:`CI` files based on the ci_provider for target in env.

    :param env: the OZI project file rendering environment
    :type env: jinja2.Environment
    :param target: directory path to render the project
    :type target: Path
    :param ci_provider: the name of the project continuous integration provider
    :type ci_provider: str
    :return: the ci_user of the target repository for the continuous integration provider
    :rtype: str
    """

def render_project_files(env: Environment, target: Path, name: str) -> None:
    """Render the primary new project files(excluding CI).

    :param env: the OZI project file rendering environment
    :type env: jinja2.Environment
    :param target: directory path to render the project
    :type target: Path
    :param name: the canonical project name (without normalization)
    :type name: str
    """
