Skip to content

Id generator

ID Generator Module

This module provides various strategies for generating unique identifiers. Each generator implements the BaseIDGenerator interface and specifies the type and size of IDs it produces.

Classes:

Name Description
AsyncIDGenerator

ID generator that produces UUID version 4 strings asynchronously.
BaseIDGenerator

Abstract base class for ID generation strategies.
BigIntIDGenerator

ID generator that produces big integer IDs based on current time in nanoseconds.
DefaultIDGenerator

Default ID generator that returns empty strings.
HexIDGenerator

ID generator that produces hexadecimal strings.
IDType

Enumeration of supported ID types.
IntIDGenerator

ID generator that produces 32-bit random integers.
ShortIDGenerator

ID generator that produces short alphanumeric strings.
TimestampIDGenerator

ID generator that produces integer IDs based on current time in microseconds.
UUIDGenerator

ID generator that produces UUID version 4 strings.

Classes

AsyncIDGenerator

Bases: BaseIDGenerator

ID generator that produces UUID version 4 strings asynchronously.

UUIDs are 128-bit identifiers that are virtually guaranteed to be unique across space and time. The generated strings are 36 characters long (32 hexadecimal digits + 4 hyphens in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). This generator provides an asynchronous interface for generating UUIDs.

Methods:

Name Description
generate

Asynchronously generate a new UUID4 string.

Attributes:

Name Type Description
id_type IDType

Return the type of ID generated by this generator.
Source code in pyagenity/utils/id_generator.py 
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
class AsyncIDGenerator(BaseIDGenerator):
    """
    ID generator that produces UUID version 4 strings asynchronously.

    UUIDs are 128-bit identifiers that are virtually guaranteed to be unique
    across space and time. The generated strings are 36 characters long
    (32 hexadecimal digits + 4 hyphens in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
    This generator provides an asynchronous interface for generating UUIDs.
    """

    @property
    def id_type(self) -> IDType:
        """
        Return the type of ID generated by this generator.

        Returns:
            IDType: The type of ID (STRING).
        """
        return IDType.STRING

    async def generate(self) -> str:
        """
        Asynchronously generate a new UUID4 string.

        Returns:
            str: A 36-character UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
        """
        # Simulate async operation (e.g., if fetching from an external service)
        return str(uuid.uuid4())

Attributes

id_type property 
id_type

Return the type of ID generated by this generator.

Returns:

Name Type Description
IDType IDType

The type of ID (STRING).

Functions

generate async 
generate()

Asynchronously generate a new UUID4 string.

Returns:

Name Type Description
str str

A 36-character UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
Source code in pyagenity/utils/id_generator.py 
226
227
228
229
230
231
232
233
234
async def generate(self) -> str:
    """
    Asynchronously generate a new UUID4 string.

    Returns:
        str: A 36-character UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
    """
    # Simulate async operation (e.g., if fetching from an external service)
    return str(uuid.uuid4())

BaseIDGenerator

Bases: ABC

Abstract base class for ID generation strategies.

All ID generators must implement the id_type property and generate method.

Methods:

Name Description
generate

Generate a new unique ID.

Attributes:

Name Type Description
id_type IDType

Return the type of ID generated by this generator.
Source code in pyagenity/utils/id_generator.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class BaseIDGenerator(ABC):
    """Abstract base class for ID generation strategies.

    All ID generators must implement the id_type property and generate method.
    """

    @property
    @abstractmethod
    def id_type(self) -> IDType:
        """Return the type of ID generated by this generator.

        Returns:
            IDType: The type of ID (STRING, INTEGER, or BIGINT).
        """
        raise NotImplementedError("id_type method must be implemented")

    @abstractmethod
    def generate(self) -> str | int | Awaitable[str | int]:
        """Generate a new unique ID.

        Returns:
            str | int: A new unique identifier of the appropriate type.
        """
        raise NotImplementedError("generate method must be implemented")

Attributes

id_type abstractmethod property 
id_type

Return the type of ID generated by this generator.

Returns:

Name Type Description
IDType IDType

The type of ID (STRING, INTEGER, or BIGINT).

Functions

generate abstractmethod 
generate()

Generate a new unique ID.

Returns:

Type Description
str | int | Awaitable[str | int]

str | int: A new unique identifier of the appropriate type.
Source code in pyagenity/utils/id_generator.py 
41
42
43
44
45
46
47
48
@abstractmethod
def generate(self) -> str | int | Awaitable[str | int]:
    """Generate a new unique ID.

    Returns:
        str | int: A new unique identifier of the appropriate type.
    """
    raise NotImplementedError("generate method must be implemented")

BigIntIDGenerator

Bases: BaseIDGenerator

ID generator that produces big integer IDs based on current time in nanoseconds.

Generates IDs by multiplying current Unix timestamp by 1e9, resulting in large integers that are sortable by creation time. Typical size is 19-20 digits.

Methods:

Name Description
generate

Generate a new big integer ID based on current nanoseconds.

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class BigIntIDGenerator(BaseIDGenerator):
    """ID generator that produces big integer IDs based on current time in nanoseconds.

    Generates IDs by multiplying current Unix timestamp by 1e9, resulting in
    large integers that are sortable by creation time. Typical size is 19-20 digits.
    """

    @property
    def id_type(self) -> IDType:
        return IDType.BIGINT

    def generate(self) -> int:
        """Generate a new big integer ID based on current nanoseconds.

        Returns:
            int: A large integer (19-20 digits) representing nanoseconds since Unix epoch.
        """
        # Use current time in nanoseconds for higher uniqueness
        return int(time.time() * 1_000_000_000)

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a new big integer ID based on current nanoseconds.

Returns:

Name Type Description
int int

A large integer (19-20 digits) representing nanoseconds since Unix epoch.
Source code in pyagenity/utils/id_generator.py 
83
84
85
86
87
88
89
90
def generate(self) -> int:
    """Generate a new big integer ID based on current nanoseconds.

    Returns:
        int: A large integer (19-20 digits) representing nanoseconds since Unix epoch.
    """
    # Use current time in nanoseconds for higher uniqueness
    return int(time.time() * 1_000_000_000)

DefaultIDGenerator

Bases: BaseIDGenerator

Default ID generator that returns empty strings.

This generator is intended as a placeholder that can be configured to use framework defaults (typically UUID-based). Currently returns empty strings. If empty string is returned, the framework will use its default UUID-based generator. If the framework is not configured to use UUID generation, it will fall back to UUID4.

Methods:

Name Description
generate

Generate a default ID (currently empty string).

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
class DefaultIDGenerator(BaseIDGenerator):
    """Default ID generator that returns empty strings.

    This generator is intended as a placeholder that can be configured
    to use framework defaults (typically UUID-based). Currently returns
    empty strings. If empty string is returned, the framework will use its default
    UUID-based generator. If the framework is not configured to use
    UUID generation, it will fall back to UUID4.
    """

    @property
    def id_type(self) -> IDType:
        return IDType.STRING

    def generate(self) -> str:
        """Generate a default ID (currently empty string).

        If empty string is returned, the framework will use its default
        UUID-based generator. If the framework is not configured to use
        UUID generation, it will fall back to UUID4.

        Returns:
            str: An empty string (framework will substitute with UUID).
        """
        # if you keep empty, then it will be used default
        # framework default which is UUID based
        # if framework not using then uuid 4 will be used
        return ""

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a default ID (currently empty string).

If empty string is returned, the framework will use its default UUID-based generator. If the framework is not configured to use UUID generation, it will fall back to UUID4.

Returns:

Name Type Description
str str

An empty string (framework will substitute with UUID).
Source code in pyagenity/utils/id_generator.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def generate(self) -> str:
    """Generate a default ID (currently empty string).

    If empty string is returned, the framework will use its default
    UUID-based generator. If the framework is not configured to use
    UUID generation, it will fall back to UUID4.

    Returns:
        str: An empty string (framework will substitute with UUID).
    """
    # if you keep empty, then it will be used default
    # framework default which is UUID based
    # if framework not using then uuid 4 will be used
    return ""

HexIDGenerator

Bases: BaseIDGenerator

ID generator that produces hexadecimal strings.

Generates cryptographically secure random hex strings of 32 characters (representing 16 random bytes). Each character is a hexadecimal digit (0-9, a-f).

Methods:

Name Description
generate

Generate a new 32-character hexadecimal string.

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
class HexIDGenerator(BaseIDGenerator):
    """ID generator that produces hexadecimal strings.

    Generates cryptographically secure random hex strings of 32 characters
    (representing 16 random bytes). Each character is a hexadecimal digit (0-9, a-f).
    """

    @property
    def id_type(self) -> IDType:
        return IDType.STRING

    def generate(self) -> str:
        """Generate a new 32-character hexadecimal string.

        Returns:
            str: A 32-character hex string (e.g., '1a2b3c4d5e6f7890abcdef1234567890').
        """
        return secrets.token_hex(16)

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a new 32-character hexadecimal string.

Returns:

Name Type Description
str str

A 32-character hex string (e.g., '1a2b3c4d5e6f7890abcdef1234567890').
Source code in pyagenity/utils/id_generator.py 
154
155
156
157
158
159
160
def generate(self) -> str:
    """Generate a new 32-character hexadecimal string.

    Returns:
        str: A 32-character hex string (e.g., '1a2b3c4d5e6f7890abcdef1234567890').
    """
    return secrets.token_hex(16)

IDType

Bases: StrEnum

Enumeration of supported ID types.

Attributes:

Name Type Description
BIGINT
INTEGER
STRING
Source code in pyagenity/utils/id_generator.py 
17
18
19
20
21
22
class IDType(enum.StrEnum):
    """Enumeration of supported ID types."""

    STRING = "string"  # String-based IDs
    INTEGER = "integer"  # Integer-based IDs
    BIGINT = "bigint"  # Big integer IDs

Attributes

BIGINT class-attribute instance-attribute 
BIGINT = 'bigint'
INTEGER class-attribute instance-attribute 
INTEGER = 'integer'
STRING class-attribute instance-attribute 
STRING = 'string'

IntIDGenerator

Bases: BaseIDGenerator

ID generator that produces 32-bit random integers.

Generates cryptographically secure random integers using secrets.randbits(32). Values range from 0 to 2^32 - 1 (4,294,967,295).

Methods:

Name Description
generate

Generate a new 32-bit random integer.

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
class IntIDGenerator(BaseIDGenerator):
    """ID generator that produces 32-bit random integers.

    Generates cryptographically secure random integers using secrets.randbits(32).
    Values range from 0 to 2^32 - 1 (4,294,967,295).
    """

    @property
    def id_type(self) -> IDType:
        return IDType.INTEGER

    def generate(self) -> int:
        """Generate a new 32-bit random integer.

        Returns:
            int: A random integer between 0 and 4,294,967,295 (inclusive).
        """
        return secrets.randbits(32)

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a new 32-bit random integer.

Returns:

Name Type Description
int int

A random integer between 0 and 4,294,967,295 (inclusive).
Source code in pyagenity/utils/id_generator.py 
134
135
136
137
138
139
140
def generate(self) -> int:
    """Generate a new 32-bit random integer.

    Returns:
        int: A random integer between 0 and 4,294,967,295 (inclusive).
    """
    return secrets.randbits(32)

ShortIDGenerator

Bases: BaseIDGenerator

ID generator that produces short alphanumeric strings.

Generates 8-character strings using uppercase/lowercase letters and digits. Each character is randomly chosen from 62 possible characters (26 + 26 + 10). Total possible combinations: 62^8 ≈ 2.18 x 10^14.

Methods:

Name Description
generate

Generate a new 8-character alphanumeric string.

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
class ShortIDGenerator(BaseIDGenerator):
    """ID generator that produces short alphanumeric strings.

    Generates 8-character strings using uppercase/lowercase letters and digits.
    Each character is randomly chosen from 62 possible characters (26 + 26 + 10).
    Total possible combinations: 62^8 ≈ 2.18 x 10^14.
    """

    @property
    def id_type(self) -> IDType:
        return IDType.STRING

    def generate(self) -> str:
        """Generate a new 8-character alphanumeric string.

        Returns:
            str: An 8-character string containing letters and digits
                 (e.g., 'Ab3XyZ9k').
        """
        alphabet = string.ascii_letters + string.digits
        return "".join(secrets.choice(alphabet) for _ in range(8))

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a new 8-character alphanumeric string.

Returns:

Name Type Description
str str

An 8-character string containing letters and digits (e.g., 'Ab3XyZ9k').
Source code in pyagenity/utils/id_generator.py 
195
196
197
198
199
200
201
202
203
def generate(self) -> str:
    """Generate a new 8-character alphanumeric string.

    Returns:
        str: An 8-character string containing letters and digits
             (e.g., 'Ab3XyZ9k').
    """
    alphabet = string.ascii_letters + string.digits
    return "".join(secrets.choice(alphabet) for _ in range(8))

TimestampIDGenerator

Bases: BaseIDGenerator

ID generator that produces integer IDs based on current time in microseconds.

Generates IDs by multiplying current Unix timestamp by 1e6, resulting in integers that are sortable by creation time. Typical size is 16-17 digits.

Methods:

Name Description
generate

Generate a new integer ID based on current microseconds.

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
class TimestampIDGenerator(BaseIDGenerator):
    """ID generator that produces integer IDs based on current time in microseconds.

    Generates IDs by multiplying current Unix timestamp by 1e6, resulting in
    integers that are sortable by creation time. Typical size is 16-17 digits.
    """

    @property
    def id_type(self) -> IDType:
        return IDType.INTEGER

    def generate(self) -> int:
        """Generate a new integer ID based on current microseconds.

        Returns:
            int: An integer (16-17 digits) representing microseconds since Unix epoch.
        """
        return int(time.time() * 1000000)

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a new integer ID based on current microseconds.

Returns:

Name Type Description
int int

An integer (16-17 digits) representing microseconds since Unix epoch.
Source code in pyagenity/utils/id_generator.py 
174
175
176
177
178
179
180
def generate(self) -> int:
    """Generate a new integer ID based on current microseconds.

    Returns:
        int: An integer (16-17 digits) representing microseconds since Unix epoch.
    """
    return int(time.time() * 1000000)

UUIDGenerator

Bases: BaseIDGenerator

ID generator that produces UUID version 4 strings.

UUIDs are 128-bit identifiers that are virtually guaranteed to be unique across space and time. The generated strings are 36 characters long (32 hexadecimal digits + 4 hyphens in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Methods:

Name Description
generate

Generate a new UUID4 string.

Attributes:

Name Type Description
id_type IDType
Source code in pyagenity/utils/id_generator.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
class UUIDGenerator(BaseIDGenerator):
    """ID generator that produces UUID version 4 strings.

    UUIDs are 128-bit identifiers that are virtually guaranteed to be unique
    across space and time. The generated strings are 36 characters long
    (32 hexadecimal digits + 4 hyphens in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
    """

    @property
    def id_type(self) -> IDType:
        return IDType.STRING

    def generate(self) -> str:
        """Generate a new UUID4 string.

        Returns:
            str: A 36-character UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
        """
        return str(uuid.uuid4())

Attributes

id_type property 
id_type

Functions

generate 
generate()

Generate a new UUID4 string.

Returns:

Name Type Description
str str

A 36-character UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
Source code in pyagenity/utils/id_generator.py 
63
64
65
66
67
68
69
def generate(self) -> str:
    """Generate a new UUID4 string.

    Returns:
        str: A 36-character UUID string (e.g., '550e8400-e29b-41d4-a716-446655440000').
    """
    return str(uuid.uuid4())