11# ctrlplane-api-client
2+
23A client library for accessing Ctrlplane API
34
45## Usage
6+
57First, create a client:
68
79``` python
@@ -47,7 +49,7 @@ By default, when you're calling an HTTPS API it will attempt to verify that SSL
4749
4850``` python
4951client = AuthenticatedClient(
50- base_url = " https://internal_api.example.com" ,
52+ base_url = " https://internal_api.example.com" ,
5153 token = " SuperSecretToken" ,
5254 verify_ssl = " /path/to/certificate_bundle.pem" ,
5355)
@@ -57,18 +59,20 @@ You can also disable certificate validation altogether, but beware that **this i
5759
5860``` python
5961client = AuthenticatedClient(
60- base_url = " https://internal_api.example.com" ,
61- token = " SuperSecretToken" ,
62+ base_url = " https://internal_api.example.com" ,
63+ token = " SuperSecretToken" ,
6264 verify_ssl = False
6365)
6466```
6567
6668Things to know:
69+
67701 . Every path/method combo becomes a Python module with four functions:
68- 1 . ` sync ` : Blocking request that returns parsed data (if successful) or ` None `
69- 1 . ` sync_detailed ` : Blocking request that always returns a ` Request ` , optionally with ` parsed ` set if the request was successful.
70- 1 . ` asyncio ` : Like ` sync ` but async instead of blocking
71- 1 . ` asyncio_detailed ` : Like ` sync_detailed ` but async instead of blocking
71+
72+ 1 . ` sync ` : Blocking request that returns parsed data (if successful) or ` None `
73+ 1 . ` sync_detailed ` : Blocking request that always returns a ` Request ` , optionally with ` parsed ` set if the request was successful.
74+ 1 . ` asyncio ` : Like ` sync ` but async instead of blocking
75+ 1 . ` asyncio_detailed ` : Like ` sync_detailed ` but async instead of blocking
7276
73771 . All path/query params, and bodies become method arguments.
74781 . If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
@@ -110,15 +114,26 @@ client.set_httpx_client(httpx.Client(base_url="https://api.example.com", proxies
110114```
111115
112116## Building / publishing this package
113- This project uses [ Poetry] ( https://python-poetry.org/ ) to manage dependencies and packaging. Here are the basics:
117+
118+ This project uses [ Poetry] ( https://python-poetry.org/ ) to manage dependencies and packaging. Here are the basics:
119+
1141201 . Update the metadata in pyproject.toml (e.g. authors, version)
1151211 . If you're using a private repository, configure it with Poetry
116- 1 . ` poetry config repositories.<your-repository-name> <url-to-your-repository> `
117- 1 . ` poetry config http-basic.<your-repository-name> <username> <password> `
122+ 1 . ` poetry config repositories.<your-repository-name> <url-to-your-repository> `
123+ 1 . ` poetry config http-basic.<your-repository-name> <username> <password> `
1181241 . Publish the client with ` poetry publish --build -r <your-repository-name> ` or, if for public PyPI, just ` poetry publish --build `
119125
120126If you want to install this client into another project without publishing it (e.g. for development) then:
127+
1211281 . If that project ** is using Poetry** , you can simply do ` poetry add <path-to-this-client> ` from that project
1221291 . If that project is not using Poetry:
123- 1 . Build a wheel with ` poetry build -f wheel `
124- 1 . Install that wheel from the other project ` pip install <path-to-wheel> `
130+ 1 . Build a wheel with ` poetry build -f wheel `
131+ 1 . Install that wheel from the other project ` pip install <path-to-wheel> `
132+
133+ # Generate the client from the OpenAPI spec
134+
135+ ``` bash
136+ openapi-python-client generate \
137+ --output-path . \
138+ --url https://raw.githubusercontent.com/ctrlplanedev/ctrlplane/refs/heads/main/openapi.v1.json
139+ ```
0 commit comments