Instruction file imported from zenbase-ai/llml (
.cursor/rules/py.mdc). Copyright stays with the author.
Python Coding Rules for LLML Project
Project Structure and Management
- Configuration: All project metadata, dependencies, and tool configurations must be managed in
pyproject.toml. - Dependencies:
- Runtime dependencies should be added to the
[project.dependencies]section. - Development dependencies must be added to the
[project.optional-dependencies]section under thedevgroup. - Use
uvfor managing the virtual environment and installing dependencies.
- Runtime dependencies should be added to the
- Source Code: All main application logic must reside in the
py/src/directory. - Tests: All tests must be placed in the
py/tests/directory and follow the naming conventiontest_*.py.
Coding Style and Formatting
- Linter/Formatter:
ruffis the designated tool for all linting and formatting. All code must be compliant with the rules defined inpyproject.toml. - Line Length: The maximum line length is
88characters. - Quotes: Use double quotes (
") for all strings. Single quotes are not permitted. - Indentation: Use 4 spaces for indentation. Tabs are not allowed.
- Docstrings:
- All public modules, functions, and methods must have a docstring.
- Use triple-double quotes (
"""Docstring goes here""") for docstrings. - Function docstrings should clearly describe the function's purpose, arguments, and return value.
Typing and Type Safety
- Type Hinting: All function signatures, including arguments and return values, must have type hints from Python's
typingmodule. - Runtime Type Checking: The
@beartypedecorator must be applied to all functions to enforce runtime type safety. - Type Aliases: Use the
talias for thetypingmodule (e.g.,import typing as t).
Function and API Design
- Core Logic: The main logic is centered around the
llmlfunction, which is designed to be recursive. When adding new features, maintain this recursive pattern. - Immutability: The
llmlfunction should be pure and not modify its inputs. It should return a new string as the result. - Keyword Arguments: When calling functions, prefer keyword arguments for clarity, especially for functions with multiple parameters.
Error Handling
- No Explicit Error Handling: The current implementation does not have explicit
try...exceptblocks. Instead, it relies onbeartypefor type-related errors and Python's standard behavior for other issues. - Implicit Error Handling: Continue this pattern of relying on runtime checks and standard error-raising behavior unless a specific need for explicit handling arises.
Testing
- Framework: All tests must be written using the
pytestframework. - Test Naming: Test functions must start with
test_(e.g.,def test_my_feature():). - Assertions: Use
assertstatements for all checks. Do not use other assertion libraries. - Test Coverage:
- Every new feature or bug fix must be accompanied by corresponding tests.
- Aim for comprehensive test coverage, including edge cases, basic functionality, and complex scenarios.
- Run tests using
toxto ensure compatibility across all supported Python versions.
- Test Structure: Each test function should be self-contained and focus on a single piece of functionality.
Modularity and Code Organization
- Separation of Concerns:
- The core formatting logic must remain in
llml.py. - Utility functions, such as
kebab_case, should be placed inutils.py.
- The core formatting logic must remain in
- Imports:
- Use absolute imports for modules within the project (e.g.,
from .utils import kebab_case). - Standard library imports should be placed at the top of the file, followed by third-party imports, and then local application imports.
- Use absolute imports for modules within the project (e.g.,
