From 070df18fb4a0ac3879356e75a4af29be3306d0fa Mon Sep 17 00:00:00 2001 From: Steven Shimizu Date: Mon, 13 Feb 2023 12:25:53 -0800 Subject: [PATCH] docs: :books: added docstrings to RestliClient response classes (#6) --- README.md | 6 +- linkedin_api/clients/common/response.py | 17 +++- linkedin_api/clients/restli/client.py | 15 +-- linkedin_api/clients/restli/response.py | 119 +++++++++++++++++++++--- 4 files changed, 135 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index b75e44d..f252acf 100644 --- a/README.md +++ b/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()* diff --git a/linkedin_api/clients/common/response.py b/linkedin_api/clients/common/response.py index 74ae2dc..1f3c71a 100644 --- a/linkedin_api/clients/common/response.py +++ b/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 \ No newline at end of file + """ + A case-insensitive dictionary of response headers + """ + + self.url = url + """ + The final URL location of the response + """ \ No newline at end of file diff --git a/linkedin_api/clients/restli/client.py b/linkedin_api/clients/restli/client.py index 826c54f..4181bab 100644 --- a/linkedin_api/clients/restli/client.py +++ b/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. diff --git a/linkedin_api/clients/restli/response.py b/linkedin_api/clients/restli/response.py index 99c3661..e92de82 100644 --- a/linkedin_api/clients/restli/response.py +++ b/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. + """