Add docs and changelog

Author: danyeaw

CHANGELOG.rst

@@ -4,7 +4,9 @@ Changelog
 *unreleased*
 ~~~~~~~~~~~~
 
-No unreleased changes.
+Features:
+
+* Expose a public structured marker tree via ``Marker.as_ast()`` (:pull:`1145`)
 
 26.0 - 2026-01-20
 ~~~~~~~~~~~~~~~~~

docs/markers.rst

@@ -65,6 +65,41 @@ when building markers dynamically from separate conditions.
 
 .. versionadded:: 26.1
 
+You can combine existing :class:`Marker` instances with ``&`` and ``|`` instead of
+parsing one long marker string. The string form preserves PEP 508 ``and`` / ``or``
+precedence. :meth:`Marker.as_ast` returns an immutable tree of
+:class:`MarkerCompare`, :class:`MarkerAnd`, and :class:`MarkerOr` nodes (see
+:class:`MarkerNode`).
+
+.. doctest::
+
+    >>> from packaging.markers import Marker, MarkerCompare, MarkerAnd, MarkerOr
+    >>> py_at_least_310 = Marker('python_version >= "3.10"')
+    >>> posix = Marker('os_name == "posix"')
+    >>> py_at_least_310 & posix
+    <Marker('python_version >= "3.10" and os_name == "posix"')>
+    >>> windows = Marker('sys_platform == "win32"')
+    >>> macos = Marker('sys_platform == "darwin"')
+    >>> windows | macos
+    <Marker('sys_platform == "win32" or sys_platform == "darwin"')>
+    >>> expr = Marker(
+    ...     "python_version > '3.12' or (python_version == '3.12' and os_name == 'unix')"
+    ... )
+    >>> node = expr.as_ast()
+    >>> isinstance(node, MarkerOr)
+    True
+    >>> len(node.operands)
+    2
+    >>> isinstance(node.operands[0], MarkerCompare)
+    True
+    >>> (node.operands[0].left, node.operands[0].op, node.operands[0].right)
+    ('python_version', '>', '3.12')
+    >>> isinstance(node.operands[1], MarkerAnd)
+    True
+    >>> [type(p).__name__ for p in node.operands[1].operands]
+    ['MarkerCompare', 'MarkerCompare']
+
+.. versionadded:: 26.1
 
 Reference
 ---------
@@ -73,3 +108,6 @@ Reference
     :members:
     :special-members: __and__, __or__
     :exclude-members: __init__
+
+.. autodata:: MarkerCompareOp
+    :no-value:

src/packaging/markers.py

@@ -511,8 +511,8 @@ def as_ast(self) -> MarkerNode | None:
         """Return a structured tree for this marker.
 
         The tree uses :class:`MarkerCompare`, :class:`MarkerAnd`, and
-        :class:`MarkerOr`, preserving PEP 508 ``and`` / ``or`` precedence;
-        parenthesized sub-expressions are nested nodes.
+        :class:`MarkerOr`. It preserves PEP 508 ``and`` / ``or`` precedence.
+        Parenthesized sub-expressions are nested nodes.
 
         :returns: The root node, or ``None`` if the internal marker list is empty
             (a vacuous marker, which :meth:`evaluate` treats as true).