118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
---
|
|
applyTo: '**'
|
|
---
|
|
# AI Coding Guidelines for TheChart Project
|
|
|
|
## Project Overview
|
|
- **Project Name:** TheChart (Medication Tracker)
|
|
- **Purpose:** Desktop application for tracking medications and pathologies.
|
|
- **Tech Stack:** Python 3.x, Tkinter, Pandas, modular architecture.
|
|
- **Key Features:**
|
|
- Add/edit/delete daily medication and pathology entries
|
|
- Visual graphs and charts
|
|
- Data export
|
|
- Keyboard shortcuts
|
|
- Theming support
|
|
|
|
## Coding Guidelines
|
|
|
|
### 1. Code Style
|
|
- Follow PEP8 for Python code (indentation, naming, spacing).
|
|
- Use type hints for all function signatures and variables where possible.
|
|
- Use docstrings for all public methods and classes.
|
|
- Prefer f-strings for string formatting.
|
|
- Use snake_case for variables/functions, CamelCase for classes.
|
|
- Keep lines under 88 characters.
|
|
- Use descriptive names for variables and functions to enhance readability.
|
|
- Avoid global variables; use class attributes or method parameters instead.
|
|
- Use logging for debug/info messages instead of print statements.
|
|
- Use .venv/bin/activate.fish as the virtual environment activation script.
|
|
- The package manager is uv.
|
|
- Use ruff for linting and formatting.
|
|
- The terminal uses fish shell.
|
|
|
|
### 2. Architecture & Structure
|
|
- Maintain separation of concerns: UI, data management, and business logic in their respective modules.
|
|
- Use manager classes (e.g., DataManager, UIManager, ThemeManager) for encapsulating related functionality.
|
|
- UI elements and data columns must be generated dynamically based on current medicines/pathologies.
|
|
- New medicines/pathologies should not require changes to main logic—use dynamic lists and keys.
|
|
- Avoid hardcoding values; use configuration files or constants.
|
|
- Adopt a modular project structure following python best practices.
|
|
|
|
### 3. Error Handling
|
|
- Use try/except for operations that may fail (file I/O, data parsing).
|
|
- Show user-friendly error messages via messagebox dialogs.
|
|
- Log errors and important actions using the logger.
|
|
|
|
### 4. User Experience
|
|
- Always update the status bar and provide feedback for user actions.
|
|
- Use confirmation dialogs for destructive actions (e.g., deleting entries).
|
|
- Support keyboard shortcuts for all major actions.
|
|
- Keep the UI responsive and avoid blocking operations in the main thread.
|
|
|
|
### 5. Data Handling
|
|
- Use Pandas DataFrames for all data manipulation.
|
|
- Always check for duplicate dates before adding new entries.
|
|
- Store medicine doses as a string (e.g., "time:dose|time:dose") for each medicine.
|
|
- Support dynamic addition/removal of medicines and pathologies.
|
|
|
|
### 6. Testing & Robustness
|
|
- Validate all user input before saving.
|
|
- Ensure all UI elements are updated after data changes.
|
|
- Use batch operations for updating UI elements (e.g., clearing and repopulating the table).
|
|
|
|
### 7. Documentation
|
|
- Keep code well-commented and maintain clear docstrings.
|
|
- Document any non-obvious logic, especially dynamic UI/data handling.
|
|
|
|
### 8. Performance
|
|
- Use efficient methods for updating UI elements (e.g., batch delete/insert for Treeview).
|
|
- Avoid unnecessary data reloads or UI refreshes.
|
|
- Use multi-threading when appropriate.
|
|
|
|
## When Generating or Reviewing Code
|
|
- Respect the modular structure—add new logic to the appropriate manager or window class.
|
|
- Do not hardcode medicine/pathology names—always use dynamic keys from the managers.
|
|
- Preserve user feedback (status bar, dialogs) for all actions.
|
|
- Maintain keyboard shortcut support for new features.
|
|
- Code Refactoring is allowed as long as it does not change the external behavior of the code.
|
|
- Ensure compatibility with the existing UI and data model.
|
|
- Write clear, concise, and maintainable code with proper type hints and docstrings.
|
|
- Avoid using deprecated imports or patterns.
|
|
- Remove any warnings or deprecation notices from the codebase.
|
|
- Replace legacy code.
|
|
|
|
---
|
|
|
|
**Summary:**
|
|
This project is a modular, extensible Tkinter application for tracking medication and pathology data. Code should be clean, dynamic, user-friendly, and robust, following PEP8 and the architectural patterns already established. All new features or changes should integrate seamlessly with the existing managers and UI paradigms, unless instructed otherwise.
|
|
|
|
|
|
**Notes:**
|
|
A robust Python project directory structure is crucial for maintainability, scalability, and collaboration. Key best practices include:
|
|
|
|
Root Project Directory:
|
|
Create a top-level directory for your project, typically named after the project itself.
|
|
Source Code (src/ or my_package/):
|
|
Modern approach: Place all application source code within a src/ directory. This clearly separates source code from other project files.
|
|
Alternative: If your project is a single package, the main package directory (e.g., my_package/) can reside directly under the root, containing your modules and __init__.py.
|
|
Modularity: Break down your code into smaller, logical modules within this directory, each with a clear responsibility.
|
|
__init__.py: Include an __init__.py file in every directory intended to be a Python package, marking it as importable.
|
|
Tests (tests/):
|
|
Create a dedicated tests/ directory at the root level to house all your test files.
|
|
Structure tests to mirror the application's module structure for easier navigation and understanding.
|
|
Documentation (docs/):
|
|
Include a docs/ directory for project documentation, including usage guides, API references, and design documents.
|
|
Configuration (config/ or pyproject.toml):
|
|
Use pyproject.toml for modern project configuration, including project metadata, dependencies, and tool configurations (linters, formatters, test runners).
|
|
For application-specific or environment-dependent configurations, consider a config/ directory or environment variables.
|
|
Entry Point (main.py or cli.py):
|
|
Designate a clear entry point for your application, often main.py or cli.py for command-line interfaces. This file should primarily orchestrate the application's flow and delegate logic to other modules.
|
|
Other Important Files:
|
|
README.md: A comprehensive README at the root level providing project overview, installation instructions, and usage examples.
|
|
LICENSE: A license file specifying the terms of use and distribution.
|
|
.gitignore: For version control, specifying files and directories to be ignored by Git (e.g., virtual environments, compiled files, sensitive data).
|
|
requirements.txt: (or managed via pyproject.toml): Lists project dependencies.
|
|
Virtual Environments:
|
|
Utilize virtual environments (e.g., venv, conda) to isolate project dependencies and avoid conflicts. The virtual environment directory (e.g., .venv/) should be ignored by version control.
|