pytest-pyspec 0.5.2__py3-none-any.whl → 0.10.1__py3-none-any.whl

pytest_pyspec/item.py

@@ -1,51 +1,89 @@
 from types import ModuleType
 from typing import Dict, List
+
+import re
+
 import pytest
 
 class Item:
+    """
+    Wrapper around a pytest.Item that provides a human-friendly description.
+
+    Responsibilities:
+    - Derive a readable description for a test or container from either the
+      docstring of the underlying object or its Python name.
+    - Provide helpers to normalize names (convert CamelCase/snake_case into
+      words), strip common pytest prefixes, and keep a consistent
+      representation.
+    """
+
     def __init__(self, item: pytest.Item) -> None:
         self._item = item
 
     @property
-    def description(self):        
-        description = self._item.obj.__doc__
-
-        if not description:
-            description = self._item.name
-            description = self._parse_description(description)
+    def description(self) -> str:
+        """
+        Return a human-readable description for the wrapped pytest item.
 
-        description = description.splitlines()[0]
-        description = description.capitalize()
-        return description
+        Preference order:
+        1) First non-empty line of the object's docstring, stripped.
+        2) A description derived from the Python name of the item.
+        """
+        docstring = getattr(self._item.obj, "__doc__", None)
+        if docstring:
+            return self._parse_docstring(docstring)
+        return self._parse_itemname(self._item.name)
 
-    def _parse_description(self, description: str):
-        split = False
-        if description.lower().startswith("it_"):
-            description = description.replace('it_', '')
-            split = True
+    def _parse_docstring(self, docstring: str) -> str:
+        """
+        Return the first line of a docstring, trimmed of surrounding spaces.
+        """
+        first_line = docstring.splitlines()[0]
+        return first_line.strip()
 
-        if description.lower().startswith("test_it_"):
-            description = description.replace('test_it_', '')
-            split = True
+    def _parse_name(self, name: str) -> str:
+        """
+        Normalize a Python identifier into words.
 
-        if description.lower().startswith("test_describe_"):
-            description = description.replace('test_describe_', '')
-            split = True
-
-        if description.lower().startswith("describe_"):
-            description = description.replace('describe_', '')
-            split = True
+        Steps:
+        - Insert underscores before internal capital letters (turn "MyClass"
+          -> "My_Class").
+        - Lowercase everything.
+        - Replace underscores with single spaces and normalize multiple
+          underscores.
+        """
+        description = re.sub(
+            r'(?!^[A-Z])([A-Z])',
+            r'_\g<1>',
+            name,
+        )
+        description = description.lower()
+        description = ' '.join(description.split('_'))
+        return description
 
-        if split:
-            description = description.replace('_', ' ')
+    def _parse_itemname(self, name: str) -> str:
+        """
+        Create a description from a pytest test function name.
 
+        - Uses _parse_name to normalize the identifier.
+        - Removes common prefixes like "test"/"it".
+        """
+        description = self._parse_name(name)
+        description = re.sub(
+            r'^(test|it) ',
+            '',
+            description,
+        )
         return description
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return self._item.__repr__()
 
 
 class Test(Item):
+    """
+    Represents a single test item and its relationship to a container.
+    """
     def __init__(self, item: pytest.Item) -> None:
         super().__init__(item)
         self.container: Container = None
@@ -53,27 +91,47 @@ class Test(Item):
 
     @property
     def level(self) -> int:
+        """
+        Depth in the container hierarchy (root container is 0).
+        """
         if not self.container:
             return 0
         return self.container.level +1
    
     
 class Container(Item):
-    def __init__(self, item: pytest.Item):
+    """
+    Represents a grouping of tests (e.g., class/function scopes) in pytest.
+
+    Tracks:
+    - Nested containers (parents/children) following pytest's item tree.
+    - Contained tests.
+    Provides utilities to compute display names and levels.
+    """
+    def __init__(self, item: pytest.Item) -> None:
         super().__init__(item)
         self.tests: List[Test] = list()
         self.containers: List[Container] = list()
         self.parent = None
 
-    def add(self, test: Test):
+    def add(self, test: Test) -> None:
+        """
+        Attach a Test to this container and set its back-reference.
+        """
         self.tests.append(test)
         test.container = self
 
-    def add_container(self, container: 'Container'):
+    def add_container(self, container: 'Container') -> None:
+        """
+        Attach a child container and set parent back-reference.
+        """
         self.containers.append(container)
         container.parent = self
 
-    def flat_list(self):
+    def flat_list(self) -> list:
+        """
+        Return a list of containers from root to self.
+        """
         containers = []
         container = self
         while container:
@@ -83,21 +141,63 @@ class Container(Item):
 
     @property
     def level(self) -> int:
+        """
+        Compute this container's depth relative to the module root.
+
+        Walks up pytest's internal node tree until reaching a ModuleType parent.
+        """
         level = 0
         
         item = self._item
+        # Climb the pytest node hierarchy until we reach the module node
         while item.parent and not isinstance(item.parent.obj, ModuleType):
             level += 1
             item = item.parent
         
         return level
+    
+    def _parse_docstring(self, docstring: str) -> str:
+        """
+        Parse container docstring and prepend an article when appropriate.
+
+        If the first word doesn't start with "with"/"without", prefix with
+        "a ". This mirrors RSpec-style descriptions like "a function" vs
+        "with options".
+        """
+        description = super()._parse_docstring(docstring)
+        if not description.startswith(('with ', 'without ')):
+            description = f'a {description}'
+        return description
+    
+    def _parse_itemname(self, name: str) -> str:
+        """
+        Create a container description from a pytest node name.
+
+        - Normalize the identifier into words.
+        - Replace leading "test"/"describe" with the article "a ".
+        """
+        description = self._parse_name(name)
+        description = re.sub(
+            r'^([Tt]est|[Dd]escribe) ',
+            'a ',
+            description)
+        return description
 
 
 class ItemFactory:
+    """
+    Factory responsible for creating Test items and wiring them into containers.
+    """
     def __init__(self) -> None:
         self.container_factory = ContainerFactory()
 
     def create(self, item: pytest.Item) -> Test:
+        """
+        Wrap a pytest item as a Test and attach it to its Container.
+
+        Also mutates pytest's item name to the human-readable description for
+        reporting.
+        """
         test_item = Test(item)
 
         container_item = item.parent
@@ -105,33 +205,54 @@ class ItemFactory:
         if container:
             container.add(test_item)       
 
+        item.name = test_item.description
         return test_item
         
 
 class ContainerFactory:
+    """
+    Factory that ensures containers are unique per pytest node and linked
+    properly.
+    """
     def __init__(self) -> None:
         self.containers: Dict[str, Container] = dict()
 
-    def create(self, item) -> Container:
+    def create(self, item: pytest.Item) -> 'Container':
+        """
+        Create (or fetch) the deepest Container for a given pytest node.
+        """
         containers = self._create_containers(item)
         if not containers:
             return None
-        
+
         return containers[-1]
     
-    def _create_unique_container(self, item):
+    def _create_unique_container(self, item: pytest.Item) -> 'Container':
+        """
+        Return a unique Container for a pytest node, creating if absent.
+
+        Also sets the pytest node's display name to the container description.
+        """
+        # Cache containers per pytest node to keep uniqueness
         if item not in self.containers:
             container = Container(item)
             self.containers[item] = container
 
         container = self.containers.get(item)
+        # Mutate node's visible name to our human-friendly description
+        item.name = container.description
         return container
 
-    def _create_containers(self, item):
+    def _create_containers(self, item: pytest.Item) -> list:
+        """
+        Build the chain of containers from a pytest node up to the module root.
+        """
         containers = []
         child_container = None
+        # Walk upwards creating/collecting containers until the module level
         while item and not isinstance(item.obj, ModuleType):
             container = self._create_unique_container(item)
+            # Link the previous (deeper) container as a child of the current one
             if child_container:
                 container.add_container(child_container)
 

pytest_pyspec/output.py

@@ -2,7 +2,7 @@ import pytest
 from .item import Container, Test
 
 
-def print_container(container: Container):
+def print_container(container: Container) -> str:
     output = "\n"
     if container:
         for container in container.flat_list():
@@ -10,18 +10,18 @@ def print_container(container: Container):
             container = container.parent
     return output
 
-def print_parent_container(container: Container):
+def print_parent_container(container: Container) -> str:
     ident = "  " * container.level
     output = f"\n{ident}{container.description}"
     return output
 
-def print_test(test: Test):
+def print_test(test: Test) -> str:
     ident = "  " * test.level
     status = print_test_status(test)
     output = f"\n{ident}{status} {test.description}"
     return output
 
-def print_test_status(test: Test):
+def print_test_status(test: Test) -> str:
     if test.outcome == 'passed':
         return '✓'
     elif test.outcome == 'failed':

pytest_pyspec/plugin.py

@@ -1,10 +1,34 @@
+
+"""
+Pytest plugin that prints test output in an RSpec-like, readable format.
+
+When enabled with the ``--pyspec`` flag, this plugin:
+  - Extends test discovery to also match ``it_`` functions and classes whose
+    names start with ``Describe`` or ``With``.
+  - Builds a tree of containers/tests and renders them with friendly
+    descriptions (favoring docstrings when present).
+  - Uses pytest's stash to pass the current/previous Test objects between
+    hooks, so we can decide when to print a container header.
+"""
+
+from typing import Any, Tuple, Generator
+
 import pytest
 from pytest_pyspec.item import ItemFactory, Test
 from pytest_pyspec.output import print_container, print_test
 
 
-def pytest_addoption(parser: pytest.Parser,
-                     pluginmanager: pytest.PytestPluginManager):
+def pytest_addoption(
+  parser: pytest.Parser,
+  pluginmanager: pytest.PytestPluginManager
+) -> None:
+    """
+    Register the ``--pyspec`` command-line flag.
+
+    The flag toggles all formatting and discovery behavior provided by this
+    plugin. We keep discovery changes behind the flag to avoid surprises in
+    normal pytest runs.
+    """
     group = parser.getgroup('general')
     group.addoption(
         '--pyspec',
@@ -14,60 +38,129 @@ def pytest_addoption(parser: pytest.Parser,
     )
 
 
-enabled = False
-def pytest_configure(config: pytest.Config):
-    global enabled
-    if config.getoption('pyspec') and not config.getoption('verbose'):
-        enabled = True
+ENABLED_KEY = pytest.StashKey[bool]()
+def pytest_configure(config: pytest.Config) -> None:
+    """
+    Initialize plugin state and, when enabled, extend test discovery rules.
+
+    - ``enabled`` is set only when ``--pyspec`` is present and ``-v`` is not
+      used (verbose mode already prints enough, so we defer to pytest's
+      default output in that case).
+    - Appends discovery patterns for ``it_`` functions and ``Describe``/``With``
+      classes when pyspec is on.
+    """
+    # Store enabled state in config.stash for access in all hooks.
+    enabled = config.getoption('pyspec') and not config.getoption('verbose')
+    config.stash[ENABLED_KEY] = enabled
 
+    if config.getoption('pyspec'):
+        # Extend discovery to match RSpec-like naming.
         python_functions = config.getini("python_functions")
         python_functions.append('it_')
         config.option.python_functions = python_functions
 
         python_classes = config.getini("python_classes")
-        python_classes.append('describe_')
-        python_classes.append('with_')
+        python_classes.append('Describe')
+        python_classes.append('With')
         config.option.python_classes = python_classes
 
 
+# Stash keys used to share Test objects between hooks.
+# These allow the report hook to know the current and previous test, so we can
+# decide when to print a container header (on container change).
+TEST_KEY = pytest.StashKey[Test]()
+PREV_TEST_KEY = pytest.StashKey[Test]()
+def pytest_collection_modifyitems(
+  session: pytest.Session,
+  config: pytest.Config,
+  items: list[pytest.Item],
+) -> None:
+    """
+    After collection, wrap each pytest item with our Test model and stash it.
 
-test_key = pytest.StashKey[Test]()
-prev_test_key = pytest.StashKey[Test]()
-def pytest_collection_modifyitems(session, config, items):
+    The previous Test is also stashed so later hooks can determine container
+    boundaries and print headers only when the container changes.
+    """
+    enabled = config.stash.get(ENABLED_KEY, False)
     if enabled:
         factory = ItemFactory()
         prev_test = None
         for i, item in enumerate(items):
             test = factory.create(item)
-            item.stash[test_key] = test
-            item.stash[prev_test_key] = prev_test
+            item.stash[TEST_KEY] = test
+            item.stash[PREV_TEST_KEY] = prev_test
             prev_test = test
 
 
 @pytest.hookimpl(hookwrapper=True)
-def pytest_runtest_makereport(item, call):
-    outcome = yield
-    if enabled:
-        report: pytest.Report = outcome.get_result()
-        #TODO Check whether the report has a stash
-        #TODO move previous test to test class
-        report.test = item.stash[test_key]
-        report.prev_test = item.stash[prev_test_key]
+def pytest_runtest_makereport(
+  item: pytest.Item,
+  call: pytest.CallInfo
+) -> Generator[Any, Any, None]:
+  """
+  Inject Test metadata into the report object for later formatting.
 
+  As a hookwrapper we yield to let pytest create the report, then attach our
+  Test and prev_test (from stash) so ``pytest_report_teststatus`` can render
+  the right lines.
+  """
+  outcome = yield
+  enabled = item.config.stash.get(ENABLED_KEY, False)
+  if enabled:
+    report: pytest.Report = outcome.get_result()
+    # TODO Check whether the report has a stash
+    # TODO move previous test to test class
+    if TEST_KEY in item.stash:
+      report.test = item.stash[TEST_KEY]
+      report.prev_test = item.stash[PREV_TEST_KEY]
 
-def pytest_report_teststatus(report: pytest.TestReport, config: pytest.Config):
-    if enabled:
-        test = report.test
-        prev_test = report.prev_test
-
-        if report.when == 'setup':
-            if not prev_test \
-                    or test.container != prev_test.container:
-                # Show container
-                output = print_container(test.container)
-                return '', output, ('', {'white': True})
-
-        if report.when == 'call':
-            test.outcome = report.outcome
-            output = print_test(test)
-            return report.outcome, output, ''
+
+from typing import Any, Tuple
+
+def pytest_report_teststatus(
+  report: pytest.TestReport,
+  config: pytest.Config
+) -> Any:
+  """
+  Produce short status and a human-friendly text line for each test event.
+
+  Behavior (only when pyspec is enabled and a Test is attached):
+  - On setup: if the container changed, print the container header.
+  - On call (or skipped during setup): print the test line with its status
+    mark. We reuse pytest's status tuple format.
+  """
+  enabled = config.stash.get(ENABLED_KEY, False)
+  if enabled and hasattr(report, 'test'):
+    test = report.test
+    prev_test = report.prev_test
+
+    if report.when == 'setup':
+      if not prev_test or test.container != prev_test.container:
+        # Show container
+        output = print_container(test.container)
+        return '', output, ('', {'white': True})
+
+    # Determine if this is the last test in the container
+    is_last_in_container = False
+    if hasattr(test.container, 'tests'):
+      # Find the index of this test in the container's test list
+      try:
+        idx = test.container.tests.index(test)
+        is_last_in_container = idx == len(test.container.tests) - 1
+      except (ValueError, AttributeError):
+        pass
+
+    if report.when == 'call':
+      test.outcome = report.outcome
+      output = print_test(test)
+      if is_last_in_container:
+        output += '\n'
+      return report.outcome, output, ''
+
+    if report.when == 'setup' and report.skipped:
+      test.outcome = report.outcome
+      output = print_test(test)
+      if is_last_in_container:
+        output += '\n'
+      return report.outcome, output, ''
+        

pytest_pyspec-0.10.1.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: pytest-pyspec
+Version: 0.10.1
+Summary: A plugin that transforms the pytest output into a result similar to the RSpec. It enables the use of docstrings to display results and also enables the use of the prefixes "describe", "with" and "it".
+Project-URL: Repository, https://github.com/felipecrp/pytest-pyspec
+Author-email: Felipe Curty <felipecrp@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <4,>=3.10
+Requires-Dist: pytest<10,>=9
+Description-Content-Type: text/markdown
+
+[![](https://github.com/felipecrp/pytest-pyspec/actions/workflows/pytest.yml/badge.svg)](https://github.com/felipecrp/pytest-pyspec/actions/workflows/pytest.yml)
+
+The **pytest-pyspec** plugin provides semantics to the pytest output. It
+transforms the pytest's output into a result similar to the RSpec.
+
+The default pytest output is like the following:
+
+```
+test/test_pytest.py::TestFunction::test_use_test_name PASSED
+test/test_pytest.py::TestFunction::test_use_the_prefix_test PASSED
+test/test_pytest.py::TestFunction::test_use_the_prefix_it PASSED
+test/test_pytest.py::TestFunction::WithDocstring::test_use_docstring PASSED
+```
+The **pytest-pyspec** transforms the output into the following:
+
+```
+A function
+  ✓ use test name
+  ✓ use the prefix test
+  ✓ use the prefix it
+
+A function
+  with docstring
+    ✓ use docstring
+```
+
+You just need to prefix your test case classes with:
+
+- _describe / test_ to represent objects
+- _with / without_ to represent context 
+
+And prefix your tests with:
+
+- _it / test_ to represent objects
+
+The following is a sample test that generates the previous tests` output.
+
+```python
+class TestFunction:
+    def test_use_test_name(self):
+        assert 1 == 1
+    
+    def test_use_the_prefix_test(self):
+        assert 1 == 1
+    
+    def test_use_the_prefix_it(self):
+        assert 1 == 1
+
+    class WithDocstring:
+        def test_use_docstring(self):
+            assert 1 == 1
+```
+
+Moreover, you can use a docstring to overwrite the test description. The
+following tests have the same output as the previous tests:
+
+```python
+class TestA:
+    """ Function """
+    def test_1(self):
+        """ use test name """
+        assert 1 == 1
+    
+    def test_2(self):
+        """ use the prefix test """
+        assert 1 == 1
+    
+    def test_3(self):
+        """ use the prefix it """
+        assert 1 == 1
+
+    class TestB:
+        """ with docstring """
+        def test_4(self):
+            """ use docstring """
+            assert 1 == 1
+```
+
+The following test sample:
+
+```python
+import pytest
+
+class DescribeHouse:
+    def it_has_door(self):
+        assert 1 == 1
+        
+    class WithTwoFloors:
+        def it_has_stairs(self):
+            assert 1 == 1
+
+        def it_has_second_floor(self):
+            assert 1 == 1
+
+        def it_has_third_floor(self):
+            assert 1 == 2
+```
+
+Generates the following output:
+
+```
+test/test_sample.py 
+
+A house
+  ✓ has door
+
+A house
+  with two floors
+    ✓ has stairs
+    ✓ has second floor
+    ✗ has third floor
+```
+
+## Installing and running **pySpec**
+
+```bash
+pip install pytest pytest-pyspec
+pytest --pyspec
+```

pytest_pyspec-0.10.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+pytest_pyspec/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_pyspec/item.py,sha256=FCVWRd1O8EQ01eDYd7bh2v0jO-O3BERyZKIxs3WFSPo,8173
+pytest_pyspec/output.py,sha256=VJAqNhd5695Dn5G6Jow3cfQkYXbfbcSquAf1IAivUVs,816
+pytest_pyspec/plugin.py,sha256=_vx7g_2wq1AFV4mnC5tkYLbaK8xYAvlh1vstJRx35EQ,5664
+pytest_pyspec-0.10.1.dist-info/METADATA,sha256=cWocxgEZURwKPat6Yn6Qrb5gS7iZp5wcd9Kf7RTcBL0,3148
+pytest_pyspec-0.10.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pytest_pyspec-0.10.1.dist-info/entry_points.txt,sha256=6YScWbxnkpduYs2Ef3gKOe6rV8Cjbj-OxCGMDNdV4Kc,48
+pytest_pyspec-0.10.1.dist-info/licenses/LICENSE,sha256=PXKqh3rDWRsfhWsjBQ27qqYzE5E05n-eFRH95LsKRT4,1094
+pytest_pyspec-0.10.1.dist-info/RECORD,,

{pytest_pyspec-0.5.2.dist-info → pytest_pyspec-0.10.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.5.1
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any

pytest_pyspec-0.10.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+pytest_pyspec = pytest_pyspec.plugin