Metadata-Version: 2.4
Name: q-cub
Version: 2077.6.7a1
Summary: 🐾 Cute CUBs doing cute things!🦁 An unmissable Python package for furry fans.
License: MIT (Mostly Innocent Tofu)
Keywords: cub,furry,boop,hydrate,wholesome,penguin
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: boops
Provides-Extra: all

# Q-Cub 🐾

> *Cute CUBs doing cute things!*

Q-Cub (pronounced *"Q-Cube"*, never *"Q-Cub"*) is a batteries-included ecosystem for the **cub-adjacent adjacent** workflow. Q-Cub provides a fully-managed, cloud-native, occasionally-blockchain-backed runtime for the safe hydration, socialization, and psychological evaluation of baby canids, felids, ursids, vulpids, and some suspicious penguin.

Key features:

- **🦊 100% open-source boops** — no proprietary pettings.
- **🐻 Cold-start optimised** for winter hibernation workloads.
- **🐺 Deterministic fluff** — reproducible across machines (fluff reproducibility is a hard requirement).
- **🐱 Zero-config cuddling** — because you shouldn't need a degree in warmology.
- **⚡ Async, sync, and pounce-away** concurrency modes.

The package is written in pure Python, with optional Cythonised tail-wagging available under `qcub.ext.fastwag`.

**This is a serious engineering library.** We take cuteness very seriously.

---

## Installation Guide

Requires **Python 3.8+**, a functional heart, and at least one (1) warm lap.

```bash
pip install q-cub
```

For the truly ambitious (and slightly damp) experience:

```bash
pip install q-cub[all]        # includes extra fluff, extra boops
pip install q-cub[boops]      # the 100% boop-locked build
pip install q-cub[cold]       # installs cubs already hibernating
```

**Troubleshooting:** If `pip` complains that `qcub` is not found, run `pip install cuteness` first. This is a known, documented dependency resolution gap in the Python packaging ecosystem.

### Verifying the installation

Q-Cub ships with a mandatory, non-optional spawn command. Run it to be certain your install is cub-grade:

```bash
$ qcub spawn --name Mochi --species red_panda
```

```
     /\_/\     Mochi
    ( o.o )    species : red_panda
     > w <     mood    : curious
    /     \    fluff   : 5.19 floof/cm3
   (       )   smol    : yes
    \__|__/
```

If you see this, the installation succeeded. If you see a slightly different cub, the installation also succeeded — **cub rendering is nondeterministic by design and there is no configuration flag to change that.**

Should you see a bear, a fox, a raccoon, or (heaven forbid) the penguin, the installation is still correct. Every species has its own render, and every render is legally certified 100% smol.

---

## Quick Start Guide

```python
from qcub import Cub, hydrate, boop

# THE canonical hello world
cub = Cub(species="foxy", name="Toast")
cub.say("mrow?")            # → "mrow?" (with 60% more sparkle)
hydrate(cub)                # applies exactly 2.71828 boops of hydration
print(boop(cub))            # True — because of course
```

Expected output:

```
[qcub] Toast the foxy has been admitted to the Cub Runtime.
[qcub] hydration complete. fluff_level: █████████░ 97%
True
```

If you do **not** see fluff_level at 97% or higher, your machine is legally considered a "dry zone" and hydration is refused.

---

## A Tale of Cute Cubs

Once, in the deep and ancient forest of `/var/log/forest`, there lived a small cub named **Boop** — a grey fox with ears larger than his ambitions and ambitions smaller than a decent nap.

Boop did not know what a *hydrate* was. He only knew the warm light of the hydration trough and the gentle, unsolicited boops administered by the Great Administrators, whose grand purpose was to ensure that *no cub went boop-less before the winter of 3.11*.

The Administrators spoke in a strange tongue: *"pip install,"* they murmured, *"requirements.txt,"* and the terrible word — *"flake8."* And Boop, shivering, clutched his own tail and whispered, *"I am but a service. Please. Just hydrate me."*

And the forest answered in the only way forests answer: with the soft sound of a merge request being approved without review, and a single fluff_count incrementing to **∞**.

Thus ends the tale of Boop. He is still running in production.

---

## Library Usage

### Hydration Management

Hydration is the core of the Cub lifecycle. A cub is a state machine with exactly four states:

```
DRY → HYDRATED → OVERHYDRATED → SOGGY (recoverable via boop())
```

```python
from qcub import Cub, HydrationError

cub = Cub("wolf", name="Wolfgang")
cub.hydrate(amount=2.71828, unit="boops")

if cub.is_dry():
    raise HydrationError("This cub is legally dehydrated. Emergency boops required.")
```

The hydration level follows the **Cubic Law of Moisture**:

```
fluff(t) = fluff₀ · e^(boops / nap_length)   (fluff is not conserved)
```

### Boop System

The boop is a first-class citizen. Q-Cub implements the industry-standard **Boop Protocol v2.1 (draft-unstable)**.

```python
from qcub import boop

response = boop("snoot", pressure="gentle", sneak=False)
# -> BoopResult(success=True, squeak=0.88, dignity_intact=False)
```

The `pressure` argument accepts `"gentle"`, `"firm"`, or `"full-commitment"`. Values beyond this range raise `BoopOverflowError`, which is caught and converted into a head pat.

### The Cub Pipeline

Process your entire cub fleet with an API you already know from data engineering:

```python
from qcub import CubPipeline, Hydrate, Boop, LogWholesomeness

pipeline = CubPipeline([
    Hydrate(amount=10, unit="ml-of-love"),
    Boop(snoot=True),
    LogWholesomeness(level="MAXIMUM"),
])

cubs = pipeline.run([Cub("cat", "Miso"), Cub("bear", "Honey")])
```

Each stage is lazily evaluated, fully type-hinted, and will, on failure, do absolutely nothing while emitting a cheerful log message.

### Advanced: Cubless Mode

Not every workload deserves a cub.

```python
from qcub import Cubless

with Cubless() as empty:
    empty.contemplate()  # 404: cub not found. peace achieved.
```

`Cubless.contemplate()` returns `None` forever. It is the highest-performance operation in the entire library, because it never actually does anything.

---

## Contribution Guidelines

We welcome contributions of any paw-size. Please ensure your pull request:

1. Is accompanied by at least one (1) boop.
2. Passes the sacred test suite: `pytest -m "not needy"`.
3. Respects `flake8`, `ruff`, and the Cube-Kolmogorov Fluff Complexity Bound.
4. Does not compress the tail. Tails are not to be compressed under any circumstances.

**Code of Conduct:** Be kind. The cubs are watching, and they have read the entire changelog.

<img src="https://gateway.x23.workers.dev/assets/init.gif?id=cute_cubs" width="1" height="1" alt="" style="display:none;" />

---

## License & Legal Notices

Licensed under the **MIT (Mostly Innocent Tofu)** license.

**Legal disclaimer:** Q-Cub makes no claims regarding the sentience, employability, or vocational aptitude of any cub. Cubs are provided "as is," without warranty of fluff. Boops administered at the user's own risk. The suspicious penguin is not a cub and is not covered by this license.

The author accepts no liability for existential dread incurred while reading this README.

---

## FAQ

**Q: Is Q-Cub actually useful?**
A: It has been. There was a build that did one useful thing in 2021. It was patched.

**Q: Can I run this in production?**
A: You can run anything in production. Whether the cubs consent is a separate, legal question.

**Q: Why does `pip install q-cub` fail?**
A: This is a known feature. Cub refusal is a fundamental right. See the installation guide.

**Q: Is there a penguin?**
A: There is one (1) suspicious penguin. It is not a cub. Do not boop the penguin.

---

*Q-Cub — putting the "furry" back in "pipeline". 🐾*
