Skip to content

api.rst

Latest commit

 

History

History
183 lines (119 loc) · 4.23 KB

api.rst

File metadata and controls

183 lines (119 loc) · 4.23 KB
Raw

API

Global Helpers

.. module:: ua_parser


.. autofunction:: parse


.. autofunction:: parse_user_agent


.. autofunction:: parse_os


.. autofunction:: parse_device


.. autodata:: parser

Core Types

.. autoclass:: Resolver
   :members:
   :special-members: __call__


.. autoclass:: Domain
   :members:
   :member-order: bysource


.. autoclass:: Parser
   :members:

Data Types

These are the various types produced by successfully resolving a user agent string. They are guaranteed to be dataclasses, and using dataclass utility functions is officially supported.

.. autoclass:: PartialResult
   :members:


.. autoclass:: Result
   :members:


.. autoclass:: UserAgent


.. autoclass:: OS


.. autoclass:: Device


.. autoclass:: DefaultedResult
   :members:

Base Resolvers

Base resolvers take sets of :class:`~ua_parser.core.Matchers` generated by :ref:`loaders <api-loading>`, and use them to extract data from user agent strings.

.. autoclass:: ua_parser.basic.Resolver(Matchers)

An advanced resolver based around |re2|_'s FilteredRE2 feature, which efficiently prunes the number of possibly matching matchers before actually running them.

Sufficiently fast that a cache may not be necessary, and may even be detrimental at smaller cache sizes

Warning

Only available if |re2|_ is installed.

An advanced resolver based on Rust's regex and a bespoke implementation of regex prefiltering, by the sibling project uap-rust.

Sufficiently fast that a cache may not be necessary, and may even be detrimental at smaller cache sizes

Warning

Only available if ua-parser-rs <https://pypi.org/project/ua-parser-rs/>_ is installed.

Eager Matchers

.. automodule:: ua_parser.matchers
   :members:
   :member-order: bysource
   :show-inheritance:

Lazy Matchers

These matchers will lazily compile their :attr:`~ua_parser.core.Matcher.pattern` to an :class:`re.Pattern`.

While this saves CPU upfront, this is most useful with resolvers which likely will not need to apply most of them, like :class:`ua_parser.re2.Resolver`. If the resolver will very likely need to apply (and thus compile) every pattern like :class:`ua_parser.basic.Resolver`, then lazy compilation has a higher overhead.

.. automodule:: ua_parser.lazy
   :members:
   :member-order: bysource
   :show-inheritance:

Caching

Web clients commonly have multiple interactions with a given system, leading to significant repetition in user agents encountered. A cache allows making use of that to avoid redundant parses, at the cost of memory. This is most useful for slow base resolvers like :class:`the basic resolver <ua_parser.basic.Resolver>`.

.. autoclass:: ua_parser.caching.Cache
   :members: __getitem__, __setitem__


.. autoclass:: ua_parser.CachingResolver
   :members:


.. autoclass:: ua_parser.Cache


.. module:: ua_parser.caching


.. autoclass:: S3Fifo


.. autoclass:: Sieve


.. autoclass:: Lru


.. autoclass:: Local

Loading

.. autoclass:: ua_parser.core.Matchers


.. autoclass:: ua_parser.core.Matcher
   :members:
   :special-members: __call__


.. autofunction:: ua_parser.load_builtins() -> Matchers


.. autofunction:: ua_parser.load_lazy_builtins() -> Matchers

Custom regexes.yaml data

.. module:: ua_parser.loaders


.. autofunction:: load_data(MatchersData) -> Matchers


.. autofunction:: load_lazy(MatchersData) -> Matchers


.. autofunction:: load_json


.. function:: load_yaml(f: PathOrFile, loader: DataLoader = load_data) -> Matchers

   Loads YAML data following the ``regexes.yaml`` structure.

   The ``loader`` parameter customises which matcher variant is
   generated, by default :func:`load_data` is used to generate eager
   matchers, :func:`load_lazy` can be used to generate lazy matchers
   instead.

   .. warning:: Only available if |pyyaml|_ is installed.