334 lines
8.9 KiB
Markdown
334 lines
8.9 KiB
Markdown
# `multinut`
|
||
|
||
|
||
|
||
|
||
|
||
|
||
The multitool nobody asked for. Includes stuff and so.
|
||
|
||
---
|
||
|
||
## `multinut.env`
|
||
|
||
A simple but flexible environment loader.
|
||
|
||
Supports `.env` file parsing with optional mode suffixes (e.g. `.env.production`, `.env.testing`, etc.), lazy loading, and dynamic access.
|
||
|
||
### Features
|
||
|
||
* Mode-based config support (`.env.production`, `.env.testing`, etc.)
|
||
* Access via:
|
||
|
||
* `env["KEY"]`
|
||
* `env.get("KEY", ...)`
|
||
* `env.KEY`
|
||
* Optional type casting (`str`, `bool`, `list`, `dict`, etc.)
|
||
* Sane default handling
|
||
* Does **not** mutate `os.environ`
|
||
|
||
---
|
||
|
||
### Use cases
|
||
|
||
* Loading `.env` files in mode-aware Python projects
|
||
* Separating secrets and configs by deployment context
|
||
* Dynamically reading values like `env.DB_URL`, `env.get("DEBUG", default=False, cast=cast_bool)`
|
||
* Avoiding `os.environ` pollution
|
||
|
||
---
|
||
|
||
### Basic Example
|
||
|
||
```python
|
||
from multinut.env import Environment, Modes
|
||
|
||
env = Environment(env_file_name=".env", mode=Modes.DEVELOPMENT)
|
||
|
||
print(env.get("DEBUG", default=False))
|
||
print(env["API_KEY"])
|
||
print(env.DB_URL)
|
||
```
|
||
|
||
Given a `.env.development` file:
|
||
|
||
```env
|
||
DEBUG=true
|
||
API_KEY=secret
|
||
DB_URL=https://example.com
|
||
```
|
||
|
||
---
|
||
|
||
### Smart Casts Example
|
||
|
||
```python
|
||
from multinut.env import (
|
||
Environment, cast_bool, cast_int, cast_float,
|
||
cast_list, cast_tuple, cast_dict, cast_none_or_str
|
||
)
|
||
|
||
env = Environment()
|
||
|
||
print("INT:", env.get("PORT", cast=cast_int)) # -> int
|
||
print("FLOAT:", env.get("PI", cast=cast_float)) # -> float
|
||
print("BOOL:", env.get("ENABLED", cast=cast_bool)) # -> bool
|
||
print("LIST:", env.get("NUMBERS", cast=cast_list)) # -> list[str]
|
||
print("TUPLE:", env.get("WORDS", cast=cast_tuple)) # -> tuple[str]
|
||
print("DICT:", env.get("CONFIG", cast=cast_dict)) # -> dict
|
||
print("NONE_OR_STR:", env.get("OPTIONAL", cast=cast_none_or_str)) # -> None or str
|
||
```
|
||
|
||
Example `.env`:
|
||
|
||
```env
|
||
PORT=8080
|
||
PI=3.1415
|
||
ENABLED=yes
|
||
NUMBERS=1,2,3
|
||
WORDS=hello,world,test
|
||
CONFIG={"timeout": 30, "debug": true}
|
||
OPTIONAL=null
|
||
```
|
||
|
||
### Included Cast Helpers
|
||
|
||
All built-in cast functions handle common edge cases:
|
||
|
||
| Cast Function | Description |
|
||
| ------------------ | ------------------------------------------- |
|
||
| `cast_str` | Ensures string |
|
||
| `cast_int` | Converts to integer |
|
||
| `cast_float` | Converts to float |
|
||
| `cast_bool` | Accepts `1`, `true`, `yes`, `on`, etc. |
|
||
| `cast_list` | Comma-split list |
|
||
| `cast_tuple` | Comma-split, converted to tuple |
|
||
| `cast_dict` | Parses JSON string into dictionary |
|
||
| `cast_none_or_str` | Returns `None` if value is `null` or `None` |
|
||
|
||
---
|
||
|
||
### EnviromentKeyMissing
|
||
|
||
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`
|
||
|
||
Every function in `multinut.stultus` relies on a sacred remote endpoint:
|
||
`https://stultus.chipperfluff.at`
|
||
|
||
When the shrine is unreachable—due to squirrels sleeping, servers crashing, or fate itself rejecting logic—any function will raise:
|
||
|
||
```python
|
||
StultusUnavailable: [STULTUS] Failed logic call to 'operation': [reason]
|
||
```
|
||
|
||
This ensures you *see your failure* instead of trusting a broken silence.
|
||
Because when truth is outsourced, **you deserve to know when the transmission failed.**
|
||
|
||
---
|
||
|
||
### `ping()`
|
||
|
||
Use `ping()` to determine whether the squirrel logic shrine is currently active:
|
||
|
||
```python
|
||
from multinut.stultus import ping
|
||
|
||
if ping():
|
||
print("Squirrel logic shrine is listening.")
|
||
else:
|
||
print("The fluff has left the network.")
|
||
```
|
||
|
||
Returns `True` only when the `/ping` endpoint returns `{ "status": "ok" }`.
|
||
False means the fluff is silent. Prepare your backup shrine.
|
||
|
||
---
|
||
|
||
### Latin Class Hierarchy
|
||
|
||
This module replaces standard Python primitives with HTTP-wrapped equivalents.
|
||
They override operators (`==`, `>=`, `+`, `[]`, etc.) and route them through remote endpoints—ensuring **maximum latency, fragility, and squirrel-blessed absurdity**.
|
||
|
||
| Class | Latin Meaning | Description |
|
||
| -------------- | ------------------ | ----------------------------------------------- |
|
||
| `StultusMixin` | Mixin of the Fool | Injects HTTP logic into all descendants |
|
||
| `StultusInt` | Foolish Integer | Arithmetic and comparison via HTTP |
|
||
| `StultusFloat` | Foolish Float | Same as above, with floating shame |
|
||
| `StultusStr` | Foolish String | Equality, `.upper()`, `.invert()` all delegated |
|
||
| `StultusBool` | Foolish Truth | Truth is no longer local |
|
||
| `StultusList` | Foolish List | Push, pop, index via remote POST |
|
||
| `StultusDict` | Foolish Dictionary | Dictionary access through divine lookup |
|
||
|
||
Example:
|
||
|
||
```python
|
||
from multinut.stultus import StultusInt, StultusStr
|
||
|
||
a = StultusInt(5)
|
||
b = StultusInt(3)
|
||
|
||
if a >= b:
|
||
print("Confirmed by the logic gods.")
|
||
|
||
word = StultusStr("uwu")
|
||
print(word.invert()) # 'uwu' reversed, via HTTP
|
||
```
|
||
|
||
---
|
||
|
||
### Available Remote Functions
|
||
|
||
Every operation is offloaded via HTTPS.
|
||
|
||
#### Logic
|
||
|
||
```python
|
||
EQUALS(a, b)
|
||
GREATER(a, b)
|
||
LESSER(a, b)
|
||
GREATER_EQUAL(a, b) # makes 3 HTTPS requests
|
||
LESSER_EQUAL(a, b)
|
||
NOT(x)
|
||
AND(*args)
|
||
OR(*args)
|
||
```
|
||
|
||
#### Math
|
||
|
||
```python
|
||
ADD(a, b)
|
||
SUB(a, b)
|
||
MUL(a, b)
|
||
DIV(a, b) # division by zero = "division by fluff"
|
||
RANDINT(a, b) # has artificial delay
|
||
RANGE(n, shuffle=True) # shuffled server-side
|
||
```
|
||
|
||
#### List Operations
|
||
|
||
```python
|
||
LEN(list)
|
||
LIST_INDEX(list, index)
|
||
LIST_PUSH(list, item)
|
||
LIST_POP(list)
|
||
```
|
||
|
||
#### Dictionary Access
|
||
|
||
```python
|
||
DICT_GET(dict, key)
|
||
```
|
||
|
||
#### String Tools
|
||
|
||
```python
|
||
UPPER(str)
|
||
INVERT(str)
|
||
```
|
||
|
||
#### Truthiness
|
||
|
||
```python
|
||
TRUTH(x)
|
||
BOOLIFY(str) # wraps eval (yes, really)
|
||
```
|
||
|
||
#### Time & Crypto
|
||
|
||
```python
|
||
TIME() # epoch + ISO + fluff-certainty
|
||
HASH_PASSWORD(pw, algo) # e.g. sha256, sha1, md5 (pls no)
|
||
```
|
||
|
||
---
|
||
|
||
## Disclaimer
|
||
|
||
> **⚠️ WARNING:**
|
||
> This module is deliberately slow, unsafe, and ridiculous.
|
||
> It outsources core logic to a remote web server.
|
||
> Use it only for:
|
||
>
|
||
> * Chaos
|
||
> * Rituals
|
||
> * Art
|
||
> * Demos that make DevOps cry
|
||
> Never in production. Never with real data.
|
||
> Do not test this on anyone you love.
|
||
|
||
---
|
||
|
||
## Contributing to `multinut.stultus`
|
||
|
||
Pull requests are **gloriously welcome** if they contain any of the following:
|
||
|
||
* Inefficient use of the network
|
||
* Operators reimplemented in Latin
|
||
* Dumb ideas with great commitment
|
||
* Broken logic wrapped in elegant lies
|
||
* New subclasses like `StultusComplex`, `StultusPath`, or `StultusEnum`
|
||
|
||
Please **do not fix performance, security, or clarity**.
|
||
The project is working *as irrationally designed.*
|
||
|
||
> *Veritas non localis est.*
|
||
> *Truth is not local.*
|
||
|
||
---
|