Add documentation

Author: snejus

beets/dbcore/queryparse.py

@@ -16,15 +16,14 @@
 from beets.util import cached_classproperty
 
 from . import query, sort
+from .query import Query  # noqa: TC001 required for docs type resolution
+from .sort import Sort  # noqa: TC001 required for docs type resolution
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
 
     from beets.library.models import LibModel
 
-    from .query import Query
-    from .sort import Sort
-
 
 PARSE_QUERY_PART_REGEX = re.compile(
     # Non-capturing optional segment for the keyword.

beets/library/models.py

@@ -86,6 +86,7 @@ def default_sort(cls) -> Sort:
     def parse_query(
         cls, query: str | Sequence[str] | None = None
     ) -> ModelQuery:
+        """Parse human-readable search and sort syntax for this model."""
         return ModelQuery.parse(cls, query)
 
     @property

docs/_templates/autosummary/namedtuple.rst

@@ -3,3 +3,4 @@
 .. currentmodule:: {{ module }}
 
 .. autonamedtuple:: {{ objname }}
+    :members:

docs/api/database.rst

@@ -43,3 +43,10 @@ Queries
     Query
     FieldQuery
     AndQuery
+
+.. currentmodule:: beets.dbcore.queryparse
+
+.. autosummary::
+    :toctree: generated/
+
+    ModelQuery

docs/changelog.rst

@@ -65,9 +65,15 @@ Bug fixes
   ordered before present ones when sorting ascending and after them when
   descending. :bug:`3461`
 
-..
-    For plugin developers
-    ~~~~~~~~~~~~~~~~~~~~~
+For plugin developers
+~~~~~~~~~~~~~~~~~~~~~
+
+- Query parsing is now available through ``Item.parse_query`` and
+  ``Album.parse_query``, which return a
+  :class:`~beets.dbcore.queryparse.ModelQuery` containing the query and sort
+  order. The ``parse_query_string``, ``parse_query_parts``,
+  ``query_from_strings``, ``sort_from_strings``, and ``parse_sorted_query``
+  helpers are deprecated.
 
 Other changes
 ~~~~~~~~~~~~~

docs/dev/library.rst

@@ -237,6 +237,22 @@ There are many different types of queries. Just as an example,
 :class:`CollectionQuery`) takes a set of other query objects and bundles them
 together, matching only albums/items that match all constituent queries.
 
-Beets has a human-writable plain-text query syntax that can be parsed into
-:class:`Query` objects. Calling ``AndQuery.from_strings`` parses a list of query
-parts into a query object that can then be used with |Library| objects.
+Beets has a human-writable plain-text query syntax. The |Library| query methods
+accept this syntax directly:
+
+.. code-block:: python
+
+    items = lib.items('artist:"The Beatles" year-')
+
+When code needs the :class:`Query` and sort objects directly, use
+``Item.parse_query`` for item queries or ``Album.parse_query`` for album
+queries. These class methods accept either a query string or a sequence of query
+parts and return a :class:`~beets.dbcore.queryparse.ModelQuery` containing both
+objects.
+
+Use :meth:`FieldQuery.from_model` when constructing a field query directly. This
+applies the model's field aliases and normalization rules:
+
+.. code-block:: python
+
+    query = MatchQuery.from_model(Item, "artist", "The Beatles")