requiresthat 2025.6.15.6__tar.gz

requiresthat-2025.6.15.6/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: requiresthat
+Version: 2025.6.15.6
+Summary: Decorate an instance method with pre- and/or postconditions that must be fulfilled
+Author-email: Ann T Ropea <bedhanger@gmx.de>
+Project-URL: Homepage, https://gitlab.com/bedhanger/mwe/-/tree/master/python/requiresthat
+Description-Content-Type: text/x-rst
+
+requiresthat
+============
+
+Decorate an instance method with pre- and/or postconditions that must be fulfilled
+
+Example usage
+-------------
+
+.. code-block:: python
+
+    from requiresthat import requires, RequirementNotFulfilledError, APRIORI, POSTMORTEM, BEFOREANDAFTER
+
+    class C:
+
+        def __init__(self, data=None):
+            self.data = data
+
+        @requires(that='self.data is not None')
+        @requires(that='self.data == "spam"', when=APRIORI)
+        @requires(that='True is not False')
+        @requires(that='self.data != "spam"', when=POSTMORTEM)
+        @requires(that='len(self.data) >= 3', when=BEFOREANDAFTER)
+        def method(self):
+            self.data = 'ham'
+
+    X = C(data='spam')
+    X.method()
+
+The ``that`` can be almost any valid Python statement which can be evaluated for its veracity, and
+whose result will decide whether or not the method fires/will be considered a success.
+
+The parameter ``when`` decides if the condition is a-priori, post-mortem, or before-and-after.
+The default is a-priori, meaning a precondition.  Note that before-and-after does *not* mean during;
+you cannot mandate an invariant this way!
+
+``RequirementNotFulfilledError`` is the exception you have to deal with in case a condition is not
+met.

requiresthat-2025.6.15.6/README.rst

@@ -0,0 +1,37 @@
+requiresthat
+============
+
+Decorate an instance method with pre- and/or postconditions that must be fulfilled
+
+Example usage
+-------------
+
+.. code-block:: python
+
+    from requiresthat import requires, RequirementNotFulfilledError, APRIORI, POSTMORTEM, BEFOREANDAFTER
+
+    class C:
+
+        def __init__(self, data=None):
+            self.data = data
+
+        @requires(that='self.data is not None')
+        @requires(that='self.data == "spam"', when=APRIORI)
+        @requires(that='True is not False')
+        @requires(that='self.data != "spam"', when=POSTMORTEM)
+        @requires(that='len(self.data) >= 3', when=BEFOREANDAFTER)
+        def method(self):
+            self.data = 'ham'
+
+    X = C(data='spam')
+    X.method()
+
+The ``that`` can be almost any valid Python statement which can be evaluated for its veracity, and
+whose result will decide whether or not the method fires/will be considered a success.
+
+The parameter ``when`` decides if the condition is a-priori, post-mortem, or before-and-after.
+The default is a-priori, meaning a precondition.  Note that before-and-after does *not* mean during;
+you cannot mandate an invariant this way!
+
+``RequirementNotFulfilledError`` is the exception you have to deal with in case a condition is not
+met.

requiresthat-2025.6.15.6/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "requiresthat"
+version = "2025.6.15.6"
+authors = [
+    {name = "Ann T Ropea", email = "bedhanger@gmx.de"},
+]
+description = "Decorate an instance method with pre- and/or postconditions that must be fulfilled"
+readme = "README.rst"
+dependencies = []
+
+[project.urls]
+Homepage = "https://gitlab.com/bedhanger/mwe/-/tree/master/python/requiresthat"
+
+[tool.pytest.ini_options]
+pythonpath = "src"

requiresthat-2025.6.15.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

requiresthat-2025.6.15.6/src/requiresthat/__init__.py

@@ -0,0 +1 @@
+from ._requires import requires, RequirementNotFulfilledError, APRIORI, POSTMORTEM, BEFOREANDAFTER

requiresthat-2025.6.15.6/src/requiresthat/_exceptions.py

@@ -0,0 +1,15 @@
+"""Raise this when a requirement is found wanting"""
+
+import textwrap
+
+class RequirementNotFulfilledError(Exception):
+
+    def __init__(self, that, when, msg=None):
+        """Show a default or a user-provided message indicating that some condition is unmet"""
+
+        self.default_msg = textwrap.dedent(f"""
+            {that!r} ({when.name!r}) does not hold
+        """).strip()
+
+        # Call the base class' constructor to init the exception class
+        super().__init__(msg or self.default_msg)

requiresthat-2025.6.15.6/src/requiresthat/_requires.py

@@ -0,0 +1,40 @@
+"""See the README file"""
+
+from typing import Optional, Callable
+from functools import wraps
+
+from ._when import When, APRIORI, POSTMORTEM, BEFOREANDAFTER
+from ._exceptions import RequirementNotFulfilledError
+
+def requires(that, when: When = APRIORI) -> Optional[Callable]:
+    """Require <that> of the decoratee, and require it <when>"""
+
+    def func_wrapper(func: Callable) -> Optional[Callable]:
+        """First-level wrap the decoratee"""
+
+        @wraps(func)
+        def inner_wrapper(self, *pargs, **kwargs) -> Optional[Callable]:
+            """Wrap the first-level wrapper
+
+            The wrapping stops here...
+            """
+            try:
+                if when == APRIORI:
+                    assert eval(that)
+                    # We can use a return here :-)
+                    return func(self, *pargs, **kwargs)
+                elif when == POSTMORTEM:
+                    func(self, *pargs, **kwargs)
+                    assert eval(that)
+                elif when == BEFOREANDAFTER:
+                    assert eval(that)
+                    func(self, *pargs, **kwargs)
+                    assert eval(that)
+                # We don't need an else clause; trying to enlist something that's not in the enum
+                # will be penalised with an AttributeError, and small typos will be healed with a
+                # suggestion as to what you might have meant.
+            except AssertionError as exc:
+                raise RequirementNotFulfilledError(that, when) from exc
+        return inner_wrapper
+
+    return func_wrapper

requiresthat-2025.6.15.6/src/requiresthat/_when.py

@@ -0,0 +1,13 @@
+"""When should a condition hold"""
+
+from enum import Enum, auto
+
+class When(Enum):
+    APRIORI = auto()
+    POSTMORTEM = auto()
+    BEFOREANDAFTER = auto()
+    # There is no DURING or INBETWEEN!
+
+APRIORI = When.APRIORI
+POSTMORTEM = When.POSTMORTEM
+BEFOREANDAFTER = When.BEFOREANDAFTER

requiresthat-2025.6.15.6/src/requiresthat.egg-info/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: requiresthat
+Version: 2025.6.15.6
+Summary: Decorate an instance method with pre- and/or postconditions that must be fulfilled
+Author-email: Ann T Ropea <bedhanger@gmx.de>
+Project-URL: Homepage, https://gitlab.com/bedhanger/mwe/-/tree/master/python/requiresthat
+Description-Content-Type: text/x-rst
+
+requiresthat
+============
+
+Decorate an instance method with pre- and/or postconditions that must be fulfilled
+
+Example usage
+-------------
+
+.. code-block:: python
+
+    from requiresthat import requires, RequirementNotFulfilledError, APRIORI, POSTMORTEM, BEFOREANDAFTER
+
+    class C:
+
+        def __init__(self, data=None):
+            self.data = data
+
+        @requires(that='self.data is not None')
+        @requires(that='self.data == "spam"', when=APRIORI)
+        @requires(that='True is not False')
+        @requires(that='self.data != "spam"', when=POSTMORTEM)
+        @requires(that='len(self.data) >= 3', when=BEFOREANDAFTER)
+        def method(self):
+            self.data = 'ham'
+
+    X = C(data='spam')
+    X.method()
+
+The ``that`` can be almost any valid Python statement which can be evaluated for its veracity, and
+whose result will decide whether or not the method fires/will be considered a success.
+
+The parameter ``when`` decides if the condition is a-priori, post-mortem, or before-and-after.
+The default is a-priori, meaning a precondition.  Note that before-and-after does *not* mean during;
+you cannot mandate an invariant this way!
+
+``RequirementNotFulfilledError`` is the exception you have to deal with in case a condition is not
+met.

requiresthat-2025.6.15.6/src/requiresthat.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.rst
+pyproject.toml
+src/requiresthat/__init__.py
+src/requiresthat/_exceptions.py
+src/requiresthat/_requires.py
+src/requiresthat/_when.py
+src/requiresthat.egg-info/PKG-INFO
+src/requiresthat.egg-info/SOURCES.txt
+src/requiresthat.egg-info/dependency_links.txt
+src/requiresthat.egg-info/top_level.txt
+tests/test_requiresthat.py

requiresthat-2025.6.15.6/src/requiresthat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

requiresthat-2025.6.15.6/src/requiresthat.egg-info/top_level.txt

@@ -0,0 +1 @@
+requiresthat

requiresthat-2025.6.15.6/tests/test_requiresthat.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env --split-string=python -m pytest --verbose
+
+import pytest
+
+from requiresthat import requires, RequirementNotFulfilledError, APRIORI, POSTMORTEM, BEFOREANDAFTER
+
+class TestCase_requiresthat_01:
+
+    def test_trivial(self):
+
+        class Spam:
+
+            @requires(that='True is not False')
+            @requires(that='self is not None')
+            def run(self): ...
+
+        S = Spam()
+        S.run()
+
+    def test_tbd_is_more_than_none(self):
+
+        class Spam:
+
+            # Ok, we suggest that "not" is "more than", but the idea should be clear...
+            @requires(that='... is not None')
+            def run(self): ...
+
+        S = Spam()
+        S.run()
+
+    def test_good(self):
+
+        class Spam:
+
+            def __init__(self):
+                self.foo = 66
+                self.bar = None
+
+            @requires(that='self.foo == 66')
+            @requires(that='self.bar is None')
+            def run(self): ...
+
+        S = Spam()
+        S.run()
+
+    def test_bad(self):
+
+        class Spam:
+            def __init__(self):
+                self.foo = 66
+                self.bar = ... # To be continued, not None
+
+            @requires(that='self.foo == 66')
+            @requires(that='self.bar is None')
+            def run(self): ...
+
+        S = Spam()
+        with pytest.raises(RequirementNotFulfilledError):
+            S.run()
+
+    @pytest.mark.filterwarnings("ignore::SyntaxWarning")
+    def test_ugly(self):
+
+        class Spam:
+            def __init__(self):
+                pass
+
+            @requires(that=b"'24' is not 'the answer'")
+            def run(self): ...
+
+        S = Spam()
+        S.run()
+
+    def test_too_soon_is_bad(self):
+
+        class Spam:
+
+            @requires(that='self.spam == "eggs"')
+            def __init__(self):
+                self.spam = 'ham'
+
+            def run(self): ...
+
+        # We break the constructor (the fact that we confuse spam and eggs is incidental)
+        with pytest.raises(AttributeError):
+            S = Spam()
+
+        # Remember, the constructor just failed...
+        with pytest.raises(UnboundLocalError):
+            S.run()
+
+    def test_docu(self):
+
+        class C:
+
+            def __init__(self, data=None):
+                self.data = data
+
+            @requires(that='self.data is not None')
+            @requires(that='self.data == "spam"', when=APRIORI)
+            @requires(that='True is not False')
+            @requires(that='self.data != "spam"', when=POSTMORTEM)
+            @requires(that='len(self.data) >= 3', when=BEFOREANDAFTER)
+            def method(self):
+                self.data = 'ham'
+
+        X = C(data='spam')
+        X.method()