Python Patterns

Python Patterns

Overview

This skill curates the upstream python-patterns workflow from sickn33/antigravity-awesome-skills into a practical decision aid for real Python work.

Use it when the task is not “write some Python,” but “choose the right Python approach.” The core idea from upstream remains intact: teach decision-making, not pattern memorization.

This skill is strongest when the operator must decide among:

• sync vs async execution models
• threads vs processes vs in-process work
• framework or stack fit based on constraints
• where type hints add the most leverage
• how to structure a project around pyproject.toml, tests, and imports
• how to verify that a chosen pattern is actually working

Open the support files when needed:

• references/runtime-practices.md for decision matrices and failure modes
• examples/implementation-example.md for worked before/after scenarios
• scripts/validate-runtime.py to inspect a repository for layout, tooling, async, and subprocess risks

When to Use This Skill

Use this skill when:

• the user wants Python architecture guidance rather than a single code snippet
• the task involves framework selection, concurrency choices, typing strategy, packaging, or project layout
• the request asks whether a system should be async, typed, packaged, or reorganized
• the operator needs to justify tradeoffs, not just produce an implementation
• a repository should be checked for Python structure or runtime-pattern mismatches before changes are proposed

Do not use this skill as the primary router when:

• the task is language-agnostic system design with little Python-specific impact
• the user already chose the architecture and only needs feature implementation
• the work is mainly deployment, containerization, CI, or cloud operations rather than Python design

Operating Table

Workflow

1. Clarify the decision.

   • What is being chosen: framework, concurrency model, typing depth, layout, or background-task pattern?
   • What constraints matter: latency, throughput, CPU load, I/O wait, packaging needs, team familiarity, deployment model?

2. Classify the workload.

   • Mostly sequential business logic: start sync.
   • High I/O concurrency with async-capable dependencies: consider async.
   • Blocking I/O from libraries you cannot replace: consider thread offloading.
   • CPU-heavy work: consider processes or external workers.

3. Inventory the dependency stack.

   • Are the database, HTTP, messaging, and framework layers async-capable end to end?
   • Are there blocking SDKs that would negate async benefits?
   • Is this a package, an internal service, or a script repo?

4. Choose the smallest sound pattern.

   • Prefer the least complex model that fits the workload.
   • Do not adopt async only because it is modern.
   • Do not force src/ layout or heavy typing if the repo is a small script-only tool.

5. Define verification gates before implementation.

   • tests run in the intended import mode
   • lint/format checks run cleanly
   • type checking is applied where it adds signal
   • blocking calls are identified in async paths
   • performance claims are measured, not assumed

6. Implement or recommend with explicit tradeoffs. Include:

   • why this pattern was chosen
   • what alternative was rejected
   • what failure mode the choice avoids
   • how the team can verify the result

7. Validate the repository when relevant. Run:

   python scripts/validate-runtime.py .

   Then use the findings to refine the recommendation.

Decision Principles

1. Framework and stack selection

Do not rank frameworks generically. Choose based on constraints.

Prefer questions like:

• Does the app need high fan-out I/O concurrency?
• Are the core dependencies async-native?
• Is this a small internal service where simplicity matters more than concurrency features?
• Does the team need strong typing, validation, or admin tooling?
• Will the app be packaged and reused, or only deployed as one service?

A good answer names selection criteria and tradeoffs. A weak answer says “always use X.”

2. Async vs sync

Default to synchronous code unless there is a real need for structured I/O concurrency.

Use async when:

• the workload is I/O-bound
• the framework and key dependencies are async-capable
• request handlers would otherwise spend significant time waiting on sockets or similar external operations
• the team can debug event-loop behavior and cancellation correctly

Stay sync when:

• work is mostly CPU or straightforward request/response logic
• important libraries are blocking
• concurrency demands are low
• introducing async would create a mixed model with little benefit

Do not claim async is inherently faster. It is often better for coordinating many I/O-bound operations, not as a blanket performance upgrade.

3. Background work

Separate these cases clearly:

• small in-process follow-up work: safe only if it is brief, observable, and failure handling is explicit
• blocking I/O offload: use threads or executor-style offloading where appropriate
• CPU-heavy work: prefer processes or an external worker system
• durable long-running jobs: use an external queue/worker model rather than pretending in-request background tasks are reliable job infrastructure

If subprocesses are involved, prefer argument lists over shell command strings, validate inputs, and make timeouts explicit.