pytest-plugin-utils 0.1.0__tar.gz

pytest_plugin_utils-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.3
+Name: pytest-plugin-utils
+Version: 0.1.0
+Summary: Reusable configuration and artifact utilities for building pytest plugins
+Keywords: pytest,plugin,testing,utilities
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: structlog-config>=0.10.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/iloveitaly/pytest-plugin-utils
+Description-Content-Type: text/markdown
+
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/pytest-plugin-utils)](https://github.com/iloveitaly/pytest-plugin-utils/releases)
+[![Downloads](https://static.pepy.tech/badge/pytest-plugin-utils/month)](https://pepy.tech/project/pytest-plugin-utils)
+![GitHub CI Status](https://github.com/iloveitaly/pytest-plugin-utils/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# Reusable pytest Plugin Utilities
+
+Building pytest plugins means dealing with the same problems repeatedly: managing configuration options with proper precedence (CLI vs INI vs defaults), creating per-test artifact directories, and sanitizing test names for filesystem paths. This package extracts those common patterns into reusable utilities.
+
+I created this after extracting the config and path handling logic from `pytest-playwright-artifacts`. Rather than reinvent option handling in every plugin, you can use these utilities to get consistent behavior across pytest plugins.
+
+## Installation
+
+```bash
+uv add pytest-plugin-utils
+```
+
+## Usage
+
+### Configuration Options
+
+Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference:
+
+```python
+from pytest_plugin_utils import set_pytest_option, register_pytest_options, get_pytest_option
+
+def pytest_addoption(parser):
+    # Define your options (use __package__ for namespace)
+    set_pytest_option(
+        __package__,
+        "api_url",
+        default="http://localhost:3000",
+        help="API base URL",
+        available="all",  # Expose via CLI and INI
+        type_hint=str,
+    )
+
+    # Register them with pytest
+    register_pytest_options(__package__, parser)
+
+def pytest_configure(config):
+    # Retrieve with automatic type casting
+    api_url = get_pytest_option(__package__, config, "api_url", type_hint=str)
+```
+
+### Artifact Directory Management
+
+Create per-test artifact directories with sanitized names:
+
+```python
+from pytest_plugin_utils import set_artifact_dir_option, get_artifact_dir
+
+def pytest_configure(config):
+    # Configure which option name to use (use __package__ for namespace)
+    set_artifact_dir_option(__package__, "my_plugin_output")
+
+def pytest_runtest_setup(item):
+    # Get a clean directory for this specific test
+    artifact_dir = get_artifact_dir(__package__, item)
+    # Returns: /output/test-file-py-test-name-param/
+```
+
+## Features
+
+* Centralized option registry with runtime, CLI, and INI support
+* Automatic INI type inference from Python type hints (bool, str, list[str], list[Path])
+* Smart value casting with fallback precedence handling
+* Filesystem-safe test name sanitization for artifact paths
+* Per-test artifact directory creation and resolution
+* Type-safe configuration retrieval with warnings on mismatches
+
+## [MIT License](LICENSE.md)
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*
+

pytest_plugin_utils-0.1.0/README.md

@@ -0,0 +1,77 @@
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/pytest-plugin-utils)](https://github.com/iloveitaly/pytest-plugin-utils/releases)
+[![Downloads](https://static.pepy.tech/badge/pytest-plugin-utils/month)](https://pepy.tech/project/pytest-plugin-utils)
+![GitHub CI Status](https://github.com/iloveitaly/pytest-plugin-utils/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# Reusable pytest Plugin Utilities
+
+Building pytest plugins means dealing with the same problems repeatedly: managing configuration options with proper precedence (CLI vs INI vs defaults), creating per-test artifact directories, and sanitizing test names for filesystem paths. This package extracts those common patterns into reusable utilities.
+
+I created this after extracting the config and path handling logic from `pytest-playwright-artifacts`. Rather than reinvent option handling in every plugin, you can use these utilities to get consistent behavior across pytest plugins.
+
+## Installation
+
+```bash
+uv add pytest-plugin-utils
+```
+
+## Usage
+
+### Configuration Options
+
+Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference:
+
+```python
+from pytest_plugin_utils import set_pytest_option, register_pytest_options, get_pytest_option
+
+def pytest_addoption(parser):
+    # Define your options (use __package__ for namespace)
+    set_pytest_option(
+        __package__,
+        "api_url",
+        default="http://localhost:3000",
+        help="API base URL",
+        available="all",  # Expose via CLI and INI
+        type_hint=str,
+    )
+
+    # Register them with pytest
+    register_pytest_options(__package__, parser)
+
+def pytest_configure(config):
+    # Retrieve with automatic type casting
+    api_url = get_pytest_option(__package__, config, "api_url", type_hint=str)
+```
+
+### Artifact Directory Management
+
+Create per-test artifact directories with sanitized names:
+
+```python
+from pytest_plugin_utils import set_artifact_dir_option, get_artifact_dir
+
+def pytest_configure(config):
+    # Configure which option name to use (use __package__ for namespace)
+    set_artifact_dir_option(__package__, "my_plugin_output")
+
+def pytest_runtest_setup(item):
+    # Get a clean directory for this specific test
+    artifact_dir = get_artifact_dir(__package__, item)
+    # Returns: /output/test-file-py-test-name-param/
+```
+
+## Features
+
+* Centralized option registry with runtime, CLI, and INI support
+* Automatic INI type inference from Python type hints (bool, str, list[str], list[Path])
+* Smart value casting with fallback precedence handling
+* Filesystem-safe test name sanitization for artifact paths
+* Per-test artifact directory creation and resolution
+* Type-safe configuration retrieval with warnings on mismatches
+
+## [MIT License](LICENSE.md)
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*
+

pytest_plugin_utils-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "pytest-plugin-utils"
+version = "0.1.0"
+description = "Reusable configuration and artifact utilities for building pytest plugins"
+keywords = ["pytest", "plugin", "testing", "utilities"]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["structlog-config>=0.10.0"]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/pytest-plugin-utils" }
+
+# additional packaging information: https://packaging.python.org/en/latest/specifications/core-metadata/#license
+
+[build-system]
+requires = ["uv_build>=0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pyright[nodejs]>=1.1.408",
+    "ruff>=0.15.0",
+    "coverage>=7.13.4",
+    "pytest-cov>=7.0.0",
+    "covdefaults>=2.3.0",
+]
+
+[tool.pyright]
+exclude = ["examples/", "playground/", "tmp/", ".venv/", "tests/"]
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["pytest_plugin_utils"]
+
+[tool.coverage.report]
+fail_under = 50
+
+[tool.ruff]
+extend-exclude = ["playground.py", "playground/"]

pytest_plugin_utils-0.1.0/pytest_plugin_utils/__init__.py

@@ -0,0 +1,10 @@
+from pytest_plugin_utils.artifacts import (
+    get_artifact_dir as get_artifact_dir,
+    sanitize_for_artifacts as sanitize_for_artifacts,
+    set_artifact_dir_option as set_artifact_dir_option,
+)
+from pytest_plugin_utils.config import (
+    get_pytest_option as get_pytest_option,
+    register_pytest_options as register_pytest_options,
+    set_pytest_option as set_pytest_option,
+)

pytest_plugin_utils-0.1.0/pytest_plugin_utils/artifacts.py

@@ -0,0 +1,119 @@
+"""
+Path handling utilities for pytest artifact management.
+
+This module contains logic for determining where artifacts should be stored
+for individual tests, including sanitization of test names and resolution
+of output directories. The artifact directory option name can be customized
+via set_artifact_dir_option().
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+
+from .config import get_pytest_option
+
+_artifact_dir_options: dict[str, str] = {}
+
+
+def set_artifact_dir_option(namespace: str, option_name: str) -> None:
+    """
+    Set the pytest option name used for the artifact output directory.
+
+    This function should typically be called in pytest_configure() to customize
+    the option name before any tests run. It allows this module to be reused
+    by other pytest plugins that need different option names.
+
+    Example:
+        # In your conftest.py or plugin module:
+        from pytest_plugin_utils.artifacts import set_artifact_dir_option
+        from pytest_plugin_utils.config import set_pytest_option
+
+        def pytest_configure(config):
+            # Register your custom option
+            set_pytest_option(
+                __package__,
+                "my_artifacts_output",
+                default="my-test-results",
+                help="Directory for test artifacts",
+                available="cli_option",
+                type_hint=str,
+            )
+            # Configure paths module to use it
+            set_artifact_dir_option(__package__, "my_artifacts_output")
+
+    Args:
+        namespace: Unique namespace for this plugin (typically __package__).
+        option_name: The pytest option name (without '--' prefix, with underscores).
+    """
+    _artifact_dir_options[namespace] = option_name
+
+
+def get_artifact_dir_option(namespace: str) -> str:
+    """
+    Get the currently configured artifact directory option name.
+
+    Args:
+        namespace: Unique namespace for this plugin (typically __package__).
+
+    Returns:
+        The pytest option name used for the artifact output directory.
+    """
+    assert namespace in _artifact_dir_options, (
+        f"call set_artifact_dir_option({namespace!r}, ...) before using get_artifact_dir_option()"
+    )
+    return _artifact_dir_options[namespace]
+
+
+def sanitize_for_artifacts(text: str) -> str:
+    """
+    Sanitize a test nodeid or name for use as a directory name.
+
+    This function replaces characters that are not alphanumeric or hyphens
+    with a single hyphen, and removes leading/trailing hyphens. This ensures
+    that the resulting string is safe to use as a directory name on most
+    file systems.
+
+    Example:
+        >>> sanitize_for_artifacts("test_file.py::test_func[param]")
+        'test-file-py-test-func-param'
+
+    Args:
+        text: The text to sanitize (e.g., a test nodeid).
+
+    Returns:
+        A sanitized string safe for use as a directory name.
+    """
+    sanitized = re.sub(r"[^A-Za-z0-9]+", "-", text)
+    sanitized = re.sub(r"-+", "-", sanitized).strip("-")
+    return sanitized or "unknown-test"
+
+
+def get_artifact_dir(namespace: str, item: pytest.Item) -> Path:
+    """
+    Get or create the artifact directory for a specific test item.
+
+    This function determines the root output directory based on the configured
+    artifact directory option (see set_artifact_dir_option). It then creates
+    a subdirectory for the specific test item using its sanitized nodeid.
+
+    Args:
+        namespace: Unique namespace for this plugin (typically __package__).
+        item: The pytest.Item (test case) for which to get the directory.
+
+    Returns:
+        A pathlib.Path object pointing to the specific test's artifact directory.
+        The directory and its parents are created if they do not exist.
+    """
+    assert namespace in _artifact_dir_options, (
+        f"call set_artifact_dir_option({namespace!r}, ...) before using get_artifact_dir()"
+    )
+    option_name = _artifact_dir_options[namespace]
+    output_path = get_pytest_option(namespace, item.config, option_name, type_hint=Path)
+    assert output_path
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    per_test_dir = output_path / sanitize_for_artifacts(item.nodeid)
+    per_test_dir.mkdir(parents=True, exist_ok=True)
+    return per_test_dir

pytest_plugin_utils-0.1.0/pytest_plugin_utils/config.py

@@ -0,0 +1,287 @@
+"""
+Pytest option registry and resolution helpers for this plugin.
+
+Options are registered once, then resolved at read time with a consistent
+precedence: runtime overrides > INI > defaults from the registry.
+"""
+
+import typing as t
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+
+import structlog
+from _pytest.config import Config
+from _pytest.config.argparsing import Parser
+
+log = structlog.get_logger(logger_name=__package__)
+
+
+@dataclass
+class OptionDef:
+    """
+    Internal representation of the options this plugin wants to expose to pytest.
+    """
+
+    name: str
+    default: t.Any
+    help_text: str
+    available: t.Literal["all", "ini", "cli_option", None]
+    type_hint: t.Any | None
+    ini_type: (
+        t.Literal[
+            "string", "paths", "pathlist", "args", "linelist", "bool", "int", "float"
+        ]
+        | None
+    )
+
+
+REGISTRY: dict[str, list[OptionDef]] = {}
+"configuration options this plugin wants to expose to pytest, keyed by namespace"
+
+
+def _infer_ini_type(
+    type_hint: t.Any,
+) -> (
+    t.Literal["string", "paths", "pathlist", "args", "linelist", "bool", "int", "float"]
+    | None
+):
+    """
+    Infer the pytest INI type string from a Python type hint.
+
+    Supported mappings:
+    - bool -> "bool"
+    - str -> "string"
+    - list[str] -> "linelist"
+    - list[Path] -> "paths"
+
+    Unsupported/Not inferred:
+    - "args" (list of whitespace-separated strings)
+    - "pathlist" (legacy alias for "paths")
+    """
+    if type_hint is bool:
+        return "bool"
+    if type_hint is str:
+        return "string"
+
+    origin = t.get_origin(type_hint)
+    args = t.get_args(type_hint)
+
+    if origin is list:
+        if args and args[0] is str:
+            return "linelist"
+        if args and issubclass(args[0], Path):
+            return "paths"
+
+    return None
+
+
+def set_pytest_option(
+    namespace: str,
+    name: str,
+    *,
+    default: t.Any = None,
+    help: str = "",
+    available: t.Literal["all", "ini", "cli_option", None] = None,
+    type_hint: t.Any | None = None,
+) -> None:
+    """
+    Define a pytest option.
+
+    This queues the option for registration (hook_addoption) and
+    configuration (hook_configure).
+
+    Args:
+        namespace: Unique namespace for this plugin (typically __package__).
+        name: The key name (e.g. "api_url"). Use underscores.
+        default: The fallback value if not provided via CLI or INI.
+        help: Help text for the CLI/INI description.
+        available: Where this option should be exposed to the user.
+                   - 'cli_option': Adds a --flag.
+                   - 'ini': Adds a value to pytest.ini.
+                   - 'all': Adds both.
+                   - None: Purely internal/runtime (set via code only).
+        type_hint: Optional Python type hint (e.g. bool, list[str]) used for
+                   validation and INI type inference.
+    """
+    ini_type = _infer_ini_type(type_hint)
+    if namespace not in REGISTRY:
+        REGISTRY[namespace] = []
+    REGISTRY[namespace].append(
+        OptionDef(
+            name=name,
+            default=default,
+            help_text=help,
+            available=available,
+            type_hint=type_hint,
+            ini_type=ini_type,
+        )
+    )
+
+
+def register_pytest_options(namespace: str, parser: Parser) -> None:
+    """
+    Must be called within `pytest_addoption` to register CLI/INI flags.
+
+    Args:
+        namespace: Unique namespace for this plugin (typically __package__).
+        parser: The pytest parser to register options with.
+    """
+    for opt in REGISTRY.get(namespace, []):
+        help_text = opt.help_text
+        if opt.default is not None:
+            help_text = f"{opt.help_text} (default: {opt.default})"
+
+        # CLI Registration
+        if opt.available in ("all", "cli_option"):
+            cli_name = f"--{opt.name.replace('_', '-')}"
+            # CRITICAL: We set default=None here so CLI allows fallback to INI/Runtime
+            parser.addoption(cli_name, action="store", default=None, help=help_text)
+
+        # INI Registration
+        if opt.available in ("all", "ini"):
+            # We set default=None here so INI allows fallback to Runtime default
+            parser.addini(opt.name, help=help_text, default=None, type=opt.ini_type)
+
+
+def _smart_cast[T](value: t.Any, type_hint: type[T] | None) -> T | t.Any:
+    """
+    Cast a value to the expected type if it's not already correct.
+    This handles cases where CLI arguments (always strings) need conversion,
+    or where default values might not match the strict type.
+    """
+    log.debug("casting value", raw_value=value, target_type=type_hint)
+
+    if type_hint is None:
+        return value
+
+    # Handle GenericAlias types (e.g. list[str]) for isinstance checks
+    origin = t.get_origin(type_hint)
+    check_type = origin if origin is not None else type_hint
+
+    try:
+        if isinstance(value, check_type):
+            log.debug("value already correct type, no conversion needed")
+            return value
+    except TypeError:
+        # Fallback if isinstance fails (e.g. some complex types)
+        pass
+
+    if value is None:
+        return None
+
+    # Casting logic for strings (from CLI or raw defaults)
+    if type_hint is bool and isinstance(value, str):
+        result = value.lower() in ("true", "1", "yes", "on")
+        log.debug("converted string to bool", converted_value=result)
+        return result
+
+    if origin is list and isinstance(value, str):
+        # list("foo") produces ['f', 'o', 'o'], so handle string-to-list specially
+        # by splitting on newlines (CLI args or raw strings from config)
+        result = [v.strip() for v in value.splitlines() if v.strip()]
+        log.debug("converted string to list", converted_value=result)
+        return result
+
+    # Generic fallback: call type_hint(value) as constructor
+    try:
+        if origin is not None:
+            result = t.cast(type, origin)(value)
+        else:
+            result = t.cast(type, type_hint)(value)
+        log.debug("converted using type constructor", converted_value=result)
+        return result
+    except (TypeError, ValueError) as e:
+        log.debug("failed to convert value", error=str(e))
+        raise TypeError(
+            f"Cannot cast value of type {type(value)} to {type_hint}"
+        ) from e
+
+
+def get_pytest_option[T](
+    namespace: str, config: Config, key: str, *, type_hint: type[T] | None = None
+) -> T | t.Any | None:
+    """
+    Retrieve a configuration value from runtime overrides, CLI, or INI files.
+
+    Priority chain:
+    1. Runtime overrides (via config.option in pytest_configure)
+    2. CLI arguments (e.g., --my-key)
+    3. Configuration files (pytest.ini, pyproject.toml)
+
+    Args:
+            namespace: Unique namespace for this plugin (typically __package__).
+            config: The pytest Config object.
+            key: The option name (use underscores).
+            type_hint: Optional expected type for validation and smart casting.
+
+    Returns:
+            The resolved value, optionally casted. Returns None if not found.
+    """
+    log.debug(
+        "getting pytest option", namespace=namespace, key=key, type_hint=type_hint
+    )
+
+    normalized_key = key.replace("-", "_")
+    opt = next(
+        (
+            entry
+            for entry in REGISTRY.get(namespace, [])
+            if entry.name == normalized_key
+        ),
+        None,
+    )
+
+    # Validation
+    if type_hint is not None and opt is not None and opt.type_hint is not None:
+        if type_hint != opt.type_hint:
+            warnings.warn(
+                f"Type mismatch for option '{key}': requested {type_hint}, configured {opt.type_hint}"
+            )
+
+    # CLI/runtime value from config.option (argparse Namespace)
+    val = getattr(config.option, normalized_key, None)
+    source = None
+
+    if val in (None, ""):
+        # INI value from pytest.ini or pyproject.toml
+        try:
+            val = config.getini(normalized_key)
+            if val not in (None, ""):
+                source = "ini"
+        except (ValueError, KeyError):
+            val = None
+
+    else:
+        source = "cli"
+
+    if val in (None, ""):
+        # Default value from the registry
+        if opt is not None:
+            val = opt.default
+            source = "default"
+
+    log.debug("resolved raw value", key=key, raw_value=val, source=source)
+
+    # Determine effective type hint
+    effective_type_hint = type_hint
+    if effective_type_hint is None and opt is not None:
+        effective_type_hint = opt.type_hint
+
+    # Smart cast
+    if val is not None and effective_type_hint is not None:
+        try:
+            result = _smart_cast(val, effective_type_hint)
+            log.debug("returning converted value", key=key, converted_value=result)
+            return result
+        except TypeError as e:
+            # warning? or just return val?
+            # Let's log a warning and return val to be safe
+            warnings.warn(f"Failed to cast option '{key}': {e}")
+            log.debug(
+                "returning raw value after conversion failure", key=key, value=val
+            )
+            return val
+
+    log.debug("returning raw value", key=key, value=val)
+    return val