Metadata-Version: 2.3
Name: getskua
Version: 0.9.3
Summary: Shareable URLs for notebook outputs — snap any chart, DataFrame, or figure into a live link
Keywords: jupyter,notebook,sharing,visualization,data-science,matplotlib,plotly,pandas,snapshot,collaboration,cli,share
Author: Franklin Street Labs
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
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.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 :: Scientific/Engineering :: Visualization
Requires-Dist: requests>=2.31.0
Requires-Dist: click>=8.0
Requires-Dist: pytest>=7.4.3 ; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0 ; extra == 'dev'
Requires-Dist: black>=23.12.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.8 ; extra == 'dev'
Requires-Dist: mypy>=1.7.1 ; extra == 'dev'
Requires-Dist: types-requests>=2.31.0 ; extra == 'dev'
Requires-Dist: matplotlib>=3.7.0 ; extra == 'dev'
Requires-Dist: pandas>=2.0.0 ; extra == 'dev'
Requires-Dist: pillow>=10.0.0 ; extra == 'dev'
Requires-Dist: plotly>=5.0.0 ; extra == 'dev'
Requires-Dist: polars>=0.20.0 ; extra == 'dev'
Requires-Dist: pyarrow>=14.0.0 ; extra == 'dev'
Requires-Python: >=3.8
Project-URL: Documentation, https://skua.dev/docs
Project-URL: Homepage, https://skua.dev
Project-URL: Repository, https://github.com/franklinstlabs/skua
Provides-Extra: dev
Description-Content-Type: text/markdown

# Skua

**Shareable URLs for notebook outputs**

One function call turns plots, DataFrames, and text into permanent links.
Re-run the cell to update — same URL, fresh results.

## Installation

```bash
pip install getskua
```

No setup required. No account, no API key.

## Quick Start

```python
import matplotlib.pyplot as plt
import skua

fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 4, 9])
ax.set_title("Quadratic Growth")

result = skua.snap(fig, title="Quadratic Growth")
print(result.url)  # https://skua.dev/s/abc123
```

Share the URL with anyone. Call `skua.snap()` again with the same title to update in place.

## CLI

Works with any tool that can run shell commands — AI coding assistants, CI pipelines, scripts.

```bash
skua snap chart.png --title "Q3 Revenue"
skua snap data.csv --title "Sales Data" --public --tags "finance,q3"
skua snap plot.json --title "Interactive Chart"
cat report.txt | skua snap - --type text --title "Analysis"
```

Use `--json` for machine-readable output:

```bash
skua snap chart.png --title "Chart" --json
# {"url": "https://skua.dev/s/abc123", "id": "abc123", "visibility": "public"}
```

## Supported Types

Skua auto-detects the object type and picks the right serializer:

- **Matplotlib figures** — high-DPI PNG
- **Plotly figures** — fully interactive (zoom, pan, hover, export)
- **Pandas DataFrames** — sortable, filterable tables
- **Polars DataFrames** — same interactive tables (LazyFrames collected automatically)
- **NumPy arrays** — rendered as tables
- **PIL Images** — saved as PNG
- **Lists of dicts** — rendered as tables (handy for HuggingFace pipelines, eval loops)
- **PyTorch / TensorFlow tensors** — image tensors as PNG, others as tables
- **Anything else** — falls back to string representation

## API

### `skua.snap(obj, title, description=None, public=None, tags=None)`

Capture and share a Python object. Returns a `SnapResult` with `.url` and `.metadata`.
In Jupyter, the original object is displayed inline.

- `tags` — optional list of strings for categorization (max 20 tags, 50 chars each). Displayed on the snapshot page and profile listing.

### `skua.configure(public=None, api_url=None, web_url=None, token=None)`

Set session-wide defaults. Call once at the top of a notebook — per-call arguments override.

### `skua.login()`

Open the browser to verify your email. Verified accounts get 90-day retention (vs 7 days), 50 snapshots (vs 10), and a public profile page at `skua.dev/u/username`.

### `skua.auth("sk_...")`

Paste the token you receive by email after `skua.login()`.

## Limits

Anonymous sessions work out of the box:

- 7-day retention, 10 snapshots, 20 uploads/hour, 10 MB per snapshot

Verify your email to unlock:

- 90-day retention (resets on update, 1-year max), 50 snapshots, 10 MB per snapshot

## Privacy

Every snapshot is accessible to anyone who has its URL. URLs contain random IDs that are not guessable or listed anywhere, but there is no login-gated access control. The `public` flag only controls whether a snapshot appears on your profile page — it does not restrict access to the URL itself. Do not snap sensitive data.

## Documentation

Full docs, live examples, and the API reference at [skua.dev/docs](https://skua.dev/docs).

## License

MIT

## Support

Questions or feedback? Email **hello@skua.dev** or open an issue on [GitHub](https://github.com/franklinstlabs/skua).
