From 2ebac6ba7a738e608ea89b2a760711376028118d Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Sun, 28 Dec 2025 11:42:51 -0500 Subject: [PATCH] Drops crud documentation --- docs/index.md | 2 +- docs/logging.md | 10 ++- docs/requests.md | 175 ----------------------------------------------- docs/session.md | 84 ----------------------- docs/started.md | 123 +++++++++++++++++++++++++++++++++ mkdocs.yml | 3 +- 6 files changed, 129 insertions(+), 268 deletions(-) delete mode 100644 docs/requests.md delete mode 100644 docs/session.md create mode 100644 docs/started.md diff --git a/docs/index.md b/docs/index.md index 71fe89d..0bfa509 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # Keystone Python Client -Keystone includes an official Python client designed to simplify integration with the platform's [REST API](../../keystone-api/). +Keystone provides an official Python client designed to simplify integration with the platform's [REST API](../../keystone-api/). It handles authentication, request execution, and response parsing, allowing developers to concentrate on application logic rather than API mechanics. diff --git a/docs/logging.md b/docs/logging.md index 7681c24..0e4d6a3 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -1,9 +1,8 @@ # Application Logging -The Keystone Python Client includes a dedicated logger named `kclient`, which is automatically registered on package -import. The logger provides full compatibility with the standard Python `logging` module, including support for custom -handlers, formatters, and filters. -The logger can be accessed and customized in the standard fashion, demonstrated below. +The `kclient` Python logger is automatically registered on package import. +It provides full compatibility with the standard Python `logging` module and can be accessed and customized in the +standard fashion. ```python import logging @@ -32,8 +31,7 @@ These fields are passed to all log messages and may be accessed via custom forma ## Session IDs -Each client session is assigned a unique correlation ID (CID) that accompanies all emitted log records and requests. -This identifier provides a reference value for correlating client and API logs across multiple endpoints and services. +Each client session is assigned a unique correlation ID (CID) that accompanies all emitted log records. CID values are accessible as logging fields or directly from an active client session, demonstrated below: === "Synchronous" diff --git a/docs/requests.md b/docs/requests.md deleted file mode 100644 index 9764a4c..0000000 --- a/docs/requests.md +++ /dev/null @@ -1,175 +0,0 @@ -# Making API Requests - -Client classes (`KeystoneClient` and `AsyncKeystoneClient`) provide a high-level interface for interacting the API. -This includes methods for generic HTTP requests in addition to resource-specific CRUD helpers for common workflows. -All requests automatically include any active authentication or session metadata. - -## Generic HTTP Requests - -Client classes provide dedicated methods for each HTTP request type supported by the API. -Any relevant session/authentication tokens are included automatically when submitting requests. - -| HTTP Method | Function Name | Description | -|-------------|---------------|----------------------------------------------------------| -| `GET` | `http_get` | Retrieve data from the server at the specified resource. | -| `POST` | `http_post` | Submit a new record to be processed by the server. | -| `PUT` | `http_put` | Replace an existing record with a new one. | -| `PATCH` | `http_patch` | Partially update an existing record. | -| `DELETE` | `http_delete` | Remove the specified record from the server. | - -Request/response logic is handled using the `httpx` library. -API responses are returned as `httpx.Response` objects which encapsulate the response data and status code. -Users are encouraged to familiarize themselves with the `httpx` library and it's methods for parsing response -data and related metadata. -A simple example is provided below. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - response = client.http_get('version') - - response.raise_for_status() - print(response.status_code) - print(response.content) - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - response = await aclient.http_get('version') - - response.raise_for_status() - print(response.status_code) - print(response.content) - ``` - -## CRUD Operations - -Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations against each API resource. -These methods simplify data manipulation by automatically handling the request and response logic. - -CRUD methods adhere to the following naming scheme: - -| Method Name | Description | -|-----------------------|----------------------------------------------------------| -| `create_{resource}` | Create a new record for the specified resource. | -| `retrieve_{resource}` | Retrieve one or more records for the specified resource. | -| `update_{resource}` | Update an existing record for the specified resource. | -| `delete_{resource}` | Delete an existing record for the specified resource. | - -### Creating Records - -Create methods are used to submit new records to the API server. -These methods accept record details as keyword arguments and return a dictionary with the successfully created record. - -=== "Synchronous" - - ```python - new_record_data = client.create_cluster( - name="New-Cluster", - description="Cluster created for example purposes." - ) - ``` - -=== "Asynchronous" - - ```python - new_record_data = await aclient.create_cluster( - name="New-Cluster", - description="Cluster created for example purposes." - ) - ``` - -### Retrieving Records - -Data retrieval methods are used to search and return existing records. -By default, these methods return all available records on the server as a list of dictionaries. -The `filters` argument can be used to optionally filter these values against a set of search parameters. -See the [filtering documentation](../../keystone-api/api/filtering/) for instructions on structuring search queries. - -=== "Synchronous" - - ```python - all_cluster_data = client.retrieve_cluster(filters={"name": "New-Cluster"}) - ``` - -=== "Asynchronous" - - ```python - all_cluster_data = await aclient.retrieve_cluster(filters={"name": "New-Cluster"}) - ``` - -In situations where a record's primary key (i.e., it's `id` field) is already known, the individual record can be -retrieved directly. - -=== "Synchronous" - - ```python - single_cluster_data = client.retrieve_cluster(pk=1) - ``` - -=== "Asynchronous" - - ```python - single_cluster_data = await aclient.retrieve_cluster(pk=1) - ``` - -### Updating Records - -Update operations are used to modify values for an existing record. -Doing so requires specifying the record's primary key in addition to the new record values. - -=== "Synchronous" - - ```python - updated_record_data = client.update_cluster( - pk=1, - data={'description': "Updated description"} - ) - ``` - -=== "Asynchronous" - - ```python - updated_record_data = await aclient.update_cluster( - pk=1, - data={'description': "Updated description"} - ) - ``` - -### Deleting Records - -Delete methods are used to remove records from the server. - -=== "Synchronous" - - ```python - client.delete_cluster(pk=1) - ``` - -=== "Asynchronous" - - ```python - await aclient.delete_cluster(pk=1) - ``` - -If a record does not exist for the provided primary key, the function call will exit silently. -The `raise_not_exists` argument can be used to raise an exception instead. - -=== "Synchronous" - - ```python - client.delete_cluster(pk=1, raise_not_exists=True) - ``` - -=== "Asynchronous" - - ```python - await aclient.delete_cluster(pk=1, raise_not_exists=True) - ``` diff --git a/docs/session.md b/docs/session.md deleted file mode 100644 index 8e04638..0000000 --- a/docs/session.md +++ /dev/null @@ -1,84 +0,0 @@ -# Starting a Session - -Interacting with the Keystone API begins by creating a client session. -<<<<<<< Updated upstream -Session objects encapsulate the connection state and request configuration, allowing the -client to efficiently reuse connections and manage resources across multiple API calls. -======= -Session objects encapsulate the connection state, authentication details, and request configuration, allowing the -client to efficiently reuse connections across multiple API calls. ->>>>>>> Stashed changes - -## Instantiating a Client - -The client package provides support for synchronous and asynchronous API calls. -The following example instantiates a new session for a locally running server on port `8000`. -Creating the session with a context manager ensures open connections are automatically closed when no longer in use. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - ... # Your synchronous code here - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - ... # Your asynchronous code here - ``` - -Sessions can also be opened and closed manually, although this approach is generally discouraged as it increases -the likelihood of resource leaks and unclosed connections. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - client = KeystoneClient(url="http://localhost:8000"): - # Your synchronous code here - client.close() - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - aclient = AsyncKeystoneClient(url="http://localhost:8000"): - # Your asynchronous code here - await aclient.close() - ``` - -## Authenticating a Session - -The `login` and `logout` methods are used to handle user authentication. -Once authenticated, the client will automatically manage the resulting session tokens. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - client.login(username="username", password="password") - assert client.is_authenticated() - client.logout() - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - await aclient.login(username="username", password="password") - assert await aclient.is_authenticated() - await aclient.logout() - ``` diff --git a/docs/started.md b/docs/started.md new file mode 100644 index 0000000..7f77e1a --- /dev/null +++ b/docs/started.md @@ -0,0 +1,123 @@ +# Getting Started + +The `KeystoneClient` and `AsyncKeystoneClient` classes offer a streamlined, session-based interface for interacting with +the Keystone API. They automatically manage common connection settings to ensure requests are submitted efficiently +and abstract away low level API mechanics so developers can focus on application logic. + +## Instantiating a Client + +The following example instantiates a new session for a locally running server on port `8000`. +Creating the session with a context manager ensures open connections are automatically closed when no longer in use. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + ... # Your synchronous code here + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + ... # Your asynchronous code here + ``` + +Sessions can also be opened and closed manually, although this approach is generally discouraged as it increases +the likelihood of resource leaks and unclosed connections. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + client = KeystoneClient(url="http://localhost:8000"): + # Your synchronous code here + client.close() + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + aclient = AsyncKeystoneClient(url="http://localhost:8000"): + # Your asynchronous code here + await aclient.close() + ``` + +## Authenticating a Session + +The `login` and `logout` methods are used to handle user authentication. +Once authenticated, the client will automatically manage the resulting session tokens. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + client.login(username="username", password="password") + assert client.is_authenticated() + client.logout() + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + await aclient.login(username="username", password="password") + assert await aclient.is_authenticated() + await aclient.logout() + ``` + +## Making API Requests + +Client classes provide dedicated methods for each HTTP request type supported by the API. +Any relevant session/authentication tokens are included automatically when submitting requests. + +| HTTP Method | Function Name | Description | +|-------------|---------------|----------------------------------------------------------| +| `GET` | `http_get` | Retrieve data from the server at the specified resource. | +| `POST` | `http_post` | Submit a new record to be processed by the server. | +| `PUT` | `http_put` | Replace an existing record with a new one. | +| `PATCH` | `http_patch` | Partially update an existing record. | +| `DELETE` | `http_delete` | Remove the specified record from the server. | + +Request/response logic is handled using the `httpx` library. +API responses are returned as `httpx.Response` objects which encapsulate the response data and status code. +Users are encouraged to familiarize themselves with the `httpx` library and it's methods for parsing response +data and related metadata. +A simple example is provided below. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + response = client.http_get('version') + + response.raise_for_status() + print(response.status_code) + print(response.content) + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + response = await aclient.http_get('version') + + response.raise_for_status() + print(response.status_code) + print(response.content) + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 7bd3b4c..c6ec91f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,5 @@ site_name: Keystone Python Client nav: - Introduction: index.md - - session.md - - requests.md + - started.md - logging.md