django-universal-sequence 1.0.1

Thread-safe pseudo-random sequence generator for Django

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:

pip install django-universal-sequence

Install from source:

pip install -e .

---

Django Configuration

Add the application to your Django project:

INSTALLED_APPS = [
    ...
    "universal_sequence",
]

Run migrations:

python manage.py migrate

---

Basic Usage

Import the generator:

from universal_sequence.services import (
    get_next_universal_sequence
)

Generate a sequence:

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:

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

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

Example:

TKT-00048392

Orders

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:

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:

transaction.atomic()

and row-level locking:

select_for_update()

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

---

Example Model Integration

Model:

class Order(models.Model):

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

Create identifier:

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:

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

cd django-universal-sequence

Install:

pip install -e .

Run tests:

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