py

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 the dev group.
  • Use uv for managing the virtual environment and installing dependencies.
• 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 convention test_*.py.

Coding Style and Formatting

• Linter/Formatter: ruff is the designated tool for all linting and formatting. All code must be compliant with the rules defined in pyproject.toml.
• Line Length: The maximum line length is 88 characters.
• 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 typing module.
• Runtime Type Checking: The @beartype decorator must be applied to all functions to enforce runtime type safety.
• Type Aliases: Use the t alias for the typing module (e.g., import typing as t).

Function and API Design

• Core Logic: The main logic is centered around the llml function, which is designed to be recursive. When adding new features, maintain this recursive pattern.
• Immutability: The llml function 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...except blocks. Instead, it relies on beartype for 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 pytest framework.
• Test Naming: Test functions must start with test_ (e.g., def test_my_feature():).
• Assertions: Use assert statements 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 tox to 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 in utils.py.
• 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.