From 436f82dc8243cab6f7b48d58e03de766e36050c2 Mon Sep 17 00:00:00 2001 From: David Nguyen Date: Tue, 21 Jan 2025 16:35:35 +1100 Subject: [PATCH] chore: update readme --- README.md | 205 +++++++++--------------------------------------------- 1 file changed, 32 insertions(+), 173 deletions(-) diff --git a/README.md b/README.md index bd991b9..37cbea0 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,45 @@ -# documenso_sdk +Documenso Logo -Developer-friendly & type-safe Python SDK specifically catered to leverage *documenso_sdk* API. +  -
+
+## Documenso Python SDK -

-> [!IMPORTANT] -> This SDK is not yet ready for production use. To complete setup please follow the steps outlined in your [workspace](https://app.speakeasy.com/org/documenso-inc/api). Delete this section before > publishing to a package manager. +A SDK for seamless integration with Documenso v2 API. - -## Summary +The full Documenso API can be viewed here (**todo**), which includes examples. -Documenso v2 beta API: Subject to breaking changes until v2 is fully released. - +## ⚠️ Warning + +Documenso v2 API and SDKs are currently in beta. There may be to breaking changes. + +To keep updated, please follow the discussions and issues here: +- Discussion -> Todo +- Breaking change alerts -> Todo + - ## Table of Contents -* [documenso_sdk](#documensosdk) +* [Overview](#documenso-python-sdk) * [SDK Installation](#sdk-installation) * [IDE Support](#ide-support) - * [SDK Example Usage](#sdk-example-usage) * [Authentication](#authentication) + * [Document creation example](#document-creation-example) * [Available Resources and Operations](#available-resources-and-operations) * [Retries](#retries) * [Error Handling](#error-handling) - * [Server Selection](#server-selection) - * [Custom HTTP Client](#custom-http-client) * [Debugging](#debugging) * [Development](#development) * [Maturity](#maturity) * [Contributions](#contributions) - + ## SDK Installation @@ -76,13 +77,12 @@ Generally, the SDK will work well with most IDEs out of the box. However, when u - [PyCharm Pydantic Plugin](https://docs.pydantic.dev/latest/integrations/pycharm/) - -## SDK Example Usage +## Authentication -### Example +To use the SDK, you will need a Documenso API key which can be created [here](https://docs.documenso.com/developers/public-api/authentication#creating-an-api-key +). ```python -# Synchronous Example import documenso_sdk from documenso_sdk import Documenso import os @@ -90,65 +90,26 @@ import os with Documenso( api_key=os.getenv("DOCUMENSO_API_KEY", ""), ) as documenso: - - res = documenso.documents.find(order_by_direction=documenso_sdk.OrderByDirection.DESC) - - # Handle response - print(res) ``` + -
+## Document creation example -The same SDK client can also be used to make asychronous requests by importing asyncio. -```python -# Asynchronous Example -import asyncio -import documenso_sdk -from documenso_sdk import Documenso -import os +Currently creating a document involves two steps: -async def main(): - async with Documenso( - api_key=os.getenv("DOCUMENSO_API_KEY", ""), - ) as documenso: +1. Create the document +2. Upload the PDF - res = await documenso.documents.find_async(order_by_direction=documenso_sdk.OrderByDirection.DESC) +This is a temporary measure, in the near future prior to the full release we will merge these two tasks into one request. - # Handle response - print(res) +Here is a full example of the document creation process which you can copy and run. -asyncio.run(main()) -``` - +Note that the function is temporarily called `createV0`, which will be replaced by `create` once we resolve the 2 step workaround. - -## Authentication - -### Per-Client Security Schemes - -This SDK supports the following security scheme globally: - -| Name | Type | Scheme | Environment Variable | -| --------- | ------ | ------- | -------------------- | -| `api_key` | apiKey | API key | `DOCUMENSO_API_KEY` | - -To authenticate with the API the `api_key` parameter must be set when initializing the SDK client instance. For example: ```python -import documenso_sdk -from documenso_sdk import Documenso -import os - -with Documenso( - api_key=os.getenv("DOCUMENSO_API_KEY", ""), -) as documenso: - - res = documenso.documents.find(order_by_direction=documenso_sdk.OrderByDirection.DESC) - - # Handle response - print(res) - +# Todo ``` - + ## Available Resources and Operations @@ -324,110 +285,8 @@ with Documenso( ``` - -## Server Selection - -### Override Server URL Per-Client - -The default server can also be overridden globally by passing a URL to the `server_url: str` optional parameter when initializing the SDK client instance. For example: -```python -import documenso_sdk -from documenso_sdk import Documenso -import os - -with Documenso( - server_url="https://app.documenso.com/api/v2-beta", - api_key=os.getenv("DOCUMENSO_API_KEY", ""), -) as documenso: - - res = documenso.documents.find(order_by_direction=documenso_sdk.OrderByDirection.DESC) - - # Handle response - print(res) - -``` - - - -## Custom HTTP Client - -The Python SDK makes API calls using the [httpx](https://www.python-httpx.org/) HTTP library. In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with your own HTTP client instance. -Depending on whether you are using the sync or async version of the SDK, you can pass an instance of `HttpClient` or `AsyncHttpClient` respectively, which are Protocol's ensuring that the client has the necessary methods to make API calls. -This allows you to wrap the client with your own custom logic, such as adding custom headers, logging, or error handling, or you can just pass an instance of `httpx.Client` or `httpx.AsyncClient` directly. - -For example, you could specify a header for every request that this sdk makes as follows: -```python -from documenso_sdk import Documenso -import httpx - -http_client = httpx.Client(headers={"x-custom-header": "someValue"}) -s = Documenso(client=http_client) -``` - -or you could wrap the client with your own custom logic: -```python -from documenso_sdk import Documenso -from documenso_sdk.httpclient import AsyncHttpClient -import httpx - -class CustomClient(AsyncHttpClient): - client: AsyncHttpClient - - def __init__(self, client: AsyncHttpClient): - self.client = client - - async def send( - self, - request: httpx.Request, - *, - stream: bool = False, - auth: Union[ - httpx._types.AuthTypes, httpx._client.UseClientDefault, None - ] = httpx.USE_CLIENT_DEFAULT, - follow_redirects: Union[ - bool, httpx._client.UseClientDefault - ] = httpx.USE_CLIENT_DEFAULT, - ) -> httpx.Response: - request.headers["Client-Level-Header"] = "added by client" - - return await self.client.send( - request, stream=stream, auth=auth, follow_redirects=follow_redirects - ) - - def build_request( - self, - method: str, - url: httpx._types.URLTypes, - *, - content: Optional[httpx._types.RequestContent] = None, - data: Optional[httpx._types.RequestData] = None, - files: Optional[httpx._types.RequestFiles] = None, - json: Optional[Any] = None, - params: Optional[httpx._types.QueryParamTypes] = None, - headers: Optional[httpx._types.HeaderTypes] = None, - cookies: Optional[httpx._types.CookieTypes] = None, - timeout: Union[ - httpx._types.TimeoutTypes, httpx._client.UseClientDefault - ] = httpx.USE_CLIENT_DEFAULT, - extensions: Optional[httpx._types.RequestExtensions] = None, - ) -> httpx.Request: - return self.client.build_request( - method, - url, - content=content, - data=data, - files=files, - json=json, - params=params, - headers=headers, - cookies=cookies, - timeout=timeout, - extensions=extensions, - ) - -s = Documenso(async_client=CustomClient(httpx.AsyncClient())) -``` - + + ## Debugging