---
name: python-performance
description: Profile and optimize Python CPU, memory, I/O, concurrency, and numerical performance.
---

# Python Performance

Name the metric first: wall time, CPU time, allocation count, retained heap,
peak RSS, or I/O wait. Pin Python, dependencies, input, and environment; then
change one profiled cause.

## Measurement

- Use `pyperf` for repeatable benchmarks with calibration, worker processes,
  metadata, and statistical comparison.
- Use `timeit` only for small fragments. It disables cyclic GC during timing
  unless explicitly re-enabled, which can make allocation-heavy code look
  unlike production.
- Use `cProfile` for call counts and cumulative development profiles; use a
  sampling profiler such as `py-spy` for lower-overhead process observation.
- Use `tracemalloc` for Python-managed allocations. If RSS grows while its
  traces remain stable, inspect native allocations or fragmentation with
  Memray or an OS profiler.
- `sys.getsizeof` is shallow; it does not measure referenced objects.
- Use `python -X importtime` before changing startup imports.

## Data structures and Python operations

Choose from access patterns:

| Need | Prefer |
|---|---|
| Membership or deduplication | `set` or `dict`, not repeated list scans |
| Queue operations at both ends | `collections.deque`, not `list.pop(0)` |
| Priority queue | `heapq` |
| Search in maintained sorted data | `bisect` |
| Mutable binary accumulation | `bytearray`, then `bytes(buffer)` |
| Many string fragments | collect fragments and `"".join(parts)` |

These choices change semantics and memory. Do not replace a list when callers
need indexing, slicing, or compact iteration.

Generators avoid eager materialization but add iteration overhead and cannot be
reused. Built-ins and comprehensions often move work into optimized C loops,
but they are not automatically faster for every workload.

`lru_cache` trades CPU for retained memory and invalidation. On an instance
method, cache keys retain `self`; avoid it when instances must be collected.
`@dataclass(slots=True)` or `__slots__` can reduce memory for many instances but
affects dynamic attributes, inheritance, weak references, serialization, and
framework integration.

## Memory and GC

CPython uses reference counting plus cyclic GC. Distinguish:

- growing Python allocation traces;
- retained reachable objects;
- native allocations;
- allocator fragmentation;
- peak RSS;
- allocation churn that increases CPU without retaining memory.

High RSS alone is not a leak. Tune GC thresholds, call `gc.freeze()`, or change
allocators only after pause, allocation, or copy-on-write measurements identify
the collector or allocator as the cause. GC defaults differ by Python version
and free-threaded build.

## Threads, asyncio, and processes

- Threads overlap many blocking I/O operations because those calls release the
  GIL. Pure-Python CPU threads do not execute bytecode in parallel under the
  normal GIL; native extensions may release it.
- `asyncio` is cooperative concurrency. Any blocking call or long CPU loop in a
  coroutine stalls the event loop. Use bounded queues when producers can outrun
  consumers, and preserve cancellation and shutdown.
- Processes provide CPU parallelism but add startup, pickling, IPC, memory, and
  failure handling. Include all of those in the benchmark.
- Start methods vary by platform and Python version. Libraries should not force
  a global method without owning application lifecycle.
- Free-threaded CPython enables parallel Python threads but adds evolving
  overhead, synchronization requirements, and extension compatibility. Test the
  exact interpreter and dependency set.

## I/O and services

- Use buffering for repeated small reads and writes. `readinto()` can reuse a
  buffer in measured binary pipelines but adds ownership complexity.
- Batch database and network operations to reduce round trips. Oversized
  batches increase memory, lock duration, tail latency, and retry scope.
- Avoid constructing expensive log messages when the level is disabled. Queue
  handlers move slow output off latency-sensitive threads but require bounded
  capacity, ordering, loss, and shutdown decisions.
- Preserve flush, EOF, error, retry, ordering, cancellation, and protocol
  behavior when optimizing I/O.

## NumPy and native acceleration

- Chained NumPy operations can allocate full-size temporaries. Use `out=`,
  in-place operations, chunking, or fused kernels only after CPU and memory
  profiles show the temporary matters.
- Check contiguity and strides when native kernels copy or traverse arrays
  poorly. Normalize layout once at a boundary, not repeatedly in a loop.
- BLAS, process pools, application threads, and runtimes can each create worker
  pools. Measure oversubscription before limiting them with `threadpoolctl` or
  environment settings.
- Warm Numba before benchmarking. It helps supported Python-loop work, not code
  already dominated by optimized NumPy kernels.
- Cython, PyO3/Rust, GPU code, and alternative runtimes add compilation,
  transfer, ABI, packaging, debugging, and maintenance. Batch enough work per
  boundary crossing to justify them and keep a tested Python path when useful.

## CPython specialization

Use `dis.dis(fn, adaptive=True)` after warm-up as supporting evidence for a hot
loop. Do not redesign APIs to preserve one specialized opcode; specialization
rules change between versions. Re-measure after Python upgrades.

## Regression guards

Use narrow allocation, output-size, startup, or memory guards when the
toolchain and platform are pinned. Wall-time gates require dedicated hardware
or enough margin to avoid flaking; keep shared-runner timing advisory. Never
compare runs with different GC modes, profilers, hooks, or calibration.

## Related skills

- `code-review` checks a completed diff. When invoked from `code-review`, do not
  invoke it again.
- `code-simplifier` runs after the gain is proven.
- `change-impact-auditor` traces environment, serialization, imports, logging,
  and concurrency changes.
- `runtime-process-debugging` owns subprocess, pipe, lifecycle, and shutdown
  failures.

Correctness overrides performance.