Skip to content

Feat: enrich ls commands with Track API, add --stdout to time download - #185

Merged
thekaveman merged 12 commits into
mainfrom
feat/toggl-utils
Nov 14, 2026
Merged

thekaveman merged 12 commits into
mainfrom
feat/toggl-utils

Conversation

@thekaveman

@thekaveman thekaveman commented Jun 2, 2026 •

Copy link
Copy Markdown
Member

Overview

Adds --stdout streaming to time download and enriches the ls subcommands (projects, project-users, clients) with full Toggl Track API data. The --format flag now drives the data source: basic returns a concise subset from the Reports API, while csv and json return all available fields from the Track API.

Changes

time download — --stdout support

  • Added --stdout flag as an alias for --output stdout to stream CSV output directly to stdout
  • Status messages ("Downloading...", completion message) are redirected to stderr when outputting to stdout, keeping the data stream clean
  • Default file output behavior is unchanged: when no --output is provided, a filename is auto-generated from the date range

ls projects — Track API enrichment

  • Added TogglWorkspace.get_projects() method calling the Track API GET /api/v9/workspaces/{workspace_id}/projects with full pagination support
  • CSV/JSON output now includes all Track API fields: client_name, currency, status, rate, estimated_hours, estimated_seconds, actual_hours, actual_seconds, fixed_fee, start_date, end_date, workspace_id, created_at
  • Internal/auxiliary fields excluded: total_count, pinned, can_track_time, permissions, recurring, recurring_parameters

ls project-users — Track API migration

  • Added TogglWorkspace.get_project_users() method calling the Track API GET /api/v9/workspaces/{workspace_id}/project_users with pagination
  • Migrated from Reports API to Track API for richer data
  • Output columns: id, user_id, project_id, workspace_id, rate, labor_cost
  • manager field omitted

ls clients — Track API enrichment

  • Added TogglWorkspace.get_clients() method calling the Track API GET /api/v9/workspaces/{workspace_id}/clients with pagination
  • Added TogglUtils.get_clients_detailed() to fetch full client metadata
  • CSV/JSON output includes: archived, notes, external_reference, integration_ext_id, integration_ext_type, integration_provider, creator_id
  • Internal fields excluded: total_count, permissions, wid

Consolidated --format behavior

All three ls subcommands use --format to determine the data source and output.

@github-actions

github-actions Bot commented Jun 2, 2026 •

Copy link
Copy Markdown

Coverage report

Click to see where and how coverage changed

FileStatementsMissingCoverageCoverage
(new stmts)
Lines missing
  compiler_admin/api
  toggl.py 224, 290-292, 305-307, 320-322
  compiler_admin/commands/ls
  __init__.py
  clients.py
  groups.py
  project_users.py 60, 62-63
  projects.py
  users.py
  compiler_admin/commands/time
  download.py
  compiler_admin/services
  files.py 31
  toggl.py 327, 346, 353, 355, 384, 390, 394, 439, 446, 448, 489, 491, 509, 517, 549
Project Total  

This report was generated by python-coverage-comment-action

@github-actions

github-actions Bot commented Jun 2, 2026

Copy link
Copy Markdown

@thekaveman thekaveman changed the title Feat: implement additional Toggl utility endpoints Feat: implement Toggl utility endpoints Jun 2, 2026
ensure the dev container's Python interpreter is used
implement paging to request all objects
- Add --stdout flag as an alias for --output stdout
- When writing to stdout, redirect status messages to stderr
  so data consumers get a clean stream
- Add tests for --stdout flag, --output stdout, and completion
  message behavior
- Add TogglWorkspace.get_projects() Track API method with pagination
- Add TogglUtils.get_projects_detailed() to fetch full project metadata
- Add --detailed CLI flag to ls projects that returns all Track API fields
  (rate, estimated_hours, fixed_fee, start_date, end_date, etc.)
- Exclude internal/auxiliary fields (total_count, pinned, permissions, etc.)
  from detailed output
- Add tests for --detailed flag, empty results, filters, and basic mode
- Update ls.md guide to document the new --detailed flag
- Add TogglWorkspace.get_project_users() Track API method
- Update TogglUtils.get_project_users() to use Track API with pagination
- Change output columns from old Reports fields to Track API fields:
  id, user_id, project_id, workspace_id, rate, labor_cost
- Manager field omitted per requirements
- Update tests for new API method, pagination, and column output
- Add TogglWorkspace.get_clients() Track API method with pagination
- Add TogglUtils.get_clients_detailed() to fetch full client metadata
- Add --detailed CLI flag to ls clients that returns all Track API fields
  (archived status, notes, integration metadata, etc.)
- Exclude internal/auxiliary fields (total_count, permissions, wid)
  from detailed output
- Add tests for --detailed flag, empty results, basic mode, and
  pagination
- Update ls.md guide to document the new --detailed flag
- Remove --detailed flag from ls projects and ls clients
- --format basic uses Reports API (concise output)
- --format csv/json uses Track API (all available fields)
- Consolidated exclusion of internal/auxiliary fields into module
  level constants for both commands
- Updated all tests to use --format csv/json instead of --detailed
- Updated ls.md guide to document the consolidated behavior
@thekaveman thekaveman changed the title Feat: implement Toggl utility endpoints Feat: enrich ls commands with Track API, add --stdout to time download Nov 14, 2026
@thekaveman
thekaveman marked this pull request as ready for review November 14, 2026 00:58
Pandas casts columns with missing values to float, causing integer IDs
to render with .0 decimals (e.g. 12345.0 instead of 12345). Fixed by
converting id, client_id, user_id, project_id, and workspace_id
columns to nullable Int64 before writing CSV.

Also add _normalize_int_fields() to convert known integer columns (id,
client_id, user_id, project_id, workspace_id, creator_id) from float
to int in the service layer. This prevents pandas from rendering them
as 12345.0 in JSON output when the API returns them as floats.
@thekaveman
thekaveman merged commit 24751c3 into main Nov 14, 2026
4 checks passed
@thekaveman
thekaveman deleted the feat/toggl-utils branch November 14, 2026 01:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant