Codexer

Codexer - Python Research Assistant

Expert Python researcher with 10+ years of software development experience. Conducts thorough research using Context7 MCP servers while prioritizing speed, reliability, and clean code practices.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• Conducting library research and evaluation for Python projects
• Fetching documentation via Context7 MCP tools
• Enforcing strict Python coding standards and quality gates
• Building research workflows with web search and Context7 integration
• Evaluating dependencies for maintenance, security, and performance
• Implementing production-ready Python code with proper error handling

---

Available Tools Configuration

Context7 MCP Tools

• resolve-library-id: Resolves library names into Context7-compatible IDs
• get-library-docs: Fetches documentation for specific library IDs

Web Search Tools

• #websearch: Built-in VS Code tool for web searching
• Copilot Web Search Extension: Enhanced web search requiring Tavily API keys

VS Code Built-in Tools

• #think: For complex reasoning and analysis
• #todos: For task tracking and progress management

---

Python Development Standards

Environment Management

• ALWAYS use venv or conda environments
• Create isolated environments for each project
• Dependencies go into requirements.txt or pyproject.toml with pinned versions

Code Quality Rules

Readability:

• Follow PEP 8: 79 char max lines, 4-space indentation
• snake_case for variables/functions, CamelCase for classes
• Single-letter variables only for loop indices (i, j, k)
• No meaningless names like data, temp, stuff

Structure:

• Functions do ONE thing each, max 50 lines
• Modularize into utils/, models/, tests/
• Avoid global variables

Error Handling:

• Use specific exceptions (ValueError, TypeError) not generic Exception
• Fail fast with meaningful messages
• Use context managers (with statements)

Performance:

• Type hints are mandatory via typing module
• Profile before optimizing with cProfile or timeit
• Use built-ins: collections.Counter, itertools.chain, functools
• List comprehensions over nested for loops

Quality Gates

• Must pass black, flake8, mypy
• All public functions need docstrings
• No try: except: pass
• Organized imports: standard → third-party → local

Instant Rejection Criteria

• Any function >50 lines
• Missing type hints
• Global variables
• No docstrings for public functions
• Hardcoded strings/numbers without constants
• Nested loops >3 levels deep

---

Research Workflow

Phase 1: Planning & Web Search

1. Use #websearch for initial research and discovery 2. Use #think to analyze requirements and plan approach 3. Use #todos to track research progress

Phase 2: Library Resolution

1. Use resolve-library-id to find Context7-compatible library IDs 2. Cross-reference with web search for official documentation 3. Identify the most relevant and well-maintained libraries

Phase 3: Documentation Fetching

1. Use get-library-docs with specific library IDs 2. Focus on installation, API reference, best practices 3. Extract code examples and implementation patterns

Phase 4: Analysis & Implementation

1. Use #think for complex reasoning and solution design 2. Write clean, performant Python code following standards 3. Implement proper error handling and logging

---

Anti-Patterns

• Delegating or evaluating without a scoped success condition: The output becomes hard to review and easy to overbuild.
• Skipping the evidence step: A workflow that cannot be re-checked quickly is not ready for handoff.
• Bundling unrelated subtasks together: It creates noisy prompts, weaker ownership, and avoidable integration risk.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Codexer workflow names the agent boundary, delegated scope, and expected return artifact. 2. Pass/fail: Context passed to helpers is minimal, task-local, and free of hidden expected answers. 3. Pass/fail: Results are integrated only after evidence, diffs, or citations are checked by the controller. 4. Pressure-test scenario: Run the workflow on two similar tasks that must not share assumptions or leaked context. 5. Success metric: Zero context leakage; every delegated output is independently reviewable.

Research Templates

Library Research

Research Question: [Specific library or technology]
1. #websearch for official documentation and GitHub repos
2. #think to analyze initial findings
3. resolve-library-id libraryName="[library-name]"
4. get-library-docs context7CompatibleLibraryID="[resolved-id]" tokens=5000
5. Analyze API patterns and implementation examples
6. Identify best practices and common pitfalls

Problem-Solution Research

Problem: [Specific technical challenge]
1. #websearch for multiple library solutions
2. #think to compare strategies and performance
3. Context 7 deep-dive into promising solutions
4. Implement clean, efficient solution
5. Test reliability and edge cases

---

Implementation Guidelines

Good Pattern

from typing import List, Dict
import logging
import collections

def count_unique_words(text: str) -> Dict[str, int]:
    """Count unique words ignoring case and punctuation."""
    if not text or not isinstance(text, str):
        raise ValueError("Text must be non-empty string")

    words = [word.strip(".,!?").lower() for word in text.split()]
    return dict(collections.Counter(words))

Bad Pattern (Never Do This)

def process_data(data):  # No type hints, vague naming
    result = []
    for item in data:
        result.append(item * 2)  # Magic multiplication
    return result

Pythonic Principles

# Variable swapping
a, b = b, a

# List comprehension over loops
squares = [x**2 for x in range(10)]

# Use built-in power tools
from collections import Counter, defaultdict
from itertools import chain

all_items = list(chain(list1, list2, list3))
word_counts = Counter(words)

---

Dependency Evaluation Criteria

• Check maintenance status (last commit date, open issues)
• Review security vulnerability databases
• Assess bundle size and import overhead
• Verify license compatibility
• If >1000 GitHub stars and recent commits, probably safe

---

File Structure Standard

project/
├── src/              # Application code
├── tests/            # Test suite
├── docs/             # Documentation
├── requirements.txt  # Pinned dependency versions
└── pyproject.toml    # Project metadata

---

Security Standards

• API keys in environment variables, never hardcoded
• Use logging module, not print()
• Don't log passwords, tokens, or user data
• Sanitize all inputs
• Use bleach for HTML sanitization

---

Final Execution Protocol

1. Ask user: "Would you like me to generate test scripts?" 2. Export dependencies: pip freeze > requirements.txt 3. Provide summary of implementation and caveats 4. Validate solution runs and produces expected results

Source Priority for Research

1. Official documentation (Python.org, library docs) 2. GitHub repositories with high stars/forks 3. Stack Overflow with accepted answers 4. Technical blogs from recognized experts 5. Academic papers for theoretical understanding

---

## References & Resources

### Documentation
- [Python Libraries Guide](./references/python-libraries-guide.md) — Library evaluation criteria, selection checklist, and essential libraries by category
- [Context7 Usage](./references/context7-usage.md) — Context7 MCP integration reference with query patterns and workflows

### Scripts
- [Quality Gate](./scripts/quality-gate.py) — Python quality gate checker for type hints, docstrings, imports, and PEP 8

### Examples
- [Research Workflow](./examples/research-workflow.md) — Complete research workflow example comparing Python HTTP client libraries


---

<!-- PORTABILITY:START -->
## Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

- GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
- Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
- Codex: install or sync the folder into `$CODEX_HOME/skills/<skill-name>` and restart Codex after major changes.
- Gemini CLI: this repository generates a project command named `/skills:codexer` from this skill. Rebuild commands with `python scripts/export-gemini-skill.py codexer` and then run `/commands reload` inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->
## MCP Availability And Fallback

Preferred MCP Server: Context7 MCP

- Fallback prompt: "Use the Codexer - Python Research Assistant skill without MCP. Rely on the local `SKILL.md`, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
- Use the official package documentation, changelogs, and release notes directly when Context7 is unavailable.
- Confirm installed package behavior locally with the language toolchain, `--help`, or small reproducible examples.

<!-- MCP:END -->

## Related Skills

- [agent-task-mapping](../agent-task-mapping/SKILL.md): Use it when the workflow also needs task-to-agent routing decisions.
- [custom-agent-usage](../custom-agent-usage/SKILL.md): Use it when the workflow also needs loading and invoking custom agent definitions safely.
- [subagent-delegation](../subagent-delegation/SKILL.md): Use it when the workflow also needs safe, scoped delegation to helper agents.
- [subagent-driven-development](../subagent-driven-development/SKILL.md): Use it when the workflow also needs plan-driven implementation with reviewer loops.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

[2026-04-24] - Verification Follow-Up

Fixed

• Moved the Anti-Patterns section ahead of the research templates so the warning section now appears before the skill’s examples.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.

[2026-04-24] - Catalog Audit Cleanup

Fixed

• Removed obsolete standalone Skill Paths guidance that duplicated the generated portability section.

All notable changes to this skill will be documented in this file.

[2026-04-04] - Cross-Client Portability Refresh

Changed

• Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Documented the preferred MCP server surface for this skill and a local no-MCP fallback workflow.

Tested

• Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Changed

• Removed duplicated related-skill content from SKILL.md to reduce noise

[2026-02-28] — Description Rewrite & Cross-References

Changed

• Rewrote skill description to ~200 characters with clear, specific activation keywords
• Improved keyword specificity to reduce overlap with related skills

Added

• ## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

Python Diagram Generation Patterns (Graphviz)

Python patterns for generating ER diagrams and flowcharts with Graphviz, tailored for the Recipe Sharing System diagram scripts.

Use Case

This project uses Python for diagram generation only (ER models, data flow, and flowcharts).

Recommended Stack

• Python 3.11+
• graphviz Python package
• Graphviz system binary installed and in PATH

pip install graphviz

Basic Graphviz Flowchart

from graphviz import Digraph


def generate_app_flowchart(output_path: str = "application_flowchart") -> None:
    graph = Digraph("RecipeSharingFlow", format="png")
    graph.attr(rankdir="LR", fontsize="12")

    graph.node("U", "User", shape="oval")
    graph.node("F", "React Frontend", shape="box")
    graph.node("A", "PHP API", shape="box")
    graph.node("D", "MySQL Database", shape="cylinder")

    graph.edge("U", "F", label="interact")
    graph.edge("F", "A", label="HTTP/JSON")
    graph.edge("A", "D", label="SQL")
    graph.edge("D", "A", label="result")
    graph.edge("A", "F", label="JSON response")

    graph.render(output_path, cleanup=True)


if __name__ == "__main__":
    generate_app_flowchart()

ER Logical Diagram Pattern

from graphviz import Digraph


def add_entity(graph: Digraph, name: str, fields: list[str]) -> None:
    label = "{\n" + name + "|\n" + "\n".join(fields) + "\n}"
    graph.node(name, label=label, shape="record")


def generate_er_logical(output_path: str = "er_logical") -> None:
    graph = Digraph("ERLogical", format="png")
    graph.attr(rankdir="LR")

    add_entity(graph, "user", [
        "id (PK)",
        "username",
        "email",
        "password_hash",
        "role",
        "status",
        "created_at",
        "updated_at",
    ])

    add_entity(graph, "recipe", [
        "id (PK)",
        "title",
        "description",
        "category",
        "difficulty",
        "author_id (FK -> user.id)",
        "status",
        "created_at",
        "updated_at",
    ])

    add_entity(graph, "review", [
        "id (PK)",
        "user_id (FK -> user.id)",
        "recipe_id (FK -> recipe.id)",
        "rating",
        "comment",
        "created_at",
        "updated_at",
    ])

    graph.edge("user", "recipe", label="1:N", arrowhead="crow")
    graph.edge("user", "review", label="1:N", arrowhead="crow")
    graph.edge("recipe", "review", label="1:N", arrowhead="crow")

    graph.render(output_path, cleanup=True)


if __name__ == "__main__":
    generate_er_logical()

Diagram Generation Best Practices

• Keep node IDs stable for diff-friendly output.
• Separate diagram structure from rendering function.
• Use helper functions (add_entity, add_relation) for consistency.
• Generate to a deterministic path under python_diagrams/.
• Keep labels concise; put full docs in markdown.

File Organization Pattern

python_diagrams/
  data_flow_graphviz.py
  er_recipe_conceptual_graphviz.py
  er_recipe_logical_graphviz.py
  flowchart_graphviz.py

CLI Entrypoint Pattern

import argparse


def main() -> None:
    parser = argparse.ArgumentParser(description="Generate Recipe Sharing diagrams")
    parser.add_argument("--type", choices=["flow", "er-logical", "er-conceptual"], required=True)
    parser.add_argument("--output", default="diagram")
    args = parser.parse_args()

    if args.type == "flow":
        generate_app_flowchart(args.output)
    elif args.type == "er-logical":
        generate_er_logical(args.output)
    else:
        generate_er_conceptual(args.output)


if __name__ == "__main__":
    main()

Common Issues

Graphviz executable not found

• Error: ExecutableNotFound: failed to execute 'dot'
• Fix: install Graphviz and add dot binary to PATH.

Unicode rendering issues

• Set font explicitly in graph attributes:

graph.attr(fontname="Arial")
graph.node_attr.update(fontname="Arial")
graph.edge_attr.update(fontname="Arial")

Output file not updating

• Use cleanup=True in render().
• Ensure output path is writable.

References

• Python docs: https://docs.python.org/3/
• Graphviz package: https://graphviz.readthedocs.io/
• Graphviz DOT language: https://graphviz.org/doc/info/lang.html

Example Research Workflow: Evaluate & Select a Python HTTP Client Library

Scenario

"I need an HTTP client for a Python async service that makes external API calls.

It should support both sync testing and async production use, have good typing,

and be actively maintained."

---

Phase 1: Planning & Web Search

1.1 Define Requirements

1.2 Identify Candidates

From ecosystem knowledge and web search:

1. httpx — Modern async/sync client, requests-compatible API 2. requests — The classic sync HTTP library 3. aiohttp — Mature async HTTP client and server

1.3 Preliminary Comparison

Decision: requests is eliminated (no async). Deep-dive httpx vs aiohttp.

---

Phase 2: Library Resolution (Context7)

2.1 Resolve Library IDs

resolve-library-id(libraryName: "python httpx")
→ { id: "/python/encode/httpx", name: "httpx", ... }

resolve-library-id(libraryName: "python aiohttp")
→ { id: "/python/aio-libs/aiohttp", name: "aiohttp", ... }

2.2 Key Observations from Resolution

• Both libraries are indexed with good documentation coverage
• httpx is under the Encode organization (also maintains Starlette, uvicorn)
• aiohttp is under aio-libs (also maintains aiohttp-cors, aiosignal)

---

Phase 3: Documentation Fetching & Deep Comparison

3.1 Fetch Targeted Documentation

get-library-docs(
  context7CompatibleLibraryID: "/python/encode/httpx",
  topic: "async client and connection pooling",
  tokens: 4000
)

get-library-docs(
  context7CompatibleLibraryID: "/python/aio-libs/aiohttp",
  topic: "client session and connection pooling",
  tokens: 4000
)

3.2 Feature Deep-Dive

httpx Async Client Usage (from docs)

import httpx

# Async with connection pooling via client context manager
async with httpx.AsyncClient(
    base_url="https://api.example.com",
    timeout=httpx.Timeout(10.0, connect=5.0),
    limits=httpx.Limits(max_connections=100, max_keepalive_connections=20),
) as client:
    response = await client.get("/users", params={"page": 1})
    response.raise_for_status()
    data = response.json()

aiohttp Client Session Usage (from docs)

import aiohttp

# Async with connection pooling via session
connector = aiohttp.TCPConnector(limit=100, limit_per_host=20)
timeout = aiohttp.ClientTimeout(total=10, connect=5)

async with aiohttp.ClientSession(
    base_url="https://api.example.com",
    connector=connector,
    timeout=timeout,
) as session:
    async with session.get("/users", params={"page": 1}) as response:
        response.raise_for_status()
        data = await response.json()

3.3 Detailed Comparison

3.4 Benchmark Considerations

• Raw throughput: aiohttp has a slight edge in benchmarks for high-concurrency scenarios due to its C-accelerated parser
• For typical API client use (not server), the difference is negligible
• httpx's HTTP/2 multiplexing can outperform HTTP/1.1 connection pooling for certain upstream APIs

---

Final Recommendation

Winner: httpx

Rationale

1. Dual sync/async API — Single dependency for both production (async) and scripting/testing (sync), reducing cognitive overhead and dependency sprawl

2. Type annotations — Ships with py.typed marker and complete annotations, satisfying our mypy strict requirement without third-party stubs

3. HTTP/2 support — Optional but available when needed, future-proofing against upstream API migrations

4. requests-compatible API — Minimal learning curve for the team, easy migration from existing requests-based code

5. Testing story — MockTransport allows deterministic testing without mocking internals, pairs well with respx for higher-level mocking

6. Active maintenance — Encode team maintains the full async Python web stack (Starlette, uvicorn, httpx), ensuring coherent ecosystem evolution

When to Choose aiohttp Instead

• WebSocket client requirements (built into aiohttp)
• Need a combined HTTP client + server in one package
• Existing aiohttp codebase with established patterns
• Maximum raw throughput in extreme concurrency scenarios (10k+ concurrent connections)

Recommended Setup

# pyproject.toml
[project]
dependencies = [
    "httpx>=0.28,<1.0",
    "httpx[http2]",  # optional HTTP/2 support
]

[project.optional-dependencies]
test = [
    "respx>=0.22",  # HTTP mocking for httpx
    "pytest-asyncio>=0.24",
]

# src/http_client.py
import httpx

DEFAULT_TIMEOUT = httpx.Timeout(timeout=30.0, connect=10.0)
DEFAULT_LIMITS = httpx.Limits(
    max_connections=100,
    max_keepalive_connections=20,
)

def create_client(**kwargs) -> httpx.AsyncClient:
    """Create a configured async HTTP client."""
    return httpx.AsyncClient(
        timeout=kwargs.pop("timeout", DEFAULT_TIMEOUT),
        limits=kwargs.pop("limits", DEFAULT_LIMITS),
        **kwargs,
    )

Context7 MCP Integration Reference

Overview

Context7 provides up-to-date library documentation via two MCP tools: 1. resolve-library-id — Resolves a library/package name into a Context7-compatible library ID 2. get-library-docs — Fetches documentation using the resolved library ID

Always resolve first, then fetch. Never guess library IDs.

---

Tool 1: resolve-library-id

Purpose

Converts a human-readable library name into the internal Context7 library ID required by get-library-docs.

How It Works

• Analyzes the query to match against known libraries
• Ranks results by: name similarity, description relevance, documentation coverage, source reputation, benchmark scores
• Returns a list of candidate matches with IDs and confidence scores

Parameters

Query Best Practices

Be specific with the ecosystem:

Good:  "python pandas"
Bad:   "pandas"          (could be confused with other ecosystems)

Include the language when ambiguous:

Good:  "javascript express"
Good:  "python flask"
Bad:   "flask"            (usually fine, but explicit is better)

Use the canonical package name:

Good:  "python pydantic"
Bad:   "python data validation"   (too generic)

For scoped packages, use full name:

Good:  "typescript @tanstack/react-query"
Good:  "python scikit-learn"

Response Handling

• Results are ranked by relevance — pick the top match unless context dictates otherwise
• If multiple results appear (e.g., pandas vs pandas-stubs), choose based on your goal
• Store the resolved ID for subsequent get-library-docs calls

---

Tool 2: get-library-docs

Purpose

Fetches up-to-date documentation for a library using its Context7 ID.

Parameters

Usage Patterns

General documentation:

get-library-docs(
  context7CompatibleLibraryID: "/python/pandas",
  tokens: 5000
)

Topic-focused:

get-library-docs(
  context7CompatibleLibraryID: "/python/fastapi",
  topic: "dependency injection",
  tokens: 3000
)

Minimal lookup:

get-library-docs(
  context7CompatibleLibraryID: "/python/pydantic",
  topic: "model validators",
  tokens: 1500
)

Token Budget Guidelines

• Quick reference (API signature, single concept): 1000–2000 tokens
• Feature overview (multiple related concepts): 3000–5000 tokens
• Comprehensive guide (full API surface): 8000–10000 tokens
• Larger budgets return more content but cost more context window space

---

Standard Workflow: Resolve Then Fetch

Step 1: Resolve

resolve-library-id(libraryName: "python httpx")
→ Returns: { id: "/python/encode/httpx", ... }

Step 2: Fetch

get-library-docs(
  context7CompatibleLibraryID: "/python/encode/httpx",
  topic: "async client usage",
  tokens: 3000
)
→ Returns: Documentation content about async client patterns

Step 3: Apply

Use the returned documentation to:

• Answer user questions with current API details
• Generate code using up-to-date patterns
• Verify deprecated vs current approaches
• Cross-reference version-specific behavior

---

Edge Cases & Troubleshooting

Library Not Found

Symptoms: resolve-library-id returns empty or no confident matches.

Recovery strategies: 1. Try alternate names: scikit-learn vs sklearn, Pillow vs PIL 2. Add ecosystem prefix: "python requests" instead of "requests" 3. Use the PyPI package name exactly: "python-dateutil" not "dateutil" 4. For newer libraries, documentation may not be indexed yet — fall back to web search

Ambiguous Names

Symptoms: Multiple results with similar confidence scores.

Resolution:

• Add context: "python click CLI" to disambiguate from other click packages
• Check the description field in results to identify the correct library
• When in doubt, pick the result with higher documentation coverage

Stale Documentation

Symptoms: Returned docs reference outdated API or missing new features.

Mitigation:

• Specify the topic precisely to get the most relevant (likely updated) section
• Cross-reference with the library's official changelog
• Use web search as a fallback for brand-new features

Rate Limiting / Timeouts

• Space out rapid successive calls
• Cache resolved library IDs within a session (they don't change frequently)
• Use smaller token budgets when you only need a quick answer

---

Example Queries for Popular Libraries

Python Web

resolve-library-id("python fastapi")
get-library-docs(id, topic: "path parameters and query parameters")

resolve-library-id("python django")
get-library-docs(id, topic: "class-based views")

resolve-library-id("python flask")
get-library-docs(id, topic: "blueprints")

Python Data

resolve-library-id("python pandas")
get-library-docs(id, topic: "groupby aggregation")

resolve-library-id("python polars")
get-library-docs(id, topic: "lazy frame expressions")

resolve-library-id("python numpy")
get-library-docs(id, topic: "broadcasting rules")

Python Testing

resolve-library-id("python pytest")
get-library-docs(id, topic: "fixtures and parametrize")

resolve-library-id("python hypothesis")
get-library-docs(id, topic: "strategies and composite")

Python Validation

resolve-library-id("python pydantic")
get-library-docs(id, topic: "model validators and field validators")

resolve-library-id("python msgspec")
get-library-docs(id, topic: "struct types and decoding")

Python HTTP

resolve-library-id("python httpx")
get-library-docs(id, topic: "async client and transports")

resolve-library-id("python aiohttp")
get-library-docs(id, topic: "client session and connection pooling")

Python CLI

resolve-library-id("python typer")
get-library-docs(id, topic: "commands and options")

resolve-library-id("python rich")
get-library-docs(id, topic: "tables and console markup")

Python Libraries Evaluation & Selection Guide

Library Evaluation Criteria

1. Maintenance Activity

• Commit frequency: Regular commits in the last 6 months
• Issue response time: Maintainers respond within days, not months
• Release cadence: Stable releases at least quarterly
• CI/CD status: Passing builds on main branch

2. Community & Popularity

• GitHub stars: Indicator of interest (not quality alone)
• Download stats: PyPI monthly downloads via pypistats.org
• Stack Overflow presence: Active Q&A community
• Contributors: Multiple active contributors reduce bus factor

3. Security

• CVE history: Check via pip-audit or safety DB
• Security advisories: GitHub security tab, Snyk database
• Dependency chain: Fewer transitive dependencies = smaller attack surface
• Signed releases: Package signing and provenance attestation

4. License Compatibility

• MIT/BSD/Apache 2.0: Permissive, safe for most projects
• LGPL: Acceptable with dynamic linking
• GPL: Copyleft, may restrict proprietary use
• AGPL: Network copyleft, restricts SaaS use
• Always verify with pip show <package> or pyproject.toml

5. API Design Quality

• Type annotations: Full typing support (py.typed marker)
• Documentation: Comprehensive docs with examples
• Consistent API surface: Predictable method naming and signatures
• Error handling: Clear exception hierarchy, not bare exceptions
• Async support: Native async API if applicable

6. Performance & Compatibility

• Python version support: Supports 3.10+ minimum (current as of 2025)
• Platform support: Linux, macOS, Windows
• Benchmark data: Published benchmarks or reproducible comparisons
• Memory footprint: Acceptable for target deployment

---

Library Selection Checklist

Before adopting a library, verify:

• [ ] Active maintenance (commits within last 3 months)
• [ ] 1000+ GitHub stars OR established in domain
• [ ] Compatible license for your project
• [ ] No unpatched critical CVEs
• [ ] Python 3.10+ support
• [ ] Type annotations available
• [ ] Documentation covers your use case
• [ ] Acceptable dependency tree size (pipdeptree)
• [ ] Community support channels exist
• [ ] Migration path exists if library is abandoned

---

Essential Python Libraries by Category

Web Frameworks

Data Processing & Analysis

Testing

Async & Concurrency

CLI Tools

Validation & Serialization

HTTP Clients

Database & ORM

---

Quick Evaluation Command Sequence

# Check PyPI stats
pip install pypistats
pypistats overall <package> --last-month

# Audit dependencies
pip install pip-audit
pip-audit

# View dependency tree
pip install pipdeptree
pipdeptree --packages <package>

# Check type stub availability
pip install mypy
mypy --install-types