Metadata-Version: 2.4
Name: vcti-short-uid
Version: 2.0.0
Summary: VCollab Short UID - short, URL-safe unique identifier generator
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-short-uid
Project-URL: Changelog, https://github.com/vcollab/vcti-python-short-uid/blob/main/CHANGELOG.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Provides-Extra: dev
Requires-Dist: vcti-short-uid[lint,test,typecheck]; extra == "dev"
Dynamic: license-file

# Short UID Generator

Short, URL-safe unique identifier generator.

## Overview

VCollab applications frequently need short, unique identifiers for
temporary file names, directory names, session IDs, or other scenarios
where brief, collision-resistant strings are needed.

The `vcti-short-uid` package provides `ShortUID` — a generator that
produces a random identifier of an exact length from the URL-safe base64
alphabet `[A-Za-z0-9_-]`, backed by `secrets.token_urlsafe`.

This package has **zero external dependencies**.

## When to use it

`ShortUID` gives you a short, URL-safe identifier of an exact length in a
single call — handy for temporary file and directory names, cache keys,
or session tags. It is **not** a secrets generator: outputs are short and,
at small lengths, guessable. For unguessable tokens use
`secrets.token_urlsafe()` directly, and for a standard 128-bit identifier
use `uuid.uuid4()`. See the
[full comparison](docs/design.md#alternatives-and-when-to-use-them).

---

## Installation

```bash
pip install vcti-short-uid
```

### In `requirements.txt`

```
vcti-short-uid>=2.0.0
```

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-short-uid>=2.0.0",
]
```

---

## Quick Start

```python
from vcti.shortuid import ShortUID

# One-shot generation (no instance needed)
uid = ShortUID.quick()               # e.g. "a3Bx9kLm"

# Custom length
long_uid = ShortUID.quick(length=16) # 16-char ID

# Reusable generator
gen = ShortUID(length=8)
uid1 = gen.generate()
uid2 = gen.generate()
```

---

## Public API

### `ShortUID(length=8)`

Create a generator instance.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `length` | `int` | `8` | Exact number of characters in generated IDs (minimum 1, no upper cap) |

**Raises:**
- `TypeError` -- if `length` is not an integer.
- `ValueError` -- if `length` is less than 1.

### `ShortUID.generate() -> str`

Generate a short, URL-safe identifier of exactly `length` characters,
drawn from `[A-Za-z0-9_-]`.

### `ShortUID.quick(length=8) -> str`  *(classmethod)*

Convenience one-liner -- creates a temporary instance and generates one ID.

### `repr(ShortUID(...))`

Returns a string like `ShortUID(length=8)` for debugging.

---

## Dependencies

None. Standard library only (`math`, `secrets`).

---

## Documentation

| If you want to… | Read |
|---|---|
| Get started using the package | Quick Start above |
| Understand the architecture and design decisions | [docs/design.md](docs/design.md) |
| Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
| Look up a specific function or type | [docs/api.md](docs/api.md) |
| See the release history | [CHANGELOG.md](CHANGELOG.md) |
