= Changelog :toc: left This document lists all notable changes and releases for `asciidoctest`. == link:https://pypi.org/project/asciidoctest/0.2.0a4/[0.2.0a4] - 2026-08-31 === Added * **Direct Python Source Code & Docstring Doctest Extraction (Issue #3)**: - **Full AST Node Traversal**: Static AST docstring extraction via `_DocstringVisitor` now extracts docstrings from functions, async functions, classes, nested classes, and nested methods using hierarchical dot-notation naming (e.g., `OuterClass.InnerClass.method_docstring`). - **Multi-target Execution Support**: `asciidoctest.extract_and_run_docstring_tests` now seamlessly accepts Python source file paths (`str` or `pathlib.Path`), module/package directories (recursively discovering `.py` files), imported module name strings, or loaded `types.ModuleType` instances. - **Per-symbol Scope Isolation**: Each symbol's docstring doctests execute in an independent copy of module globals (`dict(module.__dict__)`), preventing state mutation and leakage between separate functions or methods. - **Contextual Failure Traces**: Failure traces format with `[filepath:symbol_name]` identifying the exact location of doctest assertion failures. === Fixed * **Pytest Custom Item Fixture Compatibility**: - Initialized `_fixtureinfo` on custom pytest test items (`AsciiDocItem` and `DocstringTestItem`), eliminating `AttributeError: 'AsciiDocItem' object has no attribute '_fixtureinfo'` when running alongside third-party plugins like `pytest-pyodide`. === Changed * **Upgraded Dependencies**: - Upgraded `asciidoctrine` dependency requirement to `>=0.2.0a5` (table cols DSL, block title attachments #119, attached inline macros #120, Lark parser memoization). - Upgraded `asciidocstring` dependency requirement to `>=0.1.0a8` (AsciiDoc docstrings style guide, semantic docstring model compatibility). - Added `lark>=1.3.1` dependency constraint. * **Test Suite & Coverage Quality**: - Increased unit test coverage across `__init__.py`, `pytest_plugin.py`, and `unittest_integration.py` (achieving 100% statement coverage on `unittest_integration.py` and 109 passing tests). - Configured `asyncio_default_fixture_loop_scope = "function"` to eliminate test runner deprecation warnings. --- == link:https://pypi.org/project/asciidoctest/0.2.0a3/[0.2.0a3] - 2026-08-22 === Added * **Section Scoping, Named Contexts & Reset Markers (Issue #2)**: - **AST Section Boundary Scoping**: Automatic shared state reset when traversing across top-level section boundaries (`==`), isolating independent document chapters, classes, and topics while preserving sequential state flow within each section. - **Named Context Scopes**: Introduced `[source,python,shared=""]` support to allow multiple independent, persistent state timelines within the same document. - **Explicit Reset Markers**: Added `[source,python,reset]` and `[source,python,reset,shared]` directives (also accepting `shared="none"` or `shared="reset"`) to clear all accumulated shared state and named contexts on demand. * **Direct Doctest Extraction API (Issue #3)**: - Added `asciidoctest.extract_and_run_docstring_tests(source_path_or_module, mode="explicit")` for programmatic discovery and execution of doctests from Python source files, package directories, or imported module objects. - Added `find_docstrings_in_py_file` in `asciidoctest.parser` for AST-based static docstring discovery without running module code during parsing. * **PEP 561 Type Information**: Added `asciidoctest/py.typed` marker (PEP 561) so downstream projects using mypy or pyright receive full type information from `asciidoctest`. * **Top-level `AsciiDocTestFailure` export**: `AsciiDocTestFailure` is now re-exported from `asciidoctest.__init__` and included in `__all__`, enabling `from asciidoctest import AsciiDocTestFailure` without submodule access. * **Contextual failure messages**: `AsciiDocTestFailure` raised during directory or module docstring extraction now includes `[filepath:symbol]` context so the failing file and function are immediately identifiable. * **State model quick-reference table**: Added a comprehensive marker/namespace cheatsheet table to `docs/getting-started.adoc` and `docs/state-models.adoc`. === Fixed * **Tolerant Illustrative Includes (Issue #1)**: - Disabled include preprocessing by default (`preprocess_directives=False`) during AsciiDoc doctest parsing, allowing illustrative or documentation-only `include::...[]` macros without requiring target files to exist on disk. * **Pytest pre-filter spacing tolerance (DX)**: Updated the `.py` file pre-filter in `pytest_plugin.py` from a plain string check (`"[source,python"`) to a regex (`re.search(r"\[source\s*,\s*python", content)`), correctly handling AsciiDoc block headers with spaces after commas (e.g. `[source, python, test]`). * **`shared="none"` and `shared="reset"` not triggering reset (Issue #10)**: `block_get_shared_context` now correctly treats `shared="none"` and `shared="reset"` (case-insensitive) as falsy values that do not create named contexts, consistent with the CHANGELOG documentation. === Changed * **Upgraded Dependencies**: - Upgraded `asciidoctrine` dependency requirement to `>=0.2.0a2`. - Upgraded `asciidocstring` dependency requirement to `>=0.1.0a7`. * **`mypy --strict` compliance**: Resolved all 32 strict typing violations across `parser.py`, `runner.py`, `unittest_integration.py`, and `pytest_plugin.py`. `mypy --strict asciidoctest` now reports zero errors. --- == link:https://pypi.org/project/asciidoctest/0.2.0a2/[0.2.0a2] - 2026-07-31 === Added * **Security Policy & Documentation**: - Added `SECURITY.adoc` and dedicated Sphinx `security.adoc` page outlining execution safety context, supported version matrix, and responsible disclosure workflow. === Changed * **Upgraded Dependencies**: - Upgraded `asciidoctrine` dependency constraint to `>=0.1.0a11` to leverage configurable custom URI schemes, bare URL and email autolink features, list continuations, and Post-AST syntax checks. - Upgraded `asciidocstring` dependency constraint to `>=0.1.0a6`. * **Documentation & Styling**: - Published multi-page HTML documentation site using `sphinx_rtd_theme` styled with AsciiDoctrine's forest-green dark theme overrides. --- == link:https://pypi.org/project/asciidoctest/0.2.0a1/[0.2.0a1] - 2026-07-17 === Added * **Unified Symmetric Namespace and State Model**: - Established identical, symmetric execution and namespace isolation rules for both interactive REPL and non-interactive script blocks. - **Isolated & Ephemeral (`test`)**: Run in a clean copy of the initial namespace, keeping them fully isolated from subsequent side-effects by default. - **Persistent & Stateful (`shared`)**: Run in the sequential shared globals (like a continuous notebook), allowing variables to persist top-to-bottom across both script and interactive blocks. - **Ephemeral Copy (`shared, test`)**: Run in a temporary snapshot copy of the shared globals, enabling access to preceding variables while safely discarding local mutations when the block ends. - **No Marker**: Treated as a static listing and skipped by default. * **Intelligent `eager` Mode Safety Guard**: - In `eager` mode, unmarked listings are only run as isolated `test` blocks if the document contains zero explicit markers. If *any* block in the file has explicit attributes or roles, `eager` mode is bypassed/disabled for that file. === Refactored * **Centralized Block Marker Inspection**: - Refactored internal parsing to centralize block marker extraction (`block_has_test_marker` and `block_has_shared_marker`), eliminating duplication across the parser and runner. * **Verifiable Documentation Terminology**: - Re-framed the project documentation and `README.adoc` around verifiable and stateful narrative documentation rather than Literate Programming. --- == link:https://pypi.org/project/asciidoctest/0.1.0a4/[0.1.0a4] - 2026-07-16 === Added * **Traverser Safety Guard**: Introduced `SafeTestBlockExtractorVisitor` to safely bypass raw strings or child objects without a `.name` attribute during AST traversal, preventing crashes on complex unparsed text blocks. * **Pytest Discovery Constraints**: Configured `testpaths` under `[tool.pytest.ini_options]` in `pyproject.toml` to restrict search patterns to `tests/` and `README.adoc`, preventing slow recursive runs over external directories. === Changed * **Upgraded dependencies**: - Bumped `asciidocstring` requirement to `>=0.1.0a4` to support the latest safe parsing mode releases. --- == link:https://pypi.org/project/asciidoctest/0.1.0a3/[0.1.0a3] - 2026-07-14 === Changed * **Upgraded dependencies**: - Upgraded `asciidoctrine` to `>=0.1.0a8`. - Upgraded `asciidocstring` to `>=0.1.0a3`. * **Documentation Casing**: Aligned all references to `asciidoctest` / `AsciiDoctest` to follow standard casing style guide rules (using Title Case `AsciiDoctest` for prose, and lowercase backticks `asciidoctest` for code). --- == link:https://pypi.org/project/asciidoctest/0.1.0a2/[0.1.0a2] - 2026-07-13 === Added * **Optional test dependencies group**: Added a `[project.optional-dependencies]` section to `pyproject.toml` with a `test` target including `pytest` and `pytest-cov`. * **Advanced test coverage validation**: Added robust unit and integration tests covering parser exceptions, doctest unexpected exceptions, and class-level `unittest` TestCase helpers (achieving 97% code coverage). * **Footnote macros compatibility verification**: Added a validation suite (`tests/test_footnotes.py`) confirming compatibility with the newly introduced anonymous and named footnotes in the parsing pipeline. === Changed * **Upgraded dependencies**: - Bumped `asciidoctrine` version requirement to `>=0.1.0a7` to leverage parser newline normalization and native footnotes. - Changed `asciidocstring` version constraint to `>=0.1.0a2`. === Fixed * **Removed trailing newline workaround**: Cleaned up manual trailing-newline appending in `parser.py`, as standard line termination issues have been natively resolved in the upgraded upstream parser. --- == link:https://pypi.org/project/asciidoctest/0.1.0a1/[0.1.0a1] - 2026-07-11 === Added * **Initial Release**: Released `asciidoctest` as an alpha utility. * **Core sequential runner**: Designed a sequential execution engine supporting variable-state propagation and detailed line mappings. * **Pytest integration**: Added file collection hooks and detailed repr-failure reporting. * **Unittest integration**: Added standard library `TestSuite` compatibility wrappers (`DocFileSuite` and `DocTestSuite`).