Repository Guidelines

Project Structure & Module Organization

CoinHunter is a Python CLI package using a src/ layout. Application code lives in src/coinhunter/.

src/coinhunter/cli.py defines CLI parsing and command dispatch for coinhunter and coin.
src/coinhunter/binance/ contains thin Binance Spot client wrappers.
src/coinhunter/services/ contains domain logic for account, market, trade, portfolio, opportunity, dataset, research, and evaluation flows.
src/coinhunter/config.py, runtime.py, and audit.py handle runtime config, output, completions, upgrade flow, and logs.
tests/ contains pytest/unittest coverage by service area.
dist/ contains built release artifacts; do not edit these manually.

Build, Test, and Development Commands

Install locally with development tools:

python -m pip install -e '.[dev]'

Run the CLI from the working tree:

coinhunter --help
coin opportunity -s BTCUSDT ETHUSDT --agent

Quality checks:

pytest tests/           # run the full test suite
ruff check src tests    # lint and import ordering
mypy src                # static type checks

Coding Style & Naming Conventions

Use Python 3.10+ syntax and 4-space indentation. Keep modules small and service-oriented; prefer adding logic under src/coinhunter/services/ and keeping cli.py focused on argument parsing and dispatch.

Use snake_case for functions, variables, and modules. Use PascalCase for classes and dataclasses. Preserve existing payload key naming conventions such as notional_usdt, quote_volume, and opportunity_score.

Ruff enforces E, F, I, W, UP, B, C4, and SIM; line length E501 is ignored.

Testing Guidelines

Tests use pytest with unittest.TestCase. Add tests near the changed behavior:

CLI dispatch: tests/test_cli.py
Config/runtime: tests/test_config_runtime.py
Opportunity logic: tests/test_opportunity_service.py
Dataset/evaluation flows: tests/test_opportunity_dataset_service.py

Name tests as test_<behavior>. Prefer fake clients and injected HTTP functions over live network calls. Run pytest tests/ before submitting changes.

Commit & Pull Request Guidelines

Recent history uses short imperative subjects, often Conventional Commit prefixes:

feat: configurable ticker window for market stats
fix: use rolling_window_ticker for symbol-specific queries
refactor: flatten account command to a single balances view

Keep commits focused and describe user-visible behavior. Pull requests should include a concise summary, validation commands run, and any config or CLI changes. Link issues when applicable. For CLI output changes, include before/after examples or JSON snippets.

Security & Configuration Tips

Never commit Binance API keys, secrets, runtime logs, or local ~/.coinhunter files. Runtime secrets belong in ~/.coinhunter/.env; configuration belongs in ~/.coinhunter/config.toml. Use COINHUNTER_HOME for isolated test runs.

3.0 KiB Raw Blame History