0
# Nanoid
1

2
A tiny, secure, URL-friendly, unique string ID generator for Python. Nanoid uses cryptographically strong random APIs and generates compact IDs with a larger alphabet than UUID, reducing ID size from 36 to 21 characters while maintaining collision probability similar to UUID v4.
3

4
## Package Information
5

6
- **Package Name**: nanoid
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install nanoid`
10

11
## Core Imports
12

13
```python
14
from nanoid import generate, non_secure_generate
15
```
16

17
## Basic Usage
18

19
```python
20
from nanoid import generate
21

22
# Generate a secure 21-character ID with default alphabet
23
id = generate()  # => "NDzkGoTCdRcaRyt7GOepg"
24

25
# Generate shorter ID (higher collision probability)
26
id = generate(size=10)  # => "IRFa-VaY2b"
27

28
# Generate ID with custom alphabet (positional arguments)
29
id = generate('1234567890abcdef', 10)  # => "4f9zd13a42"
30

31
# Generate ID with custom alphabet (keyword arguments)
32
id = generate(alphabet='1234567890abcdef', size=10)  # => "4f9zd13a42"
33
```
34

35
For non-secure, fast generation:
36

37
```python
38
from nanoid import non_secure_generate
39

40
# Fast, non-cryptographic generation
41
id = non_secure_generate()
42
id = non_secure_generate('1234567890abcdef', 10)  # positional
43
id = non_secure_generate(alphabet='1234567890abcdef', size=10)  # keyword
44
```
45

46
## Capabilities
47

48
### Secure ID Generation
49

50
Generate cryptographically secure, URL-friendly unique string IDs using strong random APIs with customizable alphabet and length.
51

52
```python { .api }
53
def generate(alphabet=alphabet, size=size):
54
    """
55
    Generate a cryptographically secure unique string ID.
56
    
57
    Parameters:
58
    - alphabet (str, optional): Custom alphabet for ID generation.
59
      Defaults to URL-friendly 64-character alphabet from nanoid.resources.
60
    - size (int, optional): Length of generated ID. Defaults to 21.
61
    
62
    Returns:
63
    str: Generated unique ID string
64
    
65
    Usage:
66
    # Using defaults
67
    generate()
68
    
69
    # Positional arguments
70
    generate('0123456789abcdef', 10)
71
    
72
    # Keyword arguments  
73
    generate(alphabet='0123456789abcdef', size=10)
74
    generate(size=10)
75
    
76
    Notes:
77
    - Uses os.urandom() for cryptographically strong randomness
78
    - Default settings provide collision probability similar to UUID v4
79
    - Default alphabet excludes problematic URL characters like .(),-
80
    """
81
```
82

83
### Fast Non-Secure ID Generation
84

85
Generate IDs quickly using pseudo-random generation for non-security-critical applications where performance is prioritized over cryptographic strength.
86

87
```python { .api }
88
def non_secure_generate(alphabet=alphabet, size=size):
89
    """
90
    Generate a fast, non-secure unique string ID.
91
    
92
    Parameters:
93
    - alphabet (str, optional): Custom alphabet for ID generation.
94
      Defaults to URL-friendly 64-character alphabet from nanoid.resources.
95
    - size (int, optional): Length of generated ID. Defaults to 21.
96
    
97
    Returns:
98
    str: Generated unique ID string
99
    
100
    Usage:
101
    # Using defaults
102
    non_secure_generate()
103
    
104
    # Positional arguments
105
    non_secure_generate('0123456789abcdef', 10)
106
    
107
    # Keyword arguments  
108
    non_secure_generate(alphabet='0123456789abcdef', size=10)
109
    non_secure_generate(size=10)
110
    
111
    Notes:
112
    - Uses random.random() for fast pseudo-random generation
113
    - Not cryptographically secure - use only when security is not required
114
    - Significantly faster than secure generation for high-volume use cases
115
    """
116
```
117

118
## Constants
119

120
The package provides access to default configuration constants:
121

122
```python { .api }
123
# Default URL-friendly alphabet (64 characters)
124
alphabet = '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
125

126
# Default ID length for UUID v4-like collision probability
127
size = 21
128
```
129

130
Access constants:
131

132
```python
133
from nanoid.resources import alphabet, size
134

135
print(f"Default alphabet: {alphabet}")
136
print(f"Default size: {size}")
137
```
138

139
## Usage Examples
140

141
### Web Application IDs
142

143
```python
144
from nanoid import generate
145

146
# Generate user session IDs
147
session_id = generate()
148

149
# Generate short resource identifiers
150
post_id = generate(size=12)
151

152
# Generate database-safe IDs with custom alphabet
153
db_id = generate('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ', 16)
154
```
155

156
### Custom Alphabets for Specific Use Cases
157

158
```python
159
from nanoid import generate
160

161
# Numeric-only IDs
162
numeric_id = generate('0123456789', 10)
163

164
# Lowercase alphanumeric
165
lower_id = generate('0123456789abcdefghijklmnopqrstuvwxyz', 15)
166

167
# Base64-like alphabet
168
base64_id = generate('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/', 22)
169
```
170

171
### Performance Considerations
172

173
```python
174
from nanoid import generate, non_secure_generate
175

176
# For security-critical applications (recommended)
177
secure_token = generate()
178

179
# For high-volume, non-security-critical use (faster)
180
temp_id = non_secure_generate()
181

182
# Batch generation example
183
secure_ids = [generate(size=10) for _ in range(1000)]
184
fast_ids = [non_secure_generate(size=10) for _ in range(10000)]
185
```
186

187
## Security Features
188

189
- **Cryptographically Secure**: Uses `os.urandom()` for strong randomness in `generate()`
190
- **URL-Safe**: Default alphabet excludes characters that require URL encoding
191
- **Collision Resistant**: Default 21-character length provides ~2^126 possible combinations
192
- **Distribution Testing**: Library includes tests to verify symbol distribution uniformity
193

194
## Collision Probability
195

196
The default configuration (21 characters, 64-symbol alphabet) provides collision probability similar to UUID v4:
197

198
- **~1% probability** after generating ~7×10^15 IDs
199
- **Use size calculator** at https://zelark.github.io/nano-id-cc/ to determine appropriate ID length for your use case
200

201
## Error Handling
202

203
Both functions are designed to be robust:
204

205
- **Invalid alphabet**: Empty string or None will cause errors
206
- **Invalid size**: Negative or zero size will cause errors  
207
- **Large sizes**: Memory usage scales linearly with size parameter