Metadata-Version: 2.4
Name: django-universal-sequence
Version: 1.0.1
Summary: Thread-safe pseudo-random sequence generator for Django
Author: Pawan Sunar
License: MIT
Project-URL: Homepage, https://github.com/psunara/django-universal-sequence
Project-URL: Repository, https://github.com/psunara/django-universal-sequence
Project-URL: Issues, https://github.com/psunara/django-universal-sequence/issues
Keywords: django,sequence,random,thread-safe
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: License :: OSI Approved :: MIT License
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: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Dynamic: license-file

# Django Universal Sequence

A reusable Django library for generating unique, formatted, pseudo-random sequence numbers with database-level safety.

`django-universal-sequence` provides:

- Thread-safe sequence generation
- Database transaction locking
- Multiple sequence types
- User-defined sequence formats
- Mandatory sequence configuration
- Dynamic prefix and suffix support
- Year-based sequence tracking
- Django ORM integration


## Features

- ✅ Unique sequence generation
- ✅ Safe under concurrent requests
- ✅ Supports unlimited sequence types
- ✅ Custom digit length per sequence
- ✅ Custom prefix per generated number
- ✅ Custom suffix per generated number
- ✅ Dynamic date placeholders
- ✅ Works with Django ORM transactions


---

## Installation

Install from PyPI:

```bash
pip install django-universal-sequence
```

Install from source:

```bash
pip install -e .
```


---

## Django Configuration

Add the application to your Django project:

```python
INSTALLED_APPS = [
    ...
    "universal_sequence",
]
```

Run migrations:

```bash
python manage.py migrate
```


---

# Basic Usage

Import the generator:

```python
from universal_sequence.services import (
    get_next_universal_sequence
)
```

Generate a sequence:

```python
sequence_id = get_next_universal_sequence(
    sequence_type="unique_sequence",
    initial_digit_length=6,
    prefix="UNIQ",
    suffix="{year_short}",
)
```

Example output:

```
UNIQ58392026
```


---

# Parameters

All parameters are explicitly required.

| Parameter | Required | Description |
|-----------|----------|-------------|
| sequence_type | Yes | Unique identifier for the sequence category |
| initial_digit_length | Yes | Minimum generated number length |
| prefix | Yes | Text before the generated number |
| suffix | Yes | Text after the generated number |


Example:

```python
invoice_number = get_next_universal_sequence(
    sequence_type="invoice",
    initial_digit_length=10,
    prefix="INV-",
    suffix="/{year}",
)
```

Output:

```
INV-000045829371/2026
```


---

# Multiple Sequence Types

Each sequence type maintains its own counter.


## Customer Tickets

```python
ticket = get_next_universal_sequence(
    sequence_type="customer_ticket",
    initial_digit_length=8,
    prefix="TKT-",
    suffix="",
)
```

Example:

```
TKT-00048392
```


## Orders

```python
order = get_next_universal_sequence(
    sequence_type="order",
    initial_digit_length=12,
    prefix="ORD/",
    suffix="/{year}",
)
```

Example:

```
ORD/000000458293/2026
```


---

# Dynamic Prefix and Suffix

Prefix and suffix support dynamic templates.

Available variables:

| Variable | Example |
|----------|---------|
| `{year}` | 2026 |
| `{year_short}` | 26 |
| `{month}` | 07 |
| `{day}` | 28 |


Example:

```python
payment = get_next_universal_sequence(
    sequence_type="payment",
    initial_digit_length=8,
    prefix="PAY-{year_short}-",
    suffix="-{month}",
)
```

Output:

```
PAY-26-58392012-07
```


---

# How It Works

The library maintains a tracker table:

```
sequence_type
year
current_value
initial_digit_length
```

Generation flow:

```
Request
   |
   v
Lock sequence row
   |
   v
Increment counter
   |
   v
Apply scrambling algorithm
   |
   v
Validate digits
   |
   v
Return formatted identifier
```


Final format:

```
PREFIX + NUMBER + SUFFIX
```


---

# Database Safety

The library uses Django database transactions:

```python
transaction.atomic()
```

and row-level locking:

```python
select_for_update()
```

This prevents duplicate identifiers when multiple requests generate numbers at the same time.


---

# Example Model Integration

Model:

```python
class Order(models.Model):

    order_id = models.CharField(
        max_length=50,
        unique=True
    )
```


Create identifier:

```python
order.order_id = (
    get_next_universal_sequence(
        sequence_type="order_sequence",
        initial_digit_length=8,
        prefix="OD-",
        suffix="{year}",
    )
)
```

Example generated value:

```
OD-00483921-2026
```


---

# Requirements

- Python >= 3.9
- Django >= 4.2


---

# Development Setup

Clone repository:

```bash
git clone https://github.com/<your-account>/django-universal-sequence.git

cd django-universal-sequence
```

Install:

```bash
pip install -e .
```


Run tests:

```bash
pytest
```


---

# License

MIT License


---

# Contribution

Contributions are welcome.

Before submitting changes:

1. Add tests.
2. Update documentation.
3. Maintain backward compatibility.
4. Follow Django coding standards.


---

# Roadmap

Planned improvements:

- Django admin integration
- REST API support
- Async support
- Custom scrambling algorithms
- Sequence reset policies
- Database backend optimizations
