chore(release): version 1.3.0

Author: ddkasa

.github/workflows/publish.yaml

@@ -44,6 +44,8 @@ jobs:
     env:
       TOGGL_WORKSPACE_ID: ${{ secrets.TOGGL_WORKSPACE_ID }}
       TOGGL_API_TOKEN: ${{ secrets.TOGGL_API_TOKEN }}
+      TOGGL_ORGANIZATION_ID: ${{ secrets.TOGGL_ORGANIZATION_ID }}
+      TOGGL_USER_ID: ${{ secrets.TOGGL_USER_ID }}
       GH_ACTION: "ACTION"
 
     steps:

docs/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.0] - 2024-10-31
+
+### 🚀 Features
+
+- *(workspace)* Workspace body dataclass
+- *(workspace)* Add workspace endpoint
+- *(workspace)* Collect workspaces endpoint
+- *(workspace)* Edit workspace endpoint
+- *(workspace)* Get time constraints
+- *(workspace)* Statistics endpoint
+- *(models)* Organization model
+- *(schema)* Added organization model
+- *(endpoint)* Added organization endpoint
+- *(organization)* Add endpoint method
+- *(organization)* Get endpoint method
+- *(models)* Validate organization name
+- *(models)* Validate workspace name
+- *(organization)* Edit endpoint method
+- *(organization)* Collect endpoint method
+- *(organization)* Delete endpoint method
+- *(workspace)* Organization id property
+- *(utility)* Add org endpoint to cleanup
+- Add organization objects to __init__
+
+### 🐛 Bug Fixes
+
+- *(endpoint)* Api status not catching json decode error
+- *(body)* Verifying wrong variable
+- *(organization)* Make sure edit method stores and returns model
+
+### 🚜 Refactor
+
+- *(workspace)* Use a blank endpoint property
+- *(endpoint)* [**breaking**] Remove unnecessary class variables
+- *(workspace)* Improve get method error handling
+
+### 🕸 Deprecations
+
+- *(workspace)* Accept organization instead of workspace
+- *(workspace)* Turn get method workspace argument optional
+
+### 📚 Documentation
+
+- *(examples)* Improve authentication information
+- *(workspace)* Document new workspace features
+- *(workspace)* Improve docstrings
+- *(api)* Update project structure and mermaid
+- *(organization)* Add organization to api reference
+- *(workspace)* Add typed dicts to api documentation
+- *(config)* Reword deprecation
+- *(models)* Improve model documentation
+
+### ⚙️ Miscellaneous Tasks
+
+- *(dev-deps)* Pytest dependency added
+- *(actions)* Add new secrets to environment
+
+### 🧪 Testing
+
+- *(conftest)* Organization id fixture
+- *(workspace)* Cover new endpoint methods
+- *(tags)* Extra delete method validation
+- *(user)* Fix test date creation
+- *(workspace)* Use org id instead
+- *(organization)* Test all functionality
+- *(conftest)* User id fixture
+
 ## [1.2.0] - 2024-10-27
 
 ### 🚀 Features

docs/api-guide/model.md

@@ -1,19 +1,41 @@
 # Abstract Classes
 
 ::: toggl_api.models.TogglClass
+    options:
+        show_source: true
 
 ::: toggl_api.models.WorkspaceChild
+    options:
+        show_source: true
 
 ---
 
 # Main Models
 
+::: toggl_api.TogglOrganization
+    options:
+        show_source: true
+        members:
+            - validate_name
+
 ::: toggl_api.TogglWorkspace
+    options:
+        show_source: true
+        members:
+            - validate_name
 
 ::: toggl_api.TogglClient
+    options:
+        show_source: true
 
 ::: toggl_api.TogglProject
+    options:
+        show_source: true
 
 ::: toggl_api.TogglTracker
+    options:
+        show_source: true
 
 ::: toggl_api.TogglTag
+    options:
+        show_source: true

docs/api-guide/organization.md

@@ -0,0 +1,4 @@
+> [!NOTE]
+> Organization endpoint doesn't require a workspace id.
+
+::: toggl_api.OrganizationEndpoint

docs/api-guide/project_structure.txt

@@ -28,3 +28,37 @@ toggl_api
 ├── utility.py
 ├── version.py
 └── workspace.py
+toggl_api
+├── client.py
+├── config.py
+├── __init__.py
+├── meta
+│   ├── base_endpoint.py
+│   ├── body.py
+│   ├── cache
+│   │   ├── base_cache.py
+│   │   ├── __init__.py
+│   │   ├── json_cache.py
+│   │   └── sqlite_cache.py
+│   ├── cached_endpoint.py
+│   ├── enums.py
+│   └── __init__.py
+├── models
+│   ├── _decorators.py
+│   ├── __init__.py
+│   ├── models.py
+│   └── schema.py
+├── organization.py
+├── project.py
+├── py.typed
+├── reports
+│   ├── __init__.py
+│   └── reports.py
+├── tag.py
+├── tracker.py
+├── user.py
+├── utility.py
+├── version.py
+└── workspace.py
+
+5 directories, 27 files

docs/api-guide/workspace.md

@@ -1,5 +1,26 @@
+
+::: toggl_api.WorkspaceBody
+    options:
+        show_source: true
+
 ::: toggl_api.WorkspaceEndpoint
     options:
         show_source: true
         members:
             - get
+            - add
+            - collect
+            - edit
+            - tracker_constraints
+            - statistics
+
+
+# Types
+
+::: toggl_api.workspace.User
+    options:
+        show_source: true
+
+::: toggl_api.workspace.WorkspaceStatistics
+    options:
+        show_source: true

docs/static/mermaid/classes.mmd

@@ -59,6 +59,16 @@ classDiagram
     commit(path: Path) None
     load(path: Path) None
     process_data(data: list[TogglClass]) list[TogglClass]
+    refresh(path: Path) bool
+  }
+  class OrganizationEndpoint {
+    endpoint
+    model
+    add(name: str, workspace_name: str) TogglOrganization
+    collect() list[TogglOrganization]
+    delete(organization: TogglOrganization | int) None
+    edit(organization: TogglOrganization | int, name: str) TogglOrganization
+    get(organization: TogglOrganization | int) TogglOrganization | None
   }
   class PaginatedResult {
     next_id : Optional[int]
@@ -191,9 +201,6 @@ classDiagram
   class TogglEndpoint {
     BASE_ENDPOINT : str
     HEADERS : Final[dict]
-    NOT_FOUND : Final[int]
-    OK_RESPONSE : Final[int]
-    SERVER_ERROR : Final[int]
     endpoint
     model
     workspace_id : int
@@ -202,6 +209,10 @@ classDiagram
     process_models(data: list[dict[str, Any]]) list[TogglClass]
     request(parameters: str, headers: Optional[dict], body: Optional[dict], method: RequestMethod) Any
   }
+  class TogglOrganization {
+    from_kwargs() TogglOrganization
+    validate_name(name: str) None
+  }
   class TogglProject {
     active : bool
     client : Optional[int]
@@ -227,7 +238,10 @@ classDiagram
     running() bool
   }
   class TogglWorkspace {
+    name : str
+    organization : int
     from_kwargs() TogglWorkspace
+    validate_name(name: str) None
   }
   class TrackerBody {
     created_with : str
@@ -258,6 +272,10 @@ classDiagram
     process_bind_param(value: datetime, _) datetime | None
     process_result_value(value: Optional[datetime], _) datetime | None
   }
+  class User {
+    name : str
+    user_id : int
+  }
   class UserEndpoint {
     TRACKER_NOT_RUNNING : Final[int]
     endpoint
@@ -266,32 +284,63 @@ classDiagram
     collect(since: Optional[int | datetime], before: Optional[date], start_date: Optional[date], end_date: Optional[date]) list[TogglTracker]
     current() TogglTracker | None
     get(tracker_id: int | TogglTracker) TogglTracker | None
+    get_details() dict[str, Any]
+    verify_authentication(auth: BasicAuth) bool
   }
   class WeeklyReportEndpoint {
     endpoint
     export_report(body: ReportBody, extension: REPORT_FORMATS) bytes
     search_time_entries(body: ReportBody) list[dict[str, Any]]
   }
+  class WorkspaceBody {
+    admins : list[int]
+    name : Optional[str]
+    only_admins_may_create_projects : bool
+    only_admins_may_create_tags : bool
+    only_admins_see_billable_rates : bool
+    only_admins_see_team_dashboard : bool
+    projects_billable_by_default : bool
+    projects_enforce_billable : bool
+    projects_private_by_default : bool
+    rate_change_mode : Optional[Literal['start-today', 'override-current', 'override-all']]
+    reports_collapse : bool
+    rounding : Optional[int]
+    rounding_minutes : Optional[int]
+    format(endpoint: str) dict[str, Any]
+  }
   class WorkspaceChild {
     workspace : int
     from_kwargs() WorkspaceChild
   }
   class WorkspaceEndpoint {
     endpoint
     model
+    organization_id
+    add(organization_id: int, body: WorkspaceBody) TogglWorkspace
+    collect(since: Optional[datetime | int]) list[TogglWorkspace]
+    edit(workspace_id: TogglWorkspace | int, body: WorkspaceBody) TogglWorkspace
     get(workspace: Optional[TogglWorkspace | int]) TogglWorkspace | None
+    statistics(workspace_id: TogglWorkspace | int) WorkspaceStatistics
+    tracker_constraints(workspace_id: TogglWorkspace | int) dict[str, bool]
+  }
+  class WorkspaceStatistics {
+    admins : list[User]
+    groups_count : int
+    members_count : int
   }
   ClientBody --|> BaseBody
   ClientEndpoint --|> TogglCachedEndpoint
   JSONCache --|> TogglCache
   SqliteCache --|> TogglCache
   TogglCachedEndpoint --|> TogglEndpoint
   TogglClient --|> WorkspaceChild
+  TogglOrganization --|> TogglClass
   TogglProject --|> WorkspaceChild
   TogglTag --|> WorkspaceChild
   TogglTracker --|> WorkspaceChild
   TogglWorkspace --|> TogglClass
   WorkspaceChild --|> TogglClass
+  OrganizationEndpoint --|> TogglCachedEndpoint
   ProjectBody --|> BaseBody
   ProjectEndpoint --|> TogglCachedEndpoint
   DetailedReportEndpoint --|> ReportEndpoint
@@ -303,6 +352,7 @@ classDiagram
   TrackerBody --|> BaseBody
   TrackerEndpoint --|> TogglCachedEndpoint
   UserEndpoint --|> TogglCachedEndpoint
+  WorkspaceBody --|> BaseBody
   WorkspaceEndpoint --|> TogglCachedEndpoint
   Comparison --* TogglQuery : comparison
   JSONSession --* JSONCache : session

docs/static/mermaid/packages.mmd

@@ -31,6 +31,8 @@ classDiagram
   }
   class schema {
   }
+  class organization {
+  }
   class project {
   }
   class reports {
@@ -87,6 +89,9 @@ classDiagram
   schema --> _decorators
   schema --> models
   schema --> utility
+  organization --> meta
+  organization --> meta
+  organization --> models
   project --> meta
   project --> models
   project --> utility
@@ -105,6 +110,9 @@ classDiagram
   user --> models
   user --> utility
   workspace --> meta
+  workspace --> body
+  workspace --> base_cache
+  workspace --> enums
   workspace --> models
   base_cache ..> meta
   base_cache ..> models
@@ -113,3 +121,4 @@ classDiagram
   sqlite_cache ..> meta
   cached_endpoint ..> cache
   cached_endpoint ..> base_cache
+  organization ..> base_cache

docs/user-guide/examples.md

@@ -8,7 +8,8 @@ All Tracker, Client, Project & Tag endpoints will have most of these methods:
 
 ---
 
-- With environment variables setup correctly.
+> [!INFO]
+> With environment variables setup correctly.
 
 ### Tracker Example
 
@@ -33,6 +34,9 @@ All Tracker, Client, Project & Tag endpoints will have most of these methods:
 
 ### Project Example
 
+> [!INFO]
+> Using an existing togglrc file.
+
 ```python
 {% include "examples/project_example.py" %}
 ```

mkdocs.yml

@@ -66,6 +66,7 @@ nav:
       - Endpoint: api-guide/endpoint.md
       - Cache: api-guide/cache.md
       - Models: api-guide/model.md
+      - Organization: api-guide/organization.md
       - Workspace: api-guide/workspace.md
       - Trackers: api-guide/tracker.md
       - Projects: api-guide/project.md