|
| 1 | +# Agentic Coding Guidelines for Offline Python Dockers Runtime |
| 2 | + |
| 3 | +This document outlines the guidelines for agentic coding within the `offline-python-runtime-docker` repository. Agents operating in this codebase should adhere to these conventions to ensure consistency, maintainability, and alignment with project standards. |
| 4 | + |
| 5 | +## 1. Build, Lint, and Test Commands |
| 6 | + |
| 7 | +### 1.1 Build Commands |
| 8 | +The project uses `podman` for building Docker images. |
| 9 | +- **Build the main Docker image:** |
| 10 | + ```bash |
| 11 | + podman build . -t offline-python-runtime-docker:dev-latest-local |
| 12 | + ``` |
| 13 | + |
| 14 | +### 1.2 Test Commands |
| 15 | +The project uses `pytest` for running tests. All Python code, including tests, is designed to run within the Docker container. |
| 16 | + |
| 17 | +- **Run all tests within Docker:** |
| 18 | + ```bash |
| 19 | + podman run -v ./py-apps:/home/appuser/py-apps:Z -it localhost/offline-python-runtime-docker:dev /usr/bin/python3 -m pytest /home/appuser/py-apps/tests/ |
| 20 | + ``` |
| 21 | +- **Run a single test file within Docker:** |
| 22 | + ```bash |
| 23 | + podman run -v ./py-apps:/home/appuser/py-apps:Z -it localhost/offline-python-runtime-docker:dev /usr/bin/python3 -m pytest /home/appuser/py-apps/tests/<test_file_name>.py |
| 24 | + ``` |
| 25 | + (e.g., `podman run -v ./py-apps:/home/appuser/py-apps:Z -it localhost/offline-python-runtime-docker:dev /usr/bin/python3 -m pytest /home/appuser/py-apps/tests/test_imports.py`) |
| 26 | +- **Run a specific test within a file in Docker:** |
| 27 | + ```bash |
| 28 | + podman run -v ./py-apps:/home/appuser/py-apps:Z -it localhost/offline-python-runtime-docker:dev /usr/bin/python3 -m pytest /home/appuser/py-apps/tests/<test_file_name>.py::<test_function_name> |
| 29 | + ``` |
| 30 | + (e.g., `podman run -v ./py-apps:/home/appuser/py-apps:Z -it localhost/offline-python-runtime-docker:dev /usr/bin/python3 -m pytest /home/appuser/py-apps/tests/test_imports.py::test_basic_import`) |
| 31 | + |
| 32 | +### 1.3 Linting and Formatting |
| 33 | +Currently, there is no explicit linting or formatting tool configured for this project (e.g., `flake8`, `black`, `ruff`). Agents should: |
| 34 | +- Adhere to [PEP 8](https://www.python.org/dev/peps/pep-0008/) for code style. |
| 35 | +- Follow the existing formatting observed in `py-apps/` files. |
| 36 | +- If new linting/formatting tools are introduced in the future, adapt to them. |
| 37 | + |
| 38 | +## 2. Code Style Guidelines |
| 39 | + |
| 40 | +### 2.1 Imports |
| 41 | +- Imports should be organized according to PEP 8: |
| 42 | + 1. Standard library imports. |
| 43 | + 2. Third-party imports. |
| 44 | + 3. Local application/library-specific imports. |
| 45 | +- Each group should be separated by a blank line. |
| 46 | +- Absolute imports are preferred over relative imports where feasible for clarity. |
| 47 | + |
| 48 | +### 2.2 Formatting |
| 49 | +- **Indentation:** Use 4 spaces for indentation. |
| 50 | +- **Line Length:** Aim for a maximum of 79 characters per line, as per PEP 8. |
| 51 | +- **Blank Lines:** |
| 52 | + - Surround top-level function and class definitions with two blank lines. |
| 53 | + - Method definitions inside a class should be surrounded by one blank line. |
| 54 | + - Use blank lines sparingly to improve readability within functions. |
| 55 | + |
| 56 | +### 2.3 Types (Type Hinting) |
| 57 | +- While existing code may not extensively use type hints, agents are strongly encouraged to use [PEP 484](https://www.python.org/dev/peps/pep-0008/) style type hints for new code and when modifying existing functions. |
| 58 | +- This improves code clarity, maintainability, and enables static analysis. |
| 59 | + |
| 60 | +### 2.4 Naming Conventions |
| 61 | +- **Modules:** lowercase_with_underscores (e.g., `my_module.py`). |
| 62 | +- **Packages:** lowercase_with_underscores (e.g., `my_package/`). |
| 63 | +- **Classes:** CapWords (e.g., `MyClass`). |
| 64 | +- **Functions/Methods:** lowercase_with_underscores (e.g., `my_function`, `my_method`). |
| 65 | +- **Variables:** lowercase_with_underscores (e.g., `my_variable`). |
| 66 | +- **Constants:** ALL_CAPS_WITH_UNDERSCORES (e.g., `MY_CONSTANT`). |
| 67 | +- **Private Members:** Prefix with a single underscore (e.g., `_private_method`). |
| 68 | + |
| 69 | +### 2.5 Error Handling |
| 70 | +- Use Python's exception handling mechanisms (`try`, `except`, `finally`, `else`). |
| 71 | +- Be specific with exception types rather than catching a broad `Exception`. |
| 72 | +- Provide meaningful error messages. |
| 73 | +- Log errors appropriately, if a logging framework is present. Otherwise, print to stderr. |
| 74 | +
|
| 75 | +### 2.6 Documentation |
| 76 | +- Use [PEP 257](https://www.python.org/dev/peps/pep-0257/) docstring conventions for modules, classes, and functions. |
| 77 | +- Provide clear, concise, and comprehensive docstrings explaining the purpose, arguments, and return values. |
| 78 | +
|
| 79 | +## 3. Git Workflow |
| 80 | +- Development should primarily occur on the `develop` branch. |
| 81 | +- New features or significant changes should be implemented in dedicated feature branches, branched off from `develop`. |
| 82 | +- Follow a git-flow-like convention for branching and merging. |
| 83 | +
|
| 84 | +## 4. Cursor/Copilot Rules |
| 85 | +
|
| 86 | +No explicit `.cursor/rules/` or `.github/copilot-instructions.md` files were found in this repository. Agents should default to the general guidelines provided in this `AGENTS.md` and their inherent best practices. |
0 commit comments