AGENTS.md

Quick orientation for AI coding agents

Key facts an agent must know (short):

• The runner: runner.py dynamically imports every module under ultimatepython and runs any callable named main with zero parameters. Keep main() functions parameterless, idempotent, and side-effect safe for CI.
• Single-file runs are supported: modules are runnable with python ultimatepython/<category>/<module>.py. Most modules already include if __name__ == "__main__": main().
• Examples use plain Python stdlib only. Avoid adding new third-party dependencies without updating requirements.txt and pyproject.toml.
• Assertions are used as the primary verification mechanism inside examples (not pytest tests). Preserve their intent and messages when editing.

Patterns and conventions

• main() must be parameterless and not raise exceptions when run. Examples: ultimatepython/fundamentals/function.py, ultimatepython/oop/basic_class.py.
• Module structure: docstring, helpers, main() demonstrating usage via asserts, if __name__ == "__main__": main().
• Avoid long-running or destructive operations. For filesystem interactions, keep them local to ephemeral files and clean up after running.
• Use ruff and isort (configured in pyproject.toml) for consistency with existing modules.

Before committing

• New modules go under the appropriate folder—the runner discovers them automatically.
• If a change requires a new dependency, update requirements.txt and pyproject.toml.
• When updating README.md, consider updating translations or note why they were skipped.

Quick reference

• Run all examples: python runner.py
• Run single example: python ultimatepython/<category>/<module>.py
• Coverage target: 80% (in pyproject.toml)

Integration points & CI notes

• CI expects that running runner.py and executing each main() will succeed. Avoid adding code that requires network access, long sleeps, or interactive input.
• Do not introduce external services or config files; this repo intentionally uses only the Python standard library.

Key files

• runner.py — discovery and execution (pkgutil.walk_packages + main lookups)
• pyproject.toml — formatting, linting, coverage rules

Category Charter

Helpful guidance on where to place new Python module lessons:

• fundamentals/: Core syntax and structural constructs of the language (variables, expressions, strings, lists, loops, functions, basic comprehensions).
• oop/: Object-Oriented Programming concepts (classes, inheritance, encapsulation, abstract base classes, exception handling, custom iterators, mixins, MRO).
• stdlib/: Python standard library modules (file handling, regular expressions, json/csv formats, date/time manipulation).
• advanced/: Metaprogramming and advanced runtime behaviors (decorators, context managers, metaclasses, weak references, walrus operator, pattern matching).
• concurrency/: Multitasking and non-blocking models (threading, async/await, multiprocessing, subinterpreters).
• engineering/: Code quality, benchmarking, algorithm utilities, and data structures (mocking, benchmarking, deque, namedtuple, defaultdict, itertools, heaps).