Metadata-Version: 2.4
Name: pyarcidgen
Version: 0.0.1
Summary: Générateur d'identifiants uniques à formats personnalisables.
Home-page: https://github.com/inicode/pyarc-utilities
Author: INICODE
Author-email: contact.inicode@gmail.com
License: MIT
Keywords: python,inicode,pyarcidgen,id-generator,uuid,random,identifier,unique-id
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: summary

# pyarcidgen

**Générateur d'identifiants uniques à formats personnalisables** pour Python.

`pyarcidgen` est l'équivalent Python du package Node.js `id-generator`. Il permet
de construire des identifiants à partir d'un format textuel déclaratif mélangeant
texte littéral, chaînes aléatoires, UUID et handlers personnalisés.

Conçu et maintenu par **INICODE**.

---

## Table des matières

1. [Installation](#installation)
2. [Démarrage rapide](#démarrage-rapide)
3. [Syntaxe des formats](#syntaxe-des-formats)
4. [Tokens disponibles](#tokens-disponibles)
5. [Handlers intégrés](#handlers-intégrés)
6. [API de référence](#api-de-référence)
7. [Exemples](#exemples)
8. [Architecture](#architecture)

---

## Installation

```bash
pip install pyarcidgen
```

### Dépendances

`pyarcidgen` n'a **aucune dépendance externe** : il repose uniquement sur la
bibliothèque standard Python (`secrets`, `uuid`, `re`, `threading`, etc.).

### Installation en mode développeur (depuis les sources)

```bash
git clone https://github.com/inicode/pyarc-utilities.git
cd pyarc-utilities
python cmd.py --build --only pyarcidgen
pip install dist/pyarcidgen-*.whl
```

---

## Démarrage rapide

```python
from pyarcidgen import IdentifierGenerator, IdentifierGeneratorHandlers

gen = IdentifierGenerator.get_instance()

# Identifiant utilisateur avec random numérique
print(gen.generate("user-#rand{size:6,type:numeric}"))
# user-482910

# Identifiant de commande avec timestamp et random alphanumérique
print(
    IdentifierGenerator.generate_id(
        "order-#custom{timestamp}-#rand{size:8,type:alphanumeric-case}",
        {"timestamp": IdentifierGeneratorHandlers.timestamp},
    )
)
# order-1716230400000-Ax7KpL9m
```

---

## Syntaxe des formats

Un format est une chaîne de caractères composée de **texte littéral** et de
**tokens** de la forme :

```text
texte_littéral#token{options}texte_suivant
```

Un token commence par `#` suivi de son nom et, optionnellement, d'options entre
accolades `{}`.

```python
"prefix-#rand{size:8}-suffix"      # -> prefix-a3B9x2Q1-suffix
"uuid:#uuid{version:v4}"           # -> uuid:550e8400-e29b-41d4-a716-446655440000
"user-#custom{userId}"             # -> user-USR_001 (avec handler fourni)
```

---

## Tokens disponibles

### `#rand` — chaîne aléatoire

Génère une chaîne aléatoire cryptographiquement sûre via `secrets.choice`.

Options :

| Option | Type | Défaut | Description |
|--------|------|--------|-------------|
| `size` | `int` | `8` | Nombre de caractères à générer. |
| `type` | `str` | `alphanumeric` | Jeu de caractères (voir ci-dessous). |
| `variant` | `bool` | `false` | Si `true`, chaque appel génère une nouvelle valeur. |

Types de caractères :

| Type | Caractères |
|------|------------|
| `numeric` | `0123456789` |
| `alphabetic` | `abcdefghijklmnopqrstuvwxyz` |
| `alphabetic-case` | `a-zA-Z` |
| `alphanumeric` | `a-z0-9` |
| `alphanumeric-case` | `a-zA-Z0-9` |

Exemples :

```python
gen.generate("#rand{size:6,type:numeric}")          # 6 chiffres
gen.generate("#rand{size:12,type:alphanumeric-case,variant:true}")
```

> **Note de performance** : par défaut (`variant=false`), les valeurs aléatoires
> sont mises en cache pour un même triplet `(size, type, variant)`. Utilisez
> `variant:true` pour forcer la régénération à chaque appel.

### `#uuid` — UUID

Génère un UUID standard via le module `uuid`.

Options :

| Option | Type | Défaut | Description |
|--------|------|--------|-------------|
| `version` | `str` | `v4` | Version de l'UUID : `v1`, `v2`, `v3`, `v4`, `v5`. |

Exemples :

```python
gen.generate("#uuid{version:v4}")
gen.generate("#uuid{version:v1}")
gen.generate("#uuid{version:v5}")  # déterministe, mis en cache
```

> Les versions `v3` et `v5` sont déterministes et donc mises en cache. `v4` est
> toujours régénéré.

### `#custom` — handler personnalisé

Injecte une valeur produite par une fonction fournie par l'appelant.

```python
gen.generate(
    "user-#custom{userId}",
    {"userId": lambda: "USR_001"}
)
# user-USR_001
```

---

## Handlers intégrés

`IdentifierGeneratorHandlers` fournit des handlers prêts à l'emploi pour les
tokens `#custom` :

| Handler | Description | Exemple |
|---------|-------------|---------|
| `timestamp()` | Millisecondes depuis l'epoch. | `1716230400000` |
| `date()` | Date UTC au format `YYYYMMDD`. | `20240520` |
| `time()` | Heure UTC au format `HHMMSS`. | `143052` |
| `counter()` | Compteur auto-incrémenté sur 6 chiffres. | `000001`, `000002` |
| `env(name)` | Valeur d'une variable d'environnement. | `""` si absente |

```python
from pyarcidgen import IdentifierGenerator, IdentifierGeneratorHandlers

result = IdentifierGenerator.generate_id(
    "TXN-#custom{date}-#custom{time}-#rand{size:8,type:numeric}",
    {
        "date": IdentifierGeneratorHandlers.date,
        "time": IdentifierGeneratorHandlers.time,
    },
)
# TXN-20240520-143052-48291039
```

---

## API de référence

```python
from pyarcidgen import (
    IdentifierGenerator,
    IdentifierGeneratorHandlers,
    RandomOptions,
    UUIDOptions,
    Token,
    CustomHandler,
)

# Instance singleton (thread-safe)
gen = IdentifierGenerator.get_instance()

# Méthode d'instance
identifier = gen.generate("prefix-#rand{size:8}", custom_handlers={})

# Raccourci via le singleton
identifier = IdentifierGenerator.generate_id("prefix-#rand{size:8}")

# Vider le cache interne
gen.clear_cache()
```

### `IdentifierGenerator.generate(fmt, custom_handlers=None)`

| Paramètre | Type | Défaut | Description |
|-----------|------|--------|-------------|
| `fmt` | `str` | requis | Format de l'identifiant. |
| `custom_handlers` | `dict[str, Callable[[], str]]` | `None` | Handlers pour les tokens `#custom`. |

### Classes utilitaires

- `RandomOptions(size, type, variant)` — représente les options d'un token `#rand`.
- `UUIDOptions(version)` — représente les options d'un token `#uuid`.
- `Token(type, value)` — fragment analysé d'un format.

---

## Exemples

### Identifiant utilisateur

```python
from pyarcidgen import IdentifierGenerator

gen = IdentifierGenerator.get_instance()
user_id = gen.generate(
    "user-#custom{userId}-#rand{size:6,type:numeric}",
    {"userId": lambda: "USR_001"},
)
print(user_id)  # user-USR_001-482910
```

### Référence de commande

```python
from pyarcidgen import IdentifierGenerator, IdentifierGeneratorHandlers

order_id = IdentifierGenerator.generate_id(
    "ORD-#custom{date}-#rand{size:8,type:alphanumeric-case}",
    {"date": IdentifierGeneratorHandlers.date},
)
print(order_id)  # ORD-20240520-Ax7KpL9m
```

### Token aléatoire variant

```python
from pyarcidgen import IdentifierGenerator

# Deux appels = deux valeurs différentes
a = IdentifierGenerator.generate_id(
    "token-#rand{size:16,type:alphanumeric-case,variant:true}"
)
b = IdentifierGenerator.generate_id(
    "token-#rand{size:16,type:alphanumeric-case,variant:true}"
)
print(a != b)  # True
```

---

## Architecture

```text
pyarcidgen/
├── __init__.py      # API publique
├── generator.py     # IdentifierGenerator, parsing et résolution des tokens
└── handlers.py      # IdentifierGeneratorHandlers (timestamp, date, etc.)
```

---

## Auteur

Développé avec passion par **INICODE** — `contact.inicode@gmail.com`.

Licence : MIT.
