chore(merge): '2.2.0-release' into 'main'

ddkasa · ddkasa · commit 7c5b9af6ef73 · 2025-05-10T15:50:40.000+01:00
diff --git a/docs/api-guide/utility.md b/docs/api-guide/utility.md
@@ -0,0 +1,52 @@
+## Generate Placeholder Data
+
+> [!INFO]
+> This script requires [Faker](https://github.com/hrishikeshio/Faker.py) to be installed. Install with `pip install faker`.
+
+#### Entrypoint
+
+```sh
+generate-fake-toggl-data
+```
+
+### Arguments and Usage
+
+#### Usage
+
+```sh
+usage: generate-fake-toggl-data [-h] [-s SEED] [--cache-type {sqlite,json}] cache_path
+```
+
+#### Arguments
+
+| Short | Long           | Default | Description                                                                             |
+| ----- | -------------- | ------- | --------------------------------------------------------------------------------------- |
+| `-h`  | `--help`       |         | Show this help message and exit.                                                        |
+| `-s`  | `--seed`       | `None`  | Set the seed value.                                                                     |
+| `-t`  | `--cache-type` | `None`  | Cache storage type.<br> Required if `cache_path` doesn't end with _.json_ or _.sqlite_. |
+
+## Clean Toggl Account
+
+> [!WARNING]
+> This will permanently delete data off a Toggl account! Be sure of what you are doing before using this script.
+
+### Entrypoint
+
+```sh
+clean-toggl-account
+```
+
+### Arguments and Usage
+
+#### Usage
+
+```sh
+usage: clean-toggl-account [-h] [-o {tracker,project,tag,client,org} [{tracker,project,tag,client,org} ...]]
+```
+
+#### Arguments
+
+| Short | Long        | Default | Description                      |
+| ----- | ----------- | ------- | -------------------------------- |
+| `-h`  | `--help`    |         | Show this help message and exit. |
+| `-o`  | `--objects` | `None`  | Which objects not to parse.      |
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -75,6 +75,7 @@ nav:
       - Client: api-guide/client.md
       - Tags: api-guide/tag.md
       - Reports: api-guide/reports.md
+      - Utilities: api-guide/utility.md
   - Changelog: CHANGELOG.md
   - About:
       - Contributing: CONTRIBUTING.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -85,6 +85,10 @@ docs = [
 type = ["mypy>=1.15.0", "sqlalchemy[mypy]>=2.0.37"]
 lint = ["ruff>=0.9.5"]
 
+[project.scripts]
+clean-toggl-account = "toggl_api.utility._clean_account:main"
+generate-fake-toggl-data = "toggl_api.utility._generate_fake_data:main"
+
 
 [build-system]
 requires = ["hatchling"]
@@ -234,6 +238,9 @@ omit = [
     "*/.github/*",
     "*/.tox/*",
     "*/.git/*",
+    "src/toggl_api/utility/_cleanup.py",
+    "src/toggl_api/utility/_clean_account.py",
+    "src/toggl_api/utility/_generate_fake_data.py",
 ]
 
 [tool.coverage.report]
@@ -250,6 +257,7 @@ exclude_also = [
     "if TYPE_CHECKING:",
     "class .*\\bProtocol\\):",
     "@(abc\\.)?abstractmethod",
+
 ]
 
 # git-cliff ~ default configuration file
diff --git a/src/toggl_api/_project.py b/src/toggl_api/_project.py
@@ -8,8 +8,8 @@
 from httpx import Client, HTTPStatusError, Timeout, codes
 
 from toggl_api._exceptions import NamingError
-from toggl_api._utility import format_iso, get_timestamp
 from toggl_api.meta.cache import Comparison, TogglQuery
+from toggl_api.utility import format_iso, get_timestamp
 
 from .meta import BaseBody, RequestMethod, TogglCachedEndpoint
 from .models import TogglProject
diff --git a/src/toggl_api/_tracker.py b/src/toggl_api/_tracker.py
@@ -17,10 +17,10 @@
 from httpx import Client, HTTPStatusError, Response, Timeout, codes
 
 from ._exceptions import DateTimeError, NamingError
-from ._utility import format_iso, get_timestamp
 from .meta import BaseBody, RequestMethod, TogglCachedEndpoint
 from .meta.cache import Comparison, TogglQuery
 from .models import TogglTracker
+from .utility import format_iso, get_timestamp
 
 if TYPE_CHECKING:
     from httpx import BasicAuth
diff --git a/src/toggl_api/_workspace.py b/src/toggl_api/_workspace.py
@@ -11,10 +11,10 @@
 from httpx import Client, HTTPStatusError, Response, Timeout, codes
 
 from ._exceptions import DateTimeError, NamingError
-from ._utility import get_timestamp
 from .meta import BaseBody, RequestMethod, TogglCachedEndpoint
 from .meta.cache import Comparison, TogglCache, TogglQuery
 from .models import TogglWorkspace
+from .utility import get_timestamp
 
 if TYPE_CHECKING:
     from httpx import BasicAuth
diff --git a/src/toggl_api/asyncio/_async_reports.py b/src/toggl_api/asyncio/_async_reports.py
@@ -7,7 +7,6 @@
 from httpx import URL, AsyncClient, BasicAuth, Response
 
 from toggl_api import TogglProject, TogglWorkspace
-from toggl_api._utility import format_iso
 from toggl_api.meta import RequestMethod
 from toggl_api.reports import (
     PaginatedResult,
@@ -16,6 +15,7 @@
     ReportFormats,
     _validate_extension,
 )
+from toggl_api.utility import format_iso
 
 from ._async_endpoint import TogglAsyncEndpoint
 
diff --git a/src/toggl_api/asyncio/_async_tracker.py b/src/toggl_api/asyncio/_async_tracker.py
@@ -13,8 +13,8 @@
 from toggl_api import TogglTracker, TrackerBody
 from toggl_api._exceptions import DateTimeError, NamingError
 from toggl_api._tracker import BulkEditParameter, Edits
-from toggl_api._utility import format_iso, get_timestamp
 from toggl_api.meta import RequestMethod
+from toggl_api.utility import format_iso, get_timestamp
 
 from ._async_endpoint import TogglAsyncCachedEndpoint
 
diff --git a/src/toggl_api/asyncio/_async_workspace.py b/src/toggl_api/asyncio/_async_workspace.py
@@ -12,8 +12,8 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from toggl_api import DateTimeError, TogglWorkspace
-from toggl_api._utility import get_timestamp
 from toggl_api.meta import RequestMethod
+from toggl_api.utility import get_timestamp
 
 from ._async_endpoint import TogglAsyncCachedEndpoint
 
diff --git a/src/toggl_api/meta/cache/_json_cache.py b/src/toggl_api/meta/cache/_json_cache.py
@@ -12,7 +12,6 @@
 from typing import TYPE_CHECKING, Any, Final, Generic, TypeVar, cast
 
 from toggl_api.__about__ import __version__
-from toggl_api._utility import parse_iso
 from toggl_api.models import (
     TogglClass,
     TogglClient,
@@ -22,6 +21,7 @@
     TogglWorkspace,
     as_dict_custom,
 )
+from toggl_api.utility import parse_iso
 
 from ._base_cache import Comparison, TogglCache, TogglQuery
 
diff --git a/src/toggl_api/meta/cache/_sqlite_cache.py b/src/toggl_api/meta/cache/_sqlite_cache.py
@@ -1,5 +1,4 @@
 """SQLite cache module."""
-# ruff: noqa: E402
 
 from __future__ import annotations
 
@@ -18,9 +17,9 @@
 import contextlib
 from collections.abc import Sequence
 
-from toggl_api._utility import _requires
 from toggl_api.models import TogglClass
 from toggl_api.models._schema import register_tables
+from toggl_api.utility._helpers import _requires
 
 from ._base_cache import Comparison, TogglCache, TogglQuery
 
diff --git a/src/toggl_api/models/_models.py b/src/toggl_api/models/_models.py
@@ -15,7 +15,7 @@
     from typing_extensions import Self
 
 from toggl_api._exceptions import NamingError
-from toggl_api._utility import get_workspace, parse_iso
+from toggl_api.utility import get_workspace, parse_iso
 
 log = logging.getLogger("toggl-api-wrapper.model")
 
@@ -365,7 +365,7 @@ class TogglTracker(WorkspaceChild):
         ),
     )
     duration: timedelta | None = field(default=None)
-    stop: datetime | str | None = field(default=None)
+    stop: datetime | None = field(default=None)
     project: int | None = field(default=None)
     tags: list[TogglTag] = field(default_factory=list)
 
@@ -378,12 +378,6 @@ def __post_init__(self) -> None:
         if isinstance(self.duration, float | int):
             self.duration = timedelta(seconds=self.duration)
 
-        if self.stop:
-            self.stop = parse_iso(self.stop)  # type: ignore[assignment]
-        else:
-            now = datetime.now(tz=timezone.utc)
-            self.duration = now - self.start
-
         if isinstance(self.stop, str | datetime):
             self.stop = parse_iso(self.stop)  # type: ignore[assignment]
 
diff --git a/src/toggl_api/models/_schema.py b/src/toggl_api/models/_schema.py
@@ -20,7 +20,7 @@
     from sqlalchemy.sql import func
 
 
-from toggl_api._utility import _requires
+from toggl_api.utility._helpers import _requires
 
 from ._models import (
     TogglClient,
diff --git a/src/toggl_api/reports.py b/src/toggl_api/reports.py
@@ -9,9 +9,9 @@
 
 from toggl_api._exceptions import DateTimeError
 
-from ._utility import format_iso
 from .meta import BaseBody, RequestMethod, TogglEndpoint
 from .models import TogglProject, TogglWorkspace
+from .utility import format_iso
 
 ReportFormats = Literal["pdf", "csv"]
 
diff --git a/src/toggl_api/utility/__init__.py b/src/toggl_api/utility/__init__.py
@@ -0,0 +1,11 @@
+"""Module that contains various utility functions and scripts."""
+
+from ._helpers import (  # noqa: F401 # NOTE: Private helper.
+    _requires,
+    format_iso,
+    get_timestamp,
+    get_workspace,
+    parse_iso,
+)
+
+__all__ = ["format_iso", "get_timestamp", "get_workspace", "parse_iso"]
diff --git a/src/toggl_api/utility/_clean_account.py b/src/toggl_api/utility/_clean_account.py
@@ -1,40 +1,51 @@
+"""Contains an entrypoint for cleaning out a Toggl account."""
+
 from __future__ import annotations
 
 import argparse
 import logging
 import os
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Final, Literal, get_args
 
 from toggl_api.config import AuthenticationError, generate_authentication
 
-from .utils import _client_cleanup, _org_cleanup, _path_cleanup, _project_cleanup, _tag_cleanup, _tracker_cleanup
+from ._cleanup import _client_cleanup, _org_cleanup, _path_cleanup, _project_cleanup, _tag_cleanup, _tracker_cleanup
 
 if TYPE_CHECKING:
     from httpx import BasicAuth
 
-log = logging.getLogger("toggl-api-wrapper.scripts")
+log = logging.getLogger("toggl-api-wrapper.utility")
+
+
+Sections = Literal["tracker", "project", "tag", "client", "org"]
 
+SECTIONS: Final = frozenset(get_args(Sections))
 
-DEFAULT_OBJECT: frozenset[str] = frozenset({"tracker", "project", "tag", "client", "org"})
 
+def _generate_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser("Clean Toggl Account")
+    parser.add_argument(
+        "-o",
+        "--objects",
+        nargs="+",
+        help="Which objects not to parse.",
+        choices=SECTIONS,
+    )
+    return parser
 
-def _target_objects() -> set[str]:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("-o", "--objects", nargs="+", help="Which objects not to parse.")
 
+def _target_objects(parser: argparse.ArgumentParser) -> frozenset[Sections]:
     args = parser.parse_args().objects
-    targets = set(DEFAULT_OBJECT)
+    targets = SECTIONS
     if args is None:
         return targets
 
-    targets.difference_update(args)
+    return targets.difference(args)
 
-    return targets
 
-
-def _clean(args: set[str], auth: BasicAuth, workspace: int) -> None:
+def _clean(args: frozenset[Sections], auth: BasicAuth, workspace: int) -> None:
     cache_loc = Path() / "cache"
 
     if "tracker" in args:
@@ -62,18 +73,14 @@ def _clean(args: set[str], auth: BasicAuth, workspace: int) -> None:
 
 
 def main() -> None:
-    """
-    1. Check Arguments on which to clean.
-    2. Verify Authentication.
-    3. Clean each object
-    """
+    """Entrypoint for cleaning data from a Toggl account."""
+    parser = _generate_parser()
+    args = _target_objects(parser)
 
     fmt = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
     logging.basicConfig(encoding="utf-8", level=logging.INFO, format=fmt)
     log.info("Starting to clean toggl-account!")
 
-    args = _target_objects()
-
     try:
         auth = generate_authentication()
     except AuthenticationError as err:
diff --git a/src/toggl_api/utility/_cleanup.py b/src/toggl_api/utility/_cleanup.py
@@ -20,7 +20,8 @@ def _path_cleanup(cache_path: Path) -> None:
             _path_cleanup(cache_path)
             continue
         file.unlink()
-    cache_path.rmdir()
+    if cache_path.exists():
+        cache_path.rmdir()
 
 
 def _tracker_cleanup(wid: int, config: BasicAuth, delay: int = 1) -> None:
diff --git a/src/toggl_api/utility/_generate_fake_data.py b/src/toggl_api/utility/_generate_fake_data.py
diff --git a/src/toggl_api/utility/_helpers.py b/src/toggl_api/utility/_helpers.py
diff --git a/tests/conftest.py b/tests/conftest.py
diff --git a/tests/test_asyncio/test_async_reports/test_async_detail.py b/tests/test_asyncio/test_async_reports/test_async_detail.py
diff --git a/tests/test_projects.py b/tests/test_projects.py
diff --git a/tests/test_reports/test_detail.py b/tests/test_reports/test_detail.py
diff --git a/tests/test_utility.py b/tests/test_utility.py
