pytest-telescope 0.1.0a1__tar.gz

pytest_telescope-0.1.0a1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+site/
+*.egg-info/
+.pytest-telescope/

pytest_telescope-0.1.0a1/.readthedocs.yaml

@@ -0,0 +1,11 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true
+python:
+  install:
+    - requirements: docs/requirements.txt

pytest_telescope-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+See [development](docs/development.md) for installation and checks, and the
+[execution contract](docs/specification.md) for the complete first release.
+
+Add behavioral regression tests and relevant documentation together. Real worker
+integration tests must establish isolation before it is claimed; skipped sandbox
+tests are not a qualifying result. Keep the synthetic benchmark reproducible and
+publish observed measurements, including overhead and unfavorable results.
+
+Contributions are licensed under the project's MIT License.

pytest_telescope-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xu-hao
+
+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.

pytest_telescope-0.1.0a1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: pytest-telescope
+Version: 0.1.0a1
+Summary: Declared inputs. Isolated tests. Focused reruns.
+Project-URL: Repository, https://github.com/xu-hao/pytest-telescope
+Project-URL: Issues, https://github.com/xu-hao/pytest-telescope/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: pytest<10,>=8.3
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mkdocs==1.6.1; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-telescope
+
+Declared inputs. Isolated tests. Focused reruns.
+
+pytest-telescope uses one manifest to define which project files a test target can read
+and which changes invalidate its previous successful result. Each target is a fresh
+pytest session inside a Linux Docker container. Successful unchanged targets can reuse
+their recorded results; reused cases are reported separately from executed cases.
+
+**Alpha (0.1.0a1):** implemented and qualified on Linux with real Docker workers. The
+[benchmark](https://github.com/xu-hao/pytest-telescope/blob/main/docs/benchmark.md)
+records measured cold, warm, and selective reruns, including their overhead. The
+supported boundary and reuse assumptions are explicit; arbitrary Python determinism is
+not guaranteed.
+
+## Quickstart
+
+Requirements: Linux, Python 3.11+, and a working local Docker daemon exposed through a
+Unix socket, with permission to build and run Linux containers. Runtime preparation
+needs network access; test workers have no network. Install from this checkout in a
+virtual environment:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+```
+
+From your project's root, add a manifest to `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[tool.pytest_telescope]
+test_roots = ["tests"]
+
+[tool.pytest_telescope.bundles.common]
+inputs = ["tests/conftest.py", "app/__init__.py"]
+
+[tool.pytest_telescope.targets.parser]
+tests = ["tests/test_parser.py"]
+inputs = ["app/parser.py", "tests/data/input.json"]
+bundles = ["common"]
+```
+
+Declare every fixture, helper, application module, and resource your target needs. Then
+prepare a clean runtime and execute:
+
+```sh
+python -m pytest_telescope runtime
+python -m pytest_telescope plan
+python -m pytest_telescope run --explain -- -q
+python -m pytest_telescope run --explain -- -q
+```
+
+The second identical run can reuse complete successful targets. A missing input is an
+error, not permission to expose more of your checkout. See the
+[specification](https://github.com/xu-hao/pytest-telescope/blob/main/docs/specification.md)
+for declarations, grouping, invalidation, limits, and troubleshooting, and the
+[synthetic
+example](https://github.com/xu-hao/pytest-telescope/blob/main/examples/analytics/README.md)
+for an executable three-target project.
+
+```sh
+python -m pytest_telescope run --force -- -q
+python -m pytest_telescope run --no-cache -- -q
+python -m pytest_telescope run --timeout 120 -- -k parser
+```
+
+`--force` executes even when a successful record exists. `--no-cache` disables reuse and
+recording. For permanently non-cacheable targets, set `cache = false`. Clocks,
+randomness, environment, native state, and external services can invalidate assumptions
+about reuse: filesystem isolation does not prove arbitrary Python programs
+deterministic.
+
+## Runtime and pytest integration
+
+The runtime contains a pinned Python base image and wheel-installed dependencies, not
+your host virtual environment or an editable copy of your application. For additional
+third-party packages, pass a requirements file containing the complete transitive
+dependency closure as exact `name==version` wheel dependencies:
+
+```sh
+python -m pytest_telescope runtime --requirements requirements.txt
+```
+
+The dedicated CLI starts no host pytest session. `pytest --telescope` also routes to
+isolated workers, but other installed plugins may execute during host pytest startup.
+`pytest --telescope-plan` remains available for static planning. Ordinary pytest stays
+ordinary when telescope mode is disabled; use `-p no:telescope` to disable plugin
+loading entirely.
+
+See
+[development](https://github.com/xu-hao/pytest-telescope/blob/main/docs/development.md),
+[benchmark
+methodology](https://github.com/xu-hao/pytest-telescope/blob/main/docs/benchmark.md),
+and
+[publishing](https://github.com/xu-hao/pytest-telescope/blob/main/docs/publishing.md).
+Licensed under the [MIT
+License](https://github.com/xu-hao/pytest-telescope/blob/main/LICENSE).

pytest_telescope-0.1.0a1/README.md

@@ -0,0 +1,101 @@
+# pytest-telescope
+
+Declared inputs. Isolated tests. Focused reruns.
+
+pytest-telescope uses one manifest to define which project files a test target can read
+and which changes invalidate its previous successful result. Each target is a fresh
+pytest session inside a Linux Docker container. Successful unchanged targets can reuse
+their recorded results; reused cases are reported separately from executed cases.
+
+**Alpha (0.1.0a1):** implemented and qualified on Linux with real Docker workers. The
+[benchmark](https://github.com/xu-hao/pytest-telescope/blob/main/docs/benchmark.md)
+records measured cold, warm, and selective reruns, including their overhead. The
+supported boundary and reuse assumptions are explicit; arbitrary Python determinism is
+not guaranteed.
+
+## Quickstart
+
+Requirements: Linux, Python 3.11+, and a working local Docker daemon exposed through a
+Unix socket, with permission to build and run Linux containers. Runtime preparation
+needs network access; test workers have no network. Install from this checkout in a
+virtual environment:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+```
+
+From your project's root, add a manifest to `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+pythonpath = ["."]
+
+[tool.pytest_telescope]
+test_roots = ["tests"]
+
+[tool.pytest_telescope.bundles.common]
+inputs = ["tests/conftest.py", "app/__init__.py"]
+
+[tool.pytest_telescope.targets.parser]
+tests = ["tests/test_parser.py"]
+inputs = ["app/parser.py", "tests/data/input.json"]
+bundles = ["common"]
+```
+
+Declare every fixture, helper, application module, and resource your target needs. Then
+prepare a clean runtime and execute:
+
+```sh
+python -m pytest_telescope runtime
+python -m pytest_telescope plan
+python -m pytest_telescope run --explain -- -q
+python -m pytest_telescope run --explain -- -q
+```
+
+The second identical run can reuse complete successful targets. A missing input is an
+error, not permission to expose more of your checkout. See the
+[specification](https://github.com/xu-hao/pytest-telescope/blob/main/docs/specification.md)
+for declarations, grouping, invalidation, limits, and troubleshooting, and the
+[synthetic
+example](https://github.com/xu-hao/pytest-telescope/blob/main/examples/analytics/README.md)
+for an executable three-target project.
+
+```sh
+python -m pytest_telescope run --force -- -q
+python -m pytest_telescope run --no-cache -- -q
+python -m pytest_telescope run --timeout 120 -- -k parser
+```
+
+`--force` executes even when a successful record exists. `--no-cache` disables reuse and
+recording. For permanently non-cacheable targets, set `cache = false`. Clocks,
+randomness, environment, native state, and external services can invalidate assumptions
+about reuse: filesystem isolation does not prove arbitrary Python programs
+deterministic.
+
+## Runtime and pytest integration
+
+The runtime contains a pinned Python base image and wheel-installed dependencies, not
+your host virtual environment or an editable copy of your application. For additional
+third-party packages, pass a requirements file containing the complete transitive
+dependency closure as exact `name==version` wheel dependencies:
+
+```sh
+python -m pytest_telescope runtime --requirements requirements.txt
+```
+
+The dedicated CLI starts no host pytest session. `pytest --telescope` also routes to
+isolated workers, but other installed plugins may execute during host pytest startup.
+`pytest --telescope-plan` remains available for static planning. Ordinary pytest stays
+ordinary when telescope mode is disabled; use `-p no:telescope` to disable plugin
+loading entirely.
+
+See
+[development](https://github.com/xu-hao/pytest-telescope/blob/main/docs/development.md),
+[benchmark
+methodology](https://github.com/xu-hao/pytest-telescope/blob/main/docs/benchmark.md),
+and
+[publishing](https://github.com/xu-hao/pytest-telescope/blob/main/docs/publishing.md).
+Licensed under the [MIT
+License](https://github.com/xu-hao/pytest-telescope/blob/main/LICENSE).