===
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
<https://docs.python.org/3/library/dataclasses.html>`_, 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)

.. class:: ua_parser.re2.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.

.. class:: ua_parser.regex.Resolver(Matchers)

   An advanced resolver based on `Rust's regex
   <https://github.com/rust-lang/regex>`_ and a bespoke implementation
   of regex prefiltering, by the sibling project `uap-rust
   <https://github.com/ua-parser/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

.. _api-loading:

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.

.. _regexes.yaml: https://github.com/ua-parser/uap-core/blob/master/docs/specification.md