Add request methods docstring

starkbank · May 21, 2024 · 00db1ff · 00db1ff
1 parent 6f4543c
commit 00db1ff
Show file tree

Hide file tree

Showing 2 changed files with 62 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -2591,11 +2591,11 @@ print(workspace)
 
 ## request
 
-This resource allows you to send HTTP requests to StarkBank.
+This resource allows you to send HTTP requests to StarkBank routes.
 
 ## GET
 
-You can perform a GET request to any StarkBank.
+You can perform a GET request to any StarkBank route.
 
 It's possible to get a single resource using its id in the path.
 
@@ -2637,7 +2637,7 @@ for item in request["invoices"]:
     print(item)
 ```
 
-To list logs, you will use the same logic of the get single log.
+To list logs, you will use the same logic as for getting a single log.
 
 ```python
 import starkbank
@@ -2651,7 +2651,7 @@ for item in request["invoices"]:
     print(item)
 ```
 
-If you need to get a file related to the resource you will also use this method.
+You can get a resource file using this method.
 
 ```python
 import starkbank
@@ -2666,9 +2666,11 @@ with open("request.pdf", "wb") as file:
 
 ## POST
 
-You can perform a POST request to any StarkBank.
+You can perform a POST request to any StarkBank route.
 
-It's possible to create a list of items of the same resource.
+This will create an object for each item sent in your request
+
+**Note**: It's not possible to create multiple resources simultaneously. You need to send separate requests if you want to create multiple resources, such as invoices and boletos.
 
 ```python
 import starkbank
@@ -2696,7 +2698,7 @@ print(request)
 
 ## patch
 
-You can perform a PATCH request to any StarkBank.
+You can perform a PATCH request to any StarkBank route.
 
 It's possible to update a single item of a StarkBank resource.
 ```python
@@ -2712,7 +2714,7 @@ print(request)
 
 ## PUT
 
-You can perform a PUT request to any StarkBank.
+You can perform a PUT request to any StarkBank route.
 
 It's possible to put a single item of a StarkBank resource.
 ```python
@@ -2734,7 +2736,7 @@ print(request)
 ```
 ## DELETE
 
-You can perform a DELETE request to any StarkBank.
+You can perform a DELETE request to any StarkBank route.
 
 It's possible to delete a single item of a StarkBank resource.
 ```python

diff --git a/starkbank/request/__request.py b/starkbank/request/__request.py
@@ -3,15 +3,15 @@
 
 def get(path, query=None, user=None):
     """# Retrieve any StarkBank resource
-    Receive a json of resources previously created in the Stark Bank API
+    Receive a json of resources previously created in StarkBank's API
     ## Parameters (required):
     - path [string]: StarkBank resource's route. ex: "/invoice/"
     - query [dict, default None]: Query parameters. ex: {"limit": 1, "status": paid}
     ## Parameters (optional):
     - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user
         was set before function call
     ## Return:
-    - generator of Invoice objects with updated attributes
+    - dict of StarkBank objects with updated attributes
     """
     return rest.get_raw(
         path=path,
@@ -20,15 +20,39 @@ def get(path, query=None, user=None):
     )
 
 
-def post(path, body=None, user=None):
+def post(path, body=None, query=None, user=None):
+    """# Create any StarkBank resource
+    Send a list of jsons and create any StarkBank resource objects
+    ## Parameters (required):
+    - path [string]: StarkBank resource's route. ex: "/invoice/"
+    - body [dict]: request parameters. ex: {"invoices": [{"amount": 100, "name": "Iron Bank S.A.", "taxId": "20.018.183/0001-80"}]}
+    ## Parameters (optional):
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user
+        was set before function call
+    - query [dict, default None]: Query parameters. ex: {"limit": 1, "status": paid}
+    ## Return:
+    - list of resources jsons with updated attributes
+    """
     return rest.post_raw(
         path=path,
         payload=body,
+        query=query,
         user=user
     )
 
 
 def patch(path, body=None, user=None):
+    """# Update any StarkBank resource
+    Send a json with parameters of a single StarkBank resource object and update it
+    ## Parameters (required):
+    - path [string]: StarkBank resource's route. ex: "/invoice/5699165527090460"
+    - body [dict]: request parameters. ex: {"amount": 100}
+    ## Parameters (optional):
+    - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user
+        was set before function call
+    ## Return:
+    - json of the resource with updated attributes
+    """
     return rest.patch_raw(
         path=path,
         payload=body,
@@ -37,6 +61,18 @@ def patch(path, body=None, user=None):
 
 
 def put(path, body=None, user=None):
+    """# Put any StarkBank resource
+        Send a json with parameters of a single StarkBank resource object and create it, if the resource alredy exists,
+        you will update it.
+        ## Parameters (required):
+        - path [string]: StarkBank resource's route. ex: "/invoice"
+        - body [dict]: request parameters. ex: {"amount": 100}
+        ## Parameters (optional):
+        - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user
+            was set before function call
+        ## Return:
+        - json of the resource with updated attributes
+        """
     return rest.put_raw(
         path=path,
         payload=body,
@@ -45,6 +81,18 @@ def put(path, body=None, user=None):
 
 
 def delete(path, body=None, user=None):
+    """# Delete any StarkBank resource
+        Send a json with parameters of a single StarkBank resource object and delete it
+        you will update it.
+        ## Parameters (required):
+        - path [string]: StarkBank resource's route. ex: "/invoice/5699165527090460"
+        - body [dict]: request parameters. ex: {"amount": 100}
+        ## Parameters (optional):
+        - user [Organization/Project object, default None]: Organization or Project object. Not necessary if starkbank.user
+            was set before function call
+        ## Return:
+        - json of the resource with updated attributes
+        """
     return rest.delete_raw(
         path=path,
         payload=body,