From 8b491e4c3a9cbe0804eaf0240addb5a26ee7ef9e Mon Sep 17 00:00:00 2001
From: Paul Hallett <paul.hallett@sharesies.co.nz>
Date: Tue, 24 Oct 2023 15:53:00 +1300
Subject: [PATCH] Deployed f4e9414 with MkDocs version: 1.5.3

---
 index.html               |   2 +-
 search/search_index.json |   2 +-
 sitemap.xml.gz           | Bin 278 -> 278 bytes
 3 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 1303388..fcb0c63 100644
--- a/index.html
+++ b/index.html
@@ -552,7 +552,7 @@ <h2 id="async-support">Async support</h2>
 <h2 id="other-features">Other features</h2>
 <ul>
 <li>Written entirely in Python.</li>
-<li>Designed to work with <a href="https://fastapi.tiangolo.com/">FastAPI</a>'s and <a href="https://github.com/tfranzel/drf-spectacular">Ddrf-spectacular</a>'s OpenAPI schema generator.</li>
+<li>Designed to work with <a href="https://fastapi.tiangolo.com/">FastAPI</a>'s and <a href="https://github.com/tfranzel/drf-spectacular">drf-spectacular</a>'s OpenAPI schema generator.</li>
 <li>The generated client only depends on <a href="https://www.python-httpx.org/">httpx</a> and <a href="https://docs.pydantic.dev/latest/">Pydantic 2.4</a>.</li>
 <li>HTTP Basic and HTTP Bearer authentication support.</li>
 <li>Support your own configuration - we provide an entry point that will never be overwritten.</li>
diff --git a/search/search_index.json b/search/search_index.json
index 88ca2d0..bcbc475 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\u269c\ufe0f Clientele","text":""},{"location":"#generate-loveable-python-http-api-clients","title":"Generate loveable Python HTTP API Clients","text":"<p>Clientele lets you generate fully-typed, pythonic HTTP API Clients using an OpenAPI schema.</p> <p>It's easy to use:</p> <pre><code># Install as a global tool - it's not a dependency!\npipx install clientele\n# Generate a client\nclientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o api_client/\n</code></pre>"},{"location":"#generated-code","title":"Generated code","text":"<p>The generated code is designed by python developers, for python developers.</p> <p>It uses modern tooling and has a great developer experience.</p> <pre><code>from my_api import client, schemas\n\n# Pydantic models for inputs and outputs\ndata = schemas.RequestDataRequest(my_input=\"test\")\n\n# Easy to read client functions\nresponse = client.request_data_request_data_post(data=data)\n\n# Handle responses elegantly\nmatch response:\n    case schemas.RequestDataResponse():\n        # Handle valid response\n        ...\n    case schemas.ValidationError():\n        # Handle validation error\n        ...\n</code></pre> <p>The generated code is tiny - the example schema we use for documentation and testing only requires 250 lines of code and 5 files.</p>"},{"location":"#async-support","title":"Async support","text":"<p>You can choose to generate either a sync or an async client - we support both:</p> <pre><code>from my_async_api import client\n\n# Async client functions\nresponse = await client.simple_request_simple_request_get()\n</code></pre>"},{"location":"#other-features","title":"Other features","text":"<ul> <li>Written entirely in Python.</li> <li>Designed to work with FastAPI's and Ddrf-spectacular's OpenAPI schema generator.</li> <li>The generated client only depends on httpx and Pydantic 2.4.</li> <li>HTTP Basic and HTTP Bearer authentication support.</li> <li>Support your own configuration - we provide an entry point that will never be overwritten.</li> <li>Designed for easy testing with respx.</li> <li>API updated? Just run the same command again and check the git diff.</li> <li>Automatically formats the generated client with black.</li> </ul>"},{"location":"CHANGELOG/","title":"Change log","text":""},{"location":"CHANGELOG/#070","title":"0.7.0","text":"<ul> <li>Updated all files to use the templates engine.</li> <li>Generator files have been reorganised in clientele to support future templates.</li> <li><code>constants.py</code> has been renamed to <code>config.py</code> to better reflect how it is used. It is not generated from a template like the other files.</li> <li>If you are using Python 3.10 or later, the <code>typing.Unions</code> types will generate as the short hand <code>|</code> instead.</li> <li>To regenerate a client (and to prevent accidental overrides) you must now pass <code>--regen t</code> or <code>-r t</code> to the <code>generate</code> command. This is automatically added to the line in <code>MANIFEST.md</code> to  help.</li> <li>Clientele will now automatically run black code formatter once a client is generated or regenerated.</li> <li>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 <code>clientele</code> command in the root directory of your project.</li> <li>A lot of documentation and docs strings updates so that code in the generated client is easier to understand.</li> <li>Improved the utility for snake-casing enum keys. Tests added for the functions.</li> <li>Python 3.12 support.</li> <li>Add a \"basic\" client using the command <code>generate-basic</code>. This can be used to keep a consistent file structure for an API that does not use OpenAPI.</li> </ul>"},{"location":"CHANGELOG/#063","title":"0.6.3","text":"<ul> <li>Packaged application installs in the correct location. Resolving #6</li> <li>Updated pyproject.toml to include a better selection of links.</li> </ul>"},{"location":"CHANGELOG/#062","title":"0.6.2","text":"<ul> <li>Ignore optional URL query parameters if they are <code>None</code>.</li> </ul>"},{"location":"CHANGELOG/#061","title":"0.6.1","text":"<ul> <li>Added <code>from __future__ import annotations</code> in files to help with typing evaluation.</li> <li>Update to use pydantic 2.4.</li> <li>A bunch of documentation and readme updates.</li> <li>Small wording and grammar fixes.</li> </ul>"},{"location":"CHANGELOG/#060","title":"0.6.0","text":"<ul> <li>Significantly improved handling for response schemas. Responses from API endpoints now look at the HTTP status code to pick the correct response schema to generate from the HTTP json data. When regenerating, you will notice a bit more logic generated in the <code>http.py</code> file to handle this.</li> <li>Significantly improved coverage of exceptions raised when trying to generate response schemas.</li> <li>Response types for a class are now sorted.</li> <li>Fixed a bug where <code>put</code> methods did not generate input data correctly.</li> </ul>"},{"location":"CHANGELOG/#052","title":"0.5.2","text":"<ul> <li>Fix pathing for <code>constants.py</code> - thanks to @matthewknight for the contribution!</li> <li>Added <code>CONTRIBUTORS.md</code></li> </ul>"},{"location":"CHANGELOG/#051","title":"0.5.1","text":"<ul> <li>Support for HTTP PUT methods</li> <li>Headers objects use <code>exclude_unset</code> to avoid passing <code>None</code> values as headers, which httpx does not support.</li> </ul> <p>Additionally, an async test client is now included in the test suite. It has identical tests to the standard one but uses the async client instead.</p>"},{"location":"CHANGELOG/#050","title":"0.5.0","text":""},{"location":"CHANGELOG/#please-delete-the-constantspy-file-when-updating-to-this-version-to-have-new-features-take-affect","title":"Please delete the constants.py file when updating to this version to have new features take affect","text":"<ul> <li>Paths are resolved correctly when generating clients in nested directories.</li> <li><code>additional_headers()</code> is now applied to every client, allowing you to set up headers for all requests made by your client.</li> <li>When the client cannot match an HTTP response to a return type for the function it will now raise an <code>http.APIException</code>. This object will have the <code>response</code> attached to it for inspection by the developer.</li> <li><code>MANIFEST</code> is now renamed to <code>MANIFEST.md</code> and will include install information for Clientele, as well as information on the command used to generate the client.</li> </ul>"},{"location":"CHANGELOG/#044","title":"0.4.4","text":"<p>Examples and documentation now includes a very complex example schema built using FastAPI that offers the following variations:</p> <ul> <li>Simple request / response (no input just an output)</li> <li>A request with a URL/Path parameter.</li> <li>Models with <code>int</code>, <code>str</code>, <code>list</code>, <code>dict</code>, references to other models, enums, and <code>list</code>s of other models and enums.</li> <li>A request with query parameters.</li> <li>A response model that has optional parameters.</li> <li>An HTTP POST request that takes an input model.</li> <li>An HTTP POST request that takes path parameters and also an input model.</li> <li>An HTTP GET request that requires an HTTP header, and returns it.</li> <li>An HTTP GET endpoint that returns the HTTP bearer authorization token (also makes clientele generate the http authentication for this schema).</li> </ul> <p>A huge test suite has been added to the CI pipeline for this project using a copy of the generated client from the schema above.</p>"},{"location":"CHANGELOG/#043","title":"0.4.3","text":"<ul> <li><code>Enums</code> now inherit from <code>str</code> as well so that they serialize to JSON properly. See this little nugget.</li> </ul>"},{"location":"CHANGELOG/#042","title":"0.4.2","text":"<ul> <li>Correctly use <code>model_rebuild</code> for complex schemas where there are nested schemas, his may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema.</li> <li>Do not raise for status, instead attempt to return the response if it cannot match a response type.</li> </ul>"},{"location":"CHANGELOG/#041","title":"0.4.1","text":"<ul> <li>Correctly generate lists of nested schema classes</li> <li>Correctly build response schemas that are emphemeral (such as when they just return an array of other schemas, or when they have no $ref).</li> </ul>"},{"location":"CHANGELOG/#040","title":"0.4.0","text":"<ul> <li>Change install suggestion to use pipx as it works best as a global CLI tool.</li> <li>Improved support for OpenAPI 3.0.3 schemas (a test version is available in the example_openapi_specs directory).</li> <li><code>validate</code> command for validating an OpenAPI schema will work with clientele.</li> <li><code>version</code> command for showing the current version of clientele.</li> <li>Supports HTTP DELETE methods.</li> <li>Big refactor of how methods are generated to reduce duplicate code.</li> <li>Support optional header parameters in all request functions (where they are required).</li> <li>Very simple Oauth2 support - if it is discovered will set up HTTP Bearer auth for you.</li> <li>Uses <code>dict</code> and <code>list</code> instead of <code>typing.Dict</code> and <code>typing.List</code> respectively.</li> <li>Improved schema generation when schemas have $ref to other models.</li> </ul>"},{"location":"CHANGELOG/#032","title":"0.3.2","text":"<ul> <li>Minor changes to function name generation to make it more consistent.</li> <li>Optional parameters in schemas are working properly.</li> </ul>"},{"location":"CHANGELOG/#031","title":"0.3.1","text":"<ul> <li>Fixes a bug when generating HTTP Authentication schema.</li> <li>Fixes a bug when generating input classes for post functions, when the input schema doesn't exist yet.</li> <li>Generates pythonic function names in clients now, always (like <code>lower_case_snake_case</code>).</li> </ul>"},{"location":"CHANGELOG/#030","title":"0.3.0","text":"<ul> <li>Now generates a <code>MANIFEST</code> file with information about the build versions</li> <li>Added a <code>constants.py</code> file to the output if one does not exist yet, which can be used to store values that you do not want to change between subsequent re-generations of the clientele client, such as the API base url.</li> <li>Authentication patterns now use <code>constants.py</code> for constants values.</li> <li>Removed <code>ipython</code> from package dependencies and moved to dev dependencies.</li> <li>Documentation! https://phalt.github.io/clientele/</li> </ul>"},{"location":"CHANGELOG/#020","title":"0.2.0","text":"<ul> <li>Improved CLI output</li> <li>Code organisation is now sensible and not just one giant file</li> <li>Now supports an openapi spec generated from a dotnet project (<code>Microsoft.OpenApi.Models</code>)</li> <li>async client support  fully working</li> <li>HTTP Bearer support</li> <li>HTTP Basic support</li> </ul>"},{"location":"CHANGELOG/#010","title":"0.1.0","text":"<ul> <li>Initial version</li> <li>Mostly works with a simple FastAPI generated spec (3.0.2)</li> <li>Works with Twilio's spec (see example_openapi_specs/ directory) (3.0.1)</li> <li>Almost works with stripes</li> </ul>"},{"location":"compatibility/","title":"\ud83d\udcb1 Compatibility","text":""},{"location":"compatibility/#great-compatibility","title":"Great compatibility","text":"<p>Any standard <code>3.0.x</code> implementation works very well.</p> <p>We have tested Clientele with:</p> <ul> <li>FastAPI - our target audience, so 100% compatibility guaranteed.</li> <li>drf-spectacular works great as well, you can see which schemas we tested in this GitHub issue.</li> <li>Microsoft's OpenAPI spec has also been battle tested and works well.</li> </ul>"},{"location":"compatibility/#no-compatibility","title":"No compatibility","text":"<p>We do not support <code>2.x</code> aka \"Swagger\" - this format is quite different and deprecated.</p>"},{"location":"compatibility/#a-note-on-compatbility","title":"A note on compatbility","text":"<p>When we were building Clientele, we discovered that, despite a fantastic specification, OpenAPI has a lot of poor implementations.</p> <p>As pythonistas, we started with the auto-generated OpenAPI schemas provided by FastAPI, and then we branched out to large APIs like Twilio to test what we built.</p> <p>Despite the effort, we still keep finding subtly different OpenAPI implementations.</p> <p>Because of this we cannot guarentee 100% compatibility with an API, but we can give you a good indication of what we've tested.</p>"},{"location":"design/","title":"\ud83c\udfa8 Design","text":""},{"location":"design/#openapi-code-generators","title":"OpenAPI code generators","text":"<p>Every few years we check the HTTP API landscape to see what has changed, and what new tooling is available. A part of this research is seeing how far OpenAPI client generators have come.  </p> <p>In the early years of OpenAPI, the \"last mile\" (i.e. - generating, and using, a client library) had a pretty poor experience:</p> <ul> <li> <p>The generated code was difficult to read, leading to problems when debugging the code. It was often not idiomatic to the language.</p> </li> <li> <p>It was often bloated and repetitive, making changes tedious to support your specific project.</p> </li> <li> <p>Also, you had to install a lot of things like Java to generate the code.</p> </li> <li> <p>And finally, some API services still weren't publishing an OpenAPI schema. Or, the schema they published was different from the standard, so would not work with code generators.</p> </li> </ul> <p>This experience wasn't ideal, and was often such an impedance that it put us off using them. We would prefer instead to take a template of our own choosing, refined from years of working with HTTP APIs, and adapt it to whatever new API we were consuming.</p>"},{"location":"design/#the-landscape-in-2023","title":"The landscape in 2023","text":"<p>In the early part of 2023, we had to build an integration with a new HTTP API. So, like we did in the past, we used it as an opportunity to asses the landscape of OpenAPI client generators.</p> <p>And this was our summary at the time of writing:</p> <ul> <li> <p>API tools and providers had adopted OpenAPI very well. For example - tools like FastAPI and drf-spectacular now make it easy for the most popular python web frameworks to publish OpenAPI schemas.</p> </li> <li> <p>There are a lot of options for generating clients. They all meet the need of \"generating a python client using the schema\". But, almost universally, they have a poor developer experience.</p> </li> </ul> <p>After evaluating many python client generators, we opted to use none of them and hand craft the API client ourselves. We used the OpenAPI schema as a source to develop the input and output objects.  Then we wrote a small functional abstraction over the paths.</p> <p>Looking back over our organised, pythonic, minimal client integration, we had an idea:</p> <p>If this is the type of client we would like a generator to produce; how hard could it be to work backwards and build one?</p> <p>This was the start of Clientele.</p>"},{"location":"design/#clientele","title":"Clientele","text":"<p>As python developers ourselves, we know what makes good, readable, idiomatic python.</p> <p>We also feel like we have a grasp on the best tools to be using in our python projects.</p> <p>By starting with a client library that we like to use, and working backwards, we were able to build a client generator that produced something that python developers actually wanted.</p> <p>But what is it exactly that we aimed to do with Clientele, why is this the OpenAPI Python client that you should use?</p>"},{"location":"design/#strongly-typed-inputs-and-outputs","title":"Strongly-typed inputs and outputs","text":"<p>OpenAPI prides itself on being able to describe the input and output objects in it's schema.</p> <p>This means you can build strongly-typed interfaces to the API. This helps to solve some common niggles when using an API - such as casting a value to a string when it should be an integer.</p> <p>With Clientele, we opted to use Pydantic to build the models from the OpenAPI schema.</p> <p>Pydantic doesn't only describe the shape of an object, it also validates the attributes as well. If an API sends back the wrong attributes at run time, Pydantic will error and provide a detail description about what went wrong.</p>"},{"location":"design/#idiomatic-python","title":"Idiomatic Python","text":"<p>A lot of the client generators we tested produced a lot of poor code.</p> <p>It was clear in a few cases that the client generator was built without understanding or knowledge of good python conventions.</p> <p>In more than one case we also discovered the client generator would work by reading a file at run time. This is a very cool piece of engineering, but it is impractical to use. When you develop with these clients, the available functions and objects don't exist and you can't use an IDE's auto-complete feature.</p> <p>Clientele set out to be as pythonic as possible. We use modern tools,  idiomatic conventions, and provide some helpful bonuses like Black auto-formatting.</p>"},{"location":"design/#easy-to-understand","title":"Easy to understand","text":"<p>Eventually a developer will need to do some debugging, and sometimes they'll need to do it in the generated client code.</p> <p>A lot of the other client generators make obscure or obtuse code that is hard to pick apart and debug.</p> <p>Now, there is a suggestion that developers shouldn't have to look at this, and that is fair. But the reality doesn't match that expectation. Personally; we like to know what generated code is doing. We want to trust that it will work, and that we can adapt around it if needs be. An interesting quirk of any code generator is you can't always inspect the source when evaluating to use it. Any other tool - you'd just go to GitHub and have a read around, but you can't with code generators.</p> <p>So the code that is generated needs to be easy to understand.</p> <p>Clientele doesn't do any tricks, or magic, or anything complex. The generated code has documentation and is designed to be readable. It is only a small layer on top of already well established tools, such as HTTPX.</p> <p>In fact, we have some generated clients in our project repository so you can see what it looks like. We even have example tests for you to learn how to integrate with it.</p> <p>It is that way because we know you will need to inspect it in the future. We want you to know that this is a sane and sensible tool.</p>"},{"location":"examples/","title":"\ud83e\ude84 Client example","text":"<p>Let's build an API Client using clientele.</p> <p>Our GitHub has a bunch of schemas that are proven to work with clientele, so let's use one of those!</p>"},{"location":"examples/#generate-the-client","title":"Generate the client","text":"<p>In your project's root directory:</p> <pre><code>clientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o my_client/\n</code></pre> <p>Note</p> <p>The example above uses one of our test schemas, and will work if you copy/paste it!</p> <p>The <code>-u</code> parameter expects a URL, you can provide a path to a file with <code>-f</code> instead if you download the file.</p> <p>The <code>-o</code> parameter is the output directory of the generated client.</p> <p>Run it now and you will see this output:</p> <pre><code>my_client/\n    __init__.py\n    client.py\n    config.py\n    http.py\n    MANIFEST\n    schemas.py\n</code></pre> <p>Let's go over each file and talk about what it does.</p>"},{"location":"examples/#client","title":"Client","text":""},{"location":"examples/#get-functions","title":"GET functions","text":"<p>The <code>client.py</code> file provides all the API functions from the OpenAPI schema. Functions are a combination of the path and the HTTP method for those paths. So, a path with two HTTP methods will be turned into two python functions.</p> my_client/client.py<pre><code>from my_client import http, schemas\n\n\ndef simple_request_simple_request_get() -&gt; schemas.SimpleResponse:\n    \"\"\"Simple Request\"\"\"\n\n    response = http.get(url=\"/simple-request\")\n    return http.handle_response(simple_request_simple_request_get, response)\n\n...\n</code></pre> <p>We can see one of the functions here, <code>simple_request_simple_request_get</code>, is for a straight-forward HTTP GET request without any input arguments, and it returns a schema object.</p> <p>Here is how you might use it:</p> <pre><code>from my_client import client\n\nclient.simple_request_simple_request_get()\n&gt;&gt;&gt; SimpleResponse(name='Hello, clientele')\n</code></pre>"},{"location":"examples/#post-and-put-functions","title":"POST and PUT functions","text":"<p>A more complex example is shown just below. </p> <p>This is for an HTTP POST method, and it requires an input property called <code>data</code> that is an instance of a schema, and returns one of many potential responses. If the endpoint has url parameters or query parameters, they will appear as input arguments to the function alongside the <code>data</code> argument.</p> <pre><code>def request_data_request_data_post(\n    data: schemas.RequestDataRequest\n) -&gt; schemas.RequestDataResponse | schemas.HTTPValidationError:\n    \"\"\"Request Data\"\"\"\n\n    response = http.post(url=\"/request-data\", data=data.model_dump())\n    return http.handle_response(request_data_request_data_post, response)\n</code></pre> <p>Here is how you might use it:</p> <pre><code>from my_client import client, schemas\n\ndata = schemas.RequestDataRequest(my_input=\"Hello, world\")\nresponse = client.request_data_request_data_post(data=data)\n&gt;&gt;&gt; RequestDataResponse(your_input='Hello, world')\n</code></pre> <p>Clientele also supports the major HTTP methods PUT and DELETE in the same way.</p>"},{"location":"examples/#url-and-query-parameters","title":"URL and Query parameters","text":"<p>If your endpoint takes path parameters (aka URL parameters) then clientele will turn them into parameters in the function:</p> <pre><code>from my_client import client\n\nclient.parameter_request_simple_request(your_input=\"gibberish\")\n&gt;&gt;&gt; ParameterResponse(your_input='gibberish')\n</code></pre> <p>Query parameters will also be generated the same way. See this example for a function that takes a required query parameter.</p> <p>Note that, optional parameters that are not passed will be omitted when the URL is generated by Clientele.</p>"},{"location":"examples/#handling-responses","title":"Handling responses","text":"<p>Because we're using Pydantic to manage the input data, we get a strongly-typed response object. This works beautifully with the new structural pattern matching feature in Python 3.10 and up:</p> <pre><code>response = client.request_data_request_data_post(data=data)\n\n# Handle responses elegantly\nmatch response:\n    case schemas.RequestDataResponse():\n        # Handle valid response\n        ...\n    case schemas.ValidationError():\n        # Handle validation error\n        ...\n</code></pre>"},{"location":"examples/#api-exceptions","title":"API Exceptions","text":"<p>Clientele keeps a mapping of the paths and their potential response codes. When it gets a response code that fits into the map, it generates the pydantic object associated to it.</p> <p>If the HTTP response code is an unintended one, it will not match a return type. In this case, the function will raise an <code>http.APIException</code>.</p> <pre><code>from my_client import client, http\ntry:\n    good_response = my_client.get_my_thing()\nexcept http.APIException as e:\n    # The API got a response code we didn't expect\n    print(e.response.status_code)\n</code></pre> <p>The <code>response</code> object will be attached to this exception class for your own debugging.</p>"},{"location":"examples/#schemas","title":"Schemas","text":"<p>The <code>schemas.py</code> file has all the possible schemas, request and response, and even Enums, for the API. These are taken from OpenAPI's  schemas objects and turned into Python classes. They are all subclassed from pydantic's <code>BaseModel</code>. </p> <p>Here are a few examples:</p> my_client/schemas.py<pre><code>import pydantic\nfrom enum import Enum\n\n\nclass ParameterResponse(pydantic.BaseModel):\n    your_input: str\n\nclass RequestDataRequest(pydantic.BaseModel):\n    my_input: str\n\nclass RequestDataResponse(pydantic.BaseModel):\n    my_input: str\n\n# Enums subclass str so they serialize to JSON nicely\nclass ExampleEnum(str, Enum):\n    ONE = \"ONE\"\n    TWO = \"TWO\"\n</code></pre>"},{"location":"examples/#configuration","title":"Configuration","text":"<p>One of the problems with auto-generated clients is that you often need to configure them, and if you try and regenerate the client at some point in the future then your configuration gets wiped clean and you have to do it all over again.</p> <p>Clientele solves this problem by providing an entry point for configuration that will never be overwritten - <code>config.py</code>.</p> <p>When you first generate the project, you will see a file called <code>config.py</code> and it will offer configuration functions a bit like this:</p> <pre><code>\"\"\"\nThis file will never be updated on subsequent clientele runs.\nUse it as a space to store configuration and constants.\n\nDO NOT CHANGE THE FUNCTION NAMES\n\"\"\"\n\n\ndef api_base_url() -&gt; str:\n    \"\"\"\n    Modify this function to provide the current api_base_url.\n    \"\"\"\n    return \"http://localhost\"\n</code></pre> <p>Subsequent runs of the <code>generate</code> command with <code>--regen t</code> will not change this file if it exists, so you are free to modify the defaults to suit your needs. </p> <p>For example, if you need to source the base url of your API for different configurations, you can modify the <code>api_base_url</code> function like this:</p> <pre><code>from my_project import my_config\n\ndef api_base_url() -&gt; str:\n    \"\"\"\n    Modify this function to provide the current api_base_url.\n    \"\"\"\n    if my_config.debug:\n        return \"http://localhost:8000\"\n    elif my_config.production:\n        return \"http://my-production-url.com\"\n</code></pre> <p>Just keep the function names the same and you're good to go.</p>"},{"location":"examples/#authentication","title":"Authentication","text":"<p>If your OpenAPI spec provides security information for the following authentication methods:</p> <ul> <li>HTTP Bearer</li> <li>HTTP Basic</li> </ul> <p>Then clientele will provide you information on the environment variables you need to set to make this work during the generation. For example:</p> <pre><code>Please see my_client/config.py to set authentication variables\n</code></pre> <p>The <code>config.py</code> file will have entry points for you to configure, for example, HTTP Bearer authentication will need the <code>get_bearer_token</code> function to be updated, something like this:</p> <pre><code>def get_bearer_token() -&gt; str:\n    \"\"\"\n    HTTP Bearer authentication.\n    Used by many authentication methods - token, jwt, etc.\n    Does not require the \"Bearer\" content, just the key as a string.\n    \"\"\"\n    from os import environ\n    return environ.get(\"MY_AUTHENTICATION_TOKEN\")\n</code></pre>"},{"location":"examples/#additional-headers","title":"Additional headers","text":"<p>If you want to pass specific headers with all requests made by the client, you can configure the <code>additional_headers</code> function in <code>config.py</code> to do this.</p> <pre><code>def additional_headers() -&gt; dict:\n    \"\"\"\n    Modify this function ot provide additional headers to all\n    HTTP requests made by this client.\n    \"\"\"\n    return {}\n</code></pre> <p>Please note that if you are using this with authentication headers, then authentication headers will overwrite these defaults if they keys match.</p>"},{"location":"install/","title":"\ud83c\udfd7\ufe0f Install","text":"<p>We recommend installing with pipx as a global CLI command:</p> <pre><code>pipx install clientele\n</code></pre> <p>Once installed you can run <code>clientele version</code> to make sure you have the latest version:</p> <pre><code>&gt; clientele version\nclientele 0.7.0\n</code></pre>"},{"location":"testing/","title":"Testing","text":"<p>Clientele is designed for easy testing, and our own test suite is a great example of how easily you can write mock tests for your API Client.</p> <pre><code>import pytest\nfrom httpx import Response\nfrom respx import MockRouter\n\nfrom .test_client import client, constants, schemas\n\nBASE_URL = constants.api_base_url()\n\n\n@pytest.mark.respx(base_url=BASE_URL)\ndef test_simple_request_simple_request_get(respx_mock: MockRouter):\n    # Given\n    mocked_response = {\"status\": \"hello world\"}\n    mock_path = \"/simple-request\"\n    respx_mock.get(mock_path).mock(\n        return_value=Response(json=mocked_response, status_code=200)\n    )\n    # When\n    response = client.simple_request_simple_request_get()\n    # Then\n    assert isinstance(response, schemas.SimpleResponse)\n    assert len(respx_mock.calls) == 1\n    call = respx_mock.calls[0]\n    assert call.request.url == BASE_URL + mock_path\n</code></pre> <p>We recommend you install respx for writing your tests.</p>"},{"location":"usage/","title":"\ud83d\udcdd Use Clientele","text":"<p>Note</p> <p>You can type <code>clientele COMMAND --help</code> at anytime to see explicit information about the available arguments.</p>"},{"location":"usage/#generate","title":"<code>generate</code>","text":"<p>Generate a Python HTTP Client from an OpenAPI Schema.</p>"},{"location":"usage/#from-a-url","title":"From a URL","text":"<p>Use the <code>-u</code> or <code>--url</code> argument.</p> <p><code>-o</code> or <code>--output</code> is the target directory for the generate client.</p> <pre><code>clientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o my_client/\n</code></pre> <p>Note</p> <p>The example above uses one of our test schemas, and will work if you copy/paste it!</p>"},{"location":"usage/#from-a-file","title":"From a file","text":"<p>Alternatively you can provide a local file using the <code>-f</code> or <code>--file</code> argument.</p> <pre><code>clientele generate -f path/to/file.json -o my_client/\n</code></pre>"},{"location":"usage/#asyncio","title":"Async.io","text":"<p>If you prefer an asyncio client, just pass <code>--asyncio t</code> to your command.</p> <pre><code>clientele generate -f path/to/file.json -o my_client/ --asyncio t\n</code></pre>"},{"location":"usage/#regenerating","title":"Regenerating","text":"<p>At times you may wish to regenerate the client. This could be because the API has updated or you just want to use a newer version of clientele.</p> <p>To force a regeneration you must pass the <code>--regen</code> or <code>-r</code> argument, for example:</p> <pre><code>clientele generate -f example_openapi_specs/best.json -o my_client/  --regen t\n</code></pre> <p>Note</p> <p>You can copy and paste the command from the <code>MANIFEST.md</code> file in your previously-generated client for a quick and easy regeneration.</p>"},{"location":"usage/#validate","title":"<code>validate</code>","text":"<p>Validate lets you check if an OpenAPI schema will work with clientele.</p> <p>Note</p> <p>Some OpenAPI schema generators do not conform to the specification.</p> <p>Clientele uses openapi-core to validate the schema.</p>"},{"location":"usage/#from-a-url_1","title":"From a URL","text":"<p>Use the <code>-u</code> or <code>--url</code> argument.</p> <p><code>-o</code> or <code>--output</code> is the target directory for the generate client.</p> <pre><code>clientele validate -u http://path.com/to/openapi.json\n</code></pre>"},{"location":"usage/#from-a-file-path","title":"From a file path","text":"<p>Alternatively you can provide a local file using the <code>-f</code> or <code>--file</code> argument.</p> <pre><code>clientele validate -f /path/to/openapi.json\n</code></pre>"},{"location":"usage/#generate-basic","title":"generate-basic","text":"<p>The <code>generate-basic</code> command can be used to generate a basic file structure for an HTTP client.</p> <p>It does not required an OpenAPI schema, just a path.</p> <p>This command serves two reasons:</p> <ol> <li>You may have an HTTP API without an OpenAPI schema and you want to keep a consistent file structure with other Clientele clients.</li> <li>The generator for this basic client can be extended for your own client in the future, if you choose.</li> </ol> <pre><code>clientele generate-basic -o my_client/\n</code></pre>"},{"location":"usage/#version","title":"<code>version</code>","text":"<p>Print the current version of Clientele:</p> <pre><code>&gt; clientele version\nClientele 0.7.0\n</code></pre>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\u269c\ufe0f Clientele","text":""},{"location":"#generate-loveable-python-http-api-clients","title":"Generate loveable Python HTTP API Clients","text":"<p>Clientele lets you generate fully-typed, pythonic HTTP API Clients using an OpenAPI schema.</p> <p>It's easy to use:</p> <pre><code># Install as a global tool - it's not a dependency!\npipx install clientele\n# Generate a client\nclientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o api_client/\n</code></pre>"},{"location":"#generated-code","title":"Generated code","text":"<p>The generated code is designed by python developers, for python developers.</p> <p>It uses modern tooling and has a great developer experience.</p> <pre><code>from my_api import client, schemas\n\n# Pydantic models for inputs and outputs\ndata = schemas.RequestDataRequest(my_input=\"test\")\n\n# Easy to read client functions\nresponse = client.request_data_request_data_post(data=data)\n\n# Handle responses elegantly\nmatch response:\n    case schemas.RequestDataResponse():\n        # Handle valid response\n        ...\n    case schemas.ValidationError():\n        # Handle validation error\n        ...\n</code></pre> <p>The generated code is tiny - the example schema we use for documentation and testing only requires 250 lines of code and 5 files.</p>"},{"location":"#async-support","title":"Async support","text":"<p>You can choose to generate either a sync or an async client - we support both:</p> <pre><code>from my_async_api import client\n\n# Async client functions\nresponse = await client.simple_request_simple_request_get()\n</code></pre>"},{"location":"#other-features","title":"Other features","text":"<ul> <li>Written entirely in Python.</li> <li>Designed to work with FastAPI's and drf-spectacular's OpenAPI schema generator.</li> <li>The generated client only depends on httpx and Pydantic 2.4.</li> <li>HTTP Basic and HTTP Bearer authentication support.</li> <li>Support your own configuration - we provide an entry point that will never be overwritten.</li> <li>Designed for easy testing with respx.</li> <li>API updated? Just run the same command again and check the git diff.</li> <li>Automatically formats the generated client with black.</li> </ul>"},{"location":"CHANGELOG/","title":"Change log","text":""},{"location":"CHANGELOG/#070","title":"0.7.0","text":"<ul> <li>Updated all files to use the templates engine.</li> <li>Generator files have been reorganised in clientele to support future templates.</li> <li><code>constants.py</code> has been renamed to <code>config.py</code> to better reflect how it is used. It is not generated from a template like the other files.</li> <li>If you are using Python 3.10 or later, the <code>typing.Unions</code> types will generate as the short hand <code>|</code> instead.</li> <li>To regenerate a client (and to prevent accidental overrides) you must now pass <code>--regen t</code> or <code>-r t</code> to the <code>generate</code> command. This is automatically added to the line in <code>MANIFEST.md</code> to  help.</li> <li>Clientele will now automatically run black code formatter once a client is generated or regenerated.</li> <li>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 <code>clientele</code> command in the root directory of your project.</li> <li>A lot of documentation and docs strings updates so that code in the generated client is easier to understand.</li> <li>Improved the utility for snake-casing enum keys. Tests added for the functions.</li> <li>Python 3.12 support.</li> <li>Add a \"basic\" client using the command <code>generate-basic</code>. This can be used to keep a consistent file structure for an API that does not use OpenAPI.</li> </ul>"},{"location":"CHANGELOG/#063","title":"0.6.3","text":"<ul> <li>Packaged application installs in the correct location. Resolving #6</li> <li>Updated pyproject.toml to include a better selection of links.</li> </ul>"},{"location":"CHANGELOG/#062","title":"0.6.2","text":"<ul> <li>Ignore optional URL query parameters if they are <code>None</code>.</li> </ul>"},{"location":"CHANGELOG/#061","title":"0.6.1","text":"<ul> <li>Added <code>from __future__ import annotations</code> in files to help with typing evaluation.</li> <li>Update to use pydantic 2.4.</li> <li>A bunch of documentation and readme updates.</li> <li>Small wording and grammar fixes.</li> </ul>"},{"location":"CHANGELOG/#060","title":"0.6.0","text":"<ul> <li>Significantly improved handling for response schemas. Responses from API endpoints now look at the HTTP status code to pick the correct response schema to generate from the HTTP json data. When regenerating, you will notice a bit more logic generated in the <code>http.py</code> file to handle this.</li> <li>Significantly improved coverage of exceptions raised when trying to generate response schemas.</li> <li>Response types for a class are now sorted.</li> <li>Fixed a bug where <code>put</code> methods did not generate input data correctly.</li> </ul>"},{"location":"CHANGELOG/#052","title":"0.5.2","text":"<ul> <li>Fix pathing for <code>constants.py</code> - thanks to @matthewknight for the contribution!</li> <li>Added <code>CONTRIBUTORS.md</code></li> </ul>"},{"location":"CHANGELOG/#051","title":"0.5.1","text":"<ul> <li>Support for HTTP PUT methods</li> <li>Headers objects use <code>exclude_unset</code> to avoid passing <code>None</code> values as headers, which httpx does not support.</li> </ul> <p>Additionally, an async test client is now included in the test suite. It has identical tests to the standard one but uses the async client instead.</p>"},{"location":"CHANGELOG/#050","title":"0.5.0","text":""},{"location":"CHANGELOG/#please-delete-the-constantspy-file-when-updating-to-this-version-to-have-new-features-take-affect","title":"Please delete the constants.py file when updating to this version to have new features take affect","text":"<ul> <li>Paths are resolved correctly when generating clients in nested directories.</li> <li><code>additional_headers()</code> is now applied to every client, allowing you to set up headers for all requests made by your client.</li> <li>When the client cannot match an HTTP response to a return type for the function it will now raise an <code>http.APIException</code>. This object will have the <code>response</code> attached to it for inspection by the developer.</li> <li><code>MANIFEST</code> is now renamed to <code>MANIFEST.md</code> and will include install information for Clientele, as well as information on the command used to generate the client.</li> </ul>"},{"location":"CHANGELOG/#044","title":"0.4.4","text":"<p>Examples and documentation now includes a very complex example schema built using FastAPI that offers the following variations:</p> <ul> <li>Simple request / response (no input just an output)</li> <li>A request with a URL/Path parameter.</li> <li>Models with <code>int</code>, <code>str</code>, <code>list</code>, <code>dict</code>, references to other models, enums, and <code>list</code>s of other models and enums.</li> <li>A request with query parameters.</li> <li>A response model that has optional parameters.</li> <li>An HTTP POST request that takes an input model.</li> <li>An HTTP POST request that takes path parameters and also an input model.</li> <li>An HTTP GET request that requires an HTTP header, and returns it.</li> <li>An HTTP GET endpoint that returns the HTTP bearer authorization token (also makes clientele generate the http authentication for this schema).</li> </ul> <p>A huge test suite has been added to the CI pipeline for this project using a copy of the generated client from the schema above.</p>"},{"location":"CHANGELOG/#043","title":"0.4.3","text":"<ul> <li><code>Enums</code> now inherit from <code>str</code> as well so that they serialize to JSON properly. See this little nugget.</li> </ul>"},{"location":"CHANGELOG/#042","title":"0.4.2","text":"<ul> <li>Correctly use <code>model_rebuild</code> for complex schemas where there are nested schemas, his may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema.</li> <li>Do not raise for status, instead attempt to return the response if it cannot match a response type.</li> </ul>"},{"location":"CHANGELOG/#041","title":"0.4.1","text":"<ul> <li>Correctly generate lists of nested schema classes</li> <li>Correctly build response schemas that are emphemeral (such as when they just return an array of other schemas, or when they have no $ref).</li> </ul>"},{"location":"CHANGELOG/#040","title":"0.4.0","text":"<ul> <li>Change install suggestion to use pipx as it works best as a global CLI tool.</li> <li>Improved support for OpenAPI 3.0.3 schemas (a test version is available in the example_openapi_specs directory).</li> <li><code>validate</code> command for validating an OpenAPI schema will work with clientele.</li> <li><code>version</code> command for showing the current version of clientele.</li> <li>Supports HTTP DELETE methods.</li> <li>Big refactor of how methods are generated to reduce duplicate code.</li> <li>Support optional header parameters in all request functions (where they are required).</li> <li>Very simple Oauth2 support - if it is discovered will set up HTTP Bearer auth for you.</li> <li>Uses <code>dict</code> and <code>list</code> instead of <code>typing.Dict</code> and <code>typing.List</code> respectively.</li> <li>Improved schema generation when schemas have $ref to other models.</li> </ul>"},{"location":"CHANGELOG/#032","title":"0.3.2","text":"<ul> <li>Minor changes to function name generation to make it more consistent.</li> <li>Optional parameters in schemas are working properly.</li> </ul>"},{"location":"CHANGELOG/#031","title":"0.3.1","text":"<ul> <li>Fixes a bug when generating HTTP Authentication schema.</li> <li>Fixes a bug when generating input classes for post functions, when the input schema doesn't exist yet.</li> <li>Generates pythonic function names in clients now, always (like <code>lower_case_snake_case</code>).</li> </ul>"},{"location":"CHANGELOG/#030","title":"0.3.0","text":"<ul> <li>Now generates a <code>MANIFEST</code> file with information about the build versions</li> <li>Added a <code>constants.py</code> file to the output if one does not exist yet, which can be used to store values that you do not want to change between subsequent re-generations of the clientele client, such as the API base url.</li> <li>Authentication patterns now use <code>constants.py</code> for constants values.</li> <li>Removed <code>ipython</code> from package dependencies and moved to dev dependencies.</li> <li>Documentation! https://phalt.github.io/clientele/</li> </ul>"},{"location":"CHANGELOG/#020","title":"0.2.0","text":"<ul> <li>Improved CLI output</li> <li>Code organisation is now sensible and not just one giant file</li> <li>Now supports an openapi spec generated from a dotnet project (<code>Microsoft.OpenApi.Models</code>)</li> <li>async client support  fully working</li> <li>HTTP Bearer support</li> <li>HTTP Basic support</li> </ul>"},{"location":"CHANGELOG/#010","title":"0.1.0","text":"<ul> <li>Initial version</li> <li>Mostly works with a simple FastAPI generated spec (3.0.2)</li> <li>Works with Twilio's spec (see example_openapi_specs/ directory) (3.0.1)</li> <li>Almost works with stripes</li> </ul>"},{"location":"compatibility/","title":"\ud83d\udcb1 Compatibility","text":""},{"location":"compatibility/#great-compatibility","title":"Great compatibility","text":"<p>Any standard <code>3.0.x</code> implementation works very well.</p> <p>We have tested Clientele with:</p> <ul> <li>FastAPI - our target audience, so 100% compatibility guaranteed.</li> <li>drf-spectacular works great as well, you can see which schemas we tested in this GitHub issue.</li> <li>Microsoft's OpenAPI spec has also been battle tested and works well.</li> </ul>"},{"location":"compatibility/#no-compatibility","title":"No compatibility","text":"<p>We do not support <code>2.x</code> aka \"Swagger\" - this format is quite different and deprecated.</p>"},{"location":"compatibility/#a-note-on-compatbility","title":"A note on compatbility","text":"<p>When we were building Clientele, we discovered that, despite a fantastic specification, OpenAPI has a lot of poor implementations.</p> <p>As pythonistas, we started with the auto-generated OpenAPI schemas provided by FastAPI, and then we branched out to large APIs like Twilio to test what we built.</p> <p>Despite the effort, we still keep finding subtly different OpenAPI implementations.</p> <p>Because of this we cannot guarentee 100% compatibility with an API, but we can give you a good indication of what we've tested.</p>"},{"location":"design/","title":"\ud83c\udfa8 Design","text":""},{"location":"design/#openapi-code-generators","title":"OpenAPI code generators","text":"<p>Every few years we check the HTTP API landscape to see what has changed, and what new tooling is available. A part of this research is seeing how far OpenAPI client generators have come.  </p> <p>In the early years of OpenAPI, the \"last mile\" (i.e. - generating, and using, a client library) had a pretty poor experience:</p> <ul> <li> <p>The generated code was difficult to read, leading to problems when debugging the code. It was often not idiomatic to the language.</p> </li> <li> <p>It was often bloated and repetitive, making changes tedious to support your specific project.</p> </li> <li> <p>Also, you had to install a lot of things like Java to generate the code.</p> </li> <li> <p>And finally, some API services still weren't publishing an OpenAPI schema. Or, the schema they published was different from the standard, so would not work with code generators.</p> </li> </ul> <p>This experience wasn't ideal, and was often such an impedance that it put us off using them. We would prefer instead to take a template of our own choosing, refined from years of working with HTTP APIs, and adapt it to whatever new API we were consuming.</p>"},{"location":"design/#the-landscape-in-2023","title":"The landscape in 2023","text":"<p>In the early part of 2023, we had to build an integration with a new HTTP API. So, like we did in the past, we used it as an opportunity to asses the landscape of OpenAPI client generators.</p> <p>And this was our summary at the time of writing:</p> <ul> <li> <p>API tools and providers had adopted OpenAPI very well. For example - tools like FastAPI and drf-spectacular now make it easy for the most popular python web frameworks to publish OpenAPI schemas.</p> </li> <li> <p>There are a lot of options for generating clients. They all meet the need of \"generating a python client using the schema\". But, almost universally, they have a poor developer experience.</p> </li> </ul> <p>After evaluating many python client generators, we opted to use none of them and hand craft the API client ourselves. We used the OpenAPI schema as a source to develop the input and output objects.  Then we wrote a small functional abstraction over the paths.</p> <p>Looking back over our organised, pythonic, minimal client integration, we had an idea:</p> <p>If this is the type of client we would like a generator to produce; how hard could it be to work backwards and build one?</p> <p>This was the start of Clientele.</p>"},{"location":"design/#clientele","title":"Clientele","text":"<p>As python developers ourselves, we know what makes good, readable, idiomatic python.</p> <p>We also feel like we have a grasp on the best tools to be using in our python projects.</p> <p>By starting with a client library that we like to use, and working backwards, we were able to build a client generator that produced something that python developers actually wanted.</p> <p>But what is it exactly that we aimed to do with Clientele, why is this the OpenAPI Python client that you should use?</p>"},{"location":"design/#strongly-typed-inputs-and-outputs","title":"Strongly-typed inputs and outputs","text":"<p>OpenAPI prides itself on being able to describe the input and output objects in it's schema.</p> <p>This means you can build strongly-typed interfaces to the API. This helps to solve some common niggles when using an API - such as casting a value to a string when it should be an integer.</p> <p>With Clientele, we opted to use Pydantic to build the models from the OpenAPI schema.</p> <p>Pydantic doesn't only describe the shape of an object, it also validates the attributes as well. If an API sends back the wrong attributes at run time, Pydantic will error and provide a detail description about what went wrong.</p>"},{"location":"design/#idiomatic-python","title":"Idiomatic Python","text":"<p>A lot of the client generators we tested produced a lot of poor code.</p> <p>It was clear in a few cases that the client generator was built without understanding or knowledge of good python conventions.</p> <p>In more than one case we also discovered the client generator would work by reading a file at run time. This is a very cool piece of engineering, but it is impractical to use. When you develop with these clients, the available functions and objects don't exist and you can't use an IDE's auto-complete feature.</p> <p>Clientele set out to be as pythonic as possible. We use modern tools,  idiomatic conventions, and provide some helpful bonuses like Black auto-formatting.</p>"},{"location":"design/#easy-to-understand","title":"Easy to understand","text":"<p>Eventually a developer will need to do some debugging, and sometimes they'll need to do it in the generated client code.</p> <p>A lot of the other client generators make obscure or obtuse code that is hard to pick apart and debug.</p> <p>Now, there is a suggestion that developers shouldn't have to look at this, and that is fair. But the reality doesn't match that expectation. Personally; we like to know what generated code is doing. We want to trust that it will work, and that we can adapt around it if needs be. An interesting quirk of any code generator is you can't always inspect the source when evaluating to use it. Any other tool - you'd just go to GitHub and have a read around, but you can't with code generators.</p> <p>So the code that is generated needs to be easy to understand.</p> <p>Clientele doesn't do any tricks, or magic, or anything complex. The generated code has documentation and is designed to be readable. It is only a small layer on top of already well established tools, such as HTTPX.</p> <p>In fact, we have some generated clients in our project repository so you can see what it looks like. We even have example tests for you to learn how to integrate with it.</p> <p>It is that way because we know you will need to inspect it in the future. We want you to know that this is a sane and sensible tool.</p>"},{"location":"examples/","title":"\ud83e\ude84 Client example","text":"<p>Let's build an API Client using clientele.</p> <p>Our GitHub has a bunch of schemas that are proven to work with clientele, so let's use one of those!</p>"},{"location":"examples/#generate-the-client","title":"Generate the client","text":"<p>In your project's root directory:</p> <pre><code>clientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o my_client/\n</code></pre> <p>Note</p> <p>The example above uses one of our test schemas, and will work if you copy/paste it!</p> <p>The <code>-u</code> parameter expects a URL, you can provide a path to a file with <code>-f</code> instead if you download the file.</p> <p>The <code>-o</code> parameter is the output directory of the generated client.</p> <p>Run it now and you will see this output:</p> <pre><code>my_client/\n    __init__.py\n    client.py\n    config.py\n    http.py\n    MANIFEST\n    schemas.py\n</code></pre> <p>Let's go over each file and talk about what it does.</p>"},{"location":"examples/#client","title":"Client","text":""},{"location":"examples/#get-functions","title":"GET functions","text":"<p>The <code>client.py</code> file provides all the API functions from the OpenAPI schema. Functions are a combination of the path and the HTTP method for those paths. So, a path with two HTTP methods will be turned into two python functions.</p> my_client/client.py<pre><code>from my_client import http, schemas\n\n\ndef simple_request_simple_request_get() -&gt; schemas.SimpleResponse:\n    \"\"\"Simple Request\"\"\"\n\n    response = http.get(url=\"/simple-request\")\n    return http.handle_response(simple_request_simple_request_get, response)\n\n...\n</code></pre> <p>We can see one of the functions here, <code>simple_request_simple_request_get</code>, is for a straight-forward HTTP GET request without any input arguments, and it returns a schema object.</p> <p>Here is how you might use it:</p> <pre><code>from my_client import client\n\nclient.simple_request_simple_request_get()\n&gt;&gt;&gt; SimpleResponse(name='Hello, clientele')\n</code></pre>"},{"location":"examples/#post-and-put-functions","title":"POST and PUT functions","text":"<p>A more complex example is shown just below. </p> <p>This is for an HTTP POST method, and it requires an input property called <code>data</code> that is an instance of a schema, and returns one of many potential responses. If the endpoint has url parameters or query parameters, they will appear as input arguments to the function alongside the <code>data</code> argument.</p> <pre><code>def request_data_request_data_post(\n    data: schemas.RequestDataRequest\n) -&gt; schemas.RequestDataResponse | schemas.HTTPValidationError:\n    \"\"\"Request Data\"\"\"\n\n    response = http.post(url=\"/request-data\", data=data.model_dump())\n    return http.handle_response(request_data_request_data_post, response)\n</code></pre> <p>Here is how you might use it:</p> <pre><code>from my_client import client, schemas\n\ndata = schemas.RequestDataRequest(my_input=\"Hello, world\")\nresponse = client.request_data_request_data_post(data=data)\n&gt;&gt;&gt; RequestDataResponse(your_input='Hello, world')\n</code></pre> <p>Clientele also supports the major HTTP methods PUT and DELETE in the same way.</p>"},{"location":"examples/#url-and-query-parameters","title":"URL and Query parameters","text":"<p>If your endpoint takes path parameters (aka URL parameters) then clientele will turn them into parameters in the function:</p> <pre><code>from my_client import client\n\nclient.parameter_request_simple_request(your_input=\"gibberish\")\n&gt;&gt;&gt; ParameterResponse(your_input='gibberish')\n</code></pre> <p>Query parameters will also be generated the same way. See this example for a function that takes a required query parameter.</p> <p>Note that, optional parameters that are not passed will be omitted when the URL is generated by Clientele.</p>"},{"location":"examples/#handling-responses","title":"Handling responses","text":"<p>Because we're using Pydantic to manage the input data, we get a strongly-typed response object. This works beautifully with the new structural pattern matching feature in Python 3.10 and up:</p> <pre><code>response = client.request_data_request_data_post(data=data)\n\n# Handle responses elegantly\nmatch response:\n    case schemas.RequestDataResponse():\n        # Handle valid response\n        ...\n    case schemas.ValidationError():\n        # Handle validation error\n        ...\n</code></pre>"},{"location":"examples/#api-exceptions","title":"API Exceptions","text":"<p>Clientele keeps a mapping of the paths and their potential response codes. When it gets a response code that fits into the map, it generates the pydantic object associated to it.</p> <p>If the HTTP response code is an unintended one, it will not match a return type. In this case, the function will raise an <code>http.APIException</code>.</p> <pre><code>from my_client import client, http\ntry:\n    good_response = my_client.get_my_thing()\nexcept http.APIException as e:\n    # The API got a response code we didn't expect\n    print(e.response.status_code)\n</code></pre> <p>The <code>response</code> object will be attached to this exception class for your own debugging.</p>"},{"location":"examples/#schemas","title":"Schemas","text":"<p>The <code>schemas.py</code> file has all the possible schemas, request and response, and even Enums, for the API. These are taken from OpenAPI's  schemas objects and turned into Python classes. They are all subclassed from pydantic's <code>BaseModel</code>. </p> <p>Here are a few examples:</p> my_client/schemas.py<pre><code>import pydantic\nfrom enum import Enum\n\n\nclass ParameterResponse(pydantic.BaseModel):\n    your_input: str\n\nclass RequestDataRequest(pydantic.BaseModel):\n    my_input: str\n\nclass RequestDataResponse(pydantic.BaseModel):\n    my_input: str\n\n# Enums subclass str so they serialize to JSON nicely\nclass ExampleEnum(str, Enum):\n    ONE = \"ONE\"\n    TWO = \"TWO\"\n</code></pre>"},{"location":"examples/#configuration","title":"Configuration","text":"<p>One of the problems with auto-generated clients is that you often need to configure them, and if you try and regenerate the client at some point in the future then your configuration gets wiped clean and you have to do it all over again.</p> <p>Clientele solves this problem by providing an entry point for configuration that will never be overwritten - <code>config.py</code>.</p> <p>When you first generate the project, you will see a file called <code>config.py</code> and it will offer configuration functions a bit like this:</p> <pre><code>\"\"\"\nThis file will never be updated on subsequent clientele runs.\nUse it as a space to store configuration and constants.\n\nDO NOT CHANGE THE FUNCTION NAMES\n\"\"\"\n\n\ndef api_base_url() -&gt; str:\n    \"\"\"\n    Modify this function to provide the current api_base_url.\n    \"\"\"\n    return \"http://localhost\"\n</code></pre> <p>Subsequent runs of the <code>generate</code> command with <code>--regen t</code> will not change this file if it exists, so you are free to modify the defaults to suit your needs. </p> <p>For example, if you need to source the base url of your API for different configurations, you can modify the <code>api_base_url</code> function like this:</p> <pre><code>from my_project import my_config\n\ndef api_base_url() -&gt; str:\n    \"\"\"\n    Modify this function to provide the current api_base_url.\n    \"\"\"\n    if my_config.debug:\n        return \"http://localhost:8000\"\n    elif my_config.production:\n        return \"http://my-production-url.com\"\n</code></pre> <p>Just keep the function names the same and you're good to go.</p>"},{"location":"examples/#authentication","title":"Authentication","text":"<p>If your OpenAPI spec provides security information for the following authentication methods:</p> <ul> <li>HTTP Bearer</li> <li>HTTP Basic</li> </ul> <p>Then clientele will provide you information on the environment variables you need to set to make this work during the generation. For example:</p> <pre><code>Please see my_client/config.py to set authentication variables\n</code></pre> <p>The <code>config.py</code> file will have entry points for you to configure, for example, HTTP Bearer authentication will need the <code>get_bearer_token</code> function to be updated, something like this:</p> <pre><code>def get_bearer_token() -&gt; str:\n    \"\"\"\n    HTTP Bearer authentication.\n    Used by many authentication methods - token, jwt, etc.\n    Does not require the \"Bearer\" content, just the key as a string.\n    \"\"\"\n    from os import environ\n    return environ.get(\"MY_AUTHENTICATION_TOKEN\")\n</code></pre>"},{"location":"examples/#additional-headers","title":"Additional headers","text":"<p>If you want to pass specific headers with all requests made by the client, you can configure the <code>additional_headers</code> function in <code>config.py</code> to do this.</p> <pre><code>def additional_headers() -&gt; dict:\n    \"\"\"\n    Modify this function ot provide additional headers to all\n    HTTP requests made by this client.\n    \"\"\"\n    return {}\n</code></pre> <p>Please note that if you are using this with authentication headers, then authentication headers will overwrite these defaults if they keys match.</p>"},{"location":"install/","title":"\ud83c\udfd7\ufe0f Install","text":"<p>We recommend installing with pipx as a global CLI command:</p> <pre><code>pipx install clientele\n</code></pre> <p>Once installed you can run <code>clientele version</code> to make sure you have the latest version:</p> <pre><code>&gt; clientele version\nclientele 0.7.0\n</code></pre>"},{"location":"testing/","title":"Testing","text":"<p>Clientele is designed for easy testing, and our own test suite is a great example of how easily you can write mock tests for your API Client.</p> <pre><code>import pytest\nfrom httpx import Response\nfrom respx import MockRouter\n\nfrom .test_client import client, constants, schemas\n\nBASE_URL = constants.api_base_url()\n\n\n@pytest.mark.respx(base_url=BASE_URL)\ndef test_simple_request_simple_request_get(respx_mock: MockRouter):\n    # Given\n    mocked_response = {\"status\": \"hello world\"}\n    mock_path = \"/simple-request\"\n    respx_mock.get(mock_path).mock(\n        return_value=Response(json=mocked_response, status_code=200)\n    )\n    # When\n    response = client.simple_request_simple_request_get()\n    # Then\n    assert isinstance(response, schemas.SimpleResponse)\n    assert len(respx_mock.calls) == 1\n    call = respx_mock.calls[0]\n    assert call.request.url == BASE_URL + mock_path\n</code></pre> <p>We recommend you install respx for writing your tests.</p>"},{"location":"usage/","title":"\ud83d\udcdd Use Clientele","text":"<p>Note</p> <p>You can type <code>clientele COMMAND --help</code> at anytime to see explicit information about the available arguments.</p>"},{"location":"usage/#generate","title":"<code>generate</code>","text":"<p>Generate a Python HTTP Client from an OpenAPI Schema.</p>"},{"location":"usage/#from-a-url","title":"From a URL","text":"<p>Use the <code>-u</code> or <code>--url</code> argument.</p> <p><code>-o</code> or <code>--output</code> is the target directory for the generate client.</p> <pre><code>clientele generate -u https://raw.githubusercontent.com/phalt/clientele/main/example_openapi_specs/best.json -o my_client/\n</code></pre> <p>Note</p> <p>The example above uses one of our test schemas, and will work if you copy/paste it!</p>"},{"location":"usage/#from-a-file","title":"From a file","text":"<p>Alternatively you can provide a local file using the <code>-f</code> or <code>--file</code> argument.</p> <pre><code>clientele generate -f path/to/file.json -o my_client/\n</code></pre>"},{"location":"usage/#asyncio","title":"Async.io","text":"<p>If you prefer an asyncio client, just pass <code>--asyncio t</code> to your command.</p> <pre><code>clientele generate -f path/to/file.json -o my_client/ --asyncio t\n</code></pre>"},{"location":"usage/#regenerating","title":"Regenerating","text":"<p>At times you may wish to regenerate the client. This could be because the API has updated or you just want to use a newer version of clientele.</p> <p>To force a regeneration you must pass the <code>--regen</code> or <code>-r</code> argument, for example:</p> <pre><code>clientele generate -f example_openapi_specs/best.json -o my_client/  --regen t\n</code></pre> <p>Note</p> <p>You can copy and paste the command from the <code>MANIFEST.md</code> file in your previously-generated client for a quick and easy regeneration.</p>"},{"location":"usage/#validate","title":"<code>validate</code>","text":"<p>Validate lets you check if an OpenAPI schema will work with clientele.</p> <p>Note</p> <p>Some OpenAPI schema generators do not conform to the specification.</p> <p>Clientele uses openapi-core to validate the schema.</p>"},{"location":"usage/#from-a-url_1","title":"From a URL","text":"<p>Use the <code>-u</code> or <code>--url</code> argument.</p> <p><code>-o</code> or <code>--output</code> is the target directory for the generate client.</p> <pre><code>clientele validate -u http://path.com/to/openapi.json\n</code></pre>"},{"location":"usage/#from-a-file-path","title":"From a file path","text":"<p>Alternatively you can provide a local file using the <code>-f</code> or <code>--file</code> argument.</p> <pre><code>clientele validate -f /path/to/openapi.json\n</code></pre>"},{"location":"usage/#generate-basic","title":"generate-basic","text":"<p>The <code>generate-basic</code> command can be used to generate a basic file structure for an HTTP client.</p> <p>It does not required an OpenAPI schema, just a path.</p> <p>This command serves two reasons:</p> <ol> <li>You may have an HTTP API without an OpenAPI schema and you want to keep a consistent file structure with other Clientele clients.</li> <li>The generator for this basic client can be extended for your own client in the future, if you choose.</li> </ol> <pre><code>clientele generate-basic -o my_client/\n</code></pre>"},{"location":"usage/#version","title":"<code>version</code>","text":"<p>Print the current version of Clientele:</p> <pre><code>&gt; clientele version\nClientele 0.7.0\n</code></pre>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index b00e65a61ec5279b421d18ef337d80682172b16a..f7a14991b26f72c4a9686384544465e028ddfe1f 100644
GIT binary patch
delta 15
WcmbQnG>wT(zMF%i$8aN?03!e%vIBMi

delta 15
WcmbQnG>wT(zMF$1U2h|s03!e$#RE<N