AGENTS.md

Operational guide for agentic coding assistants in this repository.

Repository Snapshot

• Project type: Python demo project for video/audio download and search.
• Python: 3.12 (.python-version, pyproject.toml).
• Dependency manager: uv (uv.lock is present).
• Primary libs: yt-dlp, pytubefix (from Git URLs).
• Flat source layout: main.py, demo_ytdlp.py, demo_pytubefix.py.
• No test suite exists yet.

Rule Files

Checked for extra instruction files:

• .cursorrules: not found
• .cursor/rules/: not found
• .github/copilot-instructions.md: not found If these files are added later, follow them when they conflict with this file.

Build, Lint, and Test Commands

This repo has no formal build step. Use lint + script execution as verification.

Environment / Dependencies

• Sync environment from lockfile:
  • uv sync
• Add dependency:
  • uv add <package>
• Run command inside project environment:
  • uv run <command>

Run Scripts

• Basic yt-dlp demo:
  • uv run python main.py
• yt-dlp feature demo:
  • uv run python demo_ytdlp.py
• pytubefix feature demo:
  • uv run python demo_pytubefix.py

Lint / Format

Ruff is configured in pyproject.toml.

• Lint all files:
  • uv run ruff check .
• Auto-fix lint issues:
  • uv run ruff check . --fix
• Format all files:
  • uv run ruff format .
• Verify formatting only:
  • uv run ruff format . --check

Test Commands

No tests currently exist, but use pytest conventions when tests are added.

• Run all tests:
  • uv run pytest
• Run one test file:
  • uv run pytest tests/test_example.py
• Run one test function:
  • uv run pytest tests/test_example.py::test_function_name
• Run one class method:
  • uv run pytest tests/test_example.py::TestClassName::test_method_name

Single-Test Execution (Important)

Preferred deterministic form (node id):

• uv run pytest path/to/test_file.py::test_name Optional fuzzy matching while debugging:
• uv run pytest -k "keyword" Prefer explicit node IDs for agent runs.

Code Style: Enforced Rules

From pyproject.toml:

• Target Python: py312
• Line length: 119
• Quote style: double quotes
• Indentation: spaces
• McCabe max complexity: 12
• Enabled Ruff lint groups: E, F, I, B, UP, C90, C4, SIM, RET
• E501 is ignored; keep long lines readable.

Code Style: Local Conventions

Inferred from current source files.

Imports

• Keep imports at module top.
• Rely on Ruff sorting (I rules).
• Remove unused imports.

Naming

• Use snake_case for functions and variables.
• Use action-oriented function names (demo_get_info, demo_audio_download).
• Use clear config names (ydl_opts, output_path).

Types

• Keep type hints on public params and returns.
• Prefer built-in types (str, list[str], etc.) where practical.
• Avoid Any unless required by third-party APIs.

Strings and Output

• Prefer f-strings for interpolation.
• Keep output simple and explicit.

Entry Points and Resource Use

• Use if __name__ == "__main__": for script execution blocks.
• Use context managers for downloader lifecycle (with yt_dlp.YoutubeDL(...)).

Error Handling

Current demo scripts mostly allow exceptions to surface. For new non-trivial logic:

• Catch only exceptions you can handle.
• Include actionable context in errors (URL, path, operation).
• Never swallow exceptions silently.

Comments and Docstrings

• Keep docstrings short and task-focused.
• Existing files use Chinese docstrings/comments; preserve local style unless asked to change.
• Add comments only for non-obvious behavior.

Project Organization Guidance

• Keep changes minimal and targeted.
• Preserve current demo behavior unless task requires behavior changes.
• If reusable logic grows, create a package directory instead of expanding root scripts indefinitely.
• Keep generated artifacts in outputs/ or dedicated data files, not in source modules.

Runtime Notes

• Some flows rely on local cookies.txt for authenticated downloads.
• demo_ytdlp.py may depend on local runtime components (for example Node/EJS integration).
• Never commit secrets, cookies, or credentials.

Agent Verification Checklist

After edits:

1. uv run ruff check .
2. uv run ruff format . --check
3. Run touched script(s) when feasible.
4. If tests exist for touched code, run targeted tests first, then full test run. If a command cannot be executed, report why in handoff.