DOCSEARCHbyAlgolia
Submit Docs

httpagentparser

repository·master·Indexed 42 days ago

https://github.com/shon/httpagentparser

A fast Python library for detecting Operating Systems and Browsers from HTTP User-Agent strings. It provides lightweight detection via simple_detect(), structured parsing via detect(), and the ability to extend detection capabilities by registering custom detectors through the DetectorsHub.

Tokens
2.3K
Snippets
9
Records
9
Agent score
53%

What's inside httpagentparser

  1. Build and upload a new version

    master

    To release a new version of the package, follow these steps:

    1. Increment the __version__ variable in httpagentparser/__init__.py.
    2. Build the distribution packages using uv build.
    3. Publish the package using uv publish.
    # Bump __version__ in httpagentparser/__init__.py
uv build
uv publish

  2. Register new User Agents with hap.Browser

    master

    If you encounter User Agents that are not supported by the default httpagentparser configuration, you can extend the library by subclassing hap.Browser and registering the new detector with hap.detectorshub.register().

    To create a custom detector, define:

    • name: The name of the browser/client.
    • look_for: A string or pattern to identify the agent in the User Agent string.
    • version_splitters: (Optional) A list of strings used to split the version part of the agent string.
    • getVersion(self, agent): (Optional) A method to implement custom version extraction logic if standard splitting is insufficient.
    import httpagentparser as hap

class JakartaHTTPClinet(hap.Browser):
    name = 'Jakarta Commons-HttpClient'
    look_for = name
    version_splitters = ["/"]

class SomeNotSoCommonClient(hap.Browser):
    name = 'NotSoCommon Client'
    look_for = 'NotSoCommon'
    def getVersion(self, agent):
        return agent.split(':')[1]

# Register the new detectors
hap.detectorshub.register(JakartaHTTPClinet())
hap.detectorshub.register(SomeNotSoCommonClient())

  3. Extend detection with custom Detectors

    master

    You can extend the library by creating new detector classes that inherit from DetectorBase and registering them in the DetectorsHub.

    To create a custom detector, implement the following attributes/methods:

    • info_type: The key under which the result will be stored (e.g., 'os', 'browser').
    • name: The name of the detected entity.
    • look_for: A string or list of strings to search for in the User-Agent.
    • detect(agent, result): The logic to perform the match and populate the result dictionary.
    • can_register: Set to True to allow the detector to be automatically picked up by DetectorsHub.registerDetectors().

    Once defined, you can add it to the global detectorshub instance using detectorshub.register(YourDetectorClass()).

    from httpagentparser import DetectorBase, detectorshub

class MyCustomBrowser(DetectorBase):
    name = "MyBrowser"
    info_type = "browser"
    look_for = "MyCustomBrowser"
    can_register = True

# Register the new detector
detectorshub.register(MyCustomBrowser())

  4. Use simple_detect for quick OS and Browser identification

    master

    If you only need a high-level identification of the Operating System and the Browser, use httpagentparser.simple_detect(ua_string). It returns a tuple containing a simplified OS string and a simplified Browser name/version string.

    import httpagentparser
s = "Mozilla/5.0 (X11; U; Linux i686; en-US) AppleWebKit/532.9 (KHTML, like Gecko) Chrome/5.0.307.11 Safari/532.9"
print(httpagentparser.simple_detect(s))
# Output: ('Linux', 'Chrome 5.0.307.11')

  5. Use detect for detailed User-Agent parsing

    master

    For a structured breakdown of the User-Agent string, use httpagentparser.detect(ua_string). This returns a dictionary containing categorized information about the operating system (os), the browser (browser), and potentially the distribution (dist).

    import httpagentparser
s = "Mozilla/5.0 (X11; U; Linux i686; en-US) AppleWebKit/532.9 (KHTML, like Gecko) Chrome/5.0.307.11 Safari/532.9"
print(httpagentparser.detect(s))
# Output: {'os': {'name': 'Linux'}, 'browser': {'version': '5.0.307.11', 'name': 'Chrome'}}

  6. Extend httpagentparser by registering new User Agents

    master

    You can extend the library's detection capabilities by subclassing httpagentparser.Browser and registering the new class with hap.detectorshub.register().

    To create a custom detector, define:

    • name: A string representing the name of the browser/client.
    • look_for: A string (or pattern) used to identify the agent in the User-Agent string.
    • version_splitters (optional): A list of strings used to split the version part of the User-Agent string. Defaults to standard behavior if not provided.

    Once defined, pass an instance of your subclass to hap.detectorshub.register() to make it available for detection.

    import httpagentparser as hap

class MyCustomClient(hap.Browser):
    name = 'My Custom Client'
    look_for = 'my-client-token'
    version_splitters = ['/']

hap.detectorshub.register(MyCustomClient())

  7. Get detailed tuple info with simple_detect_tuple()

    master

    For more granular control over the simplified output, use simple_detect_tuple. It returns a 4-element tuple: (os_name, os_version, browser_name, browser_version).

    This is useful when you want the components separated but don't want the overhead of the full detect() dictionary structure. You can also pass a parsed_agent (the result of a previous detect() call) to avoid re-calculating the parsing logic.

    import httpagentparser

agent_string = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/91.0.4472.124"
os_name, os_ver, browser_name, browser_ver = httpagentparser.simple_detect_tuple(agent_string)

  8. Detect client information with detect()

    master

    The primary way to parse a User-Agent string is using the detect function. It returns a dictionary containing structured information about the client's operating system, distribution, flavor, and browser.

    By default, if a component (like a browser or OS) is not detected, it will be omitted from the dictionary. If you set fill_none=True, the resulting dictionary will include os and browser keys with name and version set to None if they weren't found.

    Supported information types include:

    • os: Operating System
    • dist: Distribution
    • flavor: Flavor
    • browser: Browser
    • bot: A boolean indicating if the agent is a known bot.
    import httpagentparser

agent_string = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
result = httpagentparser.detect(agent_string)
# Example result structure:
# {
#   'os': {'name': 'Windows', 'version': '10'},
#   'browser': {'name': 'Chrome', 'version': '91.0.4472.124'}
# }

  9. Get simplified client info with simple_detect()

    master

    If you only need a quick summary of the client without a full dictionary, use simple_detect. It returns a tuple of two strings: (os_name_version, browser_name_version).

    • os_name_version: A concatenated string of the OS flavor, distribution, and OS name, including the version if available.
    • browser_name_version: The browser name and version concatenated.

    If nothing is detected, it returns ('Unknown OS', 'Unknown Browser').

    import httpagentparser

agent_string = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
# Returns: ('Mac OS X 10.15.7', 'Chrome 91.0.4472.124')
os_info, browser_info = httpagentparser.simple_detect(agent_string)