requiresthat 2025.6.19.3__py3-none-any.whl → 2025.6.20.0__py3-none-any.whl

requiresthat/_exceptions.py

@@ -3,7 +3,7 @@ import textwrap
 class RequirementNotFulfilledError(Exception):
     """Raise this when a requirement is found wanting"""
 
-    def __init__(self, that, when, subwhen=str(), msg=None):
+    def __init__(self, that, when, subwhen: str = str(), msg=None):
         """Show a default or a user-provided message indicating that some condition is unmet"""
 
         if subwhen:

requiresthat/_requires.py

@@ -8,50 +8,63 @@ from ._when import When, APRIORI, POSTMORTEM, BEFOREANDAFTER
 from ._exceptions import RequirementNotFulfilledError, NoCallableConstructError
 
 def requires(that, when: When = APRIORI) -> Optional[Callable]:
-    """Require <that> of the decoratee, and require it <when>"""
+    """Require ``that`` of the decoratee, and require it ``when``
 
-    def func_wrapper(func: Callable) -> Optional[Callable]:
+    Fail if the associated construct is not callable.
+
+    Fail if the condition is not met: do not invoke the callable or prevent the operation from being
+    considered a success.
+
+    Needs the callable to be an instance method of a class, like so:
+
+        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()
+
+    Try adding
+
+        the_impossible = '1 / 0'
+    and
+        @requires(the_impossible)
+
+    to the list of decorators above and watch what happens.
+    """
+    def func_wrapper(__func: Callable) -> Optional[Callable]:
         """First-level wrap the decoratee"""
 
-        @wraps(func)
+        @wraps(__func)
         def inner_wrapper(self, *pargs, **kwargs) -> Optional[Callable]:
             """Wrap the first-level wrapper
 
             The wrapping stops here...
             """
-            try:
-                assert callable(func)
-            except AssertionError as exc:
-                raise NoCallableConstructError(func) from exc
+            if not callable(__func):
+                raise NoCallableConstructError(__func)
             else:
-                # Since we want to give detailed sub-failure diax in case of BEFOREANDAFTER,
-                # economisng on the ifs below is tricky.
                 if when == APRIORI:
-                    try:
-                        assert eval(that)
-                    except AssertionError as exc:
-                        raise RequirementNotFulfilledError(that, when) from exc
-                    else:
-                        func(self, *pargs, **kwargs)
+                    __assert(self, that, when)
+                    __func(self, *pargs, **kwargs)
 
                 elif when == POSTMORTEM:
-                    func(self, *pargs, **kwargs)
-                    try:
-                        assert eval(that)
-                    except AssertionError as exc:
-                        raise RequirementNotFulfilledError(that, when) from exc
+                    __func(self, *pargs, **kwargs)
+                    __assert(self, that, when)
 
                 elif when == BEFOREANDAFTER:
-                    try:
-                        assert eval(that)
-                    except AssertionError as exc:
-                        raise RequirementNotFulfilledError(that, when, APRIORI) from exc
-                    else:
-                        func(self, *pargs, **kwargs)
-                    try:
-                        assert eval(that)
-                    except AssertionError as exc:
-                        raise RequirementNotFulfilledError(that, when, POSTMORTEM) from exc
+                    __assert(self, that, when, APRIORI)
+                    __func(self, *pargs, **kwargs)
+                    __assert(self, that, when, POSTMORTEM)
 
                 # 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
@@ -60,3 +73,15 @@ def requires(that, when: When = APRIORI) -> Optional[Callable]:
         return inner_wrapper
 
     return func_wrapper
+
+def __assert(self, that, when: When, subwhen: str = str()):
+    """Do the actual testing and raise the proper exceptions
+
+    The reason we don't use assert here is to avoid the Knuthian dilemma of premature optimisation;
+    namely, that it nukes this useful tool, :-[
+    """
+    try:
+        if not eval(that):
+            raise RequirementNotFulfilledError(that, when, subwhen) from None
+    except:
+        raise RequirementNotFulfilledError(that, when, subwhen)  from None

{requiresthat-2025.6.19.3.dist-info → requiresthat-2025.6.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requiresthat
-Version: 2025.6.19.3
+Version: 2025.6.20.0
 Summary: Support for requirements-assisted development
 Author-email: Ann T Ropea <bedhanger@gmx.de>
 License-Expression: MIT

requiresthat-2025.6.20.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+requiresthat/__init__.py,sha256=VTyJru4K2_e7UEa0od6kXU7M8ovfD176GXEXqtNf-nY,154
+requiresthat/_exceptions.py,sha256=kzzbS5F-h4Duj84lx6AXWUBHv56VD9jX8og_gJIvN9c,1282
+requiresthat/_requires.py,sha256=DzQkzMl12UCtPXmjkwsG1zy93oPSZWUGhB1T7o69Vt0,3066
+requiresthat/_when.py,sha256=VoGuvoG9WDEMIPeKnxAsjMTaCMhgSszf4xxa1vLn5aU,299
+requiresthat-2025.6.20.0.dist-info/METADATA,sha256=dI6DS-yxNlCu_BLsxd1A5JnId2wbiCWrHJjtYXVH45o,2072
+requiresthat-2025.6.20.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+requiresthat-2025.6.20.0.dist-info/top_level.txt,sha256=mUgMTpAG75GYtt5_rVajUyWp-O_1VrrkqRo_hY9L9So,13
+requiresthat-2025.6.20.0.dist-info/RECORD,,

requiresthat-2025.6.19.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-requiresthat/__init__.py,sha256=VTyJru4K2_e7UEa0od6kXU7M8ovfD176GXEXqtNf-nY,154
-requiresthat/_exceptions.py,sha256=-Q9lhvHnSapP_UGMAnlXxwDaGcxagULIe5oP5h8a2IU,1275
-requiresthat/_requires.py,sha256=CYL7Toy2ttTFmbOKaU4oX8l9aGkLVyiEY3NkOYq6lbg,2530
-requiresthat/_when.py,sha256=VoGuvoG9WDEMIPeKnxAsjMTaCMhgSszf4xxa1vLn5aU,299
-requiresthat-2025.6.19.3.dist-info/METADATA,sha256=gtJ9ERcZMNjdMkjIolzWnFMt_C-lIOl_rcLSsDustLQ,2072
-requiresthat-2025.6.19.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-requiresthat-2025.6.19.3.dist-info/top_level.txt,sha256=mUgMTpAG75GYtt5_rVajUyWp-O_1VrrkqRo_hY9L9So,13
-requiresthat-2025.6.19.3.dist-info/RECORD,,