pytester-utils 1.0.0__py3-none-any.whl

pytester_utils/__init__.py

@@ -0,0 +1,42 @@
+from pytester_utils import errors
+from pytester_utils._plugin import PYTESTER_RUN_METHODS, PytesterRunMethod
+from pytester_utils.pytester_utils import (
+    OutputMatchPattern,
+    PytesterOutcomes,
+    PytesterTestCase,
+    TestFiles,
+    get_default_env,
+    get_default_pytest_args,
+    run_pytester,
+    set_default_env,
+    set_default_pytest_args,
+)
+from pytester_utils.test_file import (
+    AnyTestFile,
+    FunctionTestFile,
+    RawFileFunction,
+    TestFile,
+    TestFileBuilder,
+    TestFileMetadata,
+)
+
+__all__ = [
+    "PYTESTER_RUN_METHODS",
+    "AnyTestFile",
+    "FunctionTestFile",
+    "OutputMatchPattern",
+    "PytesterOutcomes",
+    "PytesterRunMethod",
+    "PytesterTestCase",
+    "RawFileFunction",
+    "TestFile",
+    "TestFileBuilder",
+    "TestFileMetadata",
+    "TestFiles",
+    "errors",
+    "get_default_env",
+    "get_default_pytest_args",
+    "run_pytester",
+    "set_default_env",
+    "set_default_pytest_args",
+]

pytester_utils/_ast_utils.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+import warnings
+from collections.abc import Callable, Mapping
+from typing import Any, cast
+
+from pytester_utils.errors import (
+    ArgumentWithDefaultValueError,
+    MissingInjectionVariablesError,
+    UnusedInjectedVariablesWarning,
+)
+
+
+def _build_assign_statements(variables: Mapping[str, Any]) -> list[ast.Assign]:
+    variable_statements: list[ast.Assign] = []
+
+    for variable, value in variables.items():
+        if inspect.isfunction(value) or inspect.ismethod(value):
+            assignment_value = ast.Name(value.__name__)
+        else:
+            assignment_value = ast.Constant(value)
+
+        assign_statement = ast.Assign(
+            targets=[ast.Name(variable)],
+            value=assignment_value,
+            lineno=1,
+        )
+        variable_statements.append(assign_statement)
+
+    return variable_statements
+
+
+def _create_variable_injection_lines(variables: Mapping[str, Any]) -> list[str]:
+    if len(variables) == 0:
+        return []
+
+    variable_statements = _build_assign_statements(variables)
+    lines = [ast.unparse(statement) for statement in variable_statements]
+    return lines
+
+
+def _get_function_def[**P, R](func: Callable[P, R]) -> ast.FunctionDef:
+    source_lines = inspect.getsourcelines(func)[0]
+    source = "\n".join(source_lines)
+    source = textwrap.dedent(source)
+
+    module = ast.parse(source)
+    statements = module.body
+    function_def: ast.FunctionDef | None = None
+    for statement in statements:
+        if isinstance(statement, ast.FunctionDef):
+            function_def = statement
+            break
+    if function_def is None:
+        # This is a runtime error because it should not be possible as we always take a func as an argument
+        msg = "Failed to get ast function definition from function."
+        raise RuntimeError(msg)
+    return function_def
+
+
+def _verify_valid_function(function_signature: inspect.Signature, variables: Mapping[str, Any]) -> None:
+    for param in function_signature.parameters.values():
+        if param.default is not inspect.Parameter.empty:
+            raise ArgumentWithDefaultValueError(str(param))
+
+    unused_variables = [variable for variable in variables if variable not in function_signature.parameters]
+    if len(unused_variables) > 0:
+        warnings.warn(UnusedInjectedVariablesWarning(unused_variables), stacklevel=2)
+
+    missing_variables = [variable for variable in function_signature.parameters if variable not in variables]
+    if len(missing_variables) > 0:
+        raise MissingInjectionVariablesError(missing_variables)
+
+
+def _get_module_imports_from_function_def[**P, R](func: Callable[P, R]) -> list[str]:
+    module = inspect.getmodule(func)
+    if module is None:
+        # This is a runtime error because it should not be possible as we always take a func as an argument
+        msg = "Failed to get module from function."
+        raise RuntimeError(msg)
+    tree = ast.parse(inspect.getsource(module))
+
+    imports: list[str] = [ast.unparse(node) for node in tree.body if isinstance(node, (ast.Import, ast.ImportFrom))]
+
+    return imports
+
+
+def get_function_body_source_lines[**P, R](
+    func: Callable[P, R],
+    variables: Mapping[str, Any],
+    auto_inject_imports: bool,
+) -> str:
+    """
+    Get the source lines for a function body with optional injected imports and variables.
+
+    Args:
+        func (Callable[P, R]): Function to extract the source lines from.
+        variables (Mapping[str, Any]): Mapping of variables to inject to the top of the result.
+        auto_inject_imports (bool): Whether to automagically prepend the defining
+            module imports to the top of the result.
+
+    Returns:
+        str: Source lines of the given function, with the optional modifications.
+    """
+    function_signature = inspect.signature(func)
+    _verify_valid_function(function_signature, variables)
+    variables = {variable: value for variable, value in variables.items() if variable in function_signature.parameters}
+
+    function_def = _get_function_def(func)
+
+    function_contents = ast.unparse(cast("ast.AST", function_def.body))
+    function_contents = textwrap.dedent(function_contents)
+
+    variable_injection_lines = _create_variable_injection_lines(variables)
+    if len(variable_injection_lines) > 0:
+        variable_injection_lines.append("")
+
+    imports: list[str] = []
+    if auto_inject_imports:
+        imports = _get_module_imports_from_function_def(func)
+        if len(imports) > 0:
+            imports.append("")
+
+    function_contents = "\n".join(
+        [
+            *imports,
+            *variable_injection_lines,
+            function_contents,
+        ],
+    )
+    return function_contents

pytester_utils/_env_patching.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import unittest.mock
+from collections.abc import Callable, Generator, Mapping, Sequence
+from contextlib import contextmanager
+from typing import Any, cast
+
+_ENV_VARS_TO_REMOVE_ON_SANITIZE = {
+    "LC_CTYPE",
+    "LINES",
+    "COLUMNS",
+}
+_ENV_VAR_PREFIXES_TO_REMOVE_ON_SANITIZE = {
+    "PYTEST_",
+    "PYTESTER_",
+}
+
+
+def _get_current_env() -> dict[str, str]:
+    # It is important to copy the environment dict, since we don't
+    # want it to be modified when the env itself is modified
+    return dict(os.environ)
+
+
+def _set_current_env(env: Mapping[str, str]) -> None:
+    os.environ.clear()
+    os.environ.update(env)
+
+
+def _sanitize_env(env: Mapping[str, str]) -> dict[str, str]:
+    env = dict(env)
+    keys_to_pop = {
+        key
+        for key in env
+        if key in _ENV_VARS_TO_REMOVE_ON_SANITIZE
+        or any(key.startswith(prefix) for prefix in _ENV_VAR_PREFIXES_TO_REMOVE_ON_SANITIZE)
+    }
+    for key in keys_to_pop:
+        env.pop(key, None)
+    return env
+
+
+def _resolve_env_to_patch(
+    env: Mapping[str, str],
+    inherit: bool,
+    to_inherit: Mapping[str, str],
+) -> dict[str, str]:
+    new_env = {**(to_inherit if inherit else {}), **env}
+    sanitized_new_env = _sanitize_env(new_env)
+    return sanitized_new_env
+
+
+@contextmanager
+def _patch_current_env(env: Mapping[str, str], inherit: bool) -> Generator[None]:
+    snapshot = _get_current_env()
+    new_env = _resolve_env_to_patch(env, inherit, snapshot)
+    try:
+        _set_current_env(new_env)
+        yield
+    finally:
+        _set_current_env(snapshot)
+
+
+@contextmanager
+def _patch_popen_env(env: Mapping[str, str], inherit: bool) -> Generator[None]:
+    snapshot = _get_current_env()
+    new_env = _resolve_env_to_patch(env, inherit, snapshot)
+
+    original_popen = subprocess.Popen
+
+    def _patched_popen(*args: Any, **kwargs: Any) -> subprocess.Popen:
+        if "env" not in kwargs:
+            kwargs["env"] = new_env
+        proc = original_popen(*args, **kwargs)
+        return proc
+
+    if original_popen.__name__ == _patched_popen.__name__:
+        yield  # TODO: #3 Properly support nested patching of Popen
+    else:
+        with unittest.mock.patch(
+            original_popen.__module__ + "." + original_popen.__name__,
+            _patched_popen,
+        ):
+            yield
+
+
+type _EnvPatcher = Callable[[Mapping[str, str], bool], Generator[None]]
+_ENV_PATCHERS = cast("list[_EnvPatcher]", [_patch_current_env, _patch_popen_env])
+
+
+@contextmanager
+def _run_env_patchers(
+    env: Mapping[str, str],
+    inherit: bool,
+    patchers: Sequence[_EnvPatcher] | None = None,
+) -> Generator[None]:
+    if patchers is None:
+        patchers = _ENV_PATCHERS
+
+    if len(patchers) == 0:
+        yield
+    else:
+        patchers = list(patchers)
+        patcher = patchers.pop(0)
+        with patcher(env, inherit), _run_env_patchers(env, inherit, patchers):  # ty: ignore[invalid-context-manager]
+            yield
+
+
+@contextmanager
+def patch_env(env: Mapping[str, str], inherit: bool) -> Generator[None]:
+    """
+    Patch the current environment with the given environment.
+
+    Args:
+        env (Mapping[str, str]): Environment mapping, describing the new environment.
+        inherit (bool): Whether to inherit the current environment and apply the new env on top of it.
+    """
+    with _run_env_patchers(env, inherit):
+        yield

pytester_utils/_plugin.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import os
+from typing import Literal, cast, get_args
+
+import pytest
+
+from pytester_utils.errors import FixtureRequestNotAvailableError
+
+type PytesterRunMethod = Literal["inprocess", "subprocess"]
+"""Method for running pytester sessions, either in the same process as the test or in a separate subprocess."""
+
+PYTESTER_RUN_METHODS: set[PytesterRunMethod] = set(get_args(PytesterRunMethod.__value__))
+_DEFAULT_PYTESTER_RUN_METHOD: PytesterRunMethod = "subprocess"
+
+PYTESTER_RUN_METHOD_CLI_FLAG = "--pytester-run-method"
+_PYTESTER_RUN_METHOD_PYTESTER_VAR = "pytester_run_method"
+PYTESTER_RUN_METHOD_ENV_VAR = "PYTESTER_RUN_METHOD"
+
+_CLI_PARSER_GROUP = "pytester-utils"
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup(_CLI_PARSER_GROUP)
+
+    pytester_run_methods = [
+        f"{_DEFAULT_PYTESTER_RUN_METHOD} (default)",
+        *[method for method in PYTESTER_RUN_METHODS if method != _DEFAULT_PYTESTER_RUN_METHOD],
+    ]
+    group.addoption(
+        PYTESTER_RUN_METHOD_CLI_FLAG,
+        dest=_PYTESTER_RUN_METHOD_PYTESTER_VAR,
+        help=f"Run method for pytester via {PYTESTER_RUN_METHOD_CLI_FLAG}, choices: {', '.join(pytester_run_methods)}",
+        type=str,
+        default=None,
+        action="store",
+        choices=list(PYTESTER_RUN_METHODS),
+        required=False,
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    _parse_pytester_run_method_from_cli(config)
+
+
+def _parse_pytester_run_method(value: str | None, source: str) -> PytesterRunMethod | None:
+    if value is None or not isinstance(value, str):
+        return None
+
+    pytester_run_method = value.strip().lower()
+    if pytester_run_method in PYTESTER_RUN_METHODS:
+        return cast("PytesterRunMethod", pytester_run_method)
+
+    msg = f"Invalid value for {source}: {value!r}. Valid choices are: {list(PYTESTER_RUN_METHODS)!r}"
+    raise pytest.UsageError(msg)
+
+
+def _parse_pytester_run_method_from_cli(config: pytest.Config) -> PytesterRunMethod | None:
+    pytester_run_method_arg = cast("str | None", config.getoption(PYTESTER_RUN_METHOD_CLI_FLAG, None))
+    return _parse_pytester_run_method(pytester_run_method_arg, f"command-line option {PYTESTER_RUN_METHOD_CLI_FLAG!r}")
+
+
+def _parse_pytester_run_method_from_env() -> PytesterRunMethod | None:
+    pytester_run_method_env = os.environ.get(PYTESTER_RUN_METHOD_ENV_VAR, None)
+    return _parse_pytester_run_method(pytester_run_method_env, f"environment variable {PYTESTER_RUN_METHOD_ENV_VAR!r}")
+
+
+def get_default_pytester_run_method(config: pytest.Config) -> PytesterRunMethod:
+    pytester_run_method_from_cli = _parse_pytester_run_method_from_cli(config)
+    if pytester_run_method_from_cli is not None:
+        return pytester_run_method_from_cli
+
+    pytester_run_method_from_env = _parse_pytester_run_method_from_env()
+    if pytester_run_method_from_env is not None:
+        return pytester_run_method_from_env
+
+    return _DEFAULT_PYTESTER_RUN_METHOD
+
+
+_request: pytest.FixtureRequest | None = None
+
+
+def get_request() -> pytest.FixtureRequest:
+    if _request is None:
+        raise FixtureRequestNotAvailableError
+    return _request
+
+
+def pytest_runtest_setup(item: pytest.Item) -> None:
+    if not isinstance(item, pytest.Function):
+        return
+    global _request  # noqa: PLW0603 - global-statement
+    _request = item._request  # noqa: SLF001 - private-member-access
+
+
+def pytest_runtest_teardown() -> None:
+    global _request  # noqa: PLW0603 - global-statement
+    _request = None

pytester_utils/errors.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class InvalidFileFunctionError(SyntaxError):
+    """Raised when a file function is invalid."""
+
+    def __init__(self, reason: str, *args: Any) -> None:
+        self.reason = reason
+        super().__init__(f"Invalid file function: {reason}", *args)
+
+
+class ArgumentWithDefaultValueError(InvalidFileFunctionError):
+    """Raised when a file function has an argument with a default value, which is invalid for file functions."""
+
+    def __init__(self, argument: str) -> None:
+        self.argument = argument
+        super().__init__(
+            f"The function has an argument '{argument}' with a default value, which is invalid "
+            "for file functions. Try using `TestFile.build()` instead.",
+        )
+
+
+class NotConvertibleToTestFileError(ValueError):
+    """Raised when a function cannot be converted into a `TestFile`."""
+
+    def __init__(self, func: Any) -> None:  # noqa: ANN401 - any-type
+        self.func = func
+        super().__init__(f"Cannot convert {func} into a TestFile.")
+
+
+class FixtureRequestNotAvailableError(ValueError):
+    """Raised when the fixture request is not available at a desired stage."""
+
+    def __init__(self) -> None:
+        super().__init__("Fixture request is not available at this stage.")
+
+
+class DuplicateSpecialFilesError(ValueError):
+    """Raised when special files are defined multiple times."""
+
+    def __init__(self, names: list[str]) -> None:
+        self.names = names
+        super().__init__(
+            f"The files {names!r} must be defined up to once each but were "
+            "defined twice, once via their fields and once via extra_files.",
+        )
+
+
+class UnusedInjectedVariablesWarning(UserWarning):
+    """Raised when extra variables are provided for function body injection."""
+
+    def __init__(self, unused_variables: list[str]) -> None:
+        self.unused_variables = unused_variables
+        super().__init__(f"Unused variables were injected: {unused_variables!r}")
+
+
+class MissingInjectionVariablesError(ValueError):
+    """Raised when required function parameters were not provided in injected variables."""
+
+    def __init__(self, missing_variables: list[str]) -> None:
+        self.missing_variables = missing_variables
+        super().__init__(f"Missing injection variables: {missing_variables!r}.")

pytester_utils/pytester_utils.py

@@ -0,0 +1,484 @@
+from __future__ import annotations
+
+import re
+from abc import abstractmethod
+from collections.abc import Callable, Mapping, Sequence
+from pathlib import Path
+from typing import Literal, Protocol, Self, overload
+
+import pytest
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    NonNegativeInt,
+    computed_field,
+    model_validator,
+    validate_call,
+)
+
+from pytester_utils._env_patching import patch_env
+from pytester_utils._plugin import (
+    PYTESTER_RUN_METHOD_CLI_FLAG,
+    PytesterRunMethod,
+    get_default_pytester_run_method,
+    get_request,
+)
+from pytester_utils.errors import DuplicateSpecialFilesError
+from pytester_utils.test_file import AnyTestFile, TestFile
+
+
+class _DefaultParams(BaseModel):
+    pytest_args: list[str] = Field(default_factory=lambda: ["-l", *(["-v"] * 3), "-rA", "--log-cli-level=INFO"])
+    env_vars: dict[str, str] = Field(default_factory=dict)
+
+
+_default_params = _DefaultParams()
+
+
+def get_default_pytest_args() -> list[str]:
+    """Get a copy of the default pytest arguments used for running nested pytest sessions."""
+    return list(_default_params.pytest_args)
+
+
+def get_default_env() -> dict[str, str]:
+    """Get a copy of the default environment variables used for running nested pytest sessions."""
+    return dict(_default_params.env_vars)
+
+
+def set_default_pytest_args(pytest_args: Sequence[str]) -> None:
+    """Set the default pytest arguments used for running nested pytest sessions."""
+    _default_params.pytest_args = list(pytest_args)
+
+
+def set_default_env(env_vars: Mapping[str, str]) -> None:
+    """Set the default environment variables used for running nested pytest sessions."""
+    _default_params.env_vars = dict(env_vars)
+
+
+def _assert_pytester_exit_code(
+    result: pytest.RunResult,
+    assert_exit_code: pytest.ExitCode | None,
+) -> None:
+    if assert_exit_code is None:
+        return
+
+    assert result.ret == assert_exit_code, (
+        f"Expected pytest exit code to be {assert_exit_code}, but got {result.ret}. "
+        "See result.stdout and result.stderr for more details."
+    )
+
+
+def _assert_pytester_outcomes(
+    result: pytest.RunResult,
+    assert_outcomes: PytesterOutcomes | None,
+) -> None:
+    if assert_outcomes is None:
+        return
+
+    assert_kwargs = assert_outcomes.model_dump(
+        exclude_defaults=True,
+        exclude_none=True,
+        exclude={"custom_outcomes"},
+    )
+    if len(assert_kwargs) > 0:
+        result.assert_outcomes(**assert_kwargs)
+
+    if len(assert_outcomes.custom_outcomes) > 0:
+        other_result_outcomes = {
+            outcome: amount
+            for outcome, amount in result.parseoutcomes().items()
+            if outcome not in PytesterOutcomes.model_fields
+        }
+        assert assert_outcomes.custom_outcomes == other_result_outcomes, (
+            "Unexpected pytest outcomes. See result.stdout and result.stderr for more details."
+        )
+
+
+def _assert_pytester_output(
+    line_matcher: pytest.LineMatcher,
+    match_patterns: list[OutputMatchPattern],
+) -> None:
+    if len(match_patterns) == 0:
+        return
+
+    for match_pattern in match_patterns:
+        pattern_sequence = match_pattern.match_pattern
+
+        if match_pattern.line_match_method == "regex":
+            match_lines = line_matcher.re_match_lines
+        elif match_pattern.line_match_method == "glob":
+            match_lines = line_matcher.fnmatch_lines
+
+        if isinstance(pattern_sequence, Sequence) and not isinstance(pattern_sequence, str):
+            consecutive = True
+            actual_pattern_sequence = pattern_sequence
+        else:
+            consecutive = False
+            actual_pattern_sequence = [pattern_sequence]
+
+        match_lines(actual_pattern_sequence, consecutive=consecutive)
+
+
+def _assert_pytester_result(
+    result: pytest.RunResult,
+    assert_exit_code: pytest.ExitCode | None,
+    assert_outcomes: PytesterOutcomes | None,
+    match_stdout_patterns: list[OutputMatchPattern],
+    match_stderr_patterns: list[OutputMatchPattern],
+) -> None:
+    try:
+        _assert_pytester_exit_code(result, assert_exit_code)
+        _assert_pytester_outcomes(result, assert_outcomes)
+        _assert_pytester_output(result.stdout, match_stdout_patterns)
+        _assert_pytester_output(result.stderr, match_stderr_patterns)
+    except ValueError as e:
+        for arg in e.args:
+            if not isinstance(arg, str):
+                continue
+            message = arg.lower()
+            if all((segment in message) for segment in ["terminal summary", "not found"]):
+                msg = (
+                    "Pytest failed to capture terminal summary. This might be caused when running "
+                    "pytester without the `-s` flag with pytester run method set to `inprocess`."
+                )
+                raise RuntimeError(msg) from e
+        raise
+
+
+def _resolve_pytester_method(
+    pytester: pytest.Pytester,
+    pytester_run_method: PytesterRunMethod,
+) -> _PytesterRunProtocol:
+    run_pytest_methods = {
+        "inprocess": pytester.runpytest_inprocess,
+        "subprocess": pytester.runpytest_subprocess,
+    }
+    run_pytest_method = run_pytest_methods[pytester_run_method]
+    return run_pytest_method
+
+
+class _PytesterRunProtocol(Protocol):
+    @abstractmethod
+    def __call__(self, *args: str) -> pytest.RunResult: ...
+
+
+class PytesterOutcomes(BaseModel):
+    """Represents the expected outcomes of a pytest run."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    passed: NonNegativeInt | None = None
+    skipped: NonNegativeInt | None = None
+    failed: NonNegativeInt | None = None
+    errors: NonNegativeInt | None = None
+    xpassed: NonNegativeInt | None = None
+    xfailed: NonNegativeInt | None = None
+    warnings: NonNegativeInt | None = None
+    deselected: NonNegativeInt | None = None
+    custom_outcomes: dict[str, NonNegativeInt] = Field(default_factory=dict)
+
+
+class OutputMatchPattern(BaseModel):
+    """Represents a pattern to match against the output of a pytest run, along with the matching method."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    match_pattern: Sequence[str | re.Pattern[str]] | str | re.Pattern[str]
+    line_match_method: Literal["regex", "glob"]
+
+    @overload
+    def __init__(
+        self,
+        match_pattern: Sequence[str | re.Pattern[str]] | str | re.Pattern[str],
+        line_match_method: Literal["regex"] = "regex",
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        match_pattern: Sequence[str] | str,
+        line_match_method: Literal["glob"],
+    ) -> None: ...
+
+    def __init__(
+        self,
+        match_pattern: Sequence[str | re.Pattern[str]] | str | re.Pattern[str],
+        line_match_method: Literal["regex", "glob"] = "regex",
+    ) -> None:
+        """
+        Pattern used for matching against stdout or stderr of the nested pytest session.
+
+        Pattern can be either regex or glob pattern.
+
+        Instead of a single pattern, it is possible to pass a sequence
+        of patterns to be matched for consecutive matching.
+        """
+        super().__init__(
+            match_pattern=match_pattern,
+            line_match_method=line_match_method,
+        )
+
+
+class TestFiles(BaseModel):
+    """Represents a collection of test files, extra files, and special files to be used in a pytester session."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, arbitrary_types_allowed=True)
+
+    conftest: AnyTestFile | None = None
+    """Optional `conftest.py` file to add alongside the test files."""
+
+    test_files: Sequence[AnyTestFile]
+    """Files containing test cases, to be run inside pytest session(s)."""
+
+    extra_files: Mapping[str, AnyTestFile] = Field(default_factory=dict)
+    """Files without any test cases, useful for utilities."""
+
+    # Pytest tries to collect the class as a test class when imported by a test module.
+    # This variable tells pytest it doesn't contain tests even though it has the "Test" prefix in the name.
+    __test__ = False
+
+    @model_validator(mode="after")
+    def _validate_special_files(self) -> Self:
+        duplicate_file_names: list[str] = [
+            name
+            for name, field in {
+                "conftest": self.conftest,
+            }.items()
+            if field is not None and name in self.extra_files
+        ]
+
+        if len(duplicate_file_names) > 0:
+            raise DuplicateSpecialFilesError(duplicate_file_names)
+
+        return self
+
+    @computed_field
+    @property
+    def special_files(self) -> dict[str, AnyTestFile]:
+        return {
+            name: file
+            for name, file in {
+                "__init__": self.extra_files.get("__init__"),
+                "conftest": self.conftest or self.extra_files.get("conftest"),
+            }.items()
+            if file is not None
+        }
+
+    @computed_field
+    @property
+    def all_non_test_files(self) -> dict[str, AnyTestFile]:
+        return {
+            **self.extra_files,
+            **self.special_files,
+        }
+
+    @overload
+    def make_pytester_tmp_files(self, pytester: pytest.Pytester) -> list[str]: ...
+
+    @overload
+    def make_pytester_tmp_files(self, pytester: pytest.Pytester, tests_dir_name: str) -> Path: ...
+
+    def make_pytester_tmp_files(
+        self,
+        pytester: pytest.Pytester,
+        tests_dir_name: str | None = None,
+    ) -> list[str] | Path:
+        """
+        Register the files into the pytester session using `pytester.makepyfile(...)`.
+
+        Return the list of paths of the test files, which should be passed to pytester's run method.
+        When `tests_dir_name` is provided, return its created path instead.
+
+        Optionally specify a directory name to create for containing
+        the test files (excluding special files and extra files).
+        """
+        tests_dir_name = tests_dir_name.strip() if tests_dir_name is not None else ""
+        test_file_name_prefix = ""
+        tests_dir_path: Path | None = None
+        if len(tests_dir_name) > 0:
+            test_file_name_prefix = f"{tests_dir_name}/"
+            tests_dir_path = pytester.mkpydir(tests_dir_name)
+
+        for extra_file_name, extra_file_function in self.all_non_test_files.items():
+            file_function = TestFile.from_any(extra_file_function)
+            pytester.makepyfile(**{extra_file_name: file_function.source_lines})
+
+        test_file_paths: list[str] = []
+        for test_file_function in self.test_files:
+            file_function = TestFile.from_any(test_file_function)
+            test_file_name = f"{test_file_name_prefix}{file_function.metadata.name}"
+            test_file_path = pytester.makepyfile(**{test_file_name: file_function.source_lines})
+            test_path_str = str(test_file_path.absolute())
+            test_file_paths.append(test_path_str)
+
+        if tests_dir_path is not None:
+            return tests_dir_path
+        return test_file_paths
+
+
+class PytesterTestCase(BaseModel):
+    """Represents a test case to be run in a pytester session."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    test_files: TestFiles | Sequence[AnyTestFile] | AnyTestFile
+    """Files to be created in the pytester sessions."""
+
+    pytest_args: list[str] = Field(default_factory=list)
+    """Command line arguments to pass to the nested pytest session."""
+
+    include_default_pytest_args: bool = True
+    """
+    Whether to pass the default command line arguments to the nested pytest session.
+
+    Can be combined with `pytest_args` to pass additional arguments.
+
+    The default pytest arguments can be modified via `set_default_pytest_args(...)` and `get_default_pytest_args(...)`.
+    """
+
+    env: dict[str, str] = Field(default_factory=dict)
+    """
+    Environment variables to pass to the nested pytest session, optionally overriding the default environment variables.
+
+    Explicitly set environment variables take priority over default
+    environment variables. Both default and explicit environment
+    variables take priority over inherited environment variables.
+    """
+
+    include_default_env: bool = True
+    """
+    Whether to pass the default environment variables to the nested pytest session.
+
+    Can be combined with `env` to pass additional environment variables.
+
+    The default environment variables can be modified via `set_default_env(...)` and `get_default_env(...)`.
+
+    Explicitly set environment variables take priority over default
+    environment variables. Both default and explicit environment
+    variables take priority over inherited environment variables.
+    """
+
+    inherit_env: bool = True
+    """
+    Whether to pass the environment variables of the invoking process to the nested pytest session.
+
+    Can be combined with `env` to pass additional arguments
+
+    Explicitly set environment variables take priority over default
+    environment variables. Both default and explicit environment
+    variables take priority over inherited environment variables.
+    """
+
+    pytester_run_method: PytesterRunMethod | None = None
+    """
+    Desired method for running pytester.
+
+    Default value for the argument `pytester_run_method` can be set via the
+    cli flag `--pytester-run-method`. When not defined, an environment variable
+    `PYTESTER_RUN_METHOD` can be used to set the default value. When neither is
+    defined, the default value is `subprocess`.
+    """
+
+    assert_exit_code: pytest.ExitCode | None = pytest.ExitCode.OK
+    """Expected exit code used for asserting against the exit code of the nested pytest session's exit code."""
+
+    assert_outcomes: PytesterOutcomes | None = None
+    """Expected outcomes used for asserting against the nested pytest session's outcomes."""
+
+    match_stdout_patterns: list[OutputMatchPattern] | OutputMatchPattern = Field(default_factory=list)
+    """Expected patterns used for matching against the nested pytest session's stdout."""
+
+    match_stderr_patterns: list[OutputMatchPattern] | OutputMatchPattern = Field(default_factory=list)
+    """Expected patterns used for matching against the nested pytest session's stderr."""
+
+
+def run_pytester(test_case: PytesterTestCase) -> pytest.RunResult:
+    request = get_request()
+    pytester = request.getfixturevalue("pytester")
+
+    pytest_args = [
+        *(_default_params.pytest_args if test_case.include_default_pytest_args else []),
+        *test_case.pytest_args,
+    ]
+    env = {
+        **(_default_params.env_vars if test_case.include_default_env else {}),
+        **test_case.env,
+    }
+
+    if isinstance(test_case.test_files, TestFiles):
+        test_files = test_case.test_files
+    elif isinstance(test_case.test_files, Sequence):
+        test_files = TestFiles(test_files=test_case.test_files)
+    elif isinstance(test_case.test_files, (TestFile, Callable)):
+        test_files = TestFiles(test_files=[test_case.test_files])
+
+    run_result = _run_pytester(
+        config=request.config,
+        pytester=pytester,
+        pytester_run_method=test_case.pytester_run_method,
+        test_files=test_files,
+        pytest_args=pytest_args,
+        env=env,
+        inherit_env=test_case.inherit_env,
+    )
+
+    _assert_pytester_result(
+        result=run_result,
+        assert_exit_code=test_case.assert_exit_code,
+        assert_outcomes=test_case.assert_outcomes,
+        match_stdout_patterns=test_case.match_stdout_patterns
+        if isinstance(test_case.match_stdout_patterns, list)
+        else [test_case.match_stdout_patterns],
+        match_stderr_patterns=test_case.match_stderr_patterns
+        if isinstance(test_case.match_stderr_patterns, list)
+        else [test_case.match_stderr_patterns],
+    )
+
+    return run_result
+
+
+@validate_call(config=ConfigDict(arbitrary_types_allowed=True))
+def _run_pytester(  # noqa: PLR0913 - too-many-arguments
+    *,
+    config: pytest.Config,
+    pytester: pytest.Pytester,
+    pytester_run_method: PytesterRunMethod | None = None,
+    test_files: TestFiles,
+    pytest_args: Sequence[str] | None = None,
+    env: Mapping[str, str] | None = None,
+    inherit_env: bool = True,
+) -> pytest.RunResult:
+    """
+    Run pytester with the given files and args.
+
+    Default value for the argument `pytester_run_method` can be set via the
+    cli flag `--pytester-run-method`. When not defined, an environment variable
+    `PYTESTER_RUN_METHOD` can be used to set the default value. When neither is
+    defined, the default value is `subprocess`.
+
+    Args:
+        config (pytest.Config): Config object from the pytest session.
+        pytester (pytest.Pytester): Fixture for running pytester, obtained from the pytest session.
+        test_files (TestFiles): Files to be created in the pytester sessions.
+        pytester_run_method (PytesterRunMethod | None, optional): Desired method for running pytester.
+        pytest_args (Sequence[str] | None, optional): Command line arguments to pass to the nested pytest session.
+        env (Mapping[str, str] | None, optional): Environment variables to pass to the nested pytest
+            session, optionally overriding the default environment variables.
+        inherit_env (bool, optional): Whether to pass the environment variables of the invoking
+            process to the nested pytest session.
+
+    Returns:
+        pytest.RunResult: The result of running the nested pytest session.
+    """
+    pytest_args = list(pytest_args or [])
+    env = dict(env or {})
+
+    pytester_run_method = pytester_run_method or get_default_pytester_run_method(config)
+    pytester_run_method_flag = (PYTESTER_RUN_METHOD_CLI_FLAG, pytester_run_method)
+    run_pytest = _resolve_pytester_method(pytester, pytester_run_method)
+
+    test_file_paths = test_files.make_pytester_tmp_files(pytester)
+    with patch_env(env, inherit_env):
+        run_result = run_pytest(*test_file_paths, *pytest_args, *pytester_run_method_flag)
+    return run_result

pytester_utils/test_file.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from types import FunctionType
+from typing import Any, Self, overload, override
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+)
+
+from pytester_utils._ast_utils import get_function_body_source_lines
+from pytester_utils.errors import NotConvertibleToTestFileError
+
+type RawFileFunction = Callable[..., Any]
+"""Raw Python function that can be converted into a Python file."""
+
+type AnyTestFile = TestFile | RawFileFunction
+"""Any object that can be converted into a Python file."""
+
+
+class TestFile(ABC):
+    __test__ = False
+
+    @property
+    @abstractmethod
+    def metadata(self) -> TestFileMetadata: ...
+
+    @property
+    @abstractmethod
+    def source_lines(self) -> str:
+        """
+        Get the source lines of the test file.
+
+        Multi-line source is returned as a single string with newline characters.
+        """
+
+    @classmethod
+    def build(cls) -> TestFileBuilder:
+        """Initialize a builder for the implementations of this class."""
+        return TestFileBuilder()
+
+    @staticmethod
+    def from_any(obj: AnyTestFile) -> TestFile:
+        """
+        Convert any object that can be converted into a Python file into a `TestFile`.
+
+        If the object is already a `TestFile`, it is returned as-is.
+        If the object is a raw Python function, it is wrapped in a `FunctionTestFile` with default metadata.
+        """
+        if isinstance(obj, TestFile):
+            return obj
+        if isinstance(obj, FunctionType):
+            return FunctionTestFile(obj, TestFileMetadata(name=obj.__name__) if hasattr(obj, "__name__") else None)
+        raise NotConvertibleToTestFileError(obj)
+
+    @overload
+    def inject(self, /, **variables_kwargs: Any) -> Self: ...
+
+    @overload
+    def inject(self, variables_dict: dict[str, Any], /) -> Self: ...
+
+    def inject(self, variables_dict: dict[str, Any] | None = None, /, **variables_kwargs: Any) -> Self:
+        """
+        Inject variables into the test file.
+
+        When generating a file based on a test file function, a variable is injected only
+        if there is an argument in the test file function's signature with the same name.
+        """
+        self.metadata.injected_variables.update(variables_dict or {})
+        self.metadata.injected_variables.update(variables_kwargs)
+        return self
+
+
+class TestFileMetadata(BaseModel):
+    __test__ = False
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = "test_unnamed"
+    injected_variables: dict[str, Any] = Field(default_factory=dict)
+    auto_inject_imports: bool = True
+
+
+class FunctionTestFile(TestFile):
+    """
+    Container for attaching metadata to a function that can be converted into a Python file.
+
+    For simplicity, it is advised to use `TestFile.build().finalize_from_raw()` as a decorator instead.
+    """
+
+    def __init__(self, func: RawFileFunction, metadata: TestFileMetadata | None = None) -> None:
+        self._func = func
+        self._metadata = metadata or (
+            TestFileMetadata(name=str(func.__name__)) if hasattr(func, "__name__") else TestFileMetadata()
+        )
+
+    @property
+    def func(self) -> RawFileFunction:
+        return self._func
+
+    @property
+    @override
+    def metadata(self) -> TestFileMetadata:
+        return self._metadata
+
+    @property
+    @override
+    def source_lines(self) -> str:
+        return get_function_body_source_lines(
+            self._func,
+            self._metadata.injected_variables,
+            self._metadata.auto_inject_imports,
+        )
+
+
+class TestFileBuilder:
+    """
+    Builder class for the class `TestFile`.
+
+    Finalize building by using one of the methods with the prefix "finalize".
+    """
+
+    __test__ = False
+
+    def __init__(self) -> None:
+        self._raw_metadata: dict[str, Any] = {}
+
+    def finalize_from_raw(self) -> Callable[[RawFileFunction], TestFile]:
+        """Finalize building by decorating a file function with the returned decorator."""
+
+        def wrapper(func: RawFileFunction) -> TestFile:
+            raw_metadata = self._raw_metadata.copy()
+            if "name" not in raw_metadata and hasattr(func, "__name__"):
+                raw_metadata["name"] = func.__name__
+            metadata = TestFileMetadata.model_validate(raw_metadata)
+            test_file = FunctionTestFile(func, metadata)
+            return test_file
+
+        return wrapper
+
+    def set_name(self, name: str) -> Self:
+        """Set the name of the test file."""
+        self._raw_metadata["name"] = name
+        return self
+
+    @overload
+    def inject(self, /, **variables_kwargs: Any) -> Self: ...
+
+    @overload
+    def inject(self, variables_dict: dict[str, Any], /) -> Self: ...
+
+    def inject(self, variables_dict: dict[str, Any] | None = None, /, **variables_kwargs: Any) -> Self:
+        """
+        Inject variables into the test file.
+
+        When generating a file based on a test file function, a variable is injected only
+        if there is an argument in the test file function's signature with the same name.
+        """
+        injected_variables: dict[str, Any] = self._raw_metadata.setdefault("injected_variables", {})
+        injected_variables.update(variables_dict or {})
+        injected_variables.update(variables_kwargs)
+        return self
+
+    def set_auto_inject_imports(self, auto_inject_imports: bool) -> Self:
+        """Set whether to automatically inject imports from the defining module."""
+        self._raw_metadata["auto_inject_imports"] = auto_inject_imports
+        return self

pytester_utils-1.0.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: pytester-utils
+Version: 1.0.0
+Summary: Powerful and ergonomic wrapper for pytester for your mental health.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pydantic~=2.13
+Requires-Dist: pytest~=9.1
+Description-Content-Type: text/markdown
+
+# Pytester Utils
+
+[![CI](https://github.com/Guy-Yudovich/pytester-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Guy-Yudovich/pytester-utils/actions/workflows/ci.yml) [![Coverage](https://codecov.io/gh/Guy-Yudovich/pytester-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/Guy-Yudovich/pytester-utils) [![Latest Release](https://img.shields.io/github/v/release/Guy-Yudovich/pytester-utils)](https://github.com/Guy-Yudovich/pytester-utils/releases) [![PyPI](https://img.shields.io/pypi/v/pytester-utils)](https://pypi.org/project/pytester-utils/) [![License](https://img.shields.io/github/license/Guy-Yudovich/pytester-utils)](https://github.com/Guy-Yudovich/pytester-utils/blob/main/LICENSE) [![Python](https://img.shields.io/badge/python-3.12+-blue?logo=python&logoColor=white)](https://www.python.org) [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) [![Tested with pytest | pytester | pytester-utils](https://img.shields.io/badge/tested_with-pytest_%7C_pytester_%7C_pytester--utils-0A9EDC?logo=pytest&logoColor=white)](https://github.com/Guy-Yudovich/pytester-utils)
+
+Powerful and ergonomic wrapper for pytester for your mental health.

pytester_utils-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pytester_utils/__init__.py,sha256=BtyGVb8vaMh6bpI76d9evsjYa82Vo_MZxT1wvv6PNQc,944
+pytester_utils/_ast_utils.py,sha256=Rav38Fj7oa3U-2Wl15DbO54747JHyDO5qGaEDzOSM78,4745
+pytester_utils/_env_patching.py,sha256=RTKwZ_PueaaiCXyRJBMkoQRudr88RlstsSf9Dm030YY,3401
+pytester_utils/_plugin.py,sha256=Sxz7yDVx0mchFbodz7B1mLT3WewbBbR7zbiRutNQUEQ,3518
+pytester_utils/errors.py,sha256=Mxi8k_Jcq8ii73dOkrWX472v0gCosM5MbhEjGLi3XpY,2350
+pytester_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytester_utils/pytester_utils.py,sha256=ZleckPWMKWuy6tLw4hJ5Wu2selG0vP2kCQHjccNP5Mg,17847
+pytester_utils/test_file.py,sha256=iKiTtE08kFetOedK_yyPoS33t4lhGMAqjCgKMh7Oi5o,5611
+pytester_utils-1.0.0.dist-info/METADATA,sha256=RBB1V6V-l178bnordwS7DSAod84W63RgMNa0ouL8ar4,2004
+pytester_utils-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pytester_utils-1.0.0.dist-info/entry_points.txt,sha256=lPbBb4rtljNzEFKzJq8nbHxV4VmApGs-ncoxfIc6-vU,51
+pytester_utils-1.0.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pytester_utils-1.0.0.dist-info/RECORD,,

pytester_utils-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytester_utils-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+pytester_utils = pytester_utils._plugin

pytester_utils-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.