Metadata-Version: 2.4
Name: inkling-loader
Version: 0.2.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Summary: Reveal ASCII art as a progress indicator.
Keywords: progress,ascii,terminal,loader,tqdm
Author: Cody Taylor
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/codizzler/inkling
Project-URL: Repository, https://github.com/codizzler/inkling

# inkling (Python)

Reveal ASCII art as a progress indicator, from Python. Same engine as the Rust crate,
exposed as a tiny extension built with [PyO3](https://pyo3.rs). It installs as
`inkling-loader` and imports as `inkling`.

![Inkling revealing ASCII art in rainbow as a task runs](https://raw.githubusercontent.com/codizzler/inkling/main/docs/demo-hero.gif)

```sh
pip install inkling-loader
```

Determinate, like `tqdm` but the bar is a drawing:

```python
from inkling import Loader

with Loader(total=len(items), rainbow=True) as bar:
    for it in items:
        work(it)
        bar.inc()
```

A download, setting the position as bytes arrive:

```python
bar = Loader(total=content_length, art_path="dragon.txt")
for chunk in response:
    file.write(chunk)
    bar.inc(len(chunk))
bar.finish()
```

Log while the reveal is live. `println` puts a line above the art and redraws beneath it,
so nothing lands in the middle of the drawing:

```python
with Loader(total=len(files), geodesic=True) as bar:
    for path in files:
        if check(path):
            bar.println(f"ok {path}")
        bar.inc()
```

The package ships `py.typed` and full type stubs, so editors and type checkers see the
whole surface rather than an opaque native module.

| Method | Effect |
| --- | --- |
| `inc(delta=1)` | advance the position |
| `set(pos)` | set the absolute position |
| `set_length(total)` | change the total |
| `set_message(text)` | caption beneath the art |
| `println(line)` | print a line above the live reveal |
| `finish()` / `finish_and_clear()` | finish, keeping or erasing the art |

| Property | Value |
| --- | --- |
| `position`, `length` | current and total units of work |
| `elapsed` | seconds since the loader started |
| `rate` | average units per second |
| `eta` | estimated seconds remaining, or `None` |

Constructor keywords: `total`, `art`, `art_path`, `ordering` (`"auto"`, `"geodesic"`,
`"scanline"`, `"reading"`, `"ltr"`, `"rtl"`), the shorthands `rainbow`, `geodesic` and
`reading`, plus `light`, `color`, `head`, `body`, `feather`, `easing`, `start`, `bridge`,
and `message`.

## The inkling family

This is the Python package. The same engine ships five ways:

- **`inkling-loader` on PyPI** (this package), for Python. `pip install inkling-loader`, import as `inkling`.
- **`inkling-loader`** on crates.io, the Rust library. `cargo add inkling-loader`.
- **`inkling-cli`**, the `inkling` command, to drive a reveal from any language through a pipe.
  `cargo install inkling-cli`.
- **`inkling-loader` on npm**, the Node addon. `npm install inkling-loader`.
- **`inkling-wasm` on npm**, the WebAssembly build for the browser.

## Building from source

```sh
pip install maturin
maturin develop            # build and install into the current venv
maturin build --release    # produce a wheel in target/wheels
```

Built from the [inkling](https://github.com/codizzler/inkling) Rust core. License: MIT.

