tidal-dl/AGENTS.md

applyTo

applyTo
**/*.py

Project General Coding Standards

Python Version Support

• Target Python 3.12 and 3.13
• Use modern Python features supported by the minimum version (3.12)
• Avoid deprecated features and use future-proof syntax

Naming Conventions

• Use snake_case for variable and function names
• Use CamelCase for class names
• Follow PEP 8 style guidelines strictly
• Prefix private class members with underscore (_)
• Use ALL_CAPS for constants
• Use descriptive names that clearly indicate purpose and content
• Avoid single-letter variable names except for loop counters or mathematical contexts

Type Annotations

• Use type annotations for ALL function and method parameters, return types, and variables (PEP 484)
• Use modern built-in generics: list, dict, set, tuple instead of List, Dict, Set, Tuple from typing
• Use None type for optional parameters: str | None instead of Optional[str]
• Use union types with | operator: int | str instead of Union[int, str]
• For complex types, import from collections.abc: Callable, Iterable, etc.
• Always specify generic types: use list[str] not just list
• Use pathlib.Path for file paths, not str

Error Handling

• Use try/except blocks for operations that may fail
• Always log errors with contextual information using the project's logger
• Catch specific exceptions, avoid bare except: clauses
• Use finally blocks for cleanup operations
• For HTTP operations with requests library:
  • Use timeout parameter (default: REQUESTS_TIMEOUT_SEC)
  • Implement retry logic with requests.adapters.Retry for network operations
  • Always close response objects in finally blocks or use context managers
• For file operations:
  • Use context managers (with statement) for file handling
  • Use pathlib.Path methods for path operations
  • Handle OSError and its subclasses appropriately

Code Style and Formatting

• Line length: maximum 120 characters (as configured in Black and Ruff)
• Use Black formatting style with preview features enabled
• Follow isort configuration for import ordering:
  1. FUTURE
  2. TYPING
  3. STDLIB
  4. THIRDPARTY
  5. FIRSTPARTY
  6. LOCALFOLDER
• Include trailing commas in multi-line constructs
• Use more blank lines to achieve better code organization and readability
• Use 4 spaces for indentation (no tabs)

Modern Python Features

• Follow PEP 492 – Coroutines with async and await syntax (when applicable)
• Follow PEP 498 – Literal String Interpolation (f-strings)
• Follow PEP 572 – Assignment Expressions (walrus operator := when it improves readability)
• Use structural pattern matching (match/case) for Python 3.10+ when appropriate
• Prefer pathlib.Path over os.path for file operations
• Use Enum and StrEnum for constants with related values
• Use dataclasses or dataclasses-json for structured data

Concurrency and Threading

• Use concurrent.futures.ThreadPoolExecutor for I/O-bound parallel operations
• Always use context managers with executors
• Set appropriate max_workers based on operation type (use configuration values)
• Handle futures with futures.as_completed() for better responsiveness
• Implement abort/cancellation mechanisms using threading.Event
• Cancel pending futures when aborting operations
• Use thread-safe data structures when sharing data between threads
• Avoid blocking operations in GUI threads

Resource Management

• Always use context managers (with statements) for:
  • File operations
  • Network connections
  • Thread pools and executors
  • Temporary directories and files
• Use tempfile.TemporaryDirectory with ignore_cleanup_errors=True for temp operations
• Close network responses explicitly in finally blocks or use context managers
• Clean up temporary files after processing
• Use pathlib.Path.unlink(missing_ok=True) for safe file deletion

File and Path Handling

• Use pathlib.Path exclusively for path operations
• Sanitize file paths using pathvalidate.sanitize_filename and project's path_file_sanitize
• Use .expanduser() for paths that may contain ~
• Use .absolute() to get absolute paths
• Use .resolve() to resolve symlinks
• Check file existence with Path.exists(), Path.is_file(), Path.is_dir()
• Use os.makedirs(path, exist_ok=True) or Path.mkdir(parents=True, exist_ok=True)
• Handle cross-platform path differences automatically with pathlib

Code Documentation

• Write docstrings for ALL modules, classes, functions, and methods using Google docstring style
• Include type information in docstrings even when type hints are present
• Document all parameters with their types and descriptions
• Document return values with type and description
• Document raised exceptions
• Use line comments to explain complex logic, algorithms, or non-obvious decisions
• When refactoring code:
  • Update or add docstrings to reflect new behavior
  • Update existing line comments rather than removing them
  • Add TODO comments for known limitations or future improvements

Logging

• Use the project's logger (via fn_logger or similar)
• Log levels:
  • debug: Detailed diagnostic information
  • info: General informational messages (e.g., download completion)
  • error: Error conditions with context
  • exception: Errors with full traceback
• Include relevant context in log messages (file names, IDs, URLs, etc.)
• Use f-strings for log message formatting

GUI Development (PySide6/Qt)

• Follow Qt naming conventions for slots and signals
• Use type hints for signal parameters
• Emit signals for cross-thread communication (never call GUI methods directly from worker threads)
• Use Qt's threading mechanisms appropriately
• Handle GUI progress updates via signals
• Implement proper cleanup in close events
• Use QThread or ThreadPoolExecutor for background operations, never block the GUI thread

API Integration (TIDAL)

• Always check if media is available before processing (media.available)
• Handle tidalapi.exceptions.TooManyRequests gracefully
• Implement retry logic for transient failures
• Use sessions appropriately
• Handle stream manifests and encryption properly
• Respect API rate limits and implement delays when configured

Testing

• Place tests in the tests/ directory
• Use pytest as the testing framework
• Use descriptive test function names: test_<functionality_being_tested>
• Test edge cases: empty lists, None values, invalid inputs
• Mock external dependencies (API calls, file system when appropriate)
• Use fixtures for common test setup
• Aim for meaningful test coverage, not just high percentages

Security

• Never hardcode credentials (use configuration or environment variables)
• Use base64 encoding only for obfuscation, not security
• Handle sensitive data (tokens, keys) carefully
• Use secure temporary file creation
• Validate and sanitize all user inputs, especially file paths
• Handle decryption keys securely (don't log them)

Performance

• Use generators for large datasets when possible
• Implement streaming for large file downloads
• Use appropriate chunk sizes for file I/O (use CHUNK_SIZE constant)
• Cache expensive computations when safe to do so
• Use batch operations where applicable
• Profile code before optimizing
• Consider memory usage for large collections

Configuration and Settings

• Use the Settings class for all configuration
• Access settings via self.settings.data.*
• Validate configuration values
• Provide sensible defaults
• Use type-safe configuration access
• Document configuration options

Code Quality Tools

• Run Ruff for linting before committing
• Run Black for formatting before committing
• Run mypy for type checking
• Use pre-commit hooks to automate checks
• Address all linting warnings and errors
• Keep code complexity low (avoid deep nesting, long functions)

Best Practices Summary

1. Type Safety: Always use type hints, enable strict mypy checks
2. Error Handling: Catch specific exceptions, log with context, clean up resources
3. Readability: Write self-documenting code with clear names and structure
4. Documentation: Comprehensive docstrings and comments for complex logic
5. Testing: Test edge cases and error conditions
6. Performance: Use efficient algorithms and data structures
7. Maintainability: Keep functions focused, avoid code duplication
8. Security: Validate inputs, handle credentials safely
9. Compatibility: Support Python 3.12-3.13, handle cross-platform differences
10. Standards: Follow PEP 8, PEP 484, and project-specific configurations