Improve doc strings

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
 

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)

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

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)

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
 

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)

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)