# Easy to use python client for the Clio Manage API
This API client is designed to interact with the Clio API, providing robust handling for HTTP request methods, query parameters, payload validation, and dynamic endpoint management.
### Installation
```bash
pip install clio-manage-api-client
```
### Initialization
```python
import clio-manage-api-client as Clio
client = Clio.Manage(access_token="your_access_token") # 'store_responses=True' for sqlite response handler
```
## Key Features
1. **Dynamic Endpoint Management**:
- Dynamically initializes and manages endpoints using metadata from the `models.endpoints` module.
- Supports operations like `index`, `show`, `post`, `patch`, `delete` as well as sub-methods for relational endpoints (Explained Below)
- Endpoints that return content can use the `download` method. Output path can be provided in the call or set within the client
2. **Integrated Query Parameter and Payload Handling**:
- Automatically validates, converts, and processes query parameters and payload data.
- Ensures type safety and required field validation for all inputs.
- Query parameters are processed first and removed from `kwargs`. Remaining `kwargs` are processed for payload data.
3. **Pagination Support**:
- Handles paginated responses seamlessly when using the `all` method.
- Automatically appends results from all pages.
4. **Reserved Keywords and Parameter Mappings**:
- Handles reserved keywords and endpoint-specific parameters via a `mappings` dictionary.
- Reserved keywords such as `from` and `X-API-VERSION` are mapped to their correct representations (e.g., `from_` to `from`).
- Parameters like `matter_id` and `id` are interchangeable, ensuring ease of use for endpoints that deviate from the general schema.
5. **Dynamic Endpoint Resolution**:
- Determines whether to call the `index` or `show` endpoint based on the presence of `id` in `kwargs`.
- For example:
- `client.get.matters(id=123)` calls the `show` endpoint.
- `client.get.matters(limit=10)` calls the `index` endpoint.
6. **Rate Limiting**:
- Enforces rate limits using the `RateMonitor` class to ensure compliance with API restrictions.
7. **Error Reporting**:
- Provides detailed validation error messages when inputs do not meet the expected types or requirements.
---
# Examples
- **Models are now generated when the client is first ran directly from the latest API documentation**
- **The Openapi spec file that is used to generate the dataclasses is now stored in the models/ subdirectory**
- **Get the latest changes made to the API by using the update.py script. Existing model classes will be backed up**
### Single Request Example
```python
response = client.get.matters() # Default limit is 200
print(json.dumps(response, indent=2))
```
### Relational Endpoint Example
```python
related_contacts = client.get.matters.related_contacts(id=12345, fields="id,name")
print(json.dumps(related_contacts, indent=2))
```
### Fetch All Paginated Results
```python
response_all = client.all.matters(fields="id,name")
print(f"Total items retrieved: {len(response_all['data'])}")
print(json.dumps(response_all, indent=2))
```
### Request With Generated Fields
**Using all**
```python
# Returns data from all available non nested fields
response = client.get.matters(fields="all", limit=10)
print(json.dumps(response, indent=2))
# With nested fields
response = client.get.matters(fields="all,client{all}", limit=10)
print(json.dumps(response, indent=2))
# Returns the id and etag of every nested resource within the endpoint
response = client.get.matters(fields="all_ids", limit=10)
print(json.dumps(response, indent=2))
```
### Datetime and Timedeltas
```python
# Absolute dates
one_year_ago = date.today() - timedelta(days=365)
response = client.all.matters(limit=200, open_date__= f'>={one_year_ago}', order="open_date(asc)", fields="all,client{name},practice_area{name,category},responsible_attorney{name}")
print(json.dumps(response, indent=2))
# Helper functions: end_of_the_month()
entries = client.all.calendar_entries(fields="start_at,end_at,all_day,location,description,summary,attendees{name}", from_=datetime.now(), to=end_of_the_month())
print(json.dumps(response, indent=2))
```
### Exporting
**To Excel Spreadsheet:**
**Requires pandas < 2.0 and openpyxl**
```python
save_to_xlsx(client.all.contacts(fields="all,custom_field_values{field_name,value}"), "contacts.xlsx")
```
---
## Logical Argument and Type Conversion
**Example Endpoint**:
- **`https://app.clio.com/api/v4/matters/{matter_id}/client.json`**
- **`https://app.clio.com/api/v4/matters/{id}.json`**
Both `matter_id` and `id` can be used interchangeably. The client automatically maps `matter_id` to `id` for consistency.
## Example Usage
```python
# Calls the 'show' endpoint for a specific matter
response = client.get.matters(id=123)
# Calls the 'client' relation endpoint for a specific matter
response = client.get.matters.client(matter_id=123)
# Calls the 'client' relation endpoint for a specific matter
response = client.get.matters.client(id=123)
```
## Arrays(Needs more testing):
- **Can be provided using by including a double underscore**
- **Any text after the underscores get converted into a query parameter keyword**
- **`ids__ = [123,456,789]` gets converted to `ids[]=123&ids[]=456&ids[]=789`**
- **`jurisdiction__id = 123` gets converted to `jurisdiction[id]=123`**
---
## Reserved Keywords and Mapping
The client automatically handles reserved keywords and non-standard endpoint parameters through a predefined `mappings` dictionary. This ensures compatibility and ease of use for all endpoints.
### Example Mappings
```python
mappings = {
"X_API_VERSION": "X-API-VERSION",
"from_": "from",
"ids__": "ids",
"jurisdiction__id": "jurisdiction[id]",
"service_type__id": "service_type[id]",
"trigger__id": "trigger[id]",
}
```
## Internal Design
### Endpoint Resolution
- The `show` endpoint is prioritized if `id` is present in the `kwargs`.
- The `index` endpoint is called if `id` is not provided.
### `_request_handler`
Handles requests, including:
- Pagination support.
- Query parameter and payload validation.
- Dynamic path formatting with provided arguments.
---
## Known Issues
- On some endpoints, DELETE throws an HTTPEXCEPTION but the command completes successfully in Clio. This can be circumvented by using a try/except block inside the running loop
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/unigrated-solutions/clio-api-python-client",
"name": "clio-manage-api-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "clio python client, clio api client, clio manage api, legal, client, sdk, integration, unigration",
"author": "Unigrated Partners",
"author_email": "dev@unigratedpartners.com",
"download_url": "https://files.pythonhosted.org/packages/f7/c0/515f9abd5b37084e33e9f9e5ad55186e85a6b19f887fe008e8081cf0de1b/clio_manage_api_client-0.1.3.tar.gz",
"platform": null,
"description": "# Easy to use python client for the Clio Manage API \n\nThis API client is designed to interact with the Clio API, providing robust handling for HTTP request methods, query parameters, payload validation, and dynamic endpoint management.\n\n### Installation\n\n```bash\npip install clio-manage-api-client\n```\n\n### Initialization\n```python\nimport clio-manage-api-client as Clio\n\nclient = Clio.Manage(access_token=\"your_access_token\") # 'store_responses=True' for sqlite response handler\n```\n## Key Features\n\n1. **Dynamic Endpoint Management**:\n - Dynamically initializes and manages endpoints using metadata from the `models.endpoints` module.\n - Supports operations like `index`, `show`, `post`, `patch`, `delete` as well as sub-methods for relational endpoints (Explained Below)\n - Endpoints that return content can use the `download` method. Output path can be provided in the call or set within the client\n\n2. **Integrated Query Parameter and Payload Handling**:\n - Automatically validates, converts, and processes query parameters and payload data.\n - Ensures type safety and required field validation for all inputs.\n - Query parameters are processed first and removed from `kwargs`. Remaining `kwargs` are processed for payload data.\n\n3. **Pagination Support**:\n - Handles paginated responses seamlessly when using the `all` method.\n - Automatically appends results from all pages.\n\n4. **Reserved Keywords and Parameter Mappings**:\n - Handles reserved keywords and endpoint-specific parameters via a `mappings` dictionary.\n - Reserved keywords such as `from` and `X-API-VERSION` are mapped to their correct representations (e.g., `from_` to `from`).\n - Parameters like `matter_id` and `id` are interchangeable, ensuring ease of use for endpoints that deviate from the general schema.\n\n5. **Dynamic Endpoint Resolution**:\n - Determines whether to call the `index` or `show` endpoint based on the presence of `id` in `kwargs`.\n - For example:\n - `client.get.matters(id=123)` calls the `show` endpoint.\n - `client.get.matters(limit=10)` calls the `index` endpoint.\n\n6. **Rate Limiting**:\n - Enforces rate limits using the `RateMonitor` class to ensure compliance with API restrictions.\n\n7. **Error Reporting**:\n - Provides detailed validation error messages when inputs do not meet the expected types or requirements.\n\n---\n# Examples\n- **Models are now generated when the client is first ran directly from the latest API documentation**\n- **The Openapi spec file that is used to generate the dataclasses is now stored in the models/ subdirectory**\n- **Get the latest changes made to the API by using the update.py script. Existing model classes will be backed up**\n\n### Single Request Example\n\n```python\nresponse = client.get.matters() # Default limit is 200\nprint(json.dumps(response, indent=2))\n```\n\n### Relational Endpoint Example\n\n```python\nrelated_contacts = client.get.matters.related_contacts(id=12345, fields=\"id,name\")\nprint(json.dumps(related_contacts, indent=2))\n```\n\n### Fetch All Paginated Results\n\n```python\nresponse_all = client.all.matters(fields=\"id,name\")\nprint(f\"Total items retrieved: {len(response_all['data'])}\")\nprint(json.dumps(response_all, indent=2))\n```\n\n### Request With Generated Fields\n\n**Using all**\n```python\n# Returns data from all available non nested fields\nresponse = client.get.matters(fields=\"all\", limit=10)\nprint(json.dumps(response, indent=2))\n\n# With nested fields\nresponse = client.get.matters(fields=\"all,client{all}\", limit=10)\nprint(json.dumps(response, indent=2))\n\n# Returns the id and etag of every nested resource within the endpoint\nresponse = client.get.matters(fields=\"all_ids\", limit=10)\nprint(json.dumps(response, indent=2))\n\n```\n\n### Datetime and Timedeltas\n\n```python\n# Absolute dates\none_year_ago = date.today() - timedelta(days=365)\nresponse = client.all.matters(limit=200, open_date__= f'>={one_year_ago}', order=\"open_date(asc)\", fields=\"all,client{name},practice_area{name,category},responsible_attorney{name}\")\nprint(json.dumps(response, indent=2))\n\n# Helper functions: end_of_the_month()\nentries = client.all.calendar_entries(fields=\"start_at,end_at,all_day,location,description,summary,attendees{name}\", from_=datetime.now(), to=end_of_the_month())\nprint(json.dumps(response, indent=2))\n```\n\n### Exporting\n\n**To Excel Spreadsheet:**\n\n**Requires pandas < 2.0 and openpyxl**\n```python\nsave_to_xlsx(client.all.contacts(fields=\"all,custom_field_values{field_name,value}\"), \"contacts.xlsx\")\n```\n---\n\n## Logical Argument and Type Conversion\n\n**Example Endpoint**:\n- **`https://app.clio.com/api/v4/matters/{matter_id}/client.json`**\n- **`https://app.clio.com/api/v4/matters/{id}.json`**\n\nBoth `matter_id` and `id` can be used interchangeably. The client automatically maps `matter_id` to `id` for consistency.\n\n## Example Usage\n\n```python\n# Calls the 'show' endpoint for a specific matter\nresponse = client.get.matters(id=123)\n\n# Calls the 'client' relation endpoint for a specific matter\nresponse = client.get.matters.client(matter_id=123)\n\n# Calls the 'client' relation endpoint for a specific matter\nresponse = client.get.matters.client(id=123)\n```\n\n## Arrays(Needs more testing):\n- **Can be provided using by including a double underscore**\n- **Any text after the underscores get converted into a query parameter keyword**\n - **`ids__ = [123,456,789]` gets converted to `ids[]=123&ids[]=456&ids[]=789`**\n - **`jurisdiction__id = 123` gets converted to `jurisdiction[id]=123`**\n\n---\n\n\n## Reserved Keywords and Mapping\n\nThe client automatically handles reserved keywords and non-standard endpoint parameters through a predefined `mappings` dictionary. This ensures compatibility and ease of use for all endpoints.\n\n### Example Mappings\n\n```python\nmappings = {\n \"X_API_VERSION\": \"X-API-VERSION\",\n \"from_\": \"from\", \n \"ids__\": \"ids\",\n \"jurisdiction__id\": \"jurisdiction[id]\",\n \"service_type__id\": \"service_type[id]\",\n \"trigger__id\": \"trigger[id]\",\n}\n```\n\n## Internal Design\n\n### Endpoint Resolution\n\n- The `show` endpoint is prioritized if `id` is present in the `kwargs`.\n- The `index` endpoint is called if `id` is not provided.\n\n### `_request_handler`\n\nHandles requests, including:\n- Pagination support.\n- Query parameter and payload validation.\n- Dynamic path formatting with provided arguments.\n\n---\n\n## Known Issues\n\n- On some endpoints, DELETE throws an HTTPEXCEPTION but the command completes successfully in Clio. This can be circumvented by using a try/except block inside the running loop\n \n## License\n\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Python Client for the Clio Manage API.",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/unigrated-solutions/clio-api-python-client/issues",
"Homepage": "https://github.com/unigrated-solutions/clio-api-python-client"
},
"split_keywords": [
"clio python client",
" clio api client",
" clio manage api",
" legal",
" client",
" sdk",
" integration",
" unigration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a33cac0c46de8cd64c82b2f62c13fbbc99a35f29b6ddc505f5820bec4150e8ab",
"md5": "65af6c7fae034c6d6de5ce4770a971c2",
"sha256": "58e6fe3f1321924f5b8ff52627b4f3cd56bbf60b53bbdc71b8f04d1678921c18"
},
"downloads": -1,
"filename": "clio_manage_api_client-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65af6c7fae034c6d6de5ce4770a971c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 74769,
"upload_time": "2025-08-14T05:02:00",
"upload_time_iso_8601": "2025-08-14T05:02:00.178882Z",
"url": "https://files.pythonhosted.org/packages/a3/3c/ac0c46de8cd64c82b2f62c13fbbc99a35f29b6ddc505f5820bec4150e8ab/clio_manage_api_client-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f7c0515f9abd5b37084e33e9f9e5ad55186e85a6b19f887fe008e8081cf0de1b",
"md5": "d7c56a9772631584c14086b586218cad",
"sha256": "321de4673e2157fbd2c4a9bcd5e01c6b6c9683b94a37297c030cfb5d126d4b8b"
},
"downloads": -1,
"filename": "clio_manage_api_client-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "d7c56a9772631584c14086b586218cad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 71841,
"upload_time": "2025-08-14T05:02:01",
"upload_time_iso_8601": "2025-08-14T05:02:01.370228Z",
"url": "https://files.pythonhosted.org/packages/f7/c0/515f9abd5b37084e33e9f9e5ad55186e85a6b19f887fe008e8081cf0de1b/clio_manage_api_client-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 05:02:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "unigrated-solutions",
"github_project": "clio-api-python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "certifi",
"specs": []
},
{
"name": "charset-normalizer",
"specs": []
},
{
"name": "et_xmlfile",
"specs": []
},
{
"name": "idna",
"specs": []
},
{
"name": "mypy-extensions",
"specs": []
},
{
"name": "numpy",
"specs": [
[
"<",
"2.0"
]
]
},
{
"name": "openpyxl",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "pytz",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "six",
"specs": []
},
{
"name": "typing-inspect",
"specs": []
},
{
"name": "typing_extensions",
"specs": []
},
{
"name": "tzdata",
"specs": []
},
{
"name": "urllib3",
"specs": []
},
{
"name": "aiohttp",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "clio-api-model-generator",
"specs": [
[
"==",
"0.2.1"
]
]
}
],
"lcname": "clio-manage-api-client"
}
JSON
