0
# User Agents
1

2
A Python library that provides an easy way to identify devices like mobile phones, tablets and their capabilities by parsing browser user agent strings. The library reliably detects whether a user agent represents a mobile, tablet, or PC device and determines touch capabilities.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
from user_agents import parse
14
```
15

16
Alternative imports:
17

18
```python
19
import user_agents
20
# Access via module: user_agents.parse(ua_string)
21

22
# Access version information
23
from user_agents import VERSION
24
# or
25
import user_agents
26
version = user_agents.VERSION  # (2, 2, 0)
27
```
28

29
## Basic Usage
30

31
```python
32
from user_agents import parse
33

34
# Parse an iPhone user agent string
35
ua_string = 'Mozilla/5.0 (iPhone; CPU iPhone OS 5_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B179 Safari/7534.48.3'
36
user_agent = parse(ua_string)
37

38
# Access device type properties
39
print(user_agent.is_mobile)        # True
40
print(user_agent.is_tablet)        # False
41
print(user_agent.is_touch_capable) # True
42
print(user_agent.is_pc)            # False
43
print(user_agent.is_bot)           # False
44

45
# Access device, OS, and browser information
46
print(user_agent.device.family)    # 'iPhone'
47
print(user_agent.os.family)        # 'iOS'
48
print(user_agent.browser.family)   # 'Mobile Safari'
49

50
# Get formatted strings
51
print(str(user_agent))              # "iPhone / iOS 5.1 / Mobile Safari 5.1"
52
print(user_agent.get_device())      # 'iPhone'
53
print(user_agent.get_os())          # 'iOS 5.1'
54
print(user_agent.get_browser())     # 'Mobile Safari 5.1'
55
```
56

57
## Capabilities
58

59
### User Agent Parsing
60

61
Parse user agent strings to extract device, operating system, and browser information with device classification capabilities.
62

63
```python { .api }
64
def parse(user_agent_string: str) -> UserAgent:
65
    """
66
    Parse a user agent string and return a UserAgent instance.
67
    
68
    Parameters:
69
    - user_agent_string: str, the user agent string to parse
70
    
71
    Returns:
72
    UserAgent instance with parsed information
73
    """
74
```
75

76
### Device Classification
77

78
The UserAgent class provides comprehensive device type detection and information access.
79

80
```python { .api }
81
class UserAgent:
82
    """
83
    Main user agent analysis class with device detection capabilities.
84
    
85
    Attributes:
86
    - ua_string: str, original user agent string
87
    - os: OperatingSystem, operating system information
88
    - browser: Browser, browser information
89
    - device: Device, device information
90
    """
91
    
92
    def __init__(self, user_agent_string: str):
93
        """Initialize UserAgent with user agent string."""
94
    
95
    def __str__(self) -> str:
96
        """Return formatted string representation: 'Device / OS / Browser'."""
97
    
98
    def __unicode__(self) -> str:
99
        """Return Unicode string representation (Python 2 compatibility)."""
100
    
101
    def get_device(self) -> str:
102
        """Return device name or 'PC' if is_pc is True."""
103
    
104
    def get_os(self) -> str:
105
        """Return formatted OS name with version."""
106
    
107
    def get_browser(self) -> str:
108
        """Return formatted browser name with version."""
109
    
110
    @property
111
    def is_mobile(self) -> bool:
112
        """True if device is identified as a mobile phone."""
113
    
114
    @property
115
    def is_tablet(self) -> bool:
116
        """True if device is identified as a tablet."""
117
    
118
    @property
119
    def is_pc(self) -> bool:
120
        """True if device is identified as a desktop/laptop PC."""
121
    
122
    @property
123
    def is_touch_capable(self) -> bool:
124
        """True if device has touch screen capabilities."""
125
    
126
    @property
127
    def is_bot(self) -> bool:
128
        """True if user agent is a web crawler/spider."""
129
    
130
    @property
131
    def is_email_client(self) -> bool:
132
        """True if user agent is an email client."""
133
    
134
    def _is_android_tablet(self) -> bool:
135
        """
136
        Internal method to determine if Android device is a tablet.
137
        Returns True for Android devices without 'Mobile Safari' in user agent string
138
        (except Firefox Mobile).
139
        """
140
    
141
    def _is_blackberry_touch_capable_device(self) -> bool:
142
        """
143
        Internal method to determine if BlackBerry device has touch capabilities.
144
        Returns True for BlackBerry Bold Touch series (99XX) and Storm devices (95XX).
145
        """
146
```
147

148
### Information Containers
149

150
Structured data containers for parsed user agent components.
151

152
```python { .api }
153
class Browser:
154
    """
155
    Browser information namedtuple.
156
    
157
    Attributes:
158
    - family: str, browser family name
159
    - version: tuple, version numbers as tuple
160
    - version_string: str, version as formatted string
161
    """
162

163
class OperatingSystem:
164
    """
165
    Operating system information namedtuple.
166
    
167
    Attributes:
168
    - family: str, OS family name  
169
    - version: tuple, version numbers as tuple
170
    - version_string: str, version as formatted string
171
    """
172

173
class Device:
174
    """
175
    Device information namedtuple.
176
    
177
    Attributes:
178
    - family: str, device family name
179
    - brand: str, device brand
180
    - model: str, device model
181
    """
182
```
183

184
### Utility Functions
185

186
Helper functions for parsing user agent components (primarily for internal use).
187

188
```python { .api }
189
def parse_browser(family: str, major=None, minor=None, patch=None, patch_minor=None) -> Browser:
190
    """Create Browser namedtuple from parsed data."""
191

192
def parse_operating_system(family: str, major=None, minor=None, patch=None, patch_minor=None) -> OperatingSystem:
193
    """Create OperatingSystem namedtuple from parsed data."""
194

195
def parse_device(family: str, brand: str, model: str) -> Device:
196
    """Create Device namedtuple from parsed data."""
197

198
def parse_version(major=None, minor=None, patch=None, patch_minor=None) -> tuple:
199
    """Parse version components into tuple of integers."""
200

201
def verify_attribute(attribute):
202
    """Convert string digits to integers, leave other values unchanged.
203
    
204
    Parameters:
205
    - attribute: any, the attribute to verify
206
    
207
    Returns:
208
    int if attribute is a digit string, otherwise returns original attribute
209
    """
210
```
211

212
## Types
213

214
```python { .api }
215
VERSION: tuple = (2, 2, 0)
216
# Package version tuple
217

218
# Device classification constants
219
MOBILE_DEVICE_FAMILIES: tuple = (
220
    'iPhone', 'iPod', 'Generic Smartphone', 'Generic Feature Phone',
221
    'PlayStation Vita', 'iOS-Device'
222
)
223

224
TABLET_DEVICE_FAMILIES: tuple = (
225
    'iPad', 'BlackBerry Playbook', 'Blackberry Playbook', 'Kindle',
226
    'Kindle Fire', 'Kindle Fire HD', 'Galaxy Tab', 'Xoom', 'Dell Streak'
227
)
228

229
TOUCH_CAPABLE_DEVICE_FAMILIES: tuple = (
230
    'BlackBerry Playbook', 'Blackberry Playbook', 'Kindle Fire'
231
)
232

233
PC_OS_FAMILIES: tuple = (
234
    'Windows 95', 'Windows 98', 'Solaris'
235
)
236

237
MOBILE_OS_FAMILIES: tuple = (
238
    'Windows Phone', 'Windows Phone OS', 'Symbian OS', 'Bada',
239
    'Windows CE', 'Windows Mobile', 'Maemo'
240
)
241

242
TOUCH_CAPABLE_OS_FAMILIES: tuple = (
243
    'iOS', 'Android', 'Windows Phone', 'Windows CE', 'Windows Mobile',
244
    'Firefox OS', 'MeeGo'
245
)
246

247
MOBILE_BROWSER_FAMILIES: tuple = (
248
    'IE Mobile', 'Opera Mobile', 'Opera Mini', 'Chrome Mobile',
249
    'Chrome Mobile WebView', 'Chrome Mobile iOS'
250
)
251

252
EMAIL_PROGRAM_FAMILIES: set = {
253
    'Outlook', 'Windows Live Mail', 'AirMail', 'Apple Mail', 'Thunderbird',
254
    'Lightning', 'ThunderBrowse', 'The Bat!', 'Lotus Notes', 'IBM Notes',
255
    'Barca', 'MailBar', 'kmail2', 'YahooMobileMail'
256
}
257
```
258

259
## Usage Examples
260

261
### Different Device Types
262

263
```python
264
from user_agents import parse
265

266
# Mobile phone (Android)
267
android_ua = 'Mozilla/5.0 (Linux; U; Android 4.0.4; en-gb; GT-I9300 Build/IMM76D) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30'
268
user_agent = parse(android_ua)
269
print(user_agent.is_mobile)        # True
270
print(user_agent.is_touch_capable) # True
271
print(str(user_agent))             # "Samsung GT-I9300 / Android 4.0.4 / Android 4.0.4"
272

273
# Tablet (iPad)
274
ipad_ua = 'Mozilla/5.0(iPad; U; CPU iPhone OS 3_2 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Version/4.0.4 Mobile/7B314 Safari/531.21.10'
275
user_agent = parse(ipad_ua)
276
print(user_agent.is_tablet)        # True
277
print(user_agent.is_touch_capable) # True
278
print(str(user_agent))             # "iPad / iOS 3.2 / Mobile Safari 4.0.4"
279

280
# Desktop PC
281
pc_ua = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13+ (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2'
282
user_agent = parse(pc_ua)
283
print(user_agent.is_pc)            # True
284
print(user_agent.is_touch_capable) # False
285
print(str(user_agent))             # "PC / Mac OS X 10.6.8 / Safari 5.1.7"
286

287
# Bot detection
288
bot_ua = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)'
289
user_agent = parse(bot_ua)
290
print(user_agent.is_bot)           # True
291
print(str(user_agent))             # "Spider / Other / Googlebot 2.1"
292
```
293

294
### Accessing Detailed Information
295

296
```python
297
from user_agents import parse
298

299
ua_string = 'Mozilla/5.0 (iPhone; CPU iPhone OS 5_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B179 Safari/7534.48.3'
300
user_agent = parse(ua_string)
301

302
# Browser details
303
print(user_agent.browser.family)         # 'Mobile Safari'
304
print(user_agent.browser.version)        # (5, 1)
305
print(user_agent.browser.version_string) # '5.1'
306

307
# OS details  
308
print(user_agent.os.family)              # 'iOS'
309
print(user_agent.os.version)             # (5, 1)
310
print(user_agent.os.version_string)      # '5.1'
311

312
# Device details
313
print(user_agent.device.family)          # 'iPhone'
314
print(user_agent.device.brand)           # 'Apple'  
315
print(user_agent.device.model)           # 'iPhone'
316
```