mirror of
https://github.com/daniviga/django-ram.git
synced 2026-02-04 01:50:39 +01:00
Add AGENTS.md and tests generated via opencode
This commit is contained in:
333
AGENTS.md
Normal file
333
AGENTS.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# Django Railroad Assets Manager - Agent Guidelines
|
||||
|
||||
This document provides coding guidelines and command references for AI coding agents working on the Django-RAM project.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Django Railroad Assets Manager (django-ram) is a Django 6.0+ application for managing model railroad collections with DCC++ EX integration. The project manages rolling stock, consists, metadata, books/magazines, and provides an optional REST API for DCC control.
|
||||
|
||||
## Environment Setup
|
||||
|
||||
### Python Requirements
|
||||
- Python 3.11+ (tested on 3.13, 3.14)
|
||||
- Django >= 6.0
|
||||
- Working directory: `ram/` (Django project root)
|
||||
- Virtual environment recommended: `python3 -m venv venv && source venv/bin/activate`
|
||||
|
||||
### Installation
|
||||
```bash
|
||||
pip install -r requirements.txt # Core dependencies
|
||||
pip install -r requirements-dev.txt # Development tools
|
||||
cd ram && python manage.py migrate # Initialize database
|
||||
python manage.py createsuperuser # Create admin user
|
||||
```
|
||||
|
||||
### Frontend Assets
|
||||
```bash
|
||||
npm install # Install clean-css-cli, terser
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ram/ # Django project root
|
||||
├── ram/ # Core settings, URLs, base models
|
||||
├── portal/ # Public-facing frontend (Bootstrap 5)
|
||||
├── roster/ # Rolling stock management (main app)
|
||||
├── metadata/ # Manufacturers, companies, scales, decoders
|
||||
├── bookshelf/ # Books and magazines
|
||||
├── consist/ # Train consists (multiple locomotives)
|
||||
├── repository/ # Document repository
|
||||
├── driver/ # DCC++ EX API gateway (optional, disabled by default)
|
||||
└── storage/ # Runtime data (SQLite DB, media, cache)
|
||||
```
|
||||
|
||||
## Build/Lint/Test Commands
|
||||
|
||||
### Running the Development Server
|
||||
```bash
|
||||
cd ram
|
||||
python manage.py runserver # Runs on http://localhost:8000
|
||||
```
|
||||
|
||||
### Database Management
|
||||
```bash
|
||||
python manage.py makemigrations # Create new migrations
|
||||
python manage.py migrate # Apply migrations
|
||||
python manage.py showmigrations # Show migration status
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run all tests (comprehensive test suite with 75+ tests)
|
||||
python manage.py test
|
||||
|
||||
# Run tests for a specific app
|
||||
python manage.py test roster # Rolling stock tests
|
||||
python manage.py test metadata # Metadata tests
|
||||
python manage.py test bookshelf # Books/magazines tests
|
||||
python manage.py test consist # Consist tests
|
||||
|
||||
# Run a specific test case class
|
||||
python manage.py test roster.tests.RollingStockTestCase
|
||||
python manage.py test metadata.tests.ScaleTestCase
|
||||
|
||||
# Run a single test method
|
||||
python manage.py test roster.tests.RollingStockTestCase.test_road_number_int_extraction
|
||||
python manage.py test bookshelf.tests.TocEntryTestCase.test_toc_entry_page_validation_exceeds_book
|
||||
|
||||
# Run with verbosity for detailed output
|
||||
python manage.py test --verbosity=2
|
||||
|
||||
# Keep test database for inspection
|
||||
python manage.py test --keepdb
|
||||
|
||||
# Run tests matching a pattern
|
||||
python manage.py test --pattern="test_*.py"
|
||||
```
|
||||
|
||||
### Linting
|
||||
```bash
|
||||
# Run flake8 (configured in requirements-dev.txt)
|
||||
flake8 . # Lint entire project
|
||||
flake8 roster/ # Lint specific app
|
||||
flake8 roster/models.py # Lint specific file
|
||||
|
||||
# Note: No .flake8 config exists; uses PEP 8 defaults
|
||||
# Long lines use # noqa: E501 comments in settings.py
|
||||
```
|
||||
|
||||
### Admin Commands
|
||||
```bash
|
||||
python manage.py createsuperuser # Create admin user
|
||||
python manage.py purge_cache # Custom: purge cache
|
||||
python manage.py loaddata <fixture> # Load sample data
|
||||
```
|
||||
|
||||
### Debugging & Profiling
|
||||
```bash
|
||||
# Use pdbpp for debugging (installed via requirements-dev.txt)
|
||||
import pdb; pdb.set_trace() # Set breakpoint in code
|
||||
|
||||
# Use pyinstrument for profiling
|
||||
python manage.py runserver --noreload # With pyinstrument middleware
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### General Python Style
|
||||
- **PEP 8 compliant** - Follow standard Python style guide
|
||||
- **Line length**: 79 characters preferred; 119 acceptable for complex lines
|
||||
- **Long lines**: Use `# noqa: E501` comment when necessary (see settings.py)
|
||||
- **Indentation**: 4 spaces (no tabs)
|
||||
- **Encoding**: UTF-8
|
||||
|
||||
### Import Organization
|
||||
Follow Django's import style (as seen in models.py, views.py, admin.py):
|
||||
|
||||
```python
|
||||
# 1. Standard library imports
|
||||
import os
|
||||
import re
|
||||
from itertools import chain
|
||||
from functools import reduce
|
||||
|
||||
# 2. Related third-party imports
|
||||
from django.db import models
|
||||
from django.conf import settings
|
||||
from django.contrib import admin
|
||||
from tinymce import models as tinymce
|
||||
|
||||
# 3. Local application imports
|
||||
from ram.models import BaseModel, Image
|
||||
from ram.utils import DeduplicatedStorage, slugify
|
||||
from metadata.models import Scale, Manufacturer
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
- Group imports by category with blank lines between
|
||||
- Use `from module import specific` for commonly used items
|
||||
- Avoid `import *`
|
||||
- Use `as` for aliasing when needed (e.g., `tinymce.models as tinymce`)
|
||||
|
||||
### Naming Conventions
|
||||
- **Classes**: `PascalCase` (e.g., `RollingStock`, `BaseModel`)
|
||||
- **Functions/methods**: `snake_case` (e.g., `get_items_per_page()`, `image_thumbnail()`)
|
||||
- **Variables**: `snake_case` (e.g., `road_number`, `item_number_slug`)
|
||||
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `BASE_DIR`, `ALLOWED_HOSTS`)
|
||||
- **Private methods**: Prefix with `_` (e.g., `_internal_method()`)
|
||||
- **Model Meta options**: Use `verbose_name`, `verbose_name_plural`, `ordering`
|
||||
|
||||
### Django Model Patterns
|
||||
|
||||
```python
|
||||
class MyModel(BaseModel): # Inherit from BaseModel for common fields
|
||||
# Field order: relationships first, then data fields, then metadata
|
||||
foreign_key = models.ForeignKey(OtherModel, on_delete=models.CASCADE)
|
||||
name = models.CharField(max_length=128)
|
||||
slug = models.SlugField(max_length=128, unique=True)
|
||||
created = models.DateTimeField(auto_now_add=True)
|
||||
|
||||
class Meta:
|
||||
ordering = ["name"]
|
||||
verbose_name = "My Model"
|
||||
verbose_name_plural = "My Models"
|
||||
|
||||
def __str__(self):
|
||||
return self.name
|
||||
|
||||
@property
|
||||
def computed_field(self):
|
||||
"""Document properties with docstrings."""
|
||||
return self.calculate_something()
|
||||
```
|
||||
|
||||
**Model field conventions:**
|
||||
- Use `null=True, blank=True` for optional fields
|
||||
- Use `help_text` for user-facing field descriptions
|
||||
- Use `limit_choices_to` for filtered ForeignKey choices
|
||||
- Use `related_name` for reverse relations
|
||||
- Set `on_delete=models.CASCADE` explicitly
|
||||
- Use `default=None` with `null=True` for nullable fields
|
||||
|
||||
### Admin Customization
|
||||
|
||||
```python
|
||||
@admin.register(MyModel)
|
||||
class MyModelAdmin(admin.ModelAdmin):
|
||||
list_display = ("name", "created", "custom_method")
|
||||
list_filter = ("category", "created")
|
||||
search_fields = ("name", "slug")
|
||||
autocomplete_fields = ("foreign_key",)
|
||||
readonly_fields = ("created", "updated")
|
||||
save_as = True # Enable "Save as new" button
|
||||
|
||||
@admin.display(description="Custom Display")
|
||||
def custom_method(self, obj):
|
||||
return format_html('<strong>{}</strong>', obj.name)
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```python
|
||||
# Use Django's exception classes
|
||||
from django.core.exceptions import ValidationError, ObjectDoesNotExist
|
||||
from django.http import Http404
|
||||
from django.db.utils import OperationalError, ProgrammingError
|
||||
|
||||
# Handle database errors gracefully
|
||||
try:
|
||||
config = get_site_conf()
|
||||
except (OperationalError, ProgrammingError):
|
||||
config = default_config # Provide fallback
|
||||
```
|
||||
|
||||
### Type Hints
|
||||
- **Not currently used** in this project
|
||||
- Follow existing patterns without type hints unless explicitly adding them
|
||||
|
||||
## Django-Specific Patterns
|
||||
|
||||
### Using BaseModel
|
||||
All major models inherit from `ram.models.BaseModel`:
|
||||
```python
|
||||
from ram.models import BaseModel
|
||||
|
||||
class MyModel(BaseModel):
|
||||
# Automatically includes: uuid, description, notes, creation_time,
|
||||
# updated_time, published, obj_type, obj_label properties
|
||||
pass
|
||||
```
|
||||
|
||||
### Using PublicManager
|
||||
Models use `PublicManager` for filtering published items:
|
||||
```python
|
||||
from ram.managers import PublicManager
|
||||
|
||||
objects = PublicManager() # Only returns items where published=True
|
||||
```
|
||||
|
||||
### Image and Document Patterns
|
||||
```python
|
||||
from ram.models import Image, Document, PrivateDocument
|
||||
|
||||
class MyImage(Image):
|
||||
my_model = models.ForeignKey(MyModel, on_delete=models.CASCADE)
|
||||
# Inherits: order, image, image_thumbnail()
|
||||
|
||||
class MyDocument(PrivateDocument):
|
||||
my_model = models.ForeignKey(MyModel, on_delete=models.CASCADE)
|
||||
# Inherits: description, file, private, creation_time, updated_time
|
||||
```
|
||||
|
||||
### Using DeduplicatedStorage
|
||||
For media files that should be deduplicated:
|
||||
```python
|
||||
from ram.utils import DeduplicatedStorage
|
||||
|
||||
image = models.ImageField(upload_to="images/", storage=DeduplicatedStorage)
|
||||
```
|
||||
|
||||
## Testing Practices
|
||||
|
||||
### Test Coverage
|
||||
The project has comprehensive test coverage:
|
||||
- **roster/tests.py**: RollingStock, RollingClass models (~340 lines, 19+ tests)
|
||||
- **metadata/tests.py**: Scale, Manufacturer, Company, etc. (~378 lines, 29+ tests)
|
||||
- **bookshelf/tests.py**: Book, Magazine, Catalog, TocEntry (~436 lines, 25+ tests)
|
||||
- **consist/tests.py**: Consist, ConsistItem (~315 lines, 15+ tests)
|
||||
- **ram/tests.py**: BaseModel, utility functions (~140 lines, 11+ tests)
|
||||
|
||||
### Writing Tests
|
||||
```python
|
||||
from django.test import TestCase
|
||||
from django.core.exceptions import ValidationError
|
||||
from roster.models import RollingStock
|
||||
|
||||
class RollingStockTestCase(TestCase):
|
||||
def setUp(self):
|
||||
"""Set up test data."""
|
||||
# Create necessary related objects
|
||||
self.company = Company.objects.create(name="RGS", country="US")
|
||||
self.scale = Scale.objects.create(scale="HO", ratio="1:87", tracks=16.5)
|
||||
# ...
|
||||
|
||||
def test_road_number_int_extraction(self):
|
||||
"""Test automatic extraction of integer from road number."""
|
||||
stock = RollingStock.objects.create(
|
||||
rolling_class=self.rolling_class,
|
||||
road_number="RGS-42",
|
||||
scale=self.scale,
|
||||
)
|
||||
self.assertEqual(stock.road_number_int, 42)
|
||||
|
||||
def test_validation_error(self):
|
||||
"""Test that validation errors are raised correctly."""
|
||||
with self.assertRaises(ValidationError):
|
||||
# Test validation logic
|
||||
pass
|
||||
```
|
||||
|
||||
**Testing best practices:**
|
||||
- Use descriptive test method names with `test_` prefix
|
||||
- Include docstrings explaining what each test verifies
|
||||
- Create necessary test data in `setUp()` method
|
||||
- Test both success and failure cases
|
||||
- Use `assertRaises()` for exception testing
|
||||
- Test model properties, methods, and validation logic
|
||||
|
||||
## Git & Version Control
|
||||
|
||||
- Branch: `master` (main development branch)
|
||||
- CI runs on push and PR to master
|
||||
- Follow conventional commit messages
|
||||
- No pre-commit hooks configured (consider adding)
|
||||
|
||||
## Additional Notes
|
||||
|
||||
- **Settings override**: Use `ram/local_settings.py` for local configuration
|
||||
- **Debug mode**: `DEBUG = True` in settings.py (change for production)
|
||||
- **Database**: SQLite by default (in `storage/db.sqlite3`)
|
||||
- **Static files**: Bootstrap 5.3.8, Bootstrap Icons 1.13.1
|
||||
- **Rich text**: TinyMCE for HTMLField content
|
||||
- **REST API**: Disabled by default (`REST_ENABLED = False`)
|
||||
- **Security**: CSP middleware enabled, secure cookies in production
|
||||
Reference in New Issue
Block a user