Metadata-Version: 2.4
Name: pipedrive-api
Version: 0.11.0
Summary: A lightweight Python SDK for the Pipedrive API, built with `httpx`.
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1

# Pipedrive API

A lightweight Python SDK for the Pipedrive API, built with `httpx`.

## Installation

```bash
pip install pipedrive-api
```

## Usage

```python
from pipedrive import Pipedrive

pipedrive = Pipedrive(domain="yourcompany", api_token="your-api-token")

# Deals
pipedrive.deals.list()
pipedrive.deals.get(123)
```

Or use as a context manager:

```python
with Pipedrive(domain="yourcompany", api_token="your-api-token") as pipedrive:
    deals = pipedrive.deals.list()
```

## Authentication

Authenticate using your Pipedrive API token. You can find it in Pipedrive under Settings → Personal preferences → API.

It is recommended to load credentials from environment variables rather than hardcoding them:

```python
import os

pipedrive = Pipedrive(
    domain=os.environ["PIPEDRIVE_DOMAIN"],
    api_token=os.environ["PIPEDRIVE_API_TOKEN"],
)
```

## Pagination

`.list()` returns a single page of results. Use `.stream()` to automatically paginate through all results, yielding one item at a time:

```python
for deal in pipedrive.deals.stream():
    print(deal["id"])
```

This works on all endpoints that support listing:

```python
for org in pipedrive.organizations.stream():
    ...

for person in pipedrive.persons.stream():
    ...
```

You can pass the same filtering parameters as `.list()`:

```python
for deal in pipedrive.deals.stream(status="open", limit=50):
    print(deal["title"])
```

To collect all results into a list:

```python
all_deals = list(pipedrive.deals.stream())
```

## Error Handling

All non-2xx responses raise a `PipedriveError` with a `status_code` attribute:

```python
from pipedrive import Pipedrive, PipedriveError

try:
    pipedrive.deals.get(999)
except PipedriveError as e:
    print(e.status_code)  # e.g. 404
```

## Version History

Complete version history available in the [CHANGELOG.md](CHANGELOG.md)

## Docs
Full API documentation can be found on [GitHub Pages](https://sturdy-funicular-1qjy2ql.pages.github.io/)
