From f2434ba9aa7c2bb389d6cb6a69fda712af448f00 Mon Sep 17 00:00:00 2001 From: masklinn Date: Sun, 24 Nov 2024 20:36:58 +0100 Subject: [PATCH] doc update, fixups --- README.rst | 45 +++++++++++++++++++------------------- doc/advanced/migration.rst | 30 +++++++++++++------------ doc/guides.rst | 25 ++++++++++++++------- doc/installation.rst | 22 +++++-------------- doc/quickstart.rst | 2 +- 5 files changed, 62 insertions(+), 62 deletions(-) diff --git a/README.rst b/README.rst index d3805ea..512d0d2 100644 --- a/README.rst +++ b/README.rst @@ -10,40 +10,34 @@ Build Status .. image:: https://github.com/ua-parser/uap-python/actions/workflows/ci.yml/badge.svg :alt: CI on the master branch -⚠️ THIS IS NOT THE DOCUMENTATION YOU ARE LOOKING FOR (probably) ⚠️ ------------------------------------------------------------------- - -This is the readme for the `future 1.0 `_. - -For the current releases, see `the 0.x branch -`_. - Installing ---------- -Just add ``ua-parser`` to your project's dependencies, or run +Add ``ua-parser[regex]`` to your project's dependencies, or run .. code-block:: sh - $ pip install ua-parser + $ pip install 'ua-parser[regex]' to install in the current environment. -Installing `ua-parser-rs `_ or -`google-re2 `_ is *strongly* -recommended as they yield *significantly* better performances. This -can be done directly via the ``regex`` and ``re2`` optional -dependencies respectively: +ua-parser supports CPython 3.9 and newer, recent pypy (supporting +3.10), and GraalPy 24. -.. code-block:: sh +.. note:: + + The ``[regex]`` feature is *strongly* recommended: - $ pip install 'ua_parser[regex]' - $ pip install 'ua_parser[re2]' + - ``[re2]`` is slightly slower and only works with cpython, though + it is still a great option then (and is more memory-efficient). + - Pure python (no feature) is *significantly* slower, especially on + non-cpython runtimes, but it is the most memory efficient even + with caches. -If either dependency is already available (e.g. because the software -makes use of re2 for other reasons) ``ua-parser`` will use the -corresponding resolver automatically. + See `builtin resolvers`_ for more explanation of the tradeoffs + between the different options. + +.. _builtin resolvers: https://readthedocs.org/ua-parser/uap-python/guides#builtin-resolvers Quick Start ----------- @@ -109,3 +103,10 @@ Extract device information from user-agent string >>> 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' >>> parse_device(ua_string) Device(family='Mac', brand='Apple', model='Mac') + +Upgrading +--------- + +Upgrading from 0.x? See `the upgrade guide`_. + +.. _the upgrade guide: https://readthedocs.org/ua-parser/uap-python/advanced/migration diff --git a/doc/advanced/migration.rst b/doc/advanced/migration.rst index c77b5d8..a75d85e 100644 --- a/doc/advanced/migration.rst +++ b/doc/advanced/migration.rst @@ -5,11 +5,13 @@ From 0.x to 1.0 Don't Touch A Thing =================== -The first and simplest way to transition is to not transition: the 0.x -API won't be removed for a long time, possibly ever. While it is -unlikely to get updated any further and will eventually (hopefully?) -fall behind, if you can't be arsed you probably don't have to until an -unlikely 2.0. +The first and simplest way to upgrade is to not do anything: the 0.x +API is still present in 1.x and won't be removed for a long time, +possibly ever. + +While it is unlikely to get updated any further and will eventually +(hopefully?) fall behind, if you can't be arsed you probably don't +have to do anything for now, or just now. Unavoidable Divergences ======================= @@ -29,20 +31,20 @@ special attention: # force initialisation of global parser ua_parser.parser -- The 1.0 API defaults to an :class:`re2-based parser - ` if |re2|_ is installed, although it seems - unlikely you may wish to consider replacing it with configuring a - :class:`~ua_parser.Parser` with a :class:`ua_parser.basic.Resolver` - if |re2|_ is one of your dependencies. +- The 1.0 API defaults to powerful native parsers (based on |regex|_ + or |re2|_) if available, although it seems unlikely you may wish to + consider replacing it with configuring a :class:`~ua_parser.Parser` + with a :class:`ua_parser.basic.Resolver`, especially if for some + reason |re2| is already one of your dependencies but you want to + *avoid* the |re2|-based resolver. Default Ruleset =============== While the 1.0 API was designed to better respect :pep:`8` and support -:mod:`typing`, it was also designed to easily be transitioned from. +:mod:`typing`, it was also designed to easily be transitioned to. -Given a 0.x API not using YAML, the conversion should be very easy and -consists of: +Given a 0.x API not using YAML, the conversion consists of: - updating the import from ``ua_parser.user_agent_parser`` to just ``ua_parser`` @@ -116,7 +118,7 @@ Legacy YAML support can be added via a pretty small shim:: import ua_parser from ua_parser.loaders import load_yaml - if yaml_path = os.environ.get("UA_PARSER_YAML"): + if yaml_path := os.environ.get("UA_PARSER_YAML"): ua_parser.parser = ua_parser.Parser.from_matchers( load_yaml(yaml_path)) diff --git a/doc/guides.rst b/doc/guides.rst index 039bd24..39b43e4 100644 --- a/doc/guides.rst +++ b/doc/guides.rst @@ -7,10 +7,8 @@ Guides Custom Rulesets =============== -ua-parser defaults to the version of `ua-core -`_ -current when it was packaged, using a precompiled version of -``regexes.yaml``. +ua-parser defaults to the latest stable release of `ua-core`_ via +`precompiled regexes.yaml`__. That is a suitable defaut, but there are plenty of reasons to use custom rulesets: @@ -18,10 +16,13 @@ custom rulesets: - trim down the default ruleset to only the most current or relevant rules for efficiency e.g. you might not care about CalDav or podcast applications -- add new rules relevant to your own traffic but which don't (possibly - can't) be in the main project +- add new rules relevant to your own traffic but which aren't (possibly + can't be) in the main project - experiment with the creation of new rules - use a completely bespoke ruleset to track UA-identified API clients +- use "experimental" rules which haven't been released yet (although + `ua-parser-builtins`_ provides regular prerelease versions which may + be suitable for this) ua-parser provides easy ways to load custom rolesets: @@ -38,6 +39,12 @@ ua-parser provides easy ways to load custom rolesets: parser = Parser.from_matchers(load_yaml("regexes.yaml")) parser.parse(some_ua) +.. _ua-parser-builtins: https://pypi.org/project/ua-parser-builtins + +__ ua-parser-builtins_ + +.. _ua-core: https://github.com/ua-parser/uap-core/blob/master/regexes.yaml + .. _guide-custom-global-parser: Custom Global Parser @@ -129,6 +136,8 @@ from here on:: :class:`~ua_parser.caching.Local`, which is also caching-related, and serves to use thread-local caches rather than a shared cache. +.. _builtin-resolvers: + Builtin Resolvers ================= @@ -207,9 +216,9 @@ If available, it is the second-preferred resolver, without a cache. The ``basic`` resolver is a naive linear traversal of all rules, using the standard library's ``re``. It: -- Is *extremely* slow, about 10x slower than ``re2`` in cpython, and +- Is *extremely* slow: about 10x slower than ``re2`` on cpython, and pypy and graal's regex implementations do *not* like the workload - and behind cpython by a factor of 3~4. + and are 3x-4x slower than *cpython*. - Has perfect compatibility, with the caveat above, by virtue of being built entirely out of standard library code. - Is basically as safe as Python software can be by virtue of being diff --git a/doc/installation.rst b/doc/installation.rst index ac6b311..09ba9e8 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -2,23 +2,11 @@ Installation ============ -Python Version -============== - -ua-parser currently supports CPython 3.9 and newer, recent Pypy -(supporting 3.10), and Graal 24. - -.. note:: - - While pypy and graal are supported, they are rather slow when using - pure python mode and ``[re2]`` is not supported, so using the - ``[regex]`` feature is very strongly recommended. - Installation ============ .. include:: ../README.rst - :start-line: 23 + :start-line: 14 :end-before: Quick Start Optional Dependencies @@ -35,9 +23,9 @@ if installed, but can also be installed via and alongside ua-parser: $ pip install 'ua-parser[yaml]' $ pip install 'ua-parser[regex,yaml]' -``yaml`` simply enables the ability to :func:`load yaml rulesets +``yaml`` enables the ability to :func:`load rulesets from yaml `. -The other two dependencies enable more efficient resolvers. By -default, ``ua-parser`` will select the fastest resolver it finds out -of the available set. For more, see :ref:`builtin resolvers`. +The other two features enable more efficient resolvers. By default, +``ua-parser`` will select the fastest resolver it finds out of the +available set (regex > re2 > python). diff --git a/doc/quickstart.rst b/doc/quickstart.rst index 4267ffe..c6cfe9c 100644 --- a/doc/quickstart.rst +++ b/doc/quickstart.rst @@ -3,4 +3,4 @@ Quick Start =========== .. include:: ../README.rst - :start-line: 47 + :start-line: 44