Metadata-Version: 2.4
Name: db-apimatic-sdk
Version: 0.0.1
Summary: Sample SDKs for DB by APIMatic
License-Expression: MIT
License-File: LICENSE
Keywords: sdk,api-client,openapi,rest,http,apimatic
Author: Muhammad Rafay
Author-email: muhammad.rafay@apimatic.io
Maintainer: APIMatic
Maintainer-email: support@apimatic.io
Requires-Python: >=3.10
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: certifi (>=2024.7.4)
Requires-Dist: httpx2 (>=2.13.1,<3.0.0)
Requires-Dist: pydantic[email] (>=2.11.0,<3.0.0)
Requires-Dist: typing-extensions (>=4.13.0,<5.0.0)
Project-URL: Documentation, https://developers.hellosign.com/
Description-Content-Type: text/markdown

# Dropbox Sign API SDK

[![Built with APIMatic][apimatic-badge]][apimatic-url] [![License: MIT][license-badge]][license-url] [![Python 3.10+][python-badge]][python-url]

The Dropbox Sign API SDK for Python provides access to the [Dropbox Sign API REST APIs](https://app.hellosign.com/api/reference) from Python applications.

> [!TIP]
> **Looking for a specific signature, model, enum, or error type?** This SDK ships a generated
> **[SDK map](sdk-map.md)** -- a lookup index of the SDK's entire Python surface. Consult it before
> scanning the source tree; details under [SDK map](#sdk-map).

Dropbox Sign v3 API

---

## Installation

To install the Python SDK from PyPI, with whichever package manager your project uses:

```bash
pip install db-apimatic-sdk
```

```bash
uv add db-apimatic-sdk
```

```bash
poetry add db-apimatic-sdk
```

To install from the SDK source instead, give the tool a path containing a slash — a bare folder name is looked up on PyPI, and resolves to whatever project holds that name there:

```bash
pip install <path-to-sdk>
```

---

## Quick Start

### Synchronous client

Construct `DropboxSignApiClient` with keyword arguments, and call `close()` when you are done. Every argument is optional; the full list is in the [SDK map](sdk-map.md).

```python
from dropbox_sign_api import DropboxSignApiClient
from dropbox_sign_api.core import BasicAuthCredentials

client = DropboxSignApiClient(
    api_key=BasicAuthCredentials(username="YOUR_USERNAME", password="YOUR_PASSWORD"),
    oauth2="YOUR_BEARER_TOKEN",
    environment="production",
)

# TODO: call endpoints here -- see api-reference.md

client.close()
```

Alternatively, scope it -- `with DropboxSignApiClient(...) as client:` closes the pool on exit; see [Best Practices](#best-practices).

`Client` is exported as an alias of `DropboxSignApiClient`, so `from dropbox_sign_api import Client` also works.

The SDK accepts every model-typed input in two interchangeable spellings, both type-checked: the typed model, or a plain dict with the same keys -- the `OrDict` and `Model | ModelDict` unions in the [SDK map](sdk-map.md). Pick whichever suits the call site: the dict form needs no import, while the model form adds a keyword-checked constructor and editor completion.

### Asynchronous client

`AsyncDropboxSignApiClient` mirrors `DropboxSignApiClient` with **identical method names**, and every endpoint method is a coroutine. It takes the same arguments, with some differences -- for example, the transport argument is `custom_async_http_client`.

```python
from asyncio import run

from dropbox_sign_api import AsyncDropboxSignApiClient
from dropbox_sign_api.core import BasicAuthCredentials


async def main() -> None:
    client = AsyncDropboxSignApiClient(
        api_key=BasicAuthCredentials(username="YOUR_USERNAME", password="YOUR_PASSWORD"),
        oauth2="YOUR_BEARER_TOKEN",
        environment="production",
    )
    # TODO: call endpoints here, awaiting each -- see api-reference.md
    await client.aclose()


run(main())
```

Alternatively, scope it -- `async with AsyncDropboxSignApiClient(...) as client:` closes the pool on exit. Only the async spelling is `aclose`, matching httpx2; see [Best Practices](#best-practices).

`AsyncClient` is the exported alias. Each client accepts **only** its own transport argument; passing the other's is a `TypeError` at runtime and an error under mypy.

---

## Usage

Two generated references cover the SDK; each answers a different question:

| Reference | For |
| --- | --- |
| **[API Reference](api-reference.md)** | Usage guidance for a single **parsed** operation: `client.<group>.<operation>(...)` returns the typed payload and raises `ApiError` on any non-2xx, with `.error` the typed error body, or `RawError` for a status the operation does not document. |
| **[Raw API Reference](raw-api-reference.md)** | The same for the **raw** variant: `client.<group>.with_raw_response.<operation>(...)` returns `ApiResult[T, E]` and never raises for an API error. |

Both API references carry every one of the 74 operations, with a sync and an async sample and a parameter table each.

## SDK map

This SDK ships a generated **SDK map** -- [`sdk-map.md`](sdk-map.md) -- a deterministic, lookup-oriented table of contents of the SDK's Python surface, generated by APIMatic alongside this SDK.

Consult the map before scanning or grepping the source: it answers call-level contract questions by lookup, and for anything it does not carry -- model shapes, enum values, an endpoint's route or behavioural prose -- it names the one source file to read. How to read the map itself, including the SDK-wide defaults its rows rely on, is stated at the top of [`sdk-map.md`](sdk-map.md).

## Logging

The SDK logs every HTTP exchange through Python's standard `logging` module, under the `dropbox_sign_api` logger, and configures nothing itself: with no logging set up, nothing is printed unless `DROPBOX_SIGN_API_LOG` is set. Turn it on as for any library:

```python
import logging

logging.basicConfig()  # your application's handler; the root stays at WARNING
logging.getLogger("dropbox_sign_api").setLevel(logging.INFO)  # the SDK's lines; DEBUG adds the dumps that logging_options turns on
```

Or set one environment variable before the process starts, for a run you cannot edit: `DROPBOX_SIGN_API_LOG=info` writes the request and response lines, `DROPBOX_SIGN_API_LOG=debug` adds the request headers, the request body and the response headers. If your application has configured logging, its handlers and format are used; otherwise the SDK writes to stderr.

Choose the detail with `logging_options`, a `LoggingOptions` from `dropbox_sign_api.core`:

```python
from dropbox_sign_api import DropboxSignApiClient
from dropbox_sign_api.core import LoggingOptions

client = DropboxSignApiClient(
    logging_options=LoggingOptions(log_request_headers=True, log_response_headers=True, log_request_body=True)
)
```

A plain dict with the same keys is accepted too, as for every model-typed argument (see [Quick Start](#quick-start)): `logging_options={"log_request_headers": True}`.

| Option | Default | Effect |
| --- | --- | --- |
| `log_request_headers` | `False` | Log the sent headers at DEBUG, masked. |
| `log_response_headers` | `False` | Log the received headers at DEBUG, masked. |
| `log_request_body` | `False` | Log the request body at DEBUG: its text when in memory, a description when streamed. |
| `body_size_limit` | `32768` | Bytes of a logged body kept before it is cut. |
| `redaction_placeholder` | `"REDACTED"` | What a hidden value prints as. |
| `unmask_headers` | none | Header names to show although they are not on the safe list. |
| `mask_headers` | none | Header names to hide although they are on the safe list. |
| `mask_keys` | 11 credential names | Query and form keys whose values are always hidden; naming a set replaces the default. |

A single call can be quietened with `request_options={"log_level": logging.WARNING}`: records below that level are not written for that call. It never turns on a record the client's options leave off. Header, query and form values print `REDACTED` unless known safe; a JSON body is printed as sent, so enable `log_request_body` only where its content may be logged; a response body is never logged. The levels and every field are under **Logging** in the SDK map.

## Best Practices

> [!TIP]
> Use a **single `DropboxSignApiClient` instance** for the lifetime of your application and reuse it across
> all requests. Each instance owns its own connection pool, so an instance per request forfeits
> connection reuse and leaks pools that are never closed.

Match the disposal to the client's lifetime: an application-lifetime client is closed once at shutdown with `close()` / `aclose()`; where the lifetime fits a block, `with DropboxSignApiClient() as client:` / `async with AsyncDropboxSignApiClient() as client:` releases it automatically. Both are idempotent, but a closed client is not reusable: the next call raises. The client closes **whatever transport it holds**, including one you supplied via `custom_http_client` / `custom_async_http_client`; if you intend to reuse your own transport across clients, don't hand its lifetime to a `with` block.

**Retries are on by default**: a failed idempotent request — a retryable status or no response at all — is sent again up to three times before the call gives up. Pass `retry_options=0` to turn it off, for instance in a test that stubs an error response; the policy and its defaults are under **Retries** in the SDK map.

## License

This SDK is distributed under the [MIT License][license-url].

---

## Support

Refer to the [API reference](api-reference.md) for detailed information on available operations with code samples.

For further assistance, please contact support at apisupport@hellosign.com.

---

[license-url]: LICENSE
[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
[apimatic-url]: https://www.apimatic.io
[apimatic-badge]: https://www.apimatic.io/hubfs/Built-with-APIMatic-badge.svg
[python-url]: https://www.python.org/downloads/
[python-badge]: https://img.shields.io/badge/python-3.10%2B-blue.svg

