From 00db1ffb70f8656f708df2580e2e96669ad58d64 Mon Sep 17 00:00:00 2001 From: Leonardo Kagohara Date: Tue, 21 May 2024 18:20:02 -0300 Subject: [PATCH] Add request methods docstring --- README.md | 20 +++++++------ starkbank/request/__request.py | 54 ++++++++++++++++++++++++++++++++-- 2 files changed, 62 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index b86691c0..0a4d7775 100644 --- 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 index 0f31a86b..d774d266 100644 --- a/starkbank/request/__request.py +++ b/starkbank/request/__request.py @@ -3,7 +3,7 @@ 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} @@ -11,7 +11,7 @@ def get(path, query=None, user=None): - 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,