tinygenkey 0.5.1
A tiny, secure key generator.
License: MIT
Requires Python: >=3.10
Keywords: key, generator, security, token

[![On PyPI](https://img.shields.io/pypi/v/tinygenkey.svg)](https://pypi.org/project/tinygenkey/)
![Downloads](https://pepy.tech/badge/tinygenkey)
![Python Version](https://img.shields.io/pypi/pyversions/tinygenkey.svg)
![License](https://img.shields.io/pypi/l/tinygenkey.svg)

# TinyGenKey

Cryptographically secure key generation in Python. Tiny, simple, and dependency-free.

## Installation

```bash
pip install tinygenkey
```

## Quick Start

```python
import tinygenkey as tgk

# Generate a key (default: 42 alphanumeric chars)
key = tgk.BaseKey.gen()

# With options
api_key = tgk.BaseKey.gen(
    length=32,
    prefix="api_",
    preset="hex"
)
```

## Beginner Usage

### Functional API

```python
# Simple generation
key = tgk.BaseKey.gen(length=16)

# With prefix/suffix
token = tgk.BaseKey.gen(
    length=24,
    prefix="tok_",
    suffix="_v1"
)

# Custom alphabet
pin = tgk.BaseKey.gen(
    length=6,
    alphabet=list("0123456789")
)

# Using presets
hex_key = tgk.BaseKey.gen(length=32, preset="hex")
safe_key = tgk.BaseKey.gen(length=20, preset="safe")  # URL-safe
```

### Object-Oriented API

```python
# Single key
key = tgk.Key.create(length=32, preset="hex")
print(key.value)  # Access the key
print(key)        # Same as key.value

# Multiple keys
keys = tgk.Keys.create(count=5, length=16, prefix="user_")
print(keys.values)  # List of keys
print(keys)         # Newline-separated output
```

## Advanced Usage

### Formatting Keys

```python
# Format for readability
key = tgk.BaseKey.gen(length=16)
formatted = tgk.BaseKey.format(key, group_size=4, sep="-")
# Output: "a3f7-9d2e-4b1c-8f6a"

# Auto-format on generation
key = tgk.BaseKey.gen(
    length=16,
    auto_format=True,
    group_size=4,
    sep="-"
)

# Format with Key class
key = tgk.Key.create(length=20)
key.format(group_size=5, sep=".")
print(key.value)  # "ab3f9.d2e4b.1c8f6.a9e2d"
```

### Verification

```python
# Verify a single key
report = tgk.BaseKey.verify(
    "api_a3f79d2e4b1c_key",
    preset="hex",
    min_length=10,
    max_length=20,
    prefix="api_",
    suffix="_key"
)

if report["valid"]:
    print("Valid!")
else:
    print(f"Invalid: {report['reasons']}")
    print(f"Hints: {report['hints']}")

# Using Key class
key = tgk.Key("api_abc123_key")
if key.is_valid(preset="hex", prefix="api_", suffix="_key"):
    print("Valid!")

# Verify multiple keys
keys = tgk.Keys(["key1", "key2", "key3"])
reports = keys.verify(preset="alphanumeric", min_length=4)
validity = keys.is_valid(preset="hex")  # [True, False, True]
```

### Nested/Hierarchical Keys

```python
# Complex structured keys
session_id = tgk.BaseKey.gen(
    prefix=f"sess_{tgk.BaseKey.gen(length=8, preset='hex')}_",
    length=32,
    suffix=f"_{tgk.BaseKey.gen(length=4, preset='numbers')}"
)
# Result: sess_a3f79d2e_<32 chars>_4182
```

### Available Presets

```python
# Common presets
"alphanumeric"  # a-z, A-Z, 0-9 (default)
"hex"           # 0-9, a-f
"base64"        # Base64 character set
"safe"          # URL-safe: a-z, A-Z, 0-9, -, _
"lowercase"     # a-z
"uppercase"     # A-Z
"numbers"       # 0-9
"password"      # Letters, numbers, symbols

# Specialty presets
"binary"        # 0, 1
"octal"         # 0-7
"dna"           # A, T, G, C
"emoji"         # Common emoji set
"morse"         # Dots, dashes, spaces

# Access preset character sets
tgk.PRESETS["hex"]  # ['0','1',...,'f']
tgk.HEX_LIST        # Same as above
```

## API Reference

### Classes

**`BaseKey`** - Static methods for key generation
- `gen(**kwargs) -> str` - Generate a key
- `verify(key, **kwargs) -> KeyVerifyReport` - Verify a key
- `format(key, group_size=4, sep="-") -> str` - Format with separators

**`Key`** - Single key with instance methods
- `create(**kwargs) -> Key` - Create new instance with generated key
- `value: str` - The key string
- `gen(**kwargs) -> str` - Generate new key (updates `value`)
- `format(**kwargs) -> str` - Format key (updates `value`)
- `verify(**kwargs) -> KeyVerifyReport` - Verify this key
- `is_valid(**kwargs) -> bool` - Quick validity check

**`Keys`** - Multiple keys with batch operations
- `create(count, **kwargs) -> Keys` - Create with generated keys
- `values: list[str]` - List of key strings
- `gen(count, **kwargs) -> list[str]` - Generate new keys (updates `values`)
- `format_all(group_size=4, sep="-") -> list[str]` - Format all keys
- `verify(**kwargs) -> list[KeyVerifyReport]` - Verify all keys
- `is_valid(**kwargs) -> list[bool]` - Validity for each key

### Functions

**`keys_gen(**kwargs) -> str`** - Alias for `BaseKey.gen()`

**`gen_key(**kwargs) -> str`** - Legacy function (deprecated, use `BaseKey.gen()`)

### Parameters

**Generation:**
- `length: int = 42` - Number of random characters
- `alphabet: list[str] | None` - Custom character set
- `preset: str = "alphanumeric"` - Preset name
- `prefix: str = ""` - String before key
- `suffix: str = ""` - String after key
- `auto_format: bool = False` - Auto-format on generation
- `group_size: int = 4` - Chars per group (when formatting)
- `sep: str = "-"` - Separator between groups

**Verification:**
- `alphabet_or_preset: list[str] | str | None` - Expected charset
- `min_length: int | None` - Minimum core length
- `max_length: int | None` - Maximum core length
- `prefix: str | None` - Expected prefix
- `suffix: str | None` - Expected suffix

## Security

Uses `os.urandom()` for cryptographically secure randomness. Suitable for API keys, tokens, session IDs, and secrets.

## License

MIT License - See [GitHub](https://github.com/tyydev1/pypi-tinygenkey)