How dojcsakj/toggl-track works
Project type and purpose
• Project Type: A Python-based CLI tool combined with a reusable library.
• Purpose: Provide a command-line interface (tgl) and Python API for accessing and formatting data from the Toggl Track REST API (listing time entries, grouping, filtering, output in table/JSON/NDJSON).
File structure
• Top-level:
• setup.py – packaging and entry point definition
• README.md, LICENSE, .github/ – metadata & CI workflows
• toggl_track/ – main package
• tests/ – unit & HTTP-recorded integration tests
• Package contents (toggl_track/):
• __main__.py – module entry, ties into setup.py’s console_scripts
• cli.py – argument parsing (Click or argparse)
• toggl.py – adapter/client for Toggl Track HTTP API
• result.py – transforms raw API JSON into table, JSON, NDJSON
• version.py – versioning
• tests/:
• test_*.py – unit tests for grouping, listing, versioning, formatting
• cassettes/ – recorded HTTP responses for deterministic Toggl API mocks
README for additional insights
• Describes supported commands (entries list, entries group-by, flags for --format, --json-root)
• Notes development workflow: pytest, record-mode for HTTP fixtures
• Emphasizes dual role: CLI tool and importable library
a. Main components
1. User Terminal / Shell (invokes tgl command)
2. CLI Layer (cli.py / entry point)
3. Library Core
– Argument parser module
– Toggl API client (toggl.py)
– Result formatter (result.py)
4. External Service: Toggl Track REST API
5. Testing Harness
– HTTP fixture cassette store
– pytest test runner
b. Relationships & interactions
• Shell → CLI Layer: user issues tgl entries list
• CLI Layer → Argument Parser → invokes business logic
• Business logic → Toggl API client: issues HTTP(S) requests
• Toggl API client ↔ Toggl Track REST API: GET requests, JSON responses
• Business logic → Result Formatter: converts JSON to table/JSON/NDJSON
• Result Formatter → STDOUT: displays or streams data
• Testing Harness → Toggl API client: intercepts HTTP calls using recorded cassettes
c. Architectural patterns & design principles
– Single responsibility: CLI parsing separate from API client, separate from formatting
– Adapter pattern: toggl.py wraps HTTP calls into library methods
– Modular design: importable library core, with CLI glue on top
– Test isolation: use VCR-style cassettes to mock external HTTP
d. Key technologies & libraries
– Python packaging (setup.py, console_scripts)
– HTTP client (requests or httpx inside toggl.py)
– CLI framework (click or argparse in cli.py)
– pytest + vcrpy or pytest-record for tests
– tabulate or custom table formatting in result.py
Elements
– Clear labels: “User / Shell”, “CLI parser”, “Toggl API Client”, “Result Formatter”, “Toggl Track API”, “Test Runner & Cassettes”
• Shell → CLI parser → Business logic → API client → External API
• API client → Business logic → Result formatter → Shell
• Test runner → API client (via cassettes)
Detailed capture of essential elements
• Modules by functional layer (CLI vs core vs external)
• Configuration inputs (e.g., API token via environment or config file) if present
• Output formats as branches from the formatter (Table view, JSON view, NDJSON stream)