Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 87 additions & 24 deletions peps/pep-0845.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
PEP: 845
Title: Leading-Dot Value Patterns
Title: Leading-Dot Value Patterns for match statements
Author: Thomas Kehrenberg <tmke8@posteo.net>,
Marc Mueller
Sponsor: Ethan Furman <ethan@stoneleaf.us>
Expand All @@ -16,18 +16,28 @@ Post-History: `26-Jun-2026 <https://discuss.python.org/t/pattern-matching-on-con
Abstract
========

This PEP enables the use of non-attribute names as **value patterns** in match
statements. A name prefixed with a dot is looked up using the normal name
resolution rules and compared to the match subject by equality in the same
manner as existing value patterns, instead of being treated as a **capture
pattern**. This makes it possible to match local variables and global variables
defined in the same module without using a guard clause.
This PEP enables the use of non-attribute names as **value patterns** in
match statements. This makes it possible to match local variables and
global variables defined in the same module without having to use a
guard clause.

A name prefixed with a dot is looked up using the normal name resolution
rules and compared to the match subject by equality in the same manner
as existing value patterns, instead of being treated as a **capture
pattern**.

.. code-block:: python

def get_book_titles_for_author(author: str):
for book in BOOKS:
match book:
# before
case {"title": title, "author": book_author} if (
book_author == author
):
yield title

# after
case {"title": title, "author": .author}:
yield title

Expand Down Expand Up @@ -123,6 +133,14 @@ The value pattern will be extended to support simple names
if they are prefixed by a leading dot. The lookup is performed following the
standard Python name resolution rules.

.. code-block:: python

author = "William Shakespeare"

match book:
case {"author": .author}:
...

Interaction with capture patterns
---------------------------------

Expand Down Expand Up @@ -238,27 +256,45 @@ There are no new security implications from this proposal.
How to Teach This
=================

The rule presented in the :pep:`636` tutorial can be stated as follows:
Prerequisites
-------------

Students should already be familiar with the basics of match statements.
In particular the difference between:

* Value patterns, e.g. ``HTTPStatus.OK``
* Capture patterns, e.g. ``status`` or ``_ as status``

Basics
------

In a pattern, a name **with a dot** is looked up and compared; a name
**without a dot** captures the subject.
Simple (undotted) variables can now be used in **value patterns** if
they are prefixed **with a dot**. They are looked up using the normal
name resolution rules compared to the match subject by equality in the
same manner as existing value patterns.

The leading-dot form can be introduced as "a value pattern whose namespace part
is empty": you write ``helpers.MISSING`` when the constant lives in a separate
namespace and ``.MISSING`` when it does not.
When to use
-----------

This is useful when you want to match a subject value against a variable.
Just add a **leading dot** to the variable name to differentiate it from
a **capture pattern**, e.g. ``.author`` below. Previously, this required
using a guard clause.

.. code-block:: python

MISSING = sentinel('MISSING')
def get_book_titles_for_author(author: str):
for book in BOOKS:
match book:
case {"title": title, "author": .author}:
yield title

match value:
case .MISSING: # value pattern; looked up and compared
...
case found: # capture pattern; always matches and binds
...
When not to use
---------------

Documentation for the ``match`` statement will be updated to include the
leading-dot syntax.
Do not use the **leading dot** for a name when the goal is to bind
the subject value to a variable instead, e.g. ``title`` in the example
above.


Reference Implementation
Expand All @@ -282,10 +318,29 @@ original discussions and again in the thread for this PEP: ``^CONSTANT`` (the
lookup in Python patterns. By contrast, a dot is already part of every dotted
value pattern. Curly braces could be confused with mapping patterns, while
``==CONSTANT`` could imply support for other comparison operators. General
comparison patterns are outside the scope of this PEP, as discussed below. In
comparison patterns are outside the scope of this PEP. In
the community poll referenced in `Why a leading dot`_, each of these options
received fewer approvals than the leading-dot form.

Use ``..CONSTANT``
------------------

It was suggested to use a double leading dot. The first ``.`` would be
a standin for the value lookup, while the second ``.`` would be the
regular attribute notation.

While the leading dot explicitly does not select the scope, see
`Restricting the leading-dot syntax to the current scope`_, a double-dot
would look too similar to the existing import syntax where it means to
go up a level in the directory / package hierarchy. This would create
confusion about the new **value pattern** syntax when developers assume
that ``..CONSTANT`` would resolve in the parent namespace. It would also
imply that ``.CONSTANT`` exist as well.

Either way, with a single or double leading dot, developers would have
to learn how to use it. A single leading dot avoids unnecessary
uncertainty.

Keyword-based markers (``value NAME``, ``constant case NAME:``)
---------------------------------------------------------------

Expand Down Expand Up @@ -340,8 +395,8 @@ form to a single identifier avoids this duplication.
Special-casing sentinels only
-----------------------------

Since :pep:`661` gives each sentinel a distinct type, matching could be
supported through class patterns, or sentinels could be special-cased as
Since :pep:`661` gives each :py:class:`sentinel` a distinct type, matching could
be supported through class patterns, or sentinels could be special-cased as
quasi-literals like ``None``. But the problem is not specific to sentinels:
any unqualified constant (a numeric constant, an interned default object, an
enum member imported with ``from module import MEMBER``) has the same issue.
Expand Down Expand Up @@ -392,6 +447,14 @@ object itself.
Change History
==============

* 09-Nov-2026

- Update PEP title to reference match statements.
- Rewrote `Abstract`_ to point out the main use case more clearly.
- Added a short example to `Specification`_.
- Turned `How to Teach This`_ into a mini-tutorial.
- Added `Use ..CONSTANT`_ as rejected idea.

* 25-Sep-2026

- Clarify interaction with **capture patterns**
Expand Down
Loading