Metadata-Version: 2.4
Name: whispy-client
Version: 1.1.7
Summary: Stream Python packages at runtime — the PyPI CDN client
Project-URL: Homepage, https://whispycdn.dev
Project-URL: Repository, https://github.com/Dark-Avenger-Reborn/Whispy
Project-URL: Documentation, https://whispycdn.dev/docs
Project-URL: Bug Tracker, https://github.com/Dark-Avenger-Reborn/Whispy/issues
License: MIT
Keywords: cdn,dynamic-import,packages,pypi,runtime
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.8
Description-Content-Type: text/markdown

<div align="center">

# 🌀 Whispy Client

> Import Python packages at runtime with a zero-dependency client.
> Keep your scripts clean, your environments disposable, and your setup friction low.

<p>
	<a href="https://pypi.org/project/whispy-client/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/whispy-client?style=for-the-badge&logo=pypi&logoColor=white" /></a>
	<img alt="stdlib only" src="https://img.shields.io/badge/Runtime-stdlib%20only-22c55e?style=for-the-badge" />
	<img alt="Whispy repo" src="https://img.shields.io/badge/Repo-GitHub-0ea5e9?style=for-the-badge&logo=github&logoColor=white" />
	<img alt="MIT" src="https://img.shields.io/badge/License-MIT-f59e0b?style=for-the-badge" />
</p>

</div>

The client lives in the [Whispy repository](https://github.com/Dark-Avenger-Reborn/Whispy), with the implementation in [client/whispy_client](https://github.com/Dark-Avenger-Reborn/Whispy/tree/main/client/whispy_client) and the server entrypoint in [server/app.py](../server/app.py). It downloads a bundle from a Whispy server, extracts it to a temporary directory, and imports the requested module at runtime.

## When to Use It

- Throwaway scripts that need `requests`, `numpy`, or `beautifulsoup4` without a setup step.
- Short-lived jobs where you want packages to vanish when the process exits.
- Pinned runtime experiments where one exact version matters.
- Self-hosted setups that point at your own server from the [main repo](https://github.com/Dark-Avenger-Reborn/Whispy).

## Quick Examples

```python
from whispy_client import remote, configure

configure(verbose=True)

requests = remote("requests")
numpy = remote("numpy", version="1.26.4")
bs4 = remote("beautifulsoup4", module="bs4", deps=True)
```

```python
# Version pinning (use the version parameter)
requests = remote("requests", version="2.31.0")
numpy = remote("numpy", version="1.26.4")

# Common import name mismatches
bs4 = remote("beautifulsoup4", module="bs4")
PIL = remote("pillow", module="PIL")
yaml = remote("pyyaml", module="yaml")
dateutil = remote("python-dateutil", module="dateutil")
cv2 = remote("opencv-python", module="cv2", deps=True)
```

## Import Failure Tips

If a package downloads but import fails with an error like `No module named 'numpy'`, that usually means a dependency is missing from the runtime bundle.

- Retry with `deps=True` for that call.
- Or set `configure(deps=True)` once for process-wide behavior.
- Keep `module="..."` when the import name differs from the distribution name.

Example:

```python
# opencv-python imports as cv2 and needs runtime dependencies
cv2 = remote("opencv-python", module="cv2", deps=True)
```

## Install

```bash
pip install whispy-client
```

[whispy-client on PyPI](https://pypi.org/project/whispy-client/)

For local development from this repo:

```bash
cd client
pip install -e .
```

## API

### `remote(package, *, module=None, version=None, deps=False, host=None)`

`package` is a PyPI distribution name. Specify versions using the `version` parameter (for example: `remote("requests", version="2.31.0")`). If the import name differs from the distribution name, pass `module=...`.

`deps=True` asks the server to include install-time dependencies as well. That behavior is best-effort and does not perform full dependency conflict resolution.

| Param | Description |
|-------|-------------|
| `package` | PyPI distribution name |
| `module` | Import name if different from the package name |
| `version` | Explicit version override. Specify versions here instead of embedding them in `package` |
| `deps` | Fetch install-time dependencies as well |
| `host` | Per-call Whispy server override |

### `configure(*, host=None, deps=None, verbose=None)`

Sets process-wide defaults. The default host comes from `WHISPY_HOST`, falling back to `https://whispycdn.dev`.

| Param | Description |
|-------|-------------|
| `host` | Default Whispy server URL |
| `deps` | Default dependency-fetching behavior |
| `verbose` | Print progress messages while fetching and importing |

## Code References

- The client implementation is in [client/whispy_client/core.py](https://github.com/Dark-Avenger-Reborn/Whispy/blob/testing_new/client/whispy_client/core.py).
- The server path that resolves bundles is in [server/app.py](../server/app.py).
- The release workflow is in [the repo workflow file](../.github/workflows/ci.yml).

## License

MIT. Packages are sourced from PyPI and remain under their original licenses.
