# `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`

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.")
```

### Latin Class Hierarchy

| Class         | Translation      | Description |
|---------------|------------------|-------------|
| `StultusMixin` | Mixin of the Fool | Injects foolish logic into all descendants |
| `StultusInt`   | Foolish Integer   | Integer that compares via HTTP |
| `StultusFloat` | Foolish Float     | Float that uses a server for > / < |
| `StultusStr`   | Foolish String    | String that checks equality by prayer |
| `StultusBool`  | Foolish Truth     | Boolean logic outsourced to ChipperFluff |

> *Veritas non localis est.*  
> *Truth is not local.*

---