pytest-plugin-utils 0.1.0__tar.gz → 0.2.0__tar.gz

{pytest_plugin_utils-0.1.0 → pytest_plugin_utils-0.2.0}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.3
 Name: pytest-plugin-utils
-Version: 0.1.0
+Version: 0.2.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
@@ -31,7 +30,9 @@ uv add pytest-plugin-utils
 
 ### Configuration Options
 
-Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference:
+Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference.
+
+#### For Plugin Authors
 
 ```python
 from pytest_plugin_utils import set_pytest_option, register_pytest_options, get_pytest_option
@@ -55,6 +56,38 @@ def pytest_configure(config):
     api_url = get_pytest_option(__package__, config, "api_url", type_hint=str)
 ```
 
+#### For Plugin Users
+
+Once a plugin has registered options using this package, users can configure them in three ways (in order of precedence):
+
+1. **Command Line** (highest priority):
+   ```bash
+   pytest --api-url=https://prod.example.com
+   ```
+
+2. **INI Configuration** (medium priority):
+
+   In `pytest.ini`:
+   ```ini
+   [pytest]
+   api_url = https://staging.example.com
+   ```
+
+   Or in `pyproject.toml`:
+   ```toml
+   [tool.pytest.ini_options]
+   api_url = "https://staging.example.com"
+   ```
+
+3. **Runtime/Programmatic** (via conftest.py):
+   ```python
+   def pytest_configure(config):
+       # Override at runtime
+       config.option.api_url = "https://custom.example.com"
+   ```
+
+The value resolution follows this precedence chain, with each level overriding the next: Runtime > CLI > INI > Default.
+
 ### Artifact Directory Management
 
 Create per-test artifact directories with sanitized names:
@@ -81,6 +114,13 @@ def pytest_runtest_setup(item):
 * Per-test artifact directory creation and resolution
 * Type-safe configuration retrieval with warnings on mismatches
 
+## Related Projects
+
+* [pytest-playwright-visual-snapshot](https://github.com/iloveitaly/pytest-playwright-visual-snapshot): Easy pytest visual regression testing using playwright.
+* [pytest-line-runner](https://github.com/iloveitaly/pytest-line-runner): Run pytest tests by line number instead of exact test name.
+* [pytest-celery-utils](https://github.com/iloveitaly/pytest-celery-utils): Pytest plugin for inspecting Celery task queues in Redis during tests.
+* [pytest-playwright-artifacts](https://github.com/iloveitaly/pytest-playwright-artifacts): Pytest plugin that captures HTML, screenshots, and console logs on Playwright test failures.
+
 ## [MIT License](LICENSE.md)
 
 ---

{pytest_plugin_utils-0.1.0 → pytest_plugin_utils-0.2.0}/README.md

@@ -19,7 +19,9 @@ uv add pytest-plugin-utils
 
 ### Configuration Options
 
-Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference:
+Register pytest options with automatic precedence handling (runtime > CLI > INI > defaults) and type inference.
+
+#### For Plugin Authors
 
 ```python
 from pytest_plugin_utils import set_pytest_option, register_pytest_options, get_pytest_option
@@ -43,6 +45,38 @@ def pytest_configure(config):
     api_url = get_pytest_option(__package__, config, "api_url", type_hint=str)
 ```
 
+#### For Plugin Users
+
+Once a plugin has registered options using this package, users can configure them in three ways (in order of precedence):
+
+1. **Command Line** (highest priority):
+   ```bash
+   pytest --api-url=https://prod.example.com
+   ```
+
+2. **INI Configuration** (medium priority):
+
+   In `pytest.ini`:
+   ```ini
+   [pytest]
+   api_url = https://staging.example.com
+   ```
+
+   Or in `pyproject.toml`:
+   ```toml
+   [tool.pytest.ini_options]
+   api_url = "https://staging.example.com"
+   ```
+
+3. **Runtime/Programmatic** (via conftest.py):
+   ```python
+   def pytest_configure(config):
+       # Override at runtime
+       config.option.api_url = "https://custom.example.com"
+   ```
+
+The value resolution follows this precedence chain, with each level overriding the next: Runtime > CLI > INI > Default.
+
 ### Artifact Directory Management
 
 Create per-test artifact directories with sanitized names:
@@ -69,6 +103,13 @@ def pytest_runtest_setup(item):
 * Per-test artifact directory creation and resolution
 * Type-safe configuration retrieval with warnings on mismatches
 
+## Related Projects
+
+* [pytest-playwright-visual-snapshot](https://github.com/iloveitaly/pytest-playwright-visual-snapshot): Easy pytest visual regression testing using playwright.
+* [pytest-line-runner](https://github.com/iloveitaly/pytest-line-runner): Run pytest tests by line number instead of exact test name.
+* [pytest-celery-utils](https://github.com/iloveitaly/pytest-celery-utils): Pytest plugin for inspecting Celery task queues in Redis during tests.
+* [pytest-playwright-artifacts](https://github.com/iloveitaly/pytest-playwright-artifacts): Pytest plugin that captures HTML, screenshots, and console logs on Playwright test failures.
+
 ## [MIT License](LICENSE.md)
 
 ---

{pytest_plugin_utils-0.1.0 → pytest_plugin_utils-0.2.0}/pyproject.toml

@@ -1,18 +1,18 @@
 [project]
 name = "pytest-plugin-utils"
-version = "0.1.0"
+version = "0.2.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"]
+dependencies = []
 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"]
+requires = ["uv_build>=0.10.0,<0.11"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -30,7 +30,7 @@ dev = [
 ]
 
 [tool.pyright]
-exclude = ["examples/", "playground/", "tmp/", ".venv/", "tests/"]
+exclude = ["examples/", "playground/", "tmp/", ".venv/"]
 
 [tool.pytest.ini_options]
 addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"

{pytest_plugin_utils-0.1.0 → pytest_plugin_utils-0.2.0}/pytest_plugin_utils/__init__.py

@@ -1,7 +1,6 @@
 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,

pytest_plugin_utils-0.2.0/pytest_plugin_utils/artifacts.py

@@ -0,0 +1,64 @@
+"""
+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.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+
+
+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(
+    item: pytest.Item, base_dir: Path, *, create: bool = False
+) -> Path:
+    """
+    Get or create the artifact directory for a specific test item.
+
+    This function determines the subdirectory for the specific test item
+    using its sanitized nodeid, relative to the provided base_dir.
+
+    Args:
+        item: The pytest.Item (test case) for which to get the directory.
+        base_dir: The root output directory for artifacts.
+        create: If True, creates the artifact directory and its parents if they do not exist.
+
+    Returns:
+        A pathlib.Path object pointing to the specific test's artifact directory.
+    """
+    if create:
+        base_dir.mkdir(parents=True, exist_ok=True)
+
+    per_test_dir = base_dir / sanitize_for_artifacts(item.nodeid)
+
+    if create:
+        per_test_dir.mkdir(parents=True, exist_ok=True)
+
+    return per_test_dir

{pytest_plugin_utils-0.1.0 → pytest_plugin_utils-0.2.0}/pytest_plugin_utils/config.py

@@ -10,11 +10,11 @@ import warnings
 from dataclasses import dataclass
 from pathlib import Path
 
-import structlog
+import logging
 from _pytest.config import Config
 from _pytest.config.argparsing import Parser
 
-log = structlog.get_logger(logger_name=__package__)
+log = logging.getLogger(__package__)
 
 
 @dataclass
@@ -136,7 +136,12 @@ def register_pytest_options(namespace: str, parser: Parser) -> None:
         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)
+            if opt.type_hint is bool:
+                parser.addoption(
+                    cli_name, action="store_true", default=None, help=help_text
+                )
+            else:
+                parser.addoption(cli_name, action="store", default=None, help=help_text)
 
         # INI Registration
         if opt.available in ("all", "ini"):
@@ -150,7 +155,7 @@ def _smart_cast[T](value: t.Any, type_hint: type[T] | None) -> T | t.Any:
     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)
+    log.debug("casting value raw_value=%s target_type=%s", value, type_hint)
 
     if type_hint is None:
         return value
@@ -173,14 +178,14 @@ def _smart_cast[T](value: t.Any, type_hint: type[T] | None) -> T | t.Any:
     # 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)
+        log.debug("converted string to bool converted_value=%s", 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)
+        log.debug("converted string to list converted_value=%s", result)
         return result
 
     # Generic fallback: call type_hint(value) as constructor
@@ -189,18 +194,30 @@ def _smart_cast[T](value: t.Any, type_hint: type[T] | None) -> T | t.Any:
             result = t.cast(type, origin)(value)
         else:
             result = t.cast(type, type_hint)(value)
-        log.debug("converted using type constructor", converted_value=result)
+        log.debug("converted using type constructor converted_value=%s", result)
         return result
     except (TypeError, ValueError) as e:
-        log.debug("failed to convert value", error=str(e))
+        log.debug("failed to convert value error=%s", str(e))
         raise TypeError(
             f"Cannot cast value of type {type(value)} to {type_hint}"
         ) from e
 
 
+@t.overload
 def get_pytest_option[T](
-    namespace: str, config: Config, key: str, *, type_hint: type[T] | None = None
-) -> T | t.Any | None:
+    namespace: str, config: Config, key: str, *, type_hint: type[T]
+) -> T | None: ...
+
+
+@t.overload
+def get_pytest_option(
+    namespace: str, config: Config, key: str, *, type_hint: None = None
+) -> t.Any | None: ...
+
+
+def get_pytest_option(
+    namespace: str, config: Config, key: str, *, type_hint: t.Any | None = None
+) -> t.Any | None:
     """
     Retrieve a configuration value from runtime overrides, CLI, or INI files.
 
@@ -219,7 +236,10 @@ def get_pytest_option[T](
             The resolved value, optionally casted. Returns None if not found.
     """
     log.debug(
-        "getting pytest option", namespace=namespace, key=key, type_hint=type_hint
+        "getting pytest option namespace=%s key=%s type_hint=%s",
+        namespace,
+        key,
+        type_hint,
     )
 
     normalized_key = key.replace("-", "_")
@@ -261,7 +281,7 @@ def get_pytest_option[T](
             val = opt.default
             source = "default"
 
-    log.debug("resolved raw value", key=key, raw_value=val, source=source)
+    log.debug("resolved raw value key=%s raw_value=%s source=%s", key, val, source)
 
     # Determine effective type hint
     effective_type_hint = type_hint
@@ -272,16 +292,18 @@ def get_pytest_option[T](
     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)
+            log.debug(
+                "returning converted value key=%s converted_value=%s", key, 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
+                "returning raw value after conversion failure key=%s value=%s", key, val
             )
             return val
 
-    log.debug("returning raw value", key=key, value=val)
+    log.debug("returning raw value key=%s value=%s", key, val)
     return val

pytest_plugin_utils-0.1.0/pytest_plugin_utils/artifacts.py

@@ -1,119 +0,0 @@
-"""
-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