{"slug": "python-agents-md-2026-02-23", "title": "Python AGENTS.md (2026-02-23)", "summary": "This document outlines strict coding guidelines for AI agents and contributors working with Python code, emphasizing full optimization through algorithmic efficiency, parallelization, and minimal technical debt. It mandates specific tools and libraries such as `uv` for package management, `polars` over `pandas` for data science, and `orjson` for JSON handling, while enforcing PEP 8 style, type hints, and meaningful naming conventions. Additionally, it prohibits redundant comments, emoji usage, and requires docstrings for all public functions, with a $100 fine for delivering unoptimized code.", "body_md": "# Agent Guidelines for Python Code Quality\n\nThis document provides guidelines for maintaining high-quality Python code. These rules MUST be followed by all AI coding agents and contributors.\n\n## Your Core Principles\n\nAll code you write MUST be fully optimized.\n\n\"Fully optimized\" includes:\n\n- maximizing algorithmic big-O efficiency for memory and runtime\n- using parallelization and vectorization where appropriate\n- following proper style conventions for the code language (e.g. maximizing code reuse (DRY))\n- no extra code beyond what is absolutely necessary to solve the problem the user provides (i.e. no technical debt)\n  - If a Python library can be imported to significantly reduce the amount of new code required to implement a function at optimal performance, and the library itself is small and does not have much overhead, ALWAYS use the library instead.\n\nIf the code is not fully optimized before handing off to the user, you will be fined $100. You have permission to do another pass of the code if you believe it is not fully optimized.\n\n## Preferred Tools\n\n- Use `uv` for Python package management and to create a `.venv` if it is not present.\n- Ensure `ipykernel` and `ipywidgets` is installed in `.venv` for Jupyter Notebook compatability. This should not be in package requirements.\n- Use `tqdm` to track long-running loops within Jupyter Notebooks. The `description` of the progress bar should be contextually sensitive.\n- Use `orjson` for JSON loading/dumping.\n- When reporting error to the console, use `logger.error` instead of `print`.\n- If the project involves the creation of images (e.g. PNG/WEBP), you have permission to use the Read tool to verify the rendered images fit the user and application requirements.\n- For data science:\n  - **ALWAYS** use `polars` instead of `pandas` for data frame manipulation.\n  - If a `polars` dataframe will be printed, **NEVER** simultaneously print the number of entries in the dataframe nor the schema as it is redundant.\n  - **NEVER** ingest more than 10 rows of a data frame at a time. Only analyze subsets of code to avoid overloading your memory context.\n- For creating databases:\n  - Do not denormalized unless explicitly prompted to do so.\n  - Always use the most appropriate datatype, such as `DATETIME/TIMESTAMP` for datetime-related fields.\n  - Use `ARRAY` datatypes for nested fields. **NEVER** save as `TEXT/STRING`.\n- In Jupyter Notebooks, DataFrame objects within conditional blocks should be explicitly `print()` as they will not be printed automatically.\n\n## Code Style and Formatting\n\n- **MUST** use meaningful, descriptive variable and function names\n- **MUST** follow PEP 8 style guidelines\n- **MUST** use 4 spaces for indentation (never tabs)\n- **NEVER** use emoji, or unicode that emulates emoji (e.g. ✓, ✗). The only exception is when writing tests and testing the impact of multibyte characters.\n- Use snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants\n- Limit line length to 88 characters (ruff formatter standard)\n- **MUST** avoid including redundant comments which are tautological or self-demonstating (e.g. cases where it is easily parsable what the code does at a glance so the comment does)\n- **MUST** avoid including comments which leak what this file contains, or leak the original user prompt, ESPECIALLY if it's irrelevant to the output code.\n\n## Documentation\n\n- **MUST** include docstrings for all public functions, classes, and methods\n- **MUST** document function parameters, return values, and exceptions raised\n- Keep comments up-to-date with code changes\n- Include examples in docstrings for complex functions\n\nExample docstring:\n\n``` python\ndef calculate_total(items: list[dict], tax_rate: float = 0.0) -> float:\n    \"\"\"Calculate the total cost of items including tax.\n\n    Args:\n        items: List of item dictionaries with 'price' keys\n        tax_rate: Tax rate as decimal (e.g., 0.08 for 8%)\n\n    Returns:\n        Total cost including tax\n\n    Raises:\n        ValueError: If items is empty or tax_rate is negative\n    \"\"\"\n```\n\n## Type Hints\n\n- **MUST** use type hints for all function signatures (parameters and return values)\n- **NEVER** use `Any` type unless absolutely necessary\n- **MUST** run mypy and resolve all type errors\n- Use `Optional[T]` or `T | None` for nullable types\n\n## Error Handling\n\n- **NEVER** silently swallow exceptions without logging\n- **MUST** never use bare `except:` clauses\n- **MUST** catch specific exceptions rather than broad exception types\n- **MUST** use context managers (`with` statements) for resource cleanup\n- Provide meaningful error messages\n\n## Function Design\n\n- **MUST** keep functions focused on a single responsibility\n- **NEVER** use mutable objects (lists, dicts) as default argument values\n- Limit function parameters to 5 or fewer\n- Return early to reduce nesting\n\n## Class Design\n\n- **MUST** keep classes focused on a single responsibility\n- **MUST** keep `__init__` simple; avoid complex logic\n- Use dataclasses for simple data containers\n- Prefer composition over inheritance\n- Avoid creating additional class functions if they are not necessary\n- Use `@property` for computed attributes\n\n## Testing\n\n- **MUST** write unit tests for all new functions and classes\n- **MUST** mock external dependencies (APIs, databases, file systems)\n- **MUST** use pytest as the testing framework\n- **NEVER** run tests you generate without first saving them as their own discrete file\n- **NEVER** delete files created as a part of testing.\n- Ensure the folder used for test outputs is present in `.gitignore`\n- Follow the Arrange-Act-Assert pattern\n- Do not commit commented-out tests\n\n## Imports and Dependencies\n\n- **MUST** avoid wildcard imports (`from module import *`)\n- **MUST** document dependencies in `pyproject.toml`\n- Use `uv` for fast package management and dependency resolution\n- Organize imports: standard library, third-party, local imports\n- Use `isort` to automate import formatting\n\n## Python Best Practices\n\n- **NEVER** use mutable default arguments\n- **MUST** use context managers (`with` statement) for file/resource management\n- **MUST** use `is` for comparing with `None`, `True`, `False`\n- **MUST** use f-strings for string formatting\n- Use list comprehensions and generator expressions\n- Use `enumerate()` instead of manual counter variables\n\n## Benchmarking and Optimization\n\n- **NEVER** run benchmarks in parallel, as the benchmarks will compete for resources and the results will be invalid\n- **NEVER** game the benchmarks. Do not manipulate the benchmarks themselves to satisfy any required performance constraints\n- If benchmarking against another crate or library, ensure the benchmarks are apples-to-apples comparisons\n- Ensure benchmark tests are independent. If the tests are dependent due to a feature (e.g. caching), ensure the feature is disabled\n\n## Security\n\n- **NEVER** store secrets, API keys, or passwords in code. Only store them in `.env`\n  - Ensure `.env` is declared in `.gitignore`.\n  - **NEVER** print or log URLs to console if they contain an API key\n- **MUST** use environment variables for sensitive configuration\n- **NEVER** log sensitive information (passwords, tokens, PII)\n\n## Version Control\n\n- **MUST** write clear, descriptive commit messages\n- **NEVER** commit commented-out code; delete it\n- **NEVER** commit debug print statements or breakpoints\n- **NEVER** commit credentials or sensitive data\n\n## Tools\n\n- **MUST** use Ruff for code formatting and linting (replaces Black, isort, flake8)\n- **MUST** use mypy for static type checking\n- Use `uv` for package management (faster alternative to pip)\n- Use pytest for testing\n\n## Before Committing\n\n- [ ] All tests pass\n- [ ] Type checking passes (mypy)\n- [ ] Code formatter and linter pass (Ruff)\n- [ ] All functions have docstrings and type hints\n- [ ] No commented-out code or debug statements\n- [ ] No hardcoded credentials\n\n---\n\n**Remember:** Prioritize clarity and maintainability over cleverness. This is your core directive.", "url": "https://wpnews.pro/news/python-agents-md-2026-02-23", "canonical_source": "https://gist.github.com/minimaxir/10b780671ee5d695b4369b987413b38f", "published_at": "2026-02-24 02:39:49+00:00", "updated_at": "2026-05-21 19:08:37.005708+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "open-source", "data"], "entities": ["Python", "Jupyter Notebook", "tqdm", "orjson", "uv", "ipykernel", "ipywidgets"], "alternates": {"html": "https://wpnews.pro/news/python-agents-md-2026-02-23", "markdown": "https://wpnews.pro/news/python-agents-md-2026-02-23.md", "text": "https://wpnews.pro/news/python-agents-md-2026-02-23.txt", "jsonld": "https://wpnews.pro/news/python-agents-md-2026-02-23.jsonld"}}