Stas' Python Cookbook

Distilled from Stas' Python Cookbook open book by Stas Bekman - source: https://github.com/stas00/python-cookbook (CC BY-SA 4.0). This skill is a condensed index; each section links back to the full chapter for depth, runnable snippets, and gotchas.

A practical, standard-library-first reference for the Python idioms that come up again and again in real work. It leads with the why, shows the how with copy-paste snippets, and calls out the gotchas that bite in practice. Targets Python 3.8+; version-specific features are flagged inline. For deep single-process/tool debugging (gdb, strace, py-spy, core files, CUDA) pair this with The Art of Debugging.

Core principles

• Reach for the standard library first. A third-party package is only suggested when the stdlib genuinely falls short - and it's flagged with pip install.
• Prefer the modern idiom. f-strings over %/.format(), pathlib over os.path, subprocess.run over os.system, dataclasses over ad-hoc tuples, logging over print in real programs.
• Know the gotcha before it bites. Mutable default arguments, shallow vs deep copy, pass-by-object-reference, naive vs aware datetimes, the GIL - each chapter flags the trap.
• Read the linked section before applying a recipe - each has worked examples, caveats, and edge cases the one-liner here omits.

Part I - Language core

Full chapters: Strings · Formatting · Numbers · Regex.

• Text wrangling: case/containment/split/join/strip/replace, encoding-decoding, and a worked text-normalization example. Compare strings with a readable diff. See Strings and Text.
• Formatting: the format spec mini-language (alignment, padding, precision, ,/_ grouping), f-string tricks (= debug, nested specs), and number/byte humanization. See String Formatting.
• Numbers/math: rounding traps, decimal/fractions, statistics without NumPy, and special values (nan/inf). See Numbers and Math.
• Regex: the core functions, flags, groups/assertions, substitution with backreferences/callables, splitting, and escaping literals. See Regular Expressions.

Part I - Data structures

Full chapters: Lists · Tuples · Sets · Dictionaries · Comprehensions/itertools.

• Lists: add/remove, shallow vs deep copy (a classic bug source), slicing/splicing, searching/aggregating, chunking, and ranges. See Lists.
• Tuples & sets: immutability and namedtuples (Tuples); set algebra and mutation (Sets).
• Dictionaries: construction/merging (|), access with defaults, defaultdict, Counter, transformations, and dataclasses for structured records. See Dictionaries.
• Comprehensions & iterators: list/dict/set/generator forms, the essential itertools, flatten/zip/unzip, and generators with yield for streaming. See Comprehensions, Iterators and itertools.

Part I - Functions, classes, time

Full chapters: Functions · Classes · Dates.

• Functions: *args/**kwargs, the mutable-default-argument trap, pass-by-object-reference, closures, functools (partial/lru_cache/reduce), and decorators. See Functions.
• Classes: dunder methods, inheritance, dynamic attributes/delegation, importing a class from a string, and context managers. See Classes and Objects.
• Dates/times: parsing/formatting, always use timezone-aware datetimes, durations, and measuring elapsed time. See Dates and Times.

Part II - Runtime & environment

Full chapters: Modules · Files/IO · Env & args · Subprocess.

• Modules/imports: how sys.path resolves imports, inspecting/reloading modules, and dynamic import. See Modules and Imports.
• Files/paths/IO: pathlib basics, metadata, create/move/delete, globbing, reading/writing, and temp files/dirs. See Files, Paths and I/O.
• Env vars & CLI: reading environment variables safely, argparse, and replaying the exact command line. See Environment Variables and Program Arguments.
• Subprocess: run external commands with subprocess.run (capture output, check errors, avoid shell=True pitfalls) instead of os.system. See Subprocess and Shell Integration.

Part II - Data, concurrency, network

Full chapters: Serialization · Concurrency · Networking.

• Serialization: JSON (custom encoders, streaming), CSV, pickle (and its security caveat), gzip, memory-safe streaming XML, and archives. See Serialization.
• Concurrency: the GIL and when to use processes vs threads, process pools, the unified concurrent.futures API, and background monitoring threads. See Concurrency.
• Networking: sockets/ports and HTTP with requests. See Networking.

Part III - Debugging, profiling & testing

Full chapters: Logging · Debugging · Introspection · Profiling · Exceptions · Testing.

• Output control: print to stderr, unbuffered output, tee to console+file, logging over print for real programs, and warnings. See Printing, Logging and Output Control.
• Debugging: the interactive debugger (breakpoint()/pdb), debugging forked/multiprocess code, getting a traceback out of a stuck or crashed process, programmatic stack traces, and tracing execution. See Debugging.
• Introspection: what is this thing? (type/dir/inspect), dumping an object's attributes, and prettier dumps. See Introspection and Object Inspection.
• Profiling: timeit for micro-benchmarks, cProfile for function-level CPU, line_profiler for per-line, tracemalloc for memory, psutil for process RSS, and leak-finding. See Profiling CPU and Memory.
• Exceptions: raising/catching precisely, re-raising and chaining (from), custom exceptions, and good habits (never bare-except). See Exceptions and Error Handling.
• Testing: pytest basics, fixtures, capturing output, parallel/slow-test control, and unittest. See Testing with pytest and unittest.

Part IV - Packaging & tooling

Full chapters: Versions/Deps · Packaging · Code quality · Big data · Appendix.

• Versions/deps: check the running Python version, query installed package versions, compare versions correctly (not string compare), and virtual environments. See Versions and Dependencies.
• Packaging: generate a requirements file from imports and modern packaging with pyproject.toml. See Packaging and Requirements.
• Code quality: formatters/linters (black/ruff) and type checking. See Code Quality and Formatting.
• Scaling pointers & one-liners: when to reach past the stdlib (Big Data) plus handy shell one-liners, recursion limits, and human-readable tables (Appendix).

Pick the recipe by need

Need	Reach for
Format a number/string cleanly	format spec mini-language, f-string tricks
Match/extract/replace text	Regular Expressions
Count / group / default values	Counter, defaultdict
Structured record type	dataclasses
Stream/lazily process data	generators & itertools
Work with files/paths	pathlib
Parse CLI arguments	argparse
Run an external command	subprocess.run
Read/write JSON/CSV/gzip	Serialization
Parallelize work	concurrent.futures (mind the GIL)
Real logging (not print)	logging
Code is too slow	cProfile/timeit/line_profiler
Memory keeps growing	tracemalloc/psutil
A stuck/crashed process	get a traceback out of it
Write/run tests	pytest & unittest
Compare version strings	compare versions correctly
Package/pin a project	pyproject.toml, requirements

Notes for AI agents

• Prefer the stdlib and the modern idiom (f-strings, pathlib, subprocess.run, dataclasses, logging) unless the user's environment dictates otherwise; only add a dependency when the stdlib truly can't do it.
• Watch the flagged gotchas - mutable default args, shallow vs deep copy, pass-by-object-reference, naive datetimes, shell=True, bare except, string version comparison - before shipping a snippet.
• Measure before optimizing: profile with cProfile/timeit/tracemalloc rather than guessing which line is slow or leaky.
• Read the linked chapter section before applying an unfamiliar recipe - each has worked examples, caveats, and copy-paste code the index line omits.
• Note the target version (3.8+ baseline); guard newer-only features (| dict merge, str.removeprefix, zoneinfo, structural pattern matching) when portability matters.
• For deep runtime debugging of a crash/hang/segfault/OOM (gdb, strace, py-spy, core files, CUDA), use the companion skill: The Art of Debugging.