feat: implement stultus module with logic-as-a-service, including operators and custom exceptions

README.md

@@ -112,3 +112,78 @@ All built-in cast functions handle common edge cases:
 
 if a key is get from `env.get` and it has no default given it will raise
 EnviromentKeyMissing(f"Environment variable '{key}' not found.")
+
+Understood, mistress.
+Here is the final `README.md` **section** dedicated to your chaotic masterpiece:
+
+---
+
+## `multinut.stultus`
+
+A logic module that proudly makes every operation slower, dumber, and HTTPS-dependent.
+Each logical comparison or boolean operation is turned into a full HTTPS request to `https://stultus.chipperfluff.at`, for no reason other than chaos and fluff.
+
+### Features
+
+* Logic-as-a-Service™️ (LaaS)
+* Every basic logic op (`==`, `<`, `>`, `and`, `or`, `not`) done via remote API
+* Combo logic like `>=` and `<=` make **three separate HTTPS calls** each
+* Full TLS overhead, network latency, and JSON parsing baked into every `if` statement
+* Built-in server availability check
+* Custom `StultusUnavailable` exception when your logic server goes *poof*
+
+---
+
+### Available Functions
+
+| Function              | Description         | HTTP Requests |
+| --------------------- | ------------------- | ------------- |
+| `EQUALS(a, b)`        | Returns `a == b`    | 1             |
+| `GREATER(a, b)`       | Returns `a > b`     | 1             |
+| `LESSER(a, b)`        | Returns `a < b`     | 1             |
+| `NOT(x)`              | Returns `not x`     | 1             |
+| `AND(*args)`          | Returns `all(args)` | 1             |
+| `OR(*args)`           | Returns `any(args)` | 1             |
+| `GREATER_EQUAL(a, b)` | Returns `a >= b`    | **3** 💀      |
+| `LESSER_EQUAL(a, b)`  | Returns `a <= b`    | **3** 💀      |
+
+---
+
+### Example Usage
+
+```python
+from multinut.stultus import GREATER_EQUAL, EQUALS, ping, StultusUnavailable
+
+if ping():
+    print("Stultus server is online.")
+
+try:
+    if GREATER_EQUAL(5, 5):
+        print("Greater or equal confirmed. Using three HTTP requests.")
+except StultusUnavailable as err:
+    print(f"🛑 Failed to logic: {err}")
+```
+
+---
+
+### `StultusUnavailable`
+
+If the server is unreachable, every function will raise a `StultusUnavailable` exception.
+This helps avoid silent logic failures when the sacred squirrel cloud is down.
+
+---
+
+### ping()
+
+You can check if the Stultus server is alive:
+
+```python
+from multinut.stultus import ping
+
+if ping():
+    print("Squirrel logic shrine is listening.")
+else:
+    print("The fluff has left the network.")
+```
+
+---

multinut/stultus/__init__.py

@@ -0,0 +1,20 @@
+from .opperators import (
+    EQUALS, GREATER, LESSER, GREATER_EQUAL,
+    LESSER_EQUAL, NOT, AND, OR
+)
+
+from .custom import (
+    StultusMixin, StultusInt, StultusFloat,
+    StultusStr, StultusBool
+)
+
+from .handler import ping, StultusUnavailable
+
+__all__ = [
+    "EQUALS", "GREATER", "LESSER",
+    "GREATER_EQUAL", "LESSER_EQUAL", "NOT",
+    "AND", "OR",
+    "StultusMixin", "StultusInt", "StultusFloat",
+    "StultusStr", "StultusBool",
+    "ping", "StultusUnavailable"
+]

multinut/stultus/custom.py

@@ -0,0 +1,20 @@
+from multinut.stultus import (
+    EQUALS, GREATER, LESSER, GREATER_EQUAL,
+    LESSER_EQUAL, NOT, AND, OR
+)
+
+class StultusMixin:
+    def __eq__(self, other): return EQUALS(self, other)
+    def __gt__(self, other): return GREATER(self, other)
+    def __lt__(self, other): return LESSER(self, other)
+    def __ge__(self, other): return GREATER_EQUAL(self, other)
+    def __le__(self, other): return LESSER_EQUAL(self, other)
+    def __ne__(self, other): return NOT(EQUALS(self, other))
+    def __and__(self, other): return AND(self, other)
+    def __or__(self, other): return OR(self, other)
+
+class StultusInt(StultusMixin, int): pass
+class StultusFloat(StultusMixin, float): pass
+class StultusStr(StultusMixin, str): pass
+class StultusBool(StultusMixin, bool): pass
+

multinut/stultus/handler.py

@@ -20,13 +20,4 @@ def ping() -> bool:
         return r.status_code == 200 and r.json().get("status") == "ok"
     except Exception:
         return False
-
+    
-def EQUALS(a, b): return _get("equals", {"a": a, "b": b})
-def GREATER(a, b): return _get("greater", {"a": a, "b": b})
-def LESSER(a, b): return _get("lesser", {"a": a, "b": b})
-def NOT(x): return _get("not", {"val": str(x).lower()})
-def AND(*args): return _get("and", [("val", str(v).lower()) for v in args])
-def OR(*args): return _get("or", [("val", str(v).lower()) for v in args])
-
-def GREATER_EQUAL(a, b): return OR(GREATER(a, b), EQUALS(a, b))
-def LESSER_EQUAL(a, b): return OR(LESSER(a, b), EQUALS(a, b))

multinut/stultus/opperators.py

@@ -0,0 +1,11 @@
+from .handler import _get
+
+def EQUALS(a, b): return _get("equals", {"a": a, "b": b})
+def GREATER(a, b): return _get("greater", {"a": a, "b": b})
+def LESSER(a, b): return _get("lesser", {"a": a, "b": b})
+def NOT(x): return _get("not", {"val": str(x).lower()})
+def AND(*args): return _get("and", [("val", str(v).lower()) for v in args])
+def OR(*args): return _get("or", [("val", str(v).lower()) for v in args])
+
+def GREATER_EQUAL(a, b): return OR(GREATER(a, b), EQUALS(a, b))
+def LESSER_EQUAL(a, b): return OR(LESSER(a, b), EQUALS(a, b))

setup.py

@@ -2,9 +2,9 @@ from setuptools import setup, find_packages
 
 setup(
     name='multinut',
-    version='0.2.5',
+    version='0.2.8',
     packages=find_packages(),
-    install_requires=["dotenv"],
+    install_requires=["python-dotenv"],
     author='Chipperfluff',
     author_email='contact@chipperfluff.at',
     description='A completely unnecessary multitool module.',