Guidelines for expanding/changing the public API:

(Following them makes the API easier to reason about, and easier use

in other Python implementations.)

- Think about ease of use for the user.

reducing boilerplate code needed to use the API. Bugs like to hide in

boiler plates.

to enter the public source tree. Ask yourself the following questions:

* **Are there ongoing discussions at** ``bugs.python.org`` **(b.p.o.)?**

we need to have a resolution there before we can merge the pull request.

The only branch that receives new features is ``main``, the

in-development branch. Pull requests should only target bug-fix branches

if an issue appears in only that version and possibly older versions.

the `issue tracker`_, or create a public fork of the repository.

Make sure that all of the status checks are passing.

a patch.

If you are unsure if the breakage is worth it, then ask on python-dev.

* **Does documentation need to be updated?**

* **Were appropriate labels added to signify necessary backporting of the pull request?**

If it is determined that a pull request needs to be

core developers and members of the `Python Triage Team`_ can apply

labels to GitHub pull requests).

Make sure that the contributor has signed a `Contributor

To check if a contributor’s CLA has been received, go

to `Check Python CLA <https://check-python-cla.herokuapp.com/>`_ and

put in their GitHub username. For further questions about the CLA

process, write to contributors@python.org.

require a ``NEWS`` entry. (See the following section for more information.)

for maintenance work before it is integrated into the main repository.

* **You should not commit directly into the** ``main`` **branch, or any of the maintenance branches.**

pull request.

* **For a small change, you can make a quick edit through the GitHub web UI.**

to be recompiled by the interpreter on import. Whenever ``MAGIC_NUMBER`` is

changed, the ranges in the ``magic_values`` array in :file:`PC/launcher.c`

must also be updated. Changes to :file:`Lib/importlib/_bootstrap_external.py`

bytecode target has been added.

.. note:: On Windows, running the ``./build.bat`` script will automatically

If it says 'without C extension', then you will need to build the C extension.

clone::

There is no election; each translation has to sort this out. Here are some suggestions.

- Coordinator requests are to be public on the `translation mailing list <translation_ml_>`_.

say on the choice.

- Anyone who wants to become coordinator for their native language and shows

motivation by translating and building a community will be named

I have a translation, but it's not in git. What should I do?

the team will help you create an appropriate repository. You can still use tools like transifex,

if you like.

In order to support the garbage collector, the memory layout of objects is altered

to accommodate extra information **before** the normal layout:

In this way the object can be treated as a normal python object and when the extra

information associated to the GC is needed the previous fields can be accessed by a

count field initialized to the reference count (``gc_ref`` in the figures)

of that object when the algorithm starts. This is because the algorithm needs

to modify the reference count to do the computations and in this way the

.. figure:: images/python-cyclic-gc-1-new-page.png

to ``link_2`` and ``link_3`` below as they are reachable from ``link_1``. From the

state in the previous image and after examining the objects referred to by ``link_1``

the GC knows that ``link_3`` is reachable after all, so it is moved back to the

it will know that it's reachable. To avoid visiting an object twice, the GC marks all

object, the GC does not process it twice.

.. figure:: images/python-cyclic-gc-5-new-page.png

when created. During garbage collection it is determined whether any surviving

tuples can be untracked. A tuple can be untracked if all of its contents are

already not tracked. Tuples are examined for untracking in all garbage collection

* Dictionaries containing only immutable objects also do not need to be tracked.

Dictionaries are untracked when created. If a tracked item is inserted into a

The garbage collector module provides the Python function ``is_tracked(obj)``, which returns

the current tracking status of the object. Subsequent garbage collections may change the

.. code-block:: python

to backtrack arbitrarily. This is made efficient by memoizing the rules already

matched for each position. The cost of the memoization cache is that the parser

will naturally use more memory than a simple LL(1) parser, which normally are

Key ideas

identical in both files. As an example of a grammar with Python actions, the

piece of the parser generator that parses grammar files is bootstrapped from a

meta-grammar file with Python actions that generate the grammar tree as a result

In the specific case of the PEG grammar for Python, having actions allows

directly describing how the AST is composed in the grammar itself, making it

* A PEG meta-grammar that automatically generates a Python parser that is used for the parser generator itself

(this means that there are no manually-written parsers). The meta-grammar is

located at :file:`Tools/peg_generator/pegen/metagrammar.gram`.

The source code for Pegen lives at :file:`Tools/peg_generator/pegen` but normally all typical commands to interact

with the parser generator are executed from the main makefile.

Memoization

The C parser used by Python is highly optimized and memoization can be expensive both in memory and time. Although

the memory cost is obvious (the parser needs memory for storing previous results in the cache) the execution time

a syntax error **after** valid code triggers the rule or not. For example: ::

Should trigger the syntax error in the ``$`` character. If your rule is not correctly defined this

won't happen. For example, if you try to define a rule to match Python 2 style ``print`` statements

to make a better error message and you define it as: ::

This will **seem** to work because the parser will correctly parse ``print(something)`` because it is valid

code and the second phase will never execute but if you try to parse ``print(something) $ 3`` the first pass

of the parser will fail (because of the ``$``) and in the second phase, the rule will match the

AST to decide if is valid or not but this will render the `official grammar

<https://docs.python.org/3/reference/grammar.html>`_ partially incorrect

(because actions are not included) and will make it more difficult for other

As a general rule, if an action spawns multiple lines or requires something more

complicated than a single expression of C code, is normally better to create a

When Python is compiled in debug mode (by adding ``--with-pydebug`` when running the configure step in Linux or by

adding ``-d`` when calling the :file:`PCbuild/python.bat` script in Windows), it is possible to activate a **very** verbose

mode in the generated parser. This is very useful to debug the generated parser and to understand how it works, but it

.. note::

When you review a pull request, you should provide additional details and context

Instead of simply "approving" the pull request, leave comments. For example:

which might be useful for IDEs and local debugging::

But, there are several important notes:

for local developer needs and is discouraged for anything else

2. Some modules do not support it at all. One example is``test_importlib``.

In other words: if some module does not have ``unittest.main()``, then