0
# UA Parser
1

2
A Python port of Browserscope's user agent parser that extracts detailed information about browsers, operating systems, and devices from user agent strings. The library provides comprehensive parsing capabilities with built-in caching for high-performance scenarios and supports a wide range of user agents including desktop browsers, mobile devices, bots, and other web clients.
3

4
## Package Information
5

6
- **Package Name**: ua-parser
7
- **Language**: Python
8
- **Installation**: `pip install ua-parser`
9

10
## Core Imports
11

12
```python
13
from ua_parser import user_agent_parser
14
from ua_parser import VERSION
15
```
16

17
Direct function imports:
18

19
```python
20
from ua_parser.user_agent_parser import Parse, ParseUserAgent, ParseOS, ParseDevice
21
```
22

23
## Basic Usage
24

25
```python
26
from ua_parser import user_agent_parser
27

28
# Example user agent string
29
ua_string = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.104 Safari/537.36'
30

31
# Parse all components (browser, OS, device)
32
result = user_agent_parser.Parse(ua_string)
33
print(result)
34
# {
35
#   'user_agent': {'family': 'Chrome', 'major': '41', 'minor': '0', 'patch': '2272'},
36
#   'os': {'family': 'Mac OS X', 'major': '10', 'minor': '9', 'patch': '4', 'patch_minor': None},
37
#   'device': {'family': 'Mac', 'brand': 'Apple', 'model': 'Mac'},
38
#   'string': 'Mozilla/5.0...'
39
# }
40

41
# Parse only browser information
42
browser = user_agent_parser.ParseUserAgent(ua_string)
43
print(browser)
44
# {'family': 'Chrome', 'major': '41', 'minor': '0', 'patch': '2272'}
45

46
# Parse only OS information  
47
os_info = user_agent_parser.ParseOS(ua_string)
48
print(os_info)
49
# {'family': 'Mac OS X', 'major': '10', 'minor': '9', 'patch': '4', 'patch_minor': None}
50

51
# Parse only device information
52
device = user_agent_parser.ParseDevice(ua_string)
53
print(device)
54
# {'family': 'Mac', 'brand': 'Apple', 'model': 'Mac'}
55
```
56

57
## Capabilities
58

59
### Complete User Agent Parsing
60

61
Parses the complete user agent string to extract browser, operating system, and device information in a single operation.
62

63
```python { .api }
64
def Parse(user_agent_string, **jsParseBits):
65
    """
66
    Parse all components of a user agent string.
67
    
68
    Args:
69
        user_agent_string (str): The full user-agent string
70
        **jsParseBits: Deprecated JavaScript override parameters (deprecated)
71
    
72
    Returns:
73
        dict: Dictionary with keys 'user_agent', 'os', 'device', 'string'
74
            - user_agent: Browser information with 'family', 'major', 'minor', 'patch'
75
            - os: OS information with 'family', 'major', 'minor', 'patch', 'patch_minor'  
76
            - device: Device information with 'family', 'brand', 'model'
77
            - string: Original user agent string (added by caching mechanism)
78
    """
79
```
80

81
### Browser/User Agent Parsing
82

83
Extracts browser and user agent information including family name, major version, minor version, and patch version.
84

85
```python { .api }
86
def ParseUserAgent(user_agent_string, **jsParseBits):
87
    """
88
    Parse user agent string for browser information only.
89
    
90
    Args:
91
        user_agent_string (str): The full user-agent string
92
        **jsParseBits: Deprecated JavaScript override parameters (deprecated)
93
    
94
    Returns:
95
        dict: Browser information with keys:
96
            - family (str): Browser family name (e.g., 'Chrome', 'Firefox'), defaults to 'Other'
97
            - major (str|None): Major version number
98
            - minor (str|None): Minor version number  
99
            - patch (str|None): Patch version number
100
    """
101
```
102

103
### Operating System Parsing
104

105
Extracts operating system information including OS family, major version, minor version, patch version, and patch minor version.
106

107
```python { .api }
108
def ParseOS(user_agent_string, **jsParseBits):
109
    """
110
    Parse user agent string for operating system information only.
111
    
112
    Args:
113
        user_agent_string (str): The full user-agent string
114
        **jsParseBits: Deprecated JavaScript override parameters (deprecated)
115
    
116
    Returns:
117
        dict: OS information with keys:
118
            - family (str): OS family name (e.g., 'Mac OS X', 'Windows'), defaults to 'Other'
119
            - major (str|None): Major version number
120
            - minor (str|None): Minor version number
121
            - patch (str|None): Patch version number  
122
            - patch_minor (str|None): Patch minor version number
123
    """
124
```
125

126
### Device Parsing
127

128
Extracts device information including device family, brand, and model.
129

130
```python { .api }
131
def ParseDevice(user_agent_string, **jsParseBits):
132
    """
133
    Parse user agent string for device information only.
134
    
135
    Args:
136
        user_agent_string (str): The full user-agent string
137
        **jsParseBits: Deprecated JavaScript override parameters (deprecated)
138
    
139
    Returns:
140
        dict: Device information with keys:
141
            - family (str): Device family name (e.g., 'iPhone', 'Mac'), defaults to 'Other'
142
            - brand (str|None): Device brand (e.g., 'Apple', 'Samsung')
143
            - model (str|None): Device model (e.g., 'iPhone', 'Galaxy S4')
144
    """
145
```
146

147
### Pretty Formatting
148

149
Formats parsed user agent and OS information into human-readable strings.
150

151
```python { .api }
152
def PrettyUserAgent(family, v1=None, v2=None, v3=None):
153
    """
154
    Format user agent information into a readable string.
155
    
156
    Args:
157
        family (str): Browser family name
158
        v1 (str, optional): Major version
159
        v2 (str, optional): Minor version
160
        v3 (str, optional): Patch version
161
    
162
    Returns:
163
        str: Formatted string like 'Chrome 41.0.2272' or 'Firefox 3.5.5'
164
    """
165

166
def PrettyOS(os, os_v1=None, os_v2=None, os_v3=None, os_v4=None):
167
    """
168
    Format OS information into a readable string.
169
    
170
    Args:
171
        os (str): OS family name
172
        os_v1 (str, optional): Major version
173
        os_v2 (str, optional): Minor version
174
        os_v3 (str, optional): Patch version
175
        os_v4 (str, optional): Patch minor version
176
    
177
    Returns:
178
        str: Formatted string like 'Mac OS X 10.9.4' or 'Windows 8.1'
179
    """
180
```
181

182
### Filter Generation
183

184
Generates filter parameters for JavaScript overrides (legacy functionality).
185

186
```python { .api }
187
def GetFilters(user_agent_string, js_user_agent_string=None, js_user_agent_family=None, js_user_agent_v1=None, js_user_agent_v2=None, js_user_agent_v3=None):
188
    """
189
    Return optional arguments that should be saved and used to query.
190
    
191
    Args:
192
        user_agent_string (str): The full user-agent string
193
        js_user_agent_string (str, optional): JavaScript user agent string override
194
        js_user_agent_family (str, optional): JavaScript family override
195
        js_user_agent_v1 (str, optional): JavaScript version 1 override
196
        js_user_agent_v2 (str, optional): JavaScript version 2 override  
197
        js_user_agent_v3 (str, optional): JavaScript version 3 override
198
    
199
    Returns:
200
        dict: Dictionary of filter parameters for non-None/non-empty values
201
    """
202
```
203

204
### String Replacement Utility
205

206
Internal utility function for performing regex group substitutions in replacement strings used by parser classes.
207

208
```python { .api }
209
def MultiReplace(string, match):
210
    """
211
    Perform regex group substitutions in a replacement string.
212
    
213
    Args:
214
        string (str): String containing $1, $2, etc. placeholders
215
        match (re.Match): Regex match object with captured groups
216
    
217
    Returns:
218
        str|None: String with substitutions applied, or None if result is empty
219
    """
220
```
221

222
### Deprecated Functions
223

224
These functions are deprecated but still available for backwards compatibility.
225

226
```python { .api }
227
def ParseWithJSOverrides(user_agent_string, js_user_agent_string=None, js_user_agent_family=None, js_user_agent_v1=None, js_user_agent_v2=None, js_user_agent_v3=None):
228
    """
229
    Parse user agent with JavaScript overrides (deprecated).
230
    
231
    Args:
232
        user_agent_string (str): The full user-agent string
233
        js_user_agent_string (str, optional): JavaScript user agent string override
234
        js_user_agent_family (str, optional): JavaScript family override
235
        js_user_agent_v1 (str, optional): JavaScript version 1 override
236
        js_user_agent_v2 (str, optional): JavaScript version 2 override
237
        js_user_agent_v3 (str, optional): JavaScript version 3 override
238
    
239
    Returns:
240
        tuple: (family, v1, v2, v3) version information
241
        
242
    Deprecated:
243
        Use Parse or specialized parsers instead
244
    """
245

246
def Pretty(family, v1=None, v2=None, v3=None):
247
    """
248
    Format user agent information into readable string (deprecated).
249
    
250
    Args:
251
        family (str): Browser family name
252
        v1 (str, optional): Major version
253
        v2 (str, optional): Minor version
254
        v3 (str, optional): Patch version
255
    
256
    Returns:
257
        str: Formatted string like 'Chrome 41.0.2272' or 'Firefox 3.5.5'
258
        
259
    Deprecated:
260
        Use PrettyUserAgent instead
261
    """
262
```
263

264
## Parser Classes
265

266
The library provides parser classes for advanced usage and custom regex patterns. These are primarily used internally but can be instantiated directly for custom parsing scenarios.
267

268
```python { .api }
269
class UserAgentParser:
270
    """Parser for extracting user agent (browser) information."""
271
    
272
    def __init__(self, pattern, family_replacement=None, v1_replacement=None, v2_replacement=None):
273
        """
274
        Initialize UserAgentParser.
275
        
276
        Args:
277
            pattern (str): Regular expression pattern
278
            family_replacement (str, optional): Override for family name  
279
            v1_replacement (str, optional): Override for version 1
280
            v2_replacement (str, optional): Override for version 2
281
        """
282
    
283
    def Parse(self, user_agent_string):
284
        """
285
        Parse user agent string and return version information.
286
        
287
        Args:
288
            user_agent_string (str): User agent string to parse
289
            
290
        Returns:
291
            tuple: (family, v1, v2, v3) version information
292
        """
293
    
294
    def MatchSpans(self, user_agent_string):
295
        """
296
        Get match span positions for regex groups.
297
        
298
        Args:
299
            user_agent_string (str): User agent string to parse
300
            
301
        Returns:
302
            list: List of (start, end) tuples for each regex group
303
        """
304

305
class OSParser:
306
    """Parser for extracting operating system information."""
307
    
308
    def __init__(self, pattern, os_replacement=None, os_v1_replacement=None, os_v2_replacement=None, os_v3_replacement=None, os_v4_replacement=None):
309
        """
310
        Initialize OSParser.
311
        
312
        Args:
313
            pattern (str): Regular expression pattern
314
            os_replacement (str, optional): Override for OS name
315
            os_v1_replacement (str, optional): Override for OS version 1
316
            os_v2_replacement (str, optional): Override for OS version 2
317
            os_v3_replacement (str, optional): Override for OS version 3
318
            os_v4_replacement (str, optional): Override for OS version 4
319
        """
320
    
321
    def Parse(self, user_agent_string):
322
        """
323
        Parse user agent string and return OS information.
324
        
325
        Args:
326
            user_agent_string (str): User agent string to parse
327
            
328
        Returns:
329
            tuple: (os, os_v1, os_v2, os_v3, os_v4) OS information
330
        """
331
    
332
    def MatchSpans(self, user_agent_string):
333
        """
334
        Get match span positions for regex groups.
335
        
336
        Args:
337
            user_agent_string (str): User agent string to parse
338
            
339
        Returns:
340
            list: List of (start, end) tuples for each regex group
341
        """
342

343
class DeviceParser:
344
    """Parser for extracting device information."""
345
    
346
    def __init__(self, pattern, regex_flag=None, device_replacement=None, brand_replacement=None, model_replacement=None):
347
        """
348
        Initialize DeviceParser.
349
        
350
        Args:
351
            pattern (str): Regular expression pattern
352
            regex_flag (str, optional): Regex flags ('i' for case insensitive)
353
            device_replacement (str, optional): Override for device family
354
            brand_replacement (str, optional): Override for device brand
355
            model_replacement (str, optional): Override for device model
356
        """
357
    
358
    def Parse(self, user_agent_string):
359
        """
360
        Parse user agent string and return device information.
361
        
362
        Args:
363
            user_agent_string (str): User agent string to parse
364
            
365
        Returns:
366
            tuple: (device, brand, model) device information
367
        """
368
    
369
    def MatchSpans(self, user_agent_string):
370
        """
371
        Get match span positions for regex groups.
372
        
373
        Args:
374
            user_agent_string (str): User agent string to parse
375
            
376
        Returns:
377
            list: List of (start, end) tuples for each regex group
378
        """
379
```
380

381
## Constants
382

383
```python { .api }
384
VERSION: tuple
385
"""Version tuple from ua_parser package (from ua_parser.VERSION)."""
386

387
MAX_CACHE_SIZE = 200
388
"""Maximum size of internal parsing cache before it gets cleared."""
389

390
USER_AGENT_PARSERS: list
391
"""List of UserAgentParser instances used for parsing browser information."""
392

393
OS_PARSERS: list  
394
"""List of OSParser instances used for parsing operating system information."""
395

396
DEVICE_PARSERS: list
397
"""List of DeviceParser instances used for parsing device information."""
398
```
399

400
## Error Handling
401

402
The parser functions validate input types and raise appropriate exceptions:
403

404
- `TypeError`: Raised when user_agent_string is not a string type
405
- Functions return default values for unrecognized user agents:
406
  - Browser family defaults to "Other"
407
  - OS family defaults to "Other"  
408
  - Device family defaults to "Other"
409

410
## Performance Features
411

412
- **Built-in caching**: All main parsing functions use internal caching for repeated user agent strings
413
- **Cache management**: Cache automatically clears when it reaches MAX_CACHE_SIZE (200 entries)
414
- **High-performance regex**: Uses precompiled regular expressions from uap-core project
415
- **Efficient parsing**: Parser classes provide low-level access for custom performance optimization
416

417
## Usage Examples
418

419
### Batch Processing
420

421
```python
422
from ua_parser import user_agent_parser
423

424
user_agents = [
425
    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
426
    'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)',
427
    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36'
428
]
429

430
results = []
431
for ua in user_agents:
432
    parsed = user_agent_parser.Parse(ua)
433
    results.append({
434
        'original': ua,
435
        'browser': f"{parsed['user_agent']['family']} {parsed['user_agent']['major']}",
436
        'os': parsed['os']['family'],
437
        'device': parsed['device']['family']
438
    })
439
```
440

441
### Error Handling
442

443
```python
444
from ua_parser import user_agent_parser
445

446
def safe_parse(user_agent_string):
447
    try:
448
        if not isinstance(user_agent_string, str):
449
            raise TypeError("User agent must be a string")
450
        return user_agent_parser.Parse(user_agent_string)
451
    except TypeError as e:
452
        print(f"Invalid input: {e}")
453
        return None
454
```
455

456
### Custom Parser Usage
457

458
```python
459
from ua_parser.user_agent_parser import UserAgentParser
460

461
# Create custom parser for specific pattern
462
custom_parser = UserAgentParser(
463
    pattern=r'MyBot/(\d+)\.(\d+)',
464
    family_replacement='MyBot'
465
)
466

467
result = custom_parser.Parse('MyBot/2.1 crawler')
468
# Returns: ('MyBot', '2', '1', None)
469
```