.. _re-syntax:
-Regular Expression Syntax
+Regular expression syntax
-------------------------
A regular expression (or RE) specifies a set of strings that matches it; the
*without* establishing any backtracking points.
This is the possessive version of the quantifier above.
For example, on the 6-character string ``'aaaaaa'``, ``a{3,5}+aa``
- attempt to match 5 ``'a'`` characters, then, requiring 2 more ``'a'``\ s,
+ attempts to match 5 ``'a'`` characters, then, requiring 2 more ``'a'``\ s,
will need more characters than available and thus fail, while
``a{3,5}aa`` will match with ``a{3,5}`` capturing 5, then 4 ``'a'``\ s
by backtracking and then the final 2 ``'a'``\ s are matched by the final
.. _contents-of-module-re:
-Module Contents
+Module contents
---------------
The module defines several functions, constants, and an exception. Some of the
will be conditionally ORed with other flags. Example of use as a default
value::
- def myfunc(text, flag=re.NOFLAG):
- return re.search(text, flag)
+ def myfunc(pattern, text, flag=re.NOFLAG):
+ return re.search(pattern, text, flag)
.. versionadded:: 3.11
:func:`~re.match`. Use that name when you need to retain compatibility with
older Python versions.
- .. versionchanged:: 3.15
- The alternate :func:`~re.prefixmatch` name of this API was added as a
- more explicitly descriptive name than :func:`~re.match`. Use it to better
+ .. deprecated:: 3.15
+ :func:`~re.match` has been :term:`soft deprecated` in favor of
+ the alternate :func:`~re.prefixmatch` name of this API which is
+ more explicitly descriptive. Use it to better
express intent. The norm in other languages and regular expression
implementations is to use the term *match* to refer to the behavior of
what Python has always called :func:`~re.search`.
.. _re-objects:
-Regular Expression Objects
+Regular expression objects
--------------------------
.. class:: Pattern
:meth:`~Pattern.match`. Use that name when you need to retain compatibility
with older Python versions.
- .. versionchanged:: 3.15
- The alternate :meth:`~Pattern.prefixmatch` name of this API was added as
- a more explicitly descriptive name than :meth:`~Pattern.match`. Use it to
+ .. deprecated:: 3.15
+ :meth:`~Pattern.match` has been :term:`soft deprecated` in favor of
+ the alternate :meth:`~Pattern.prefixmatch` name of this API which is
+ more explicitly descriptive. Use it to
better express intent. The norm in other languages and regular expression
implementations is to use the term *match* to refer to the behavior of
what Python has always called :meth:`~Pattern.search`.
.. _match-objects:
-Match Objects
+Match objects
-------------
Match objects always have a boolean value of ``True``.
.. _re-examples:
-Regular Expression Examples
+Regular expression examples
---------------------------
-Checking for a Pair
+Checking for a pair
^^^^^^^^^^^^^^^^^^^
In this example, we'll use the following helper function to display match
| ``%x``, ``%X`` | ``[-+]?(0[xX])?[\dA-Fa-f]+`` |
+--------------------------------+---------------------------------------------+
-To extract the filename and numbers from a string like ::
+To extract the filename and numbers from a string like:
+
+.. code-block:: text
/usr/sbin/sendmail - 0 errors, 4 warnings
-you would use a :c:func:`!scanf` format like ::
+you would use a :c:func:`!scanf` format like:
+
+.. code-block:: text
%s - %d errors, %d warnings
-The equivalent regular expression would be ::
+The equivalent regular expression would be:
+
+.. code-block:: text
(\S+) - (\d+) errors, (\d+) warnings
industry norm.
Quoting from the Zen Of Python (``python3 -m this``): *"Explicit is better than
-implicit"*. Anyone reading the name :func:`~re.prefixmatch` is likely to
-understand the intended semantics. When reading :func:`~re.match` there remains
+implicit"*. Anyone reading the name :func:`!prefixmatch` is likely to
+understand the intended semantics. When reading :func:`!match` there remains
a seed of doubt about the intended behavior to anyone not already familiar with
this old Python gotcha.
-We **do not** plan to deprecate and remove the older *match* name,
+We **do not** plan to remove the older :func:`!match` name,
as it has been used in code for over 30 years.
-Code supporting older versions of Python should continue to use *match*.
+It has been :term:`soft deprecated`:
+code supporting older versions of Python should continue to use :func:`!match`,
+while new code should prefer :func:`!prefixmatch`.
.. versionadded:: 3.15
+ :func:`!prefixmatch`
+
+.. deprecated:: 3.15
+ :func:`!match` is :term:`soft deprecated`
-Making a Phonebook
+Making a phonebook
^^^^^^^^^^^^^^^^^^
:func:`split` splits a string into a list delimited by the passed pattern. The
['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]
-Text Munging
+Text munging
^^^^^^^^^^^^
:func:`sub` replaces every occurrence of a pattern with a string or the
'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'
-Finding all Adverbs
+Finding all adverbs
^^^^^^^^^^^^^^^^^^^
:func:`findall` matches *all* occurrences of a pattern, not just the first
['carefully', 'quickly']
-Finding all Adverbs and their Positions
+Finding all adverbs and their positions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If one wants more information about all matches of a pattern than the matched
40-47: quickly
-Raw String Notation
+Raw string notation
^^^^^^^^^^^^^^^^^^^
Raw string notation (``r"text"``) keeps regular expressions sane. Without it,
<re.Match object; span=(0, 1), match='\\'>
-Writing a Tokenizer
+Writing a tokenizer
^^^^^^^^^^^^^^^^^^^
A `tokenizer or scanner <https://en.wikipedia.org/wiki/Lexical_analysis>`_
re
--
-* :func:`re.prefixmatch` and a corresponding :meth:`~re.Pattern.prefixmatch`
- have been added as alternate more explicit names for the existing
- :func:`re.match` and :meth:`~re.Pattern.match` APIs. These are intended
+* :func:`re.prefixmatch` and a corresponding :meth:`re.Pattern.prefixmatch`
+ have been added as alternate, more explicit names for the existing
+ and now :term:`soft deprecated`
+ :func:`re.match` and :meth:`re.Pattern.match` APIs. These are intended
to be used to alleviate confusion around what *match* means by following the
Zen of Python's *"Explicit is better than implicit"* mantra. Most other
language regular expression libraries use an API named *match* to mean what
(Contributed by Bénédikt Tran in :gh:`134978`.)
+
+* :mod:`re`:
+
+ * :func:`re.match` and :meth:`re.Pattern.match` are now
+ :term:`soft deprecated` in favor of the new :func:`re.prefixmatch` and
+ :meth:`re.Pattern.prefixmatch` APIs, which have been added as alternate,
+ more explicit names. These are intended to be used to alleviate confusion
+ around what *match* means by following the Zen of Python's *"Explicit is
+ better than implicit"* mantra. Most other language regular expression
+ libraries use an API named *match* to mean what Python has always called
+ *search*.
+
+ We **do not** plan to remove the older :func:`!match` name, as it has been
+ used in code for over 30 years. Code supporting older versions of Python
+ should continue to use :func:`!match`, while new code should prefer
+ :func:`!prefixmatch`. See :ref:`prefixmatch-vs-match`.
+
+ (Contributed by Gregory P. Smith in :gh:`86519` and
+ Hugo van Kemenade in :gh:`148100`.)
+
+
* :mod:`struct`:
* Calling the ``Struct.__new__()`` without required argument now is
.. include:: ../deprecations/pending-removal-in-future.rst
+.. include:: ../deprecations/soft-deprecations.rst
+
C API changes
=============
projects / thirdparty / Python / cpython.git / commitdiff
