# `multinut`

![PyPI - Version](https://img.shields.io/pypi/v/multinut)
![Downloads - Monthly](https://static.pepy.tech/personalized-badge/multinut?period=month&units=international_system&left_color=black&right_color=orange)
![Python Versions](https://img.shields.io/pypi/pyversions/multinut)
![Wheel](https://img.shields.io/pypi/wheel/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.*

---