doc update, fixups

Author: masklinn

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 <https://github.com/ua-
-parser/uap-python/milestone/1>`_.
-
-For the current releases, see `the 0.x branch
-<https://github.com/ua-parser/uap-python/tree/0.x#uap- python>`_.
-
 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 <https://pypi.org/project/ua-parser-rs>`_ or
-`google-re2 <https://pypi.org/project/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

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
-  <ua_parser.re2.Resolver>` 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))
 

doc/guides.rst

@@ -7,21 +7,22 @@ Guides
 Custom Rulesets
 ===============
 
-ua-parser defaults to the version of `ua-core
-<https://github.com/ua-parser/uap-core/blob/master/regexes.yaml>`_
-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:
 
 - 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

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
 <ua_parser.loaders.load_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).

doc/quickstart.rst

@@ -3,4 +3,4 @@ Quick Start
 ===========
 
 .. include:: ../README.rst
-   :start-line: 47
+   :start-line: 44