From 0d8871548491ea99297752a0ff52fe1a306e0b4e Mon Sep 17 00:00:00 2001 From: Paul Hallett Date: Thu, 5 Oct 2023 11:37:01 +1300 Subject: [PATCH] Improve doc strings --- CHANGELOG.md | 1 + clientele/templates/async_methods.jinja2 | 10 +++++++--- clientele/templates/http_py.jinja2 | 8 +++++--- clientele/templates/sync_methods.jinja2 | 4 ++++ docs/CHANGELOG.md | 1 + tests/async_test_client/http.py | 20 +++++++++++++------- tests/test_client/http.py | 12 +++++++++--- 7 files changed, 40 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9169d2a..f09f198 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ * To regenerate a client (and to prevent accidental overrides) you must now pass `--regen t` or `-r t` to the `generate` command. This is automatically added to the line in `MANIFEST.md` to help. * Clientele will now automatically run [black](https://black.readthedocs.io/en/stable/) code formatter once a client is generated or regenerated. * Clientele will now generate absolute paths to refer to adjacent files in the generated client, instead of relative paths. This assumes you are running the `clientele` command in the root directory of your project. +* A lot of documentation and docs strings updates so that code in the generated client is easier to understand. ## 0.6.3 diff --git a/clientele/templates/async_methods.jinja2 b/clientele/templates/async_methods.jinja2 index 34ffcd4..3b9add5 100644 --- a/clientele/templates/async_methods.jinja2 +++ b/clientele/templates/async_methods.jinja2 @@ -1,13 +1,17 @@ async def get(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP GET request """ return await client.get(parse_url(url), headers=headers) async def post(url: str, data: dict, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP POST request """ return await client.post(parse_url(url), json=data, headers=headers) -async def delete(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: - return await client.delete(parse_url(url), headers=headers) - async def put(url: str, data: dict, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP PUT request """ return await client.put(parse_url(url), json=data, headers=headers) + +async def delete(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP DELETE request """ + return await client.delete(parse_url(url), headers=headers) diff --git a/clientele/templates/http_py.jinja2 b/clientele/templates/http_py.jinja2 index 36e5974..cb546a8 100644 --- a/clientele/templates/http_py.jinja2 +++ b/clientele/templates/http_py.jinja2 @@ -23,7 +23,8 @@ class APIException(Exception): def parse_url(url: str) -> str: """ Returns the full URL from a string. - Will omit any optional query parameters passed. + + Will filter out any optional query parameters if they are None. """ api_url = f"{c.api_base_url()}{url}" url_parts = urlparse(url=api_url) @@ -46,8 +47,9 @@ def parse_url(url: str) -> str: def handle_response(func, response): """ - Returns a response that matches the data neatly for a function - If it can't - raises an error with details of the response. + Returns a schema object that matches the JSON data from the response. + + If it can't find a matching schema it will raise an error with details of the response. """ status_code = response.status_code # Get the response types diff --git a/clientele/templates/sync_methods.jinja2 b/clientele/templates/sync_methods.jinja2 index 5dc4290..c0ba6a2 100644 --- a/clientele/templates/sync_methods.jinja2 +++ b/clientele/templates/sync_methods.jinja2 @@ -1,13 +1,17 @@ def get(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP GET request """ return client.get(parse_url(url), headers=headers) def post(url: str, data: dict, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP POST request """ return client.post(parse_url(url), json=data, headers=headers) def put(url: str, data: dict, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP PUT request """ return client.put(parse_url(url), json=data, headers=headers) def delete(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """ Issue an HTTP DELETE request """ return client.delete(parse_url(url), headers=headers) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 9169d2a..f09f198 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,7 @@ * To regenerate a client (and to prevent accidental overrides) you must now pass `--regen t` or `-r t` to the `generate` command. This is automatically added to the line in `MANIFEST.md` to help. * Clientele will now automatically run [black](https://black.readthedocs.io/en/stable/) code formatter once a client is generated or regenerated. * Clientele will now generate absolute paths to refer to adjacent files in the generated client, instead of relative paths. This assumes you are running the `clientele` command in the root directory of your project. +* A lot of documentation and docs strings updates so that code in the generated client is easier to understand. ## 0.6.3 diff --git a/tests/async_test_client/http.py b/tests/async_test_client/http.py index 996138e..6300512 100644 --- a/tests/async_test_client/http.py +++ b/tests/async_test_client/http.py @@ -22,7 +22,8 @@ def __init__(self, response: httpx.Response, reason: str, *args: object) -> None def parse_url(url: str) -> str: """ Returns the full URL from a string. - Will omit any optional query parameters passed. + + Will filter out any optional query parameters if they are None. """ api_url = f"{c.api_base_url()}{url}" url_parts = urlparse(url=api_url) @@ -45,8 +46,9 @@ def parse_url(url: str) -> str: def handle_response(func, response): """ - Returns a response that matches the data neatly for a function - If it can't - raises an error with details of the response. + Returns a schema object that matches the JSON data from the response. + + If it can't find a matching schema it will raise an error with details of the response. """ status_code = response.status_code # Get the response types @@ -122,20 +124,24 @@ def handle_response(func, response): async def get(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """Issue an HTTP GET request""" return await client.get(parse_url(url), headers=headers) async def post( url: str, data: dict, headers: typing.Optional[dict] = None ) -> httpx.Response: + """Issue an HTTP POST request""" return await client.post(parse_url(url), json=data, headers=headers) -async def delete(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: - return await client.delete(parse_url(url), headers=headers) - - async def put( url: str, data: dict, headers: typing.Optional[dict] = None ) -> httpx.Response: + """Issue an HTTP PUT request""" return await client.put(parse_url(url), json=data, headers=headers) + + +async def delete(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """Issue an HTTP DELETE request""" + return await client.delete(parse_url(url), headers=headers) diff --git a/tests/test_client/http.py b/tests/test_client/http.py index e1598cf..82f0fcb 100644 --- a/tests/test_client/http.py +++ b/tests/test_client/http.py @@ -22,7 +22,8 @@ def __init__(self, response: httpx.Response, reason: str, *args: object) -> None def parse_url(url: str) -> str: """ Returns the full URL from a string. - Will omit any optional query parameters passed. + + Will filter out any optional query parameters if they are None. """ api_url = f"{c.api_base_url()}{url}" url_parts = urlparse(url=api_url) @@ -45,8 +46,9 @@ def parse_url(url: str) -> str: def handle_response(func, response): """ - Returns a response that matches the data neatly for a function - If it can't - raises an error with details of the response. + Returns a schema object that matches the JSON data from the response. + + If it can't find a matching schema it will raise an error with details of the response. """ status_code = response.status_code # Get the response types @@ -122,16 +124,20 @@ def handle_response(func, response): def get(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """Issue an HTTP GET request""" return client.get(parse_url(url), headers=headers) def post(url: str, data: dict, headers: typing.Optional[dict] = None) -> httpx.Response: + """Issue an HTTP POST request""" return client.post(parse_url(url), json=data, headers=headers) def put(url: str, data: dict, headers: typing.Optional[dict] = None) -> httpx.Response: + """Issue an HTTP PUT request""" return client.put(parse_url(url), json=data, headers=headers) def delete(url: str, headers: typing.Optional[dict] = None) -> httpx.Response: + """Issue an HTTP DELETE request""" return client.delete(parse_url(url), headers=headers)