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..84fa9ce 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,123 @@ The Python client is hosted on PyPI and can be installed in the standard fashion pip install keystone-api-client ``` -## Getting Started +## Instantiating a Client + +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. + +```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 invalidate current credentials. + +## Generic HTTP Requests + +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. + +| 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 5aa816b..0000000 --- a/docs/user_guide.md +++ /dev/null @@ -1,120 +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. - -```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