chore(release): version 1.5.1

chore(cliff): hide navigation in changelog

Author: ddkasa

cliff.toml

@@ -8,6 +8,11 @@
 [changelog]
 # template for the changelog header
 header = """
+---
+hide:
+  - navigation
+---
+
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """

docs/CHANGELOG.md

@@ -1,12 +1,23 @@
 ---
 hide:
-  - navigation
+- navigation
 ---
 
 # Changelog
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.1] - 2024-11-26
+
+### 🐛 Bug Fixes
+
+- *(models)* From_kwargs not incorporating organization id
+
+### 📚 Documentation
+
+- *(endpoints)* Correct and improve docstrings
+- *(cache, config)* Remove unnecessary type on return value in docstrings
+
 ## [1.5.0] - 2024-11-25
 
 ### 🚀 Features

docs/api-guide/organization.md

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

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "toggl-api-wrapper"
-version = "1.5.0"
+version = "1.5.1"
 description = "Simple Toggl API wrapper for non-premium features."
 authors = ["David Kasakaitis <[email protected]>"]
 license = "MIT"

toggl_api/client.py

@@ -63,6 +63,12 @@ class ClientEndpoint(TogglCachedEndpoint[TogglClient]):
 
     [Official Documentation](https://engineering.toggl.com/docs/api/clients)
 
+    Examples:
+        >>> wid = 123213324
+        >>> client_endpoint = ClientEndpoint(wid, BasicAuth(...), SqliteCache(...))
+        >>> client_endpoint.get(214125562)
+        TogglClient(214125562, "Simplicidentata", workspace=123213324)
+
     Params:
         workspace_id: The workspace the clients belong to.
         auth: Authentication for the client.
@@ -109,7 +115,7 @@ def add(self, body: ClientBody) -> TogglClient | None:
             NamingError: If no name was set as its required.
 
         Returns:
-            TogglClient: Newly created client with specified parameters.
+            Newly created client with specified parameters.
         """
 
         if body.name is None:
@@ -134,7 +140,7 @@ def get(self, client_id: int | TogglClient, *, refresh: bool = False) -> TogglCl
                 is not found in cache. Defaults to False.
 
         Returns:
-            TogglClient | None: If the client was found.
+            A TogglClient if the client was found else None.
         """
         if isinstance(client_id, TogglClient):
             client_id = client_id.id
@@ -167,7 +173,7 @@ def edit(self, client: TogglClient | int, body: ClientBody) -> TogglClient | Non
             body: New parameters to use. Ignore client status.
 
         Returns:
-            TogglClient | None: Newly edited client or None if not found.
+            Newly edited client or None if not found.
         """
         if body.status:
             log.warning("Client status not supported by edit endpoint")
@@ -188,6 +194,10 @@ def delete(self, client: TogglClient | int) -> None:
         This endpoint always hit the external API in order to keep clients consistent.
 
         [Official Documentation](https://engineering.toggl.com/docs/api/clients#delete-delete-client)
+
+        Raises:
+            HTTPStatusError: If anything thats not an *ok* or *404* status code
+                is returned.
         """
         client_id = client if isinstance(client, int) else client.id
         try:
@@ -228,12 +238,11 @@ def collect(
         [Official Documentation](https://engineering.toggl.com/docs/api/clients#get-list-clients)
 
         Args:
-            body: Status and name to target. Ignores notes. Ignores status if
-                using cache.
+            body: Status and name to target. Ignores notes. Ignores status if using cache.
             refresh: Whether to refresh cache.
 
         Returns:
-            list[TogglClient]: A list of clients. Empty if not found.
+            A list of clients. Empty if not found.
         """
         if not refresh:
             return self._collect_cache(body)

toggl_api/config.py

@@ -29,7 +29,7 @@ def generate_authentication() -> BasicAuth:
         AuthenticationError: If credentials are not set or invalid.
 
     Returns:
-        BasicAuth: BasicAuth object that is used with httpx client.
+        BasicAuth object that is used with Httpx client.
     """
     api_token = os.getenv("TOGGL_API_TOKEN")
     if api_token is None:
@@ -83,7 +83,7 @@ def use_togglrc(config_path: Optional[Path] = None) -> BasicAuth:
         AuthenticationError: If credentials are not set or invalid.
 
     Returns:
-        BasicAuth: BasicAuth object that is used with httpx client.
+        BasicAuth object that is used with httpx client.
     """
     try:
         config = _get_togglrc(config_path)
@@ -138,7 +138,7 @@ def retrieve_workspace_id(default: Optional[int] = None) -> int:
             variable or the workspace set is not an integer.
 
     Returns:
-        int: The id of the workspace.
+        The id of the workspace.
     """
 
     workspace = os.environ.get("TOGGL_WORKSPACE_ID", default)
@@ -165,7 +165,7 @@ def retrieve_togglrc_workspace_id(config_path: Optional[Path] = None) -> int:
         ValueError: If the workspace value is not an integer.
 
     Returns:
-        int: The id of the workspace.
+        The id of the workspace.
     """
 
     config = _get_togglrc(config_path)

toggl_api/meta/base_endpoint.py

@@ -117,8 +117,11 @@ class property if set to None.
             raw (bool): Whether to use the raw data. Defaults to False.
             retries (int): For recursive calls if the server fails multiple times.
 
+        Raises:
+            HTTPStatusError: If the request is not a success.
+
         Returns:
-            Any: Response data or None if request does not return any data.
+            Response data or None if request does not return any data.
         """
         if retries is None:
             retries = self.retries

toggl_api/meta/cache/json_cache.py

@@ -240,7 +240,7 @@ def delete_entries(self, update: list[T] | T, **kwargs: Any) -> None:
             self.delete_entry(entry)
         return None
 
-    def query(self, *query: TogglQuery, distinct: bool = False) -> list[TogglClass]:
+    def query(self, *query: TogglQuery, distinct: bool = False) -> list[T]:
         """Query method for filtering Toggl objects from cache.
 
         Filters cached Toggl objects by set of supplied queries.
@@ -254,7 +254,7 @@ def query(self, *query: TogglQuery, distinct: bool = False) -> list[TogglClass]:
                 with unhashable fields such as lists.
 
         Returns:
-            list[TogglClass]: A query object with parameters filtered.
+            A list of models with the query parameters that matched.
         """
 
         log.debug("Querying cache with %s parameters.", len(query), extra={"query": query})

toggl_api/meta/cache/sqlite_cache.py

@@ -132,9 +132,9 @@ def find_entry(self, query: T | dict[str, Any]) -> T | None:
         return search.filter_by(**query).first()
 
     def query(self, *query: TogglQuery, distinct: bool = False) -> Query[T]:
-        """Query method for filtering Toggl objects from cache.
+        """Query method for filtering models from cache.
 
-        Filters cached toggl objects by set of supplied queries.
+        Filters cached model by set of supplied queries.
 
         Supports queries with various comparisons with the [Comparison][toggl_api.Comparison]
         enumeration.
@@ -144,7 +144,7 @@ def query(self, *query: TogglQuery, distinct: bool = False) -> Query[T]:
             distinct: Whether to keep equivalent values around.
 
         Returns:
-            Query[TogglClass]: A SQLAlchemy query object with parameters filtered.
+            A SQLAlchemy query object with parameters filtered.
         """
 
         search = self.session.query(self.parent.model)

toggl_api/meta/cached_endpoint.py

@@ -108,9 +108,12 @@ def request(  # type: ignore[override]
             refresh: Whether to refresh the cache or not. Defaults to False.
             raw (bool): Whether to use the raw data. Defaults to False.
 
+        Raises:
+            HTTPStatusError: If the request is not a success.
+
         Returns:
-            TogglClass | Iterable[TogglClass] | None: Toggl API response data
-                processed into TogglClass objects.
+            Toggl API response data processed into TogglClass objects or not
+                depending on arguments.
         """
 
         data = self.load_cache() if self.model is not None else None
@@ -166,7 +169,7 @@ def query(self, *query: TogglQuery, distinct: bool = False) -> list[T]:
             distinct: A boolean that remove duplicate values if present.
 
         Returns:
-            Iterable: An iterable object depending on the cache used.
+            A list objects depending on the endpoint.
         """
         return list(self.cache.query(*query, distinct=distinct))