Aniworld/docs/instructions.md

Aniworld Web Application Development Instructions

This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.

Project Overview

The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in SeriesApp.py while the web layer provides REST API endpoints and a responsive UI.

Architecture Principles

• Single Responsibility: Each file/class has one clear purpose
• Dependency Injection: Use FastAPI's dependency system
• Clean Separation: Web layer calls core logic, never the reverse
• File Size Limit: Maximum 500 lines per file
• Type Hints: Use comprehensive type annotations
• Error Handling: Proper exception handling and logging

Additional Implementation Guidelines

Code Style and Standards

• Type Hints: Use comprehensive type annotations throughout all modules
• Docstrings: Follow PEP 257 for function and class documentation
• Error Handling: Implement custom exception classes with meaningful messages
• Logging: Use structured logging with appropriate log levels
• Security: Validate all inputs and sanitize outputs
• Performance: Use async/await patterns for I/O operations

📞 Escalation

If you encounter:

• Architecture issues requiring design decisions
• Tests that conflict with documented requirements
• Breaking changes needed
• Unclear requirements or expectations

Document the issue and escalate rather than guessing.

---

<EFBFBD> Credentials

Admin Login:

• Username: admin
• Password: Hallo123!

---

<EFBFBD>📚 Helpful Commands

# Run all tests
conda run -n AniWorld python -m pytest tests/ -v --tb=short

# Run specific test file
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v

# Run specific test class
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v

# Run specific test
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v

# Run with extra verbosity
conda run -n AniWorld python -m pytest tests/ -vv

# Run with full traceback
conda run -n AniWorld python -m pytest tests/ -v --tb=long

# Run and stop at first failure
conda run -n AniWorld python -m pytest tests/ -v -x

# Run tests matching pattern
conda run -n AniWorld python -m pytest tests/ -v -k "auth"

# Show all print statements
conda run -n AniWorld python -m pytest tests/ -v -s

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

---

Implementation Notes

1. Incremental Development: Implement features incrementally, testing each component thoroughly before moving to the next
2. Code Review: Review all generated code for adherence to project standards
3. Documentation: Document all public APIs and complex logic
4. Testing: Maintain test coverage above 80% for all new code
5. Performance: Profile and optimize critical paths, especially download and streaming operations
6. Security: Regular security audits and dependency updates
7. Monitoring: Implement comprehensive monitoring and alerting
8. Maintenance: Plan for regular maintenance and updates

---

Task Completion Checklist

For each task completed:

• Implementation follows coding standards
• Unit tests written and passing
• Integration tests passing
• Documentation updated
• Error handling implemented
• Logging added
• Security considerations addressed
• Performance validated
• Code reviewed
• Task marked as complete in instructions.md
• Infrastructure.md updated and other docs
• Changes committed to git; keep your messages in git short and clear
• Take the next task

---

TODO List:

✅ Task Completed Successfully

Issue Fixed: RuntimeError: generator didn't stop after athrow()

Problem: The /api/anime/add endpoint was throwing a 500 error with RuntimeError: generator didn't stop after athrow() when validation errors (HTTPException) were raised after database session dependencies yielded.

Root Cause: Async generator dependencies (get_database_session and get_optional_database_session) didn't properly handle exceptions thrown back into them after yielding. When an HTTPException was raised in the endpoint for validation errors, Python's async context manager tried to propagate the exception to the generator, but without proper exception handling around the yield statement, it resulted in the "generator didn't stop after athrow()" error.

Solution: Added proper exception handling in both database session dependencies by wrapping the yield statement with a try-except block that re-raises any exceptions, allowing FastAPI to handle them correctly.

Files Modified:

1. src/server/utils/dependencies.py - Fixed exception handling in get_database_session and get_optional_database_session
2. tests/unit/test_dependency_exception_handling.py - Created comprehensive unit tests for the fix
3. tests/api/test_anime_endpoints.py - Updated to mock BackgroundLoaderService and expect 202 status codes

Tests:

• ✅ 5 new unit tests for dependency exception handling (all passing)
• ✅ 16 anime endpoint integration tests (all passing)
• ✅ Tests verify proper handling of 400, 404, 422 status codes
• ✅ Tests verify successful requests still work correctly

Note for Users: If you're experiencing this error on a running server, please restart the server to load the fixed code:

# Stop the server (Ctrl+C)
# Then restart:
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

---

Next Tasks:

No pending tasks at this time.