Python standard library

Everything under Lib/ is the pure-Python half of the standard library. It accounts for roughly 1.1 million of the ~2.2 million lines in this repository — the single largest body of code in the tree.

Top-level layout

The directory contains a mix of single-file modules and packages. A short tour:

Subtree	Theme
Lib/asyncio/	Event loop, transports, streams, protocols. Backed by Modules/_asynciomodule.c.
Lib/collections/	Counter, OrderedDict, defaultdict, deque (in C), abstract base classes.
Lib/concurrent/	concurrent.futures thread/process pool framework.
Lib/multiprocessing/	The cross-platform multi-process API. Backed by C in Modules/_multiprocessing/.
Lib/email/	RFC 2822 / MIME parsing and generation.
Lib/http/	http.client, http.server, http.cookies, http.cookiejar.
Lib/urllib/	URL parsing and the urllib.request HTTP client.
Lib/xml/	xml.etree.ElementTree, xml.dom, xml.sax. Backed by Modules/_elementtree.c and pyexpat.
Lib/json/	JSON. Pure-Python encoder; the C accelerator is Modules/_json.c.
Lib/importlib/	The import system itself (frozen at build time). See Import system.
Lib/logging/	Logging.
Lib/unittest/	The unittest framework, including mock.
Lib/test/	The standard test suite.
Lib/idlelib/	The IDLE Tk-based IDE.
Lib/turtledemo/	Turtle graphics demos.
Lib/encodings/	Codec definitions for every supported encoding.
Lib/_pyrepl/	The pure-Python "new" REPL added in 3.13.
Lib/sqlite3/	High-level wrapper around Modules/_sqlite/.
Lib/tkinter/	Pure-Python wrapper around Modules/_tkinter.c.
Lib/zipfile/, Lib/zoneinfo/, Lib/compression/, Lib/profiling/	Newer single-purpose packages.
Lib/pathlib/	Path and friends; significantly refactored in 3.13 to a layered design.
Lib/re/	The regex DSL parser; the engine itself is Modules/_sre/.
Lib/tomllib/	TOML 1.0 reader (added in 3.11; ports tomli).
Lib/venv/	python -m venv.
Lib/profile.py, Lib/pstats.py	Profiling tools. Statistical sampler now lives under Lib/profiling/ too.

Everything else is a single-file Lib/<name>.py. The full alphabetical list lives in Doc/library/.

Pure-Python and C parity

A recurring pattern: a stdlib module ships with a pure-Python implementation and a C accelerator, and the public module re-exports the C version when available:

Module	Pure Python	C accelerator
io	Lib/_pyio.py	Modules/_io/
datetime	Lib/_pydatetime.py	Modules/_datetimemodule.c
decimal	Lib/_pydecimal.py	Modules/_decimal/
pickle	Lib/pickle.py	Modules/_pickle.c
json	Lib/json/	Modules/_json.c
int/long (Python ↔ C bridges)	Lib/_pylong.py	Objects/longobject.c
warnings	Lib/_py_warnings.py	Python/_warnings.c
abc	Lib/_py_abc.py	Modules/_abc.c
csv	(no pure variant) — wrapper in Lib/csv.py	Modules/_csv.c

The pure-Python copy serves three purposes: (1) reference implementation for spec questions, (2) fallback for builds without the C module, and (3) something readable when reviewing PRs that affect both. Behavioural changes are required to keep both versions in sync — this is a recurring source of CI failures.

Conventions in Lib/

• No third-party imports. Anything in Lib/ may only import from the standard library and from compiled extension modules in Modules/. Vendored copies are in Lib/_<package>/_vendor/ (e.g. tomllib used to vendor tomli).
• __all__ for public modules. It controls from foo import * and is the contract for "what is public".
• Underscore-prefixed modules are private. Lib/_pylong.py, Lib/_pyrepl/, Lib/_strptime.py are not part of the public API.
• Lazy imports for heavy modules. Stdlib code should defer imports of expensive modules (xml, email, unittest) until they're needed.
• from collections.abc import ..., not from collections. The latter has been deprecated for ABCs for many releases.
• Ruff-compliant. Lib/.ruff.toml — actually configured at the repo root — defines what lints apply.
• Python compatibility. The stdlib targets the same minimum Python version as the interpreter it ships with — but it must also be importable by the previous minor release's bytecode (used during the bootstrap). That's why you'll occasionally see slightly conservative syntax.

How a stdlib module is added or changed

The full procedure is in Development workflow. The stdlib-specific rules:

1. If you add a new public module, it needs:
   • An entry in Doc/library/<name>.rst.
   • An entry in Doc/whatsnew/3.X.rst.
   • A Misc/NEWS.d/next/Library/... blurb.
   • Tests under Lib/test/test_<name>.py.
2. If you remove or deprecate a module, it needs an entry in Doc/deprecations/.
3. Big changes (new module, large API additions) usually go through a PEP or at least a Discourse thread.

Test layout

Lib/test/ is its own package and uses regrtest. A few subdirectories worth knowing:

• Lib/test/support/ — testing helpers (resource gating, temp files, requirement skips). See Testing.
• Lib/test/test_capi/ — Python tests of the C API (paired with _testcapi, _testlimitedcapi, _testinternalcapi).
• Lib/test/libregrtest/ — the regrtest harness itself.
• Lib/test/test_<feature>/ — tests grouped into a package when there are many of them (e.g. test_email/, test_typing.py is the legacy single-file form, test_clinic.py ditto).
• Lib/test/data/ — fixtures.

Documentation

The .rst source for the user-facing library reference is in Doc/library/. Every public stdlib member has an entry there. The C-API documentation is in Doc/c-api/ and reusable-check-c-api-docs.yml verifies that every public C symbol shows up.