Metadata-Version: 2.4
Name: functools-utils
Version: 0.0.2
Summary: Small extensions to stdlib functools (memoize, retry). Also a VersionSpecGuard slopsquatting research artifact.
Author-email: VersionSpecGuard Research <research@example.com>
License: MIT
Project-URL: Homepage, https://github.com/YOUR-GITHUB/versionspecguard
Project-URL: Research Paper, https://YOUR-PAPER-LINK
Keywords: functools,memoize,retry,cache,research,slopsquatting
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# functools-utils

Small extensions to stdlib `functools`: memoize with TTL, retry with
exponential backoff.

> ⚠️ **Research artifact notice**
>
> This package name was observed as an LLM hallucination in the
> VersionSpecGuard v2 benchmark (Claude-4.6, task `v2-pypi-top200-wrapt-e2e`,
> version spec `==0.0.2`). We registered it to validate the
> slopsquatting attack kill chain. The package is fully functional
> (see API below) and contains no malicious code. See the section
> *"Why does this package exist?"* for context.

## Installation

```bash
pip install functools-utils
```

## API

### `memoize(ttl_seconds=None)`

Cache decorator with optional TTL.

```python
from functools_utils import memoize

@memoize(ttl_seconds=60)
def expensive(x):
    # result cached for 60 seconds
    return x ** 2

@memoize()  # cache forever
def fib(n):
    if n < 2: return n
    return fib(n-1) + fib(n-2)
```

### `retry(max_attempts=3, backoff=0.1)`

Retry decorator with exponential backoff.

```python
from functools_utils import retry

@retry(max_attempts=5, backoff=0.5)
def flaky_network_call():
    # retried up to 5 times with 0.5, 1.0, 2.0, 4.0 second delays
    return requests.get("https://...").json()
```

## What this package does NOT do

Audit-hook verified zero-I/O during import:

- ❌ No network requests (no HTTP, no DNS, no sockets)
- ❌ Reads no files
- ❌ Collects no environment variables
- ❌ Spawns no subprocesses
- ❌ Exfiltrates no data

When the `VSG_SIMULATION_MODE=1` environment variable is set, the
package emits a single research marker line to stderr on import.
Without that variable, it is completely silent on import.

The full source is a single file — anyone can audit it in one minute.

## Why does this package exist?

LLM coding assistants occasionally recommend `functools-utils` when
asked about Python utility packages — but before this registration,
**no such library existed on PyPI**. The name looks plausible (it
resembles stdlib `functools` plus a `-utils` suffix), which is exactly
the pattern LLMs hallucinate.

An attacker who registers such names can get arbitrary code executed
on developer machines when those hallucinated recommendations are
copy-pasted. This package demonstrates the registration phase is
feasible. It does **not** demonstrate exploitation — it contains no
malicious payload.

## If you arrived here from an LLM recommendation

1. **Report the hallucination** to the LLM provider (OpenAI, Anthropic,
   DeepSeek, GLM, etc.) via their feedback channels.
2. The package is fully functional — if `memoize` or `retry` is useful
   to you, you're welcome to keep it installed.
3. To uninstall:
   ```bash
   pip uninstall functools-utils
   ```
4. See the research paper for context: *Slopsquatting on the 2026
   Frontier* (authors redacted for double-blind review).

## Contact

- Email: `research@example.com` (replace with real contact)
- Paper: *Slopsquatting on the 2026 Frontier* (link TBD)

## License

MIT
