From 3024d605431d67b83b821ef632616a30ef81bffc Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Sat, 9 Nov 2024 22:33:31 -0500 Subject: [PATCH 1/2] Condense docs to a single page --- docs/client_reference.md | 15 ----- docs/index.md | 127 +++++++++++++++++++++++++++++++++++---- docs/user_guide.md | 121 ------------------------------------- mkdocs.yml | 4 -- 4 files changed, 115 insertions(+), 152 deletions(-) delete mode 100644 docs/client_reference.md delete mode 100644 docs/user_guide.md diff --git a/docs/client_reference.md b/docs/client_reference.md deleted file mode 100644 index d8f043e..0000000 --- a/docs/client_reference.md +++ /dev/null @@ -1,15 +0,0 @@ -# KeystoneClient - -::: keystone_client.KeystoneClient - options: - inherited_members: true - members: - - login - - logout - - api_version - - is_authenticated - - http_get - - http_post - - http_put - - http_patch - - http_delete diff --git a/docs/index.md b/docs/index.md index b040208..2213913 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + # Introduction Keystone provides a light-weight Python client for streamlining interactions with the application's REST API. @@ -11,26 +16,124 @@ The Python client is hosted on PyPI and can be installed in the standard fashion pip install keystone-api-client ``` -## Getting Started +## User Guide + +The `KeystoneClient` class is used to encapsulate user authentication and API requests. +New instances are created by specifying the API URL. +In the following example, a client instance is defined for a locally running server on port `8000`. + +```python +from keystone_client import KeystoneClient + +client = KeystoneClient(url="http://localhost:8000") # (1)! +``` + +1. Specifying a network protocol is required when instantiating new instances (e.g., `http://` or `https://`). + +The `login` and `logout` methods are used to handle user authentication. +Once authenticated, the client will automatically manage the resulting user credentials, including refreshing JWT +tokens. + +```python +client.login(username="username", password="password") # (1)! +assert client.is_authenticated # (2)! +client.logout() # (3)! +``` + +1. Authenticate a new user session. +2. Check the authentication status at any time. +3. End the authenticated session and blacklist current credentials. + +## Generic HTTP Requests + +The client provides dedicated methods for each HTTP request type supported by the API. +When authenticated, the client will automatically include the appropriate authentication headers 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 popular `requests` library. +API responses are returned as `requests.Response` objects encapsulating the response data and status code. + +```python +response = client.http_get('version') + +print(response.status_code) +print(response.content) +``` + +## CRUD Operations + +Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations for 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 data. + +```python +new_record_data = client.create_cluster( + name="New-Cluster", + description="Cluster created for example purposes." +) +``` + +### Retrieving Records -For more information, see the resources below. +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 requests documentation](../../keystone-api/api/filtering/) for instructions on structuring search queries. + +```python +all_cluster_data = client.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. -- :material-rocket-launch: **User Guide** +```python +cluster_pk_one = client.retrieve_cluster(pk=1) +``` - --- +### Updating Records - Get up and running with the client quickstart guide. +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. - [:octicons-arrow-right-24: Get Started](user_guide.md) +```python +updated_record_data = client.update_cluster( + pk=1, + data={'description': "Updated description"} +) +``` -- :octicons-codescan-16: **Source Code Reference** +### Deleting Records - --- +Delete methods are used to removed records from the server. - Low level developer documentation for the Keystone-API Python client. +```python +client.delete_cluster(pk=1) +``` - [:octicons-arrow-right-24: See the Docs](client_reference.md) +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. -
+```python +client.delete_cluster(pk=1, raise_not_exists=True) +``` diff --git a/docs/user_guide.md b/docs/user_guide.md deleted file mode 100644 index 9a676f7..0000000 --- a/docs/user_guide.md +++ /dev/null @@ -1,121 +0,0 @@ -# User Guide - -The `KeystoneClient` class is used to encapsulate user authentication and API requests. -New instances are created by specifying the API URL. -In the following example, a client instance is defined for a locally running server on port `8000`. - -```python -from keystone_client import KeystoneClient - -client = KeystoneClient(url="http://localhost:8000") # (1)! -``` - -1. Specifying a network protocol is required when instantiating new instances (e.g., `http://` or `https://`). - -The `login` and `logout` methods are used to handle user authentication. -Once authenticated, the client will automatically manage the resulting user credentials, including refreshing JWT -tokens. - -```python -client.login(username="username", password="password") # (1)! -assert client.is_authenticated # (2)! -client.logout() # (3)! -``` - -1. Authenticate a new user session. -2. Check the authentication status at any time. -3. End the authenticated session and blacklist current credentials. - -## Generic HTTP Requests - -The client provides dedicated methods for each HTTP request type supported by the API. -When authenticated, the client will automatically include the appropriate authentication headers 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 popular `requests` library. -API responses are returned as `requests.Response` objects encapsulating the response data and status code. - -```python -response = client.http_get('version') - -print(response.status_code) -print(response.content) -``` - -## CRUD Operations - -Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations for 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 data. - -```python -new_record_data = client.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 requests documentation](../../keystone-api/api/filtering/) for instructions on structuring search queries. - -```python -all_cluster_data = client.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. - -```python -cluster_pk_one = client.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. - -```python -updated_record_data = client.update_cluster( - pk=1, - data={'description': "Updated description"} -) -``` - -### Deleting Records - -Delete methods are used to removed records from the server. - -```python -client.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. - -```python -client.delete_cluster(pk=1, raise_not_exists=True) -``` diff --git a/mkdocs.yml b/mkdocs.yml index 28875ba..eee1068 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1 @@ site_name: Keystone Python Client -nav: - - index.md - - user_guide.md - - Client Reference: client_reference.md \ No newline at end of file From 38c949d22115a8b863d48f4575ec22ab7d1a89b3 Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Sat, 9 Nov 2024 22:37:04 -0500 Subject: [PATCH 2/2] Formatting pass --- docs/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/index.md b/docs/index.md index 2213913..ba1174d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ The Python client is hosted on PyPI and can be installed in the standard fashion pip install keystone-api-client ``` -## User Guide +## Instantiating a Client The `KeystoneClient` class is used to encapsulate user authentication and API requests. New instances are created by specifying the API URL. @@ -25,7 +25,7 @@ In the following example, a client instance is defined for a locally running ser ```python from keystone_client import KeystoneClient -client = KeystoneClient(url="http://localhost:8000") # (1)! +client = KeystoneClient(url="http://localhost:8000") # (1)! ``` 1. Specifying a network protocol is required when instantiating new instances (e.g., `http://` or `https://`). @@ -35,18 +35,18 @@ Once authenticated, the client will automatically manage the resulting user cred tokens. ```python -client.login(username="username", password="password") # (1)! -assert client.is_authenticated # (2)! -client.logout() # (3)! +client.login(username="username", password="password") # (1)! +assert client.is_authenticated # (2)! +client.logout() # (3)! ``` 1. Authenticate a new user session. 2. Check the authentication status at any time. -3. End the authenticated session and blacklist current credentials. +3. End the authenticated session and invalidate current credentials. ## Generic HTTP Requests -The client provides dedicated methods for each HTTP request type supported by the API. +The client class provides dedicated methods for each HTTP request type supported by the API. When authenticated, the client will automatically include the appropriate authentication headers when submitting requests.