Toggle table of contents sidebar

Adding to the stdlib ¶

While the stdlib contains a great amount of useful code, sometimes you wantmore than is provided. This document is meant to explain how you can get eithera new addition to a pre-existing module in the stdlib or add an entirely newmodule.

Changes to pre-existing code is not covered as that is considered a bugfix andthus is treated as a bug that should be filed on theissue tracker.

Adding to a pre-existing module¶

If you have found that a function, method, or class is useful and you believeit would be useful to the general Python community, there are some steps to gothrough in order to see it added to the stdlib.

First, you should gauge the usefulness of the code,which is typically done by sharing the code publicly.This is not a required step, but it is suggested.You have a several options for this:

Search theissue tracker for discussion related to the proposed addition.This may turn up an issue that explains why the suggestion wasn’t accepted.
Open a new thread in theIdeas Discourse categoryto gather feedback directly from the Python core developers and community.
Write a blog post about the code, which may also help gather useful feedback.

If you have found general acceptance and usefulness for your code from people,you can open an issue on theissue tracker with the code attached as apull request. If possible, also submit acontributor agreement.

If a core developer decides that your code would be useful to the generalPython community, they will then commit your code. If your code is not pickedup by a core developer and committed then please do not take this personally.Through your public sharing of your code in order to gauge community supportfor it you at least can know that others will come across it who may find ituseful.

Adding a new module¶

It must be stated upfront that getting a new module into the stdlib is verydifficult. Adding any significant amount of code to the stdlib increases theburden placed upon core developers. It also means that the module somewhatbecomes “sanctioned” by the core developers as a good way to do something,typically leading to the rest of the Python community to using the new moduleover other available solutions. All of this means that additions to the stdlibare not taken lightly.

Acceptable types of modules¶

Typically two types of modules get added to the stdlib. One type is a modulewhich implements something that is difficult to get right. A good example ofthis is themultiprocessing package. Working out the various OSissues, working through concurrency issues, etc. are all very difficult to getright.

The second type of module is one that implements something that peoplere-implement constantly. Theitertools module is a good example ofthis type as its constituent parts are not necessarily complex, but are usedregularly in a wide range of programs and can be a little tricky to get right.Modules that parse widely used data formats also fall under this type of modulethat the stdlib consists of.

While a new stdlib module does not need to appeal to all users of Python, itshould be something that a large portion of the community will find useful.This makes sure that the developer burden placed upon core developers is worthit.

Requirements¶

In order for a module to even be considered for inclusion into the stdlib, acouple of requirements must be met.

The most basic is that the code must meetstandard pull request requirements. For code that hasbeen developed outside the stdlib typically this means making sure the codingstyle guides are followed and that the proper tests have been written.

The module needs to have been out in the community for at least a year. Becauseof Python’s conservative nature when it comes to backwards-compatibility, whena module is added to the stdlib its API becomes frozen. This means that a moduleshould only enter the stdlib when it is mature and gone through its“growing pains”.

The module needs to be considered best-of-breed. When something is included inthe stdlib it tends to be chosen first for products over other third-partysolutions. By virtue of having been available to the public for at least ayear, a module needs to have established itself as (one of) the top choices bythe community for solving the problem the module is intended for.

The development of the module must move into Python’sinfrastructure (that is, the module is no longer directly maintained outside ofPython). This prevents a divergence between the code that is included in thestdlib and that which is released outside the stdlib (typically done to providethe module to older versions of Python). It also removes the burden of forcingcore developers to have to redirect bug reports or changes to an external issuetracker andVCS.

Someone involved with the development of themodule must promise to help maintain the module in the stdlib for two years.This not only helps out other core developers by alleviating workload from bugreports that arrive from the first Python release containing the module, butalso helps to make sure that the overall design of the module continues to beuniform.

Proposal process ¶

If the module you want to propose adding to the stdlib meets the requirements,you may propose its inclusionby following thePEP process.See PEP 1 for details,and thePEP index for previously-accepted PEPsthat have proposed a module for inclusion.

If the PEP is accepted, then the module will be added to the stdlibonce the authors of the module signcontributor agreements.

Adding a new environment variable¶

Names of environment variables should be uppercase and, from Python 3.13onwards, use underscores for readability and accessibility.

For example, usePYTHON_CPU_COUNT instead ofPYTHONCPUCOUNT.

Movatterモバイル変換

Adding to the stdlib¶