# Short UID Generator

## Purpose

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 URL-safe identifiers by hashing a combination of entropy,
salt, timestamp, and randomness. The result is truncated to a
configurable length (default: 8 characters).

This package has **zero external dependencies**.

---

## Installation

### From GitHub (recommended for development)

```bash
# Latest main branch
pip install vcti-short-uid


### From a GitHub Release

Download the wheel from the
[Releases](https://github.com/vcollab/vcti-python-short-uid/releases)
page and install directly:

```bash
pip install vcti-short-uid>=1.2.1
```

### In `requirements.txt`

```
vcti-short-uid>=1.2.1
```

### In `pyproject.toml` dependencies

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

---

## Quick Start

```python
from vcti.shortuid import ShortUID

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

# Reusable generator with entropy seed
gen = ShortUID(entropy="my-app")
uid1 = gen.generate()                     # 8-char default
uid2 = gen.generate(salt="report.pdf")    # salt adds context

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

---

## Public API

### `ShortUID(entropy=None, length=8)`

Create a generator instance.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `entropy` | `str \| None` | `None` | Optional base entropy seed |
| `length` | `int` | `8` | Number of characters in generated IDs (range: 1--43) |

**Raises:**
- `TypeError` -- if `length` is not an integer, or `entropy` is not a string/`None`.
- `ValueError` -- if `length` is outside the range `[1, 43]`.

### `ShortUID.generate(salt=None) -> str`

Generate a short, URL-safe unique identifier.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `salt` | `str \| None` | `None` | Additional context string |

**Raises:**
- `TypeError` -- if `salt` is not a string/`None`.

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

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

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

Returns a string like `ShortUID(entropy='my-app', length=8)` for debugging.

---

## Documentation

- [Design](docs/design.md) -- Concepts and trade-offs
- [Source Guide](docs/source-guide.md) -- Codebase walkthrough
- [API Reference](docs/api.md) -- Autodoc for all modules
- [Changelog](CHANGELOG.md) -- Release history
