Merge pull request #64 from cloudblue/LITE-26630-improve-documentation

LITE-26630: improve documentation

Author: ffaraone

connect/client/fluent.py

@@ -6,6 +6,7 @@
 import contextvars
 import threading
 from json.decoder import JSONDecodeError
+from typing import Union
 
 import httpx
 import requests
@@ -60,7 +61,7 @@ def __init__(
         self.resourceset_append = resourceset_append
 
     @property
-    def response(self):
+    def response(self) -> requests.Response:
         """
         Returns the raw
         [`requests`](https://requests.readthedocs.io/en/latest/api/#requests.Response)
@@ -69,7 +70,7 @@ def response(self):
         return self._response
 
     @response.setter
-    def response(self, value):
+    def response(self, value: requests.Response):
         self._response = value
 
     def __getattr__(self, name):
@@ -80,7 +81,7 @@ def __getattr__(self, name):
     def __call__(self, name):
         return self.ns(name)
 
-    def ns(self, name):
+    def ns(self, name: str) -> Union[NS, AsyncNS]:
         """
         Returns a `Namespace` object identified by its name.
 
@@ -107,7 +108,7 @@ def ns(self, name):
 
         return self._get_namespace_class()(self, name)
 
-    def collection(self, name):
+    def collection(self, name: str) -> Union[Collection, AsyncCollection]:
         """
         Returns a `Collection` object identified by its name.
 

connect/client/logger.py

@@ -3,10 +3,11 @@
 
 
 class RequestLogger:
+
     def __init__(self, file=sys.stdout):
         self._file = file
 
-    def obfuscate(self, key, value):
+    def obfuscate(self, key: str, value: str) -> str:
         if key in ('authorization', 'authentication'):
             if value.startswith('ApiKey '):
                 return value.split(':')[0] + '*' * 10
@@ -19,7 +20,7 @@ def obfuscate(self, key, value):
                 return f'{value[0:start_idx + 2]}******{value[end_idx - 2:]}'
         return value
 
-    def log_request(self, method, url, kwargs):
+    def log_request(self, method: str, url: str, kwargs):
         other_args = {k: v for k, v in kwargs.items() if k not in ('headers', 'json', 'params')}
 
         if 'params' in kwargs:

connect/client/mixins.py

@@ -4,6 +4,7 @@
 # Copyright (c) 2023 Ingram Micro. All Rights Reserved.
 #
 import time
+from typing import Any, Dict
 
 from httpx import HTTPError
 from requests.exceptions import RequestException, Timeout
@@ -13,7 +14,7 @@
 
 class SyncClientMixin:
 
-    def get(self, url, **kwargs):
+    def get(self, url: str, **kwargs) -> Any:
         """
         Make a GET call to the given url.
 
@@ -22,7 +23,7 @@ def get(self, url, **kwargs):
         """
         return self.execute('get', url, **kwargs)
 
-    def create(self, url, payload=None, **kwargs):
+    def create(self, url: str, payload: Dict = None, **kwargs) -> Any:
         """
         Make a POST call to the given url with the payload.
 
@@ -37,7 +38,7 @@ def create(self, url, payload=None, **kwargs):
 
         return self.execute('post', url, **kwargs)
 
-    def update(self, url, payload=None, **kwargs):
+    def update(self, url: str, payload: Dict = None, **kwargs) -> Any:
         """
         Make a PUT call to the given url with the payload.
 
@@ -52,7 +53,7 @@ def update(self, url, payload=None, **kwargs):
 
         return self.execute('put', url, **kwargs)
 
-    def delete(self, url, payload=None, **kwargs):
+    def delete(self, url: str, payload: Dict = None, **kwargs) -> Any:
         """
         Make a DELETE call to the given url with the payload.
 
@@ -67,7 +68,7 @@ def delete(self, url, payload=None, **kwargs):
 
         return self.execute('delete', url, **kwargs)
 
-    def execute(self, method, path, **kwargs):
+    def execute(self, method: str, path: str, **kwargs) -> Any:
         if (
             self._use_specs
             and self._validate_using_specs
@@ -127,7 +128,7 @@ def _execute_http_call(self, method, url, kwargs):  # noqa: CCR001
 
 class AsyncClientMixin:
 
-    async def get(self, url, **kwargs):
+    async def get(self, url: str, **kwargs) -> Any:
         """
         Make a GET call to the given url.
 
@@ -136,7 +137,7 @@ async def get(self, url, **kwargs):
         """
         return await self.execute('get', url, **kwargs)
 
-    async def create(self, url, payload=None, **kwargs):
+    async def create(self, url: str, payload: Dict = None, **kwargs) -> Any:
         """
         Make a POST call to the given url with the payload.
 
@@ -151,7 +152,7 @@ async def create(self, url, payload=None, **kwargs):
 
         return await self.execute('post', url, **kwargs)
 
-    async def update(self, url, payload=None, **kwargs):
+    async def update(self, url: str, payload: Dict = None, **kwargs) -> Any:
         """
         Make a PUT call to the given url with the payload.
 
@@ -166,7 +167,7 @@ async def update(self, url, payload=None, **kwargs):
 
         return await self.execute('put', url, **kwargs)
 
-    async def delete(self, url, payload=None, **kwargs):
+    async def delete(self, url: str, payload: Dict = None, **kwargs) -> Any:
         """
         Make a DELETE call to the given url with the payload.
 
@@ -181,7 +182,7 @@ async def delete(self, url, payload=None, **kwargs):
 
         return await self.execute('delete', url, **kwargs)
 
-    async def execute(self, method, path, **kwargs):
+    async def execute(self, method: str, path: str, **kwargs) -> Any:
         if (
             self._use_specs
             and self._validate_using_specs

connect/client/models/base.py

@@ -21,7 +21,7 @@ def __init__(self, client, path):
         self._path = path
 
     @property
-    def path(self):
+    def path(self) -> str:
         return self._path
 
     def __getattr__(self, name):
@@ -35,7 +35,7 @@ def __iter__(self):
     def __call__(self, name):
         return self.ns(name)
 
-    def collection(self, name):
+    def collection(self, name: str):
         """
         Returns a `[Async]Collection` object nested under this namespace object
         identified by its name.
@@ -55,6 +55,10 @@ def collection(self, name):
 
         Args:
             name (str): The name of the collection to access.
+
+        Returns:
+            (Union[Collection, AsyncCollection]):  Returns an object nested under this namespace
+                object identified by its name.
         """
 
         if not isinstance(name, str):
@@ -68,7 +72,7 @@ def collection(self, name):
             f'{self._path}/{name}',
         )
 
-    def ns(self, name):
+    def ns(self, name: str):
         """
         Returns a `[Async]Namespace` object nested under this namespace
         identified by its name.
@@ -88,6 +92,10 @@ def ns(self, name):
 
         Args:
             name (str): The name of the namespace to access.
+
+        Returns:
+            (Union[NS, AsyncNS]): Returns an object nested under this namespace
+                identified by its name.
         """
         if not isinstance(name, str):
             raise TypeError('`name` must be a string.')
@@ -149,6 +157,10 @@ def all(self):
         """
         Returns a `[Async]ResourceSet` object that that allow to access all the resources that
         belong to this collection.
+
+        Returns:
+            (Union[ResourceSet, AsyncResourceSet]): Returns an object that that allow to access
+                all the resources that belong to this collection.
         """
         return self._get_resourceset_class()(
             self._client,
@@ -188,6 +200,10 @@ def filter(self, *args, **kwargs):
         ```
 
         Also keyword arguments will be combined with logical **and**.
+
+        Returns:
+            (Union[ResourceSet, AsyncResourceSet]): The returned ResourceSet object will be
+                filtered based on the arguments and keyword arguments.
         """
         query = R()
         for arg in args:
@@ -208,7 +224,7 @@ def filter(self, *args, **kwargs):
             query=query,
         )
 
-    def resource(self, resource_id):
+    def resource(self, resource_id: str):
         """
         Returns a `[Async]Resource` object that represent a resource that belong to
         this collection identified by its unique identifier.
@@ -227,6 +243,10 @@ def resource(self, resource_id):
 
         Args:
             resource_id (str): The unique identifier of the resource.
+
+        Returns:
+            (Union[Resource, AsyncResource]): Returns an object that represent a resource that
+                belong to this collection identified by its unique identifier.
         """
         if not isinstance(resource_id, (str, int)):
             raise TypeError('`resource_id` must be a string or int.')
@@ -239,13 +259,17 @@ def resource(self, resource_id):
             f'{self._path}/{resource_id}',
         )
 
-    def action(self, name):
+    def action(self, name: str):
         """
         Returns an `[Async]Action` object that represent an action to perform
         on this collection identified by its name.
 
         Args:
             name (str): The name of the action to perform.
+
+        Returns:
+            (Union[Action, AsyncAction]): Returns an object that represent an action to perform
+                on this collection identified by its name.
         """
         if not isinstance(name, str):
             raise TypeError('`name` must be a string.')
@@ -311,7 +335,7 @@ def __getattr__(self, name):
     def __call__(self, name):
         return self.action(name)
 
-    def collection(self, name):
+    def collection(self, name: str):
         """
         Returns a `[Async]Collection` object nested under this resource object
         identified by its name.
@@ -335,6 +359,10 @@ def collection(self, name):
 
         Args:
             name (str): The name of the collection to access.
+
+        Returns:
+            (Union[Collection, AsyncCollection]): Returns an object nested under this resource
+                object identified by its name.
         """  # noqa: E501
         if not isinstance(name, str):
             raise TypeError('`name` must be a string.')
@@ -347,7 +375,7 @@ def collection(self, name):
             f'{self._path}/{name}',
         )
 
-    def action(self, name):
+    def action(self, name: str):
         """
         Returns an `[Async]Action` object that can be performed on this this resource object
         identified by its name.
@@ -370,6 +398,10 @@ def action(self, name):
 
         Args:
             name (str): The name of the action to perform.
+
+        Returns:
+            (Union[Action, AsyncAction]): Returns an object that can be performed on this this
+                resource object identified by its name.
         """
         if not isinstance(name, str):
             raise TypeError('`name` must be a string.')