pytest-codeblock 0.1.2__tar.gz → 0.1.4__tar.gz

{pytest_codeblock-0.1.2/pytest_codeblock.egg-info → pytest_codeblock-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-codeblock
-Version: 0.1.2
+Version: 0.1.4
 Summary: Pytest plugin to collect and test code blocks in reStructuredText and Markdown files.
 Author-email: Artur Barseghyan <artur.barseghyan@gmail.com>
 Maintainer-email: Artur Barseghyan <artur.barseghyan@gmail.com>
@@ -68,6 +68,11 @@ pytest-codeblock
 .. _Django: https://www.djangoproject.com
 .. _pip: https://pypi.org/project/pip/
 .. _uv: https://pypi.org/project/uv/
+.. _fake.py: https://github.com/barseghyanartur/fake.py
+.. _boto3: https://github.com/boto/boto3
+.. _moto: https://github.com/getmoto/moto
+.. _openai: https://github.com/openai/openai-python
+.. _Ollama: https://github.com/ollama/ollama
 
 .. Internal references
 
@@ -112,6 +117,7 @@ Features
 - **Markdown and reST support**: Automatically finds fenced code blocks
   in `.md`/`.markdown` files and `.. code-block:: python` or literal blocks
   in `.rst` files.
+- **Support for literalinclude blocks** in `.rst` files.
 - **Grouping by name**: Split a single example across multiple code blocks;
   the plugin concatenates them into one test.
 - **Minimal dependencies**: Only requires `pytest`_.
@@ -147,9 +153,7 @@ Configuration
 
     [tool.pytest.ini_options]
     testpaths = [
-        "*.rst",
         "**/*.rst",
-        "*.md",
         "**/*.md",
     ]
 
@@ -184,6 +188,8 @@ You can also use a literal block with a preceding name comment:
        y = 5
        print(y * 2)
 
+----
+
 **Grouping example**
 
 It's possible to split one logical test into multiple blocks.
@@ -216,8 +222,12 @@ Note the ``.. continue::`` directive.
 
 The above mentioned three snippets will run as a single test.
 
+----
+
 **pytest marks**
 
+In the example below, `django_db` marker is added to the code.
+
 .. code-block:: rst
 
     .. pytestmark: django_db
@@ -228,6 +238,16 @@ The above mentioned three snippets will run as a single test.
 
         user = User.objects.first()
 
+----
+
+**literalinclude**
+
+.. code-block:: rst
+
+    .. pytestmark: fakepy
+    .. literalinclude:: examples/python/create_pdf_file_example.py
+        :name: test_li_create_pdf_file
+
 Markdown usage
 --------------
 
@@ -246,6 +266,8 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
     assert result == 9
     ```
 
+----
+
 **Grouping example**
 
 .. code-block:: markdown
@@ -260,6 +282,8 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
     print(x + 1)  # Uses x from the first snippet
     ```
 
+----
+
 **pytest marks**
 
 .. code-block:: markdown
@@ -273,9 +297,23 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
 
 Customisation/hooks
 ===================
-If you want to add additional things into your specific tests, do as follows:
+Tests can be extended and fine-tuned using `pytest`_'s standard hook system.
+
+Below is an example workflow:
+
+1. **Add custom markers** to the code blocks (``fakepy``, ``aws``, ``openai``).
+2. **Implement pytest hooks** in ``conftest.py`` to react to those markers.
 
-**Add a couple of custom pytest marks**
+
+Add custom markers in reStructuredText
+--------------------------------------
+
+``fakepy`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `fake.py`_ code to generate a PDF file with random text.
+
+*Filename: README.rst*
 
 .. code-block:: rst
 
@@ -287,6 +325,15 @@ If you want to add additional things into your specific tests, do as follows:
 
         FAKER.pdf_file()
 
+``aws`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `boto3`_ code to create a bucket on AWS S3.
+
+*Filename: README.rst*
+
+.. code-block:: rst
+
     .. pytestmark: aws
     .. code-block:: python
         :name: test_create_bucket
@@ -297,6 +344,17 @@ If you want to add additional things into your specific tests, do as follows:
         s3.create_bucket(Bucket="my-bucket")
         assert "my-bucket" in [b["Name"] for b in s3.list_buckets()["Buckets"]]
 
+``openai`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `openai`_ code to ask LLM to tell a joke. Note, that next to a
+custom ``openai`` marker, ``xfail`` marker is used, which allows underlying
+code to fail, without marking entire test suite as failed.
+
+*Filename: README.rst*
+
+.. code-block:: rst
+
     .. pytestmark: xfail
     .. pytestmark: openai
     .. code-block:: python
@@ -315,12 +373,78 @@ If you want to add additional things into your specific tests, do as follows:
 
         assert isinstance(completion.choices[0].message.content, str)
 
-**Hook into it `conftest.py`**
+Add custom markers in Markdown
+------------------------------
+
+``fakepy`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: fakepy -->
+    ```python name=test_create_pdf_file
+    from fake import FAKER
+
+    FAKER.pdf_file()
+    ```
+
+``aws`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: aws -->
+    ```python name=test_create_bucket
+    import boto3
+
+    s3 = boto3.client("s3", region_name="us-east-1")
+    s3.create_bucket(Bucket="my-bucket")
+    assert "my-bucket" in [b["Name"] for b in s3.list_buckets()["Buckets"]]
+    ```
+
+``openai`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: xfail -->
+    <!-- pytestmark: openai -->
+    ```python name=test_tell_me_a_joke
+    from openai import OpenAI
+
+    client = OpenAI()
+    completion = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "developer", "content": "You are a famous comedian."},
+            {"role": "user", "content": "Tell me a joke."},
+        ],
+    )
+
+    assert isinstance(completion.choices[0].message.content, str)
+    ```
+
+Implement pytest hooks
+----------------------
+
+In the example below:
+
+- `moto`_ is used to mock AWS S3 service for all tests marked as ``aws``.
+- Environment variable ``OPENAI_BASE_URL`` is set
+  to ``http://localhost:11434/v1`` (assuming you have `Ollama`_ running) for
+  all tests marked as ``openai``.
+- ``FILE_REGISTRY.clean_up()`` is executed at the end of each test marked
+  as ``fakepy``.
 
 *Filename: conftest.py*
 
 .. code-block:: python
-    :name: test_conftest
 
     import os
     from contextlib import suppress
@@ -335,7 +459,10 @@ If you want to add additional things into your specific tests, do as follows:
     def pytest_collection_modifyitems(config, items):
         for item in items:
             if item.get_closest_marker(CODEBLOCK_MARK):
-                # Add `documentation` marker to `pytest-codeblock` tests
+                # All `pytest-codeblock` tests are automatically assigned
+                # a `codeblock` marker, which can be used for customisation.
+                # In the example below we add an additional `documentation`
+                # marker to `pytest-codeblock` tests.
                 item.add_marker(pytest.mark.documentation)
             if item.get_closest_marker("aws"):
                 # Apply `mock_aws` to all tests marked as `aws`
@@ -345,7 +472,11 @@ If you want to add additional things into your specific tests, do as follows:
     # Setup before test runs
     def pytest_runtest_setup(item):
         if item.get_closest_marker("openai"):
-            # Send all OpenAI requests to locally running Ollama
+            # Send all OpenAI requests to locally running Ollama for all
+            # tests marked as `openai`. The tests would x-pass on environments
+            # where Ollama is up and running (assuming, you have created an
+            # alias for gpt-4o using one of the available models) and would
+            # x-fail on environments, where Ollama isn't runnig.
             os.environ.setdefault("OPENAI_API_KEY", "ollama")
             os.environ.setdefault("OPENAI_BASE_URL", "http://localhost:11434/v1")
 

{pytest_codeblock-0.1.2 → pytest_codeblock-0.1.4}/README.rst

@@ -9,6 +9,11 @@ pytest-codeblock
 .. _Django: https://www.djangoproject.com
 .. _pip: https://pypi.org/project/pip/
 .. _uv: https://pypi.org/project/uv/
+.. _fake.py: https://github.com/barseghyanartur/fake.py
+.. _boto3: https://github.com/boto/boto3
+.. _moto: https://github.com/getmoto/moto
+.. _openai: https://github.com/openai/openai-python
+.. _Ollama: https://github.com/ollama/ollama
 
 .. Internal references
 
@@ -53,6 +58,7 @@ Features
 - **Markdown and reST support**: Automatically finds fenced code blocks
   in `.md`/`.markdown` files and `.. code-block:: python` or literal blocks
   in `.rst` files.
+- **Support for literalinclude blocks** in `.rst` files.
 - **Grouping by name**: Split a single example across multiple code blocks;
   the plugin concatenates them into one test.
 - **Minimal dependencies**: Only requires `pytest`_.
@@ -88,9 +94,7 @@ Configuration
 
     [tool.pytest.ini_options]
     testpaths = [
-        "*.rst",
         "**/*.rst",
-        "*.md",
         "**/*.md",
     ]
 
@@ -125,6 +129,8 @@ You can also use a literal block with a preceding name comment:
        y = 5
        print(y * 2)
 
+----
+
 **Grouping example**
 
 It's possible to split one logical test into multiple blocks.
@@ -157,8 +163,12 @@ Note the ``.. continue::`` directive.
 
 The above mentioned three snippets will run as a single test.
 
+----
+
 **pytest marks**
 
+In the example below, `django_db` marker is added to the code.
+
 .. code-block:: rst
 
     .. pytestmark: django_db
@@ -169,6 +179,16 @@ The above mentioned three snippets will run as a single test.
 
         user = User.objects.first()
 
+----
+
+**literalinclude**
+
+.. code-block:: rst
+
+    .. pytestmark: fakepy
+    .. literalinclude:: examples/python/create_pdf_file_example.py
+        :name: test_li_create_pdf_file
+
 Markdown usage
 --------------
 
@@ -187,6 +207,8 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
     assert result == 9
     ```
 
+----
+
 **Grouping example**
 
 .. code-block:: markdown
@@ -201,6 +223,8 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
     print(x + 1)  # Uses x from the first snippet
     ```
 
+----
+
 **pytest marks**
 
 .. code-block:: markdown
@@ -214,9 +238,23 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
 
 Customisation/hooks
 ===================
-If you want to add additional things into your specific tests, do as follows:
+Tests can be extended and fine-tuned using `pytest`_'s standard hook system.
+
+Below is an example workflow:
+
+1. **Add custom markers** to the code blocks (``fakepy``, ``aws``, ``openai``).
+2. **Implement pytest hooks** in ``conftest.py`` to react to those markers.
 
-**Add a couple of custom pytest marks**
+
+Add custom markers in reStructuredText
+--------------------------------------
+
+``fakepy`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `fake.py`_ code to generate a PDF file with random text.
+
+*Filename: README.rst*
 
 .. code-block:: rst
 
@@ -228,6 +266,15 @@ If you want to add additional things into your specific tests, do as follows:
 
         FAKER.pdf_file()
 
+``aws`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `boto3`_ code to create a bucket on AWS S3.
+
+*Filename: README.rst*
+
+.. code-block:: rst
+
     .. pytestmark: aws
     .. code-block:: python
         :name: test_create_bucket
@@ -238,6 +285,17 @@ If you want to add additional things into your specific tests, do as follows:
         s3.create_bucket(Bucket="my-bucket")
         assert "my-bucket" in [b["Name"] for b in s3.list_buckets()["Buckets"]]
 
+``openai`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `openai`_ code to ask LLM to tell a joke. Note, that next to a
+custom ``openai`` marker, ``xfail`` marker is used, which allows underlying
+code to fail, without marking entire test suite as failed.
+
+*Filename: README.rst*
+
+.. code-block:: rst
+
     .. pytestmark: xfail
     .. pytestmark: openai
     .. code-block:: python
@@ -256,12 +314,78 @@ If you want to add additional things into your specific tests, do as follows:
 
         assert isinstance(completion.choices[0].message.content, str)
 
-**Hook into it `conftest.py`**
+Add custom markers in Markdown
+------------------------------
+
+``fakepy`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: fakepy -->
+    ```python name=test_create_pdf_file
+    from fake import FAKER
+
+    FAKER.pdf_file()
+    ```
+
+``aws`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: aws -->
+    ```python name=test_create_bucket
+    import boto3
+
+    s3 = boto3.client("s3", region_name="us-east-1")
+    s3.create_bucket(Bucket="my-bucket")
+    assert "my-bucket" in [b["Name"] for b in s3.list_buckets()["Buckets"]]
+    ```
+
+``openai`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: xfail -->
+    <!-- pytestmark: openai -->
+    ```python name=test_tell_me_a_joke
+    from openai import OpenAI
+
+    client = OpenAI()
+    completion = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "developer", "content": "You are a famous comedian."},
+            {"role": "user", "content": "Tell me a joke."},
+        ],
+    )
+
+    assert isinstance(completion.choices[0].message.content, str)
+    ```
+
+Implement pytest hooks
+----------------------
+
+In the example below:
+
+- `moto`_ is used to mock AWS S3 service for all tests marked as ``aws``.
+- Environment variable ``OPENAI_BASE_URL`` is set
+  to ``http://localhost:11434/v1`` (assuming you have `Ollama`_ running) for
+  all tests marked as ``openai``.
+- ``FILE_REGISTRY.clean_up()`` is executed at the end of each test marked
+  as ``fakepy``.
 
 *Filename: conftest.py*
 
 .. code-block:: python
-    :name: test_conftest
 
     import os
     from contextlib import suppress
@@ -276,7 +400,10 @@ If you want to add additional things into your specific tests, do as follows:
     def pytest_collection_modifyitems(config, items):
         for item in items:
             if item.get_closest_marker(CODEBLOCK_MARK):
-                # Add `documentation` marker to `pytest-codeblock` tests
+                # All `pytest-codeblock` tests are automatically assigned
+                # a `codeblock` marker, which can be used for customisation.
+                # In the example below we add an additional `documentation`
+                # marker to `pytest-codeblock` tests.
                 item.add_marker(pytest.mark.documentation)
             if item.get_closest_marker("aws"):
                 # Apply `mock_aws` to all tests marked as `aws`
@@ -286,7 +413,11 @@ If you want to add additional things into your specific tests, do as follows:
     # Setup before test runs
     def pytest_runtest_setup(item):
         if item.get_closest_marker("openai"):
-            # Send all OpenAI requests to locally running Ollama
+            # Send all OpenAI requests to locally running Ollama for all
+            # tests marked as `openai`. The tests would x-pass on environments
+            # where Ollama is up and running (assuming, you have created an
+            # alias for gpt-4o using one of the available models) and would
+            # x-fail on environments, where Ollama isn't runnig.
             os.environ.setdefault("OPENAI_API_KEY", "ollama")
             os.environ.setdefault("OPENAI_BASE_URL", "http://localhost:11434/v1")
 

{pytest_codeblock-0.1.2 → pytest_codeblock-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytest-codeblock"
-version = "0.1.2"
+version = "0.1.4"
 description = "Pytest plugin to collect and test code blocks in reStructuredText and Markdown files."
 readme = "README.rst"
 requires-python = ">=3.9"
@@ -190,6 +190,15 @@ pythonpath = [
 norecursedirs = [".git", "examples"]
 DJANGO_SETTINGS_MODULE = "django_settings"
 
+markers = [
+    "slow: mark a test that takes a long time to run.",
+    "codeblock: pytest-codeblock markers",
+    "aws: mark test as a AWS test",
+    "documentation: mark test as a documentation test",
+    "fakepy: mark test as a fake.py test",
+    "openai: mark test as a openai test",
+]
+
 [tool.coverage.run]
 relative_files = true
 omit = [".tox/*"]

{pytest_codeblock-0.1.2 → pytest_codeblock-0.1.4}/pytest_codeblock/__init__.py

@@ -2,7 +2,7 @@ from .md import MarkdownFile
 from .rst import RSTFile
 
 __title__ = "pytest-codeblock"
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 __author__ = "Artur Barseghyan <artur.barseghyan@gmail.com>"
 __copyright__ = "2025 Artur Barseghyan"
 __license__ = "MIT"

{pytest_codeblock-0.1.2 → pytest_codeblock-0.1.4}/pytest_codeblock/rst.py

@@ -1,4 +1,5 @@
 import re
+from pathlib import Path
 from typing import Optional
 
 import pytest
@@ -14,8 +15,40 @@ __all__ = (
     "parse_rst",
 )
 
+# Highlight: Added helper function for literalinclude path resolution
+def resolve_literalinclude_path(
+    base_dir: Path,
+    include_path: str,
+) -> Optional[str]:
+    """
+    Resolve the full path for a literalinclude directive.
+    Returns None if the file doesn't exist.
+    """
+    _include_path = Path(include_path)
+    if _include_path.exists():
+        return str(_include_path.resolve())
+
+    _base_dir = Path(base_dir.dirname) if base_dir.isfile() else base_dir
+    try:
+        full_path = _base_dir / include_path
+        if full_path.exists():
+            return str(full_path.resolve())
+    except Exception:
+        pass
+    return None
+
 
-def parse_rst(text: str) -> list[CodeSnippet]:
+def get_literalinclude_content(path):
+    try:
+        with open(path) as f:
+            return f.read()
+    except Exception as e:
+        raise RuntimeError(
+            f"Failed to read literalinclude file {path}: {e}"
+        ) from e
+
+
+def parse_rst(text: str, base_dir: Path) -> list[CodeSnippet]:
     """
     Parse an RST document into CodeSnippet objects, capturing:
       - .. pytestmark: <mark>
@@ -35,28 +68,65 @@ def parse_rst(text: str) -> list[CodeSnippet]:
     while i < n:
         line = lines[i]
 
-        # Collect ".. pytestmark: xyz"
+        # --------------------------------------------------------------------
+        # Collect `.. pytestmark: xyz`
+        # --------------------------------------------------------------------
         m = re.match(r"^\s*\.\.\s*pytestmark:\s*(\w+)\s*$", line)
         if m:
             pending_marks.append(m.group(1))
             i += 1
             continue
 
-        # Collect ".. continue: foo"
+        # --------------------------------------------------------------------
+        # The `.. literalinclude` directive
+        # --------------------------------------------------------------------
+        if line.strip().startswith(".. literalinclude::"):
+            path = line.split(".. literalinclude::", 1)[1].strip()
+            name = None
+
+            # Look ahead for name
+            j = i + 1
+            while j < len(lines) and lines[j].strip():
+                if ":name:" in lines[j]:
+                    name = lines[j].split(":name:", 1)[1].strip()
+                    break
+                j += 1
+
+            if name and name.startswith("test_"):
+                full_path = resolve_literalinclude_path(base_dir, path)
+                if full_path:
+                    snippet = CodeSnippet(
+                        code=get_literalinclude_content(full_path),
+                        line=i + 1,
+                        name=name,
+                        marks=pending_marks.copy(),
+                    )
+                    snippets.append(snippet)
+
+            i = j + 1
+            continue
+
+        # --------------------------------------------------------------------
+        # Collect `.. continue: foo`
+        # --------------------------------------------------------------------
         m = re.match(r"^\s*\.\.\s*continue:\s*(\S+)\s*$", line)
         if m:
             pending_continue = m.group(1)
             i += 1
             continue
 
-        # Collect ".. codeblock-name: foo"
+        # --------------------------------------------------------------------
+        # Collect `.. codeblock-name: foo`
+        # --------------------------------------------------------------------
         m = re.match(r"^\s*\.\.\s*codeblock-name:\s*(\S+)\s*$", line)
         if m:
             pending_name = m.group(1)
             i += 1
             continue
 
-        # The code-block directive
+        # --------------------------------------------------------------------
+        # The `.. code-block` directive
+        # --------------------------------------------------------------------
         m = re.match(r"^(\s*)\.\. (?:code-block|code)::\s*(\w+)", line)
         if m:
             base_indent = len(m.group(1))
@@ -125,7 +195,9 @@ def parse_rst(text: str) -> list[CodeSnippet]:
                 i += 1
                 continue
 
+        # --------------------------------------------------------------------
         # The literal-block via "::"
+        # --------------------------------------------------------------------
         if line.rstrip().endswith("::") and pending_name:
             # Similar override logic
             if pending_continue:
@@ -176,7 +248,7 @@ class RSTFile(pytest.File):
     """Collect RST code-block tests as real test functions."""
     def collect(self):
         text = self.fspath.read_text(encoding="utf-8")
-        raw = parse_rst(text)
+        raw = parse_rst(text, self.fspath)
 
         # Only keep test_* snippets
         tests = [

{pytest_codeblock-0.1.2 → pytest_codeblock-0.1.4/pytest_codeblock.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-codeblock
-Version: 0.1.2
+Version: 0.1.4
 Summary: Pytest plugin to collect and test code blocks in reStructuredText and Markdown files.
 Author-email: Artur Barseghyan <artur.barseghyan@gmail.com>
 Maintainer-email: Artur Barseghyan <artur.barseghyan@gmail.com>
@@ -68,6 +68,11 @@ pytest-codeblock
 .. _Django: https://www.djangoproject.com
 .. _pip: https://pypi.org/project/pip/
 .. _uv: https://pypi.org/project/uv/
+.. _fake.py: https://github.com/barseghyanartur/fake.py
+.. _boto3: https://github.com/boto/boto3
+.. _moto: https://github.com/getmoto/moto
+.. _openai: https://github.com/openai/openai-python
+.. _Ollama: https://github.com/ollama/ollama
 
 .. Internal references
 
@@ -112,6 +117,7 @@ Features
 - **Markdown and reST support**: Automatically finds fenced code blocks
   in `.md`/`.markdown` files and `.. code-block:: python` or literal blocks
   in `.rst` files.
+- **Support for literalinclude blocks** in `.rst` files.
 - **Grouping by name**: Split a single example across multiple code blocks;
   the plugin concatenates them into one test.
 - **Minimal dependencies**: Only requires `pytest`_.
@@ -147,9 +153,7 @@ Configuration
 
     [tool.pytest.ini_options]
     testpaths = [
-        "*.rst",
         "**/*.rst",
-        "*.md",
         "**/*.md",
     ]
 
@@ -184,6 +188,8 @@ You can also use a literal block with a preceding name comment:
        y = 5
        print(y * 2)
 
+----
+
 **Grouping example**
 
 It's possible to split one logical test into multiple blocks.
@@ -216,8 +222,12 @@ Note the ``.. continue::`` directive.
 
 The above mentioned three snippets will run as a single test.
 
+----
+
 **pytest marks**
 
+In the example below, `django_db` marker is added to the code.
+
 .. code-block:: rst
 
     .. pytestmark: django_db
@@ -228,6 +238,16 @@ The above mentioned three snippets will run as a single test.
 
         user = User.objects.first()
 
+----
+
+**literalinclude**
+
+.. code-block:: rst
+
+    .. pytestmark: fakepy
+    .. literalinclude:: examples/python/create_pdf_file_example.py
+        :name: test_li_create_pdf_file
+
 Markdown usage
 --------------
 
@@ -246,6 +266,8 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
     assert result == 9
     ```
 
+----
+
 **Grouping example**
 
 .. code-block:: markdown
@@ -260,6 +282,8 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
     print(x + 1)  # Uses x from the first snippet
     ```
 
+----
+
 **pytest marks**
 
 .. code-block:: markdown
@@ -273,9 +297,23 @@ Any fenced code block with a recognized Python language tag (e.g., ``python``,
 
 Customisation/hooks
 ===================
-If you want to add additional things into your specific tests, do as follows:
+Tests can be extended and fine-tuned using `pytest`_'s standard hook system.
+
+Below is an example workflow:
+
+1. **Add custom markers** to the code blocks (``fakepy``, ``aws``, ``openai``).
+2. **Implement pytest hooks** in ``conftest.py`` to react to those markers.
 
-**Add a couple of custom pytest marks**
+
+Add custom markers in reStructuredText
+--------------------------------------
+
+``fakepy`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `fake.py`_ code to generate a PDF file with random text.
+
+*Filename: README.rst*
 
 .. code-block:: rst
 
@@ -287,6 +325,15 @@ If you want to add additional things into your specific tests, do as follows:
 
         FAKER.pdf_file()
 
+``aws`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `boto3`_ code to create a bucket on AWS S3.
+
+*Filename: README.rst*
+
+.. code-block:: rst
+
     .. pytestmark: aws
     .. code-block:: python
         :name: test_create_bucket
@@ -297,6 +344,17 @@ If you want to add additional things into your specific tests, do as follows:
         s3.create_bucket(Bucket="my-bucket")
         assert "my-bucket" in [b["Name"] for b in s3.list_buckets()["Buckets"]]
 
+``openai`` reStructuredText marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sample `openai`_ code to ask LLM to tell a joke. Note, that next to a
+custom ``openai`` marker, ``xfail`` marker is used, which allows underlying
+code to fail, without marking entire test suite as failed.
+
+*Filename: README.rst*
+
+.. code-block:: rst
+
     .. pytestmark: xfail
     .. pytestmark: openai
     .. code-block:: python
@@ -315,12 +373,78 @@ If you want to add additional things into your specific tests, do as follows:
 
         assert isinstance(completion.choices[0].message.content, str)
 
-**Hook into it `conftest.py`**
+Add custom markers in Markdown
+------------------------------
+
+``fakepy`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: fakepy -->
+    ```python name=test_create_pdf_file
+    from fake import FAKER
+
+    FAKER.pdf_file()
+    ```
+
+``aws`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: aws -->
+    ```python name=test_create_bucket
+    import boto3
+
+    s3 = boto3.client("s3", region_name="us-east-1")
+    s3.create_bucket(Bucket="my-bucket")
+    assert "my-bucket" in [b["Name"] for b in s3.list_buckets()["Buckets"]]
+    ```
+
+``openai`` Markdown marker
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Filename: README.md*
+
+.. code-block:: markdown
+
+    <!-- pytestmark: xfail -->
+    <!-- pytestmark: openai -->
+    ```python name=test_tell_me_a_joke
+    from openai import OpenAI
+
+    client = OpenAI()
+    completion = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "developer", "content": "You are a famous comedian."},
+            {"role": "user", "content": "Tell me a joke."},
+        ],
+    )
+
+    assert isinstance(completion.choices[0].message.content, str)
+    ```
+
+Implement pytest hooks
+----------------------
+
+In the example below:
+
+- `moto`_ is used to mock AWS S3 service for all tests marked as ``aws``.
+- Environment variable ``OPENAI_BASE_URL`` is set
+  to ``http://localhost:11434/v1`` (assuming you have `Ollama`_ running) for
+  all tests marked as ``openai``.
+- ``FILE_REGISTRY.clean_up()`` is executed at the end of each test marked
+  as ``fakepy``.
 
 *Filename: conftest.py*
 
 .. code-block:: python
-    :name: test_conftest
 
     import os
     from contextlib import suppress
@@ -335,7 +459,10 @@ If you want to add additional things into your specific tests, do as follows:
     def pytest_collection_modifyitems(config, items):
         for item in items:
             if item.get_closest_marker(CODEBLOCK_MARK):
-                # Add `documentation` marker to `pytest-codeblock` tests
+                # All `pytest-codeblock` tests are automatically assigned
+                # a `codeblock` marker, which can be used for customisation.
+                # In the example below we add an additional `documentation`
+                # marker to `pytest-codeblock` tests.
                 item.add_marker(pytest.mark.documentation)
             if item.get_closest_marker("aws"):
                 # Apply `mock_aws` to all tests marked as `aws`
@@ -345,7 +472,11 @@ If you want to add additional things into your specific tests, do as follows:
     # Setup before test runs
     def pytest_runtest_setup(item):
         if item.get_closest_marker("openai"):
-            # Send all OpenAI requests to locally running Ollama
+            # Send all OpenAI requests to locally running Ollama for all
+            # tests marked as `openai`. The tests would x-pass on environments
+            # where Ollama is up and running (assuming, you have created an
+            # alias for gpt-4o using one of the available models) and would
+            # x-fail on environments, where Ollama isn't runnig.
             os.environ.setdefault("OPENAI_API_KEY", "ollama")
             os.environ.setdefault("OPENAI_BASE_URL", "http://localhost:11434/v1")