docs: 📚 added docstrings to RestliClient response classes (#6)

README.md

@@ -682,9 +682,9 @@ Base class: [BaseRestliResponse](#class-baserestliresponse)
 
 | Properties | Type | Description |
 |---|---|---|
-| `resultsMap` | Dict[str,Any] | A map of entities that were successfully retrieved, with the key being the encoded entity id, and the value being a dictionary representing the entity |
-| `statusesMap` | Dict[str,int] | A map of entities and status code, with the key being the encoded entity id, and the value being the status code number value. |
-| `errorsMap` | Dict[str,Any] | A map containing entities that could not be successfully fetched, with the key being the encoded entity id, and the value being the error response. |
+| `results` | Dict[str,Any] | A map of entities that were successfully retrieved, with the key being the encoded entity id, and the value being a dictionary representing the entity |
+| `statuses` | Dict[str,int] | A map of entities and status code, with the key being the encoded entity id, and the value being the status code number value. |
+| `errors` | Dict[str,Any] | A map containing entities that could not be successfully fetched, with the key being the encoded entity id, and the value being the error response. |
 
 #### *class CollectionResponse()*
 

linkedin_api/clients/common/response.py

@@ -4,6 +4,21 @@
 class BaseResponse:
   def __init__(self, status_code: int, headers: CaseInsensitiveDict[str], url: str, response: Response):
     self.status_code = status_code
+    """
+    Response status code (e.g. 200, 404, 500, etc.)
+    """
+
     self.response = response
+    """
+    The raw requests.Response object
+    """
+
     self.headers = headers
-    self.url = url
+    """
+    A case-insensitive dictionary of response headers
+    """
+
+    self.url = url
+    """
+    The final URL location of the response
+    """

linkedin_api/clients/restli/client.py

@@ -18,14 +18,15 @@
 
 T = TypeVar('T', bound=BaseRestliResponse)
 
-"""
-A client for making Rest.li API calls.
-
-Attributes:
-    session (requests.Session): The session instance used to send the API requests. Session attributes can
-    be modified, which will affect all requests.
-"""
 class RestliClient:
+    """
+    A client for making Rest.li API calls.
+
+    Attributes:
+        session (requests.Session): The session instance used to send the API requests. Session attributes can
+        be modified, which will affect all requests.
+    """
+
     def __init__(self):
         """
         The constructor for the RestliClient class.

linkedin_api/clients/restli/response.py

@@ -8,12 +8,24 @@
 class Paging:
   def __init__(self, start: Optional[int] = None, count: Optional[int] = None, total: Optional[int] = None):
     self.start = start
+    """
+    The start index of returned results (zero-based index).
+    """
+
     self.count = count
+    """
+    The number of results returned in the response.
+    """
+
     self.total = total
+    """
+    The total number of results available.
+    """
 
 class BaseRestliResponse(BaseResponse):
   pass
 
+
 class GetResponse(BaseRestliResponse):
   def __init__(
     self,
@@ -24,11 +36,10 @@ def __init__(
     entity: Union[Dict[str, Any], str, int, bool]
   ) -> None:
     super().__init__(status_code, headers, url, response)
-    self._entity = entity
-
-  @property
-  def entity(self):
-    return self._entity
+    self.entity = entity
+    """
+    The representation (typically a dictionary) of the retrieved entity, decoded from the json-encoded response content.
+    """
 
 
 class BatchGetResponse(BaseRestliResponse):
@@ -44,8 +55,19 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.results = results
+    """
+    A map of entities that were successfully retrieved, with the key being the encoded entity id, and the value being a dictionary representing the entity.
+    """
+
     self.statuses = statuses
+    """
+    A map of entities and status code, with the key being the encoded entity id, and the value being the status code number value.
+    """
+
     self.errors = errors
+    """
+    A map containing entities that could not be successfully fetched, with the key being the encoded entity id, and the value being the error response.
+    """
 
 class CollectionResponse(BaseRestliResponse):
   def __init__(
@@ -60,16 +82,46 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.elements = elements
+    """
+    The list of entities returned in the response.
+    """
+
     self.paging = paging
+    """
+    Paging metadata object
+    """
+
     self.metadata = metadata
+    """
+    Optional response metadata object
+    """
 
 class BatchFinderResult:
   def __init__(self, elements: List[RestliEntity], paging: Optional[Paging] = None, metadata = None, error = None, isError: bool = False):
     self.elements = elements
+    """
+    The list of entities found for the corresponding finder criteria.
+    """
+
     self.paging = paging
+    """
+    Optional paging metadata object
+    """
+
     self.metadata = metadata
+    """
+    Optional response metadata object
+    """
+
     self.error = error
+    """
+    Optional error details if finder call failed
+    """
+
     self.isError = isError
+    """
+    Flag if this finder call experienced an error
+    """
 
 class BatchFinderResponse(BaseRestliResponse):
   def __init__(
@@ -82,6 +134,9 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.results = results
+    """
+    The list of finder results, in the same order as the requested batch finder search criteria list.
+    """
 
 class CreateResponse(BaseRestliResponse):
   def __init__(
@@ -95,13 +150,31 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.entity_id = entity_id
+    """
+    The encoded entity id of the created entity
+    """
+
     self.entity = entity
+    """
+    Optional created entity. Some APIs support returning the created entity to eliminate the need for a subsequent GET call.
+    """
 
 class BatchCreateResult:
   def __init__(self, status: int, id: str, error: Any):
     self.status = status
+    """
+    The status code of the individual create call.
+    """
+
     self.id = id
+    """
+    The id of the created entity.
+    """
+
     self.error = error
+    """
+    Error details if the create call experienced an error.
+    """
 
 class BatchCreateResponse(BaseRestliResponse):
   def __init__(
@@ -114,6 +187,9 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.elements = elements
+    """
+    The list of batch create results, corresponding to the order of the `entities` request parameter
+    """
 
 class UpdateResponse(BaseRestliResponse):
   def __init__(
@@ -126,10 +202,18 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.entity = entity
+    """
+    Optional entity after the update. Some APIs support returning the updated entity to eliminate the need for a subsequent GET call.
+    """
+
 
-class BatchUpdateResult(TypedDict):
+class BatchUpdateResult():
   # TODO add support for return entity
-  status: int
+  def __init__(self, status: int):
+    self.status = status
+    """
+    The status code of the individual update call
+    """
 
 class BatchUpdateResponse(BaseRestliResponse):
   def __init__(
@@ -142,9 +226,16 @@ def __init__(
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.results = results
+    """
+    The results map where the keys are the encoded entity ids, and the values are the individual update call results, which includes the status code.
+    """
 
-class BatchDeleteResult(TypedDict):
-  status: int
+class BatchDeleteResult():
+  def __init__(self, status: int):
+    self.status = status
+    """
+    The status code of the delete call.
+    """
 
 class BatchDeleteResponse(BaseRestliResponse):
   def __init__(
@@ -153,10 +244,13 @@ def __init__(
     url: str,
     headers: CaseInsensitiveDict[str],
     response: Response,
-    results: Dict[EncodedEntityId, BatchDeleteResult]
+    results: Optional[Dict[EncodedEntityId, BatchDeleteResult]]
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.results = results
+    """
+    The results map where the keys are the encoded entity ids, and the values are the individual delete call results, which includes the status code.
+    """
 
 class ActionResponse(BaseRestliResponse):
   def __init__(
@@ -165,8 +259,11 @@ def __init__(
     url: str,
     headers: CaseInsensitiveDict[str],
     response: Response,
-    value: Any
+    value: Optional[Any]
   ):
     super().__init__(status_code=status_code, headers=headers, url=url, response=response)
     self.value = value
+    """
+    The action response value.
+    """