tinygenkey 0.5.0

A tiny, secure key generator.

TinyGenKey

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

Installation

pip install tinygenkey

Quick Start

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

# 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

# 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

# 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

# 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

# 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

# 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