pyneedy 1.0.0__tar.gz

pyneedy-1.0.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+
+# Environment files
+.env
+.env.*
+
+# Virtual environments, caches, and IDE settings
+.venv
+.vscode
+.pytest_cache
+.ruff_cache
+
+# Documentation build
+site/
+
+# Agent Files
+CLAUDE.md
+.claude/

pyneedy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zurab Mujirishvili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyneedy-1.0.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: pyneedy
+Version: 1.0.0
+Summary: A minimal library for writing tests with optional dependencies.
+Project-URL: Homepage, https://pytooling.gitlab.io/needy/
+Project-URL: Repository, https://gitlab.com/pytooling/needy
+Project-URL: Documentation, https://pytooling.gitlab.io/needy/
+Project-URL: Bug Tracker, https://gitlab.com/pytooling/needy/-/issues
+Project-URL: Changelog, https://gitlab.com/pytooling/needy/-/blob/main/CHANGELOG.md
+Author-email: Zurab Mujirishvili <zurab.mu@gmail.com>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Needy
+
+A minimal library for writing tests with optional dependencies.
+
+## Installation
+
+Python 3.11+ is required.
+
+```bash
+pip install pyneedy
+```
+
+## Quick Start
+
+Define "probes" for the optional dependencies you want to use, e.g. JAX.
+
+```python
+class check:
+    @staticmethod
+    def jax() -> None:
+        # A probe just tries to import the optional dependency.
+        import jax as jax
+```
+
+Then wrap imports related to the optional dependency in a `needs.modules(...)` scope like this:
+
+```python
+from needy import needs
+
+from pytest import mark
+
+with needs.modules(check.jax):
+    import jax.numpy as jnp
+
+@mark.parametrize(
+    ["array", "expected_sum"],
+    [
+        (
+            array := jnp.array([1.0, 2.0]),
+            expected_sum := 3.0
+        ),
+        (
+            array := jnp.array([]),
+            expected_sum := 0.0
+        )
+    ]
+)
+def test_that_a_sum_is_computed(array, expected_sum) -> None:
+    assert array.sum() == expected_sum
+```
+
+If `jax` is installed, the imports inside the `with` block resolve normally. If it isn't, every missing import inside the block is replaced with a proxy, and only the first real use of the missing modules will raise an error.
+
+See the [docs](https://pytooling.gitlab.io/needy/) for more.
+
+## Development
+
+### Prerequisites
+
+- Python >= 3.11
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- [just](https://github.com/casey/just) (optional, for convenience)
+
+### Getting Started
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://gitlab.com/pytooling/needy.git
+   cd needy
+   ```
+
+1. Create a virtual environment and install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+1. Install pre-commit hooks:
+
+   ```bash
+   uv run pre-commit install
+   ```
+
+### Running Checks
+
+```bash
+just check
+```
+
+Or manually:
+
+```bash
+uv run ruff check --fix && uv run ruff format && uv run pyright && uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pyneedy-1.0.0/README.md

@@ -0,0 +1,99 @@
+# Needy
+
+A minimal library for writing tests with optional dependencies.
+
+## Installation
+
+Python 3.11+ is required.
+
+```bash
+pip install pyneedy
+```
+
+## Quick Start
+
+Define "probes" for the optional dependencies you want to use, e.g. JAX.
+
+```python
+class check:
+    @staticmethod
+    def jax() -> None:
+        # A probe just tries to import the optional dependency.
+        import jax as jax
+```
+
+Then wrap imports related to the optional dependency in a `needs.modules(...)` scope like this:
+
+```python
+from needy import needs
+
+from pytest import mark
+
+with needs.modules(check.jax):
+    import jax.numpy as jnp
+
+@mark.parametrize(
+    ["array", "expected_sum"],
+    [
+        (
+            array := jnp.array([1.0, 2.0]),
+            expected_sum := 3.0
+        ),
+        (
+            array := jnp.array([]),
+            expected_sum := 0.0
+        )
+    ]
+)
+def test_that_a_sum_is_computed(array, expected_sum) -> None:
+    assert array.sum() == expected_sum
+```
+
+If `jax` is installed, the imports inside the `with` block resolve normally. If it isn't, every missing import inside the block is replaced with a proxy, and only the first real use of the missing modules will raise an error.
+
+See the [docs](https://pytooling.gitlab.io/needy/) for more.
+
+## Development
+
+### Prerequisites
+
+- Python >= 3.11
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- [just](https://github.com/casey/just) (optional, for convenience)
+
+### Getting Started
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://gitlab.com/pytooling/needy.git
+   cd needy
+   ```
+
+1. Create a virtual environment and install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+1. Install pre-commit hooks:
+
+   ```bash
+   uv run pre-commit install
+   ```
+
+### Running Checks
+
+```bash
+just check
+```
+
+Or manually:
+
+```bash
+uv run ruff check --fix && uv run ruff format && uv run pyright && uv run pytest
+```
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

pyneedy-1.0.0/needy/__init__.py

@@ -0,0 +1,2 @@
+from .factory import needs as needs
+from .modules import UnknownModuleUsageError as UnknownModuleUsageError

pyneedy-1.0.0/needy/callsite.py

@@ -0,0 +1,32 @@
+import sys
+from dataclasses import dataclass
+from types import FrameType
+from typing import Final
+
+PACKAGE: Final = __name__.split(".")[0]
+
+
+def _is_internal_frame(frame: FrameType) -> bool:
+    return (name := frame.f_globals.get("__name__", "")) == PACKAGE or name.startswith(  # pyright: ignore[reportAny]
+        f"{PACKAGE}."
+    )
+
+
+@dataclass(frozen=True)
+class CallSite:
+    file: str
+    line: int
+
+    @classmethod
+    def capture(cls) -> "CallSite":
+        try:
+            frame = sys._getframe(1)  # pyright: ignore[reportPrivateUsage]
+            while frame is not None:
+                if not _is_internal_frame(frame):
+                    return cls(frame.f_code.co_filename, frame.f_lineno)
+
+                frame = frame.f_back
+        except (AttributeError, ValueError):
+            pass
+
+        return cls("<unknown>", 0)

pyneedy-1.0.0/needy/factory.py

@@ -0,0 +1,44 @@
+from needy.modules import ModuleNeeds, ModuleProbe
+
+
+class needs:
+    """Entry point for declaring optional module dependencies.
+
+    The class is a namespace, not something you instantiate. Use its
+    classmethods (currently just `modules`) to open a scope in which
+    missing optional dependencies are tolerated.
+    """
+
+    @staticmethod
+    def modules(*probes: ModuleProbe) -> ModuleNeeds:
+        """Open a scope where missing imports are replaced with proxies.
+
+        Each probe is called once on entry. If *any* probe raises
+        `ModuleNotFoundError`, the import machinery is patched for
+        the duration of the `with` block so that imports of missing
+        modules return a `Proxy` instead of
+        raising. The original import machinery is restored on exit.
+
+        Args:
+            *probes: Zero or more callables that each attempt to import
+                the optional dependencies the block requires.
+
+        Returns:
+            A context manager that installs and removes the import patch.
+
+        Example:
+            ```python
+            def jax_probe() -> None:
+                import jax as jax
+
+
+            with needs.modules(jax_probe):
+                import jax.numpy as jnp
+            ```
+        """
+
+        def combined() -> None:
+            for probe in probes:
+                probe()
+
+        return ModuleNeeds.checking(combined)

pyneedy-1.0.0/needy/modules.py

@@ -0,0 +1,215 @@
+import builtins
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Callable, NoReturn, Protocol, final, override
+
+from needy.callsite import CallSite
+
+
+class UnknownModuleUsageError(ModuleNotFoundError):
+    """Raised when a proxied (missing) module is used in a way that
+    cannot be deferred any further.
+
+    This is a subclass of `ModuleNotFoundError`, so existing
+    `except ModuleNotFoundError:` handlers will still catch it. The
+    extra attributes record where the failure originated so the
+    operation that triggered it can be traced back to the original
+    import.
+
+    Attributes:
+        module_name: Dotted name of the proxy at the point of failure,
+            including any attribute accesses (e.g. `"jax.numpy.asarray"`).
+        operation: Name of the dunder method that forced materialization
+            (e.g. `"__bool__"`, `"__eq__"`).
+        source_file: File where the missing module was originally imported.
+        source_line: Line where the missing module was originally imported.
+    """
+
+    module_name: str
+    operation: str
+    source_file: str
+    source_line: int
+
+    def __init__(
+        self,
+        *,
+        module_name: str,
+        operation: str,
+        source_file: str,
+        source_line: int,
+    ) -> None:
+        self.module_name = module_name
+        self.operation = operation
+        self.source_file = source_file
+        self.source_line = source_line
+        root = module_name.split(".")[0]
+        super().__init__(
+            f"Attempted to use {module_name!r} (operation: {operation}), "
+            + f"but module {root!r} was not installed when imported at "
+            + f"{source_file}:{source_line}"
+        )
+
+
+class ModuleProbe(Protocol):
+    """Callable that tries to import one or more optional dependencies.
+
+    A probe takes no arguments and returns nothing. It should attempt
+    the imports it represents; if any of them raise `ModuleNotFoundError`,
+    the surrounding `needs.modules(...)` scope activates its proxy
+    patch.
+    """
+
+    def __call__(self) -> None:
+        """Attempts to import a module."""
+        ...
+
+
+@final
+class Proxy:
+    __slots__: tuple[str, ...] = ("_name_", "_site_")
+    _name_: str
+    _site_: CallSite
+
+    def __init__(self, name: str, site: CallSite) -> None:
+        self._name_ = name
+        self._site_ = site
+
+    def __getattr__(self, attr: str) -> "Proxy":
+        return Proxy(f"{self._name_}.{attr}", self._site_)
+
+    @override
+    def __repr__(self) -> str:
+        return f"<Proxy: {self._name_}>"
+
+    def __bool__(self) -> bool:
+        self._fail_("__bool__")
+
+    def __len__(self) -> int:
+        self._fail_("__len__")
+
+    def __iter__(self) -> "Proxy":
+        self._fail_("__iter__")
+
+    def __next__(self) -> object:
+        self._fail_("__next__")
+
+    def __int__(self) -> int:
+        self._fail_("__int__")
+
+    def __float__(self) -> float:
+        self._fail_("__float__")
+
+    def __index__(self) -> int:
+        self._fail_("__index__")
+
+    @override
+    def __eq__(self, other: object) -> bool:
+        self._fail_("__eq__")
+
+    @override
+    def __ne__(self, other: object) -> bool:
+        self._fail_("__ne__")
+
+    @override
+    def __hash__(self) -> int:
+        self._fail_("__hash__")
+
+    def __lt__(self, other: object) -> bool:
+        self._fail_("__lt__")
+
+    def __le__(self, other: object) -> bool:
+        self._fail_("__le__")
+
+    def __gt__(self, other: object) -> bool:
+        self._fail_("__gt__")
+
+    def __ge__(self, other: object) -> bool:
+        self._fail_("__ge__")
+
+    def _chain_(self, *args: object, **kwargs: object) -> "Proxy":  # pyright: ignore[reportUnusedParameter]
+        return Proxy(self._name_, self._site_)
+
+    __call__ = _chain_
+    __getitem__ = _chain_
+
+    __add__ = __radd__ = _chain_
+    __sub__ = __rsub__ = _chain_
+    __mul__ = __rmul__ = _chain_
+    __truediv__ = __rtruediv__ = _chain_
+    __floordiv__ = __rfloordiv__ = _chain_
+    __mod__ = __rmod__ = _chain_
+    __pow__ = __rpow__ = _chain_
+    __matmul__ = __rmatmul__ = _chain_
+
+    __and__ = __rand__ = _chain_
+    __or__ = __ror__ = _chain_
+    __xor__ = __rxor__ = _chain_
+    __lshift__ = __rlshift__ = _chain_
+    __rshift__ = __rrshift__ = _chain_
+
+    __neg__ = __pos__ = __invert__ = __abs__ = _chain_
+
+    def _fail_(self, operation: str) -> NoReturn:
+        raise UnknownModuleUsageError(
+            module_name=self._name_,
+            operation=operation,
+            source_file=self._site_.file,
+            source_line=self._site_.line,
+        )
+
+
+@dataclass
+class ModuleNeeds:
+    """Context manager returned by `needs.modules(...)`.
+
+    On entry the probe is invoked. If it raises `ModuleNotFoundError`,
+    `builtins.__import__` is replaced with a patched version that
+    returns a `Proxy` for any module that fails to import. On exit the
+    original `__import__` is restored.
+
+    You normally do not construct this directly; use
+    `needs.modules(...)`.
+    """
+
+    probe: ModuleProbe
+    original_import: Callable[..., object] | None
+
+    @staticmethod
+    def checking(probe: ModuleProbe) -> "ModuleNeeds":
+        """Build a `ModuleNeeds` from a probe."""
+        return ModuleNeeds(probe, original_import=None)
+
+    def __enter__(self) -> None:
+        try:
+            self.probe()
+        except ModuleNotFoundError:
+            self.original_import = builtins.__import__
+            builtins.__import__ = self._patched_import
+
+    def _patched_import(
+        self,
+        name: str,
+        globals: dict[str, object] | None = None,
+        locals: dict[str, object] | None = None,
+        fromlist: tuple[str, ...] = (),
+        level: int = 0,
+    ) -> object:
+        assert self.original_import is not None, (
+            "The patched import function should not be called, when a "
+            "reference to the original import function is not stored."
+        )
+
+        try:
+            return self.original_import(name, globals, locals, fromlist, level)
+        except ModuleNotFoundError:
+            return Proxy(name.split(".")[0], CallSite.capture())
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self.original_import is not None:
+            builtins.__import__ = self.original_import
+            self.original_import = None

pyneedy-1.0.0/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "pyneedy"
+dynamic = ["version"]
+description = "A minimal library for writing tests with optional dependencies."
+authors = [{ name = "Zurab Mujirishvili", email = "zurab.mu@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.11"
+license-files = ["LICEN[CS]E*"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://pytooling.gitlab.io/needy/"
+Repository = "https://gitlab.com/pytooling/needy"
+Documentation = "https://pytooling.gitlab.io/needy/"
+"Bug Tracker" = "https://gitlab.com/pytooling/needy/-/issues"
+Changelog = "https://gitlab.com/pytooling/needy/-/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.409",
+    "ruff>=0.15.4",
+    "pre-commit>=4.5.1",
+]
+test = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-subtests>=0.15.0",
+    "pytest-watcher>=0.6.3",
+]
+doc = [
+    "zensical>=0.0.41",
+    "mkdocstrings[python]>=1.0.4",
+]
+
+[tool.uv]
+default-groups = ["dev", "test", "doc"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "needy/",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["needy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.pyright]
+include = ["needy", "tests"]
+
+[tool.ruff.lint]
+extend-select = ["I", "RUF018", "D"]
+
+[tool.ruff.lint.per-file-ignores]
+"*" = [
+    "D10", "D205"
+]
+"tests/**" = [
+    "F841"
+]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+known-first-party = ["needy"]
+known-local-folder = ["tests"]
+section-order = ["future", "standard-library", "first-party", "third-party", "local-folder"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true