Metadata-Version: 2.4
Name: zamzar
Version: 2.0.1
Summary: Official Python client for the Zamzar API
Home-page: https://github.com/zamzar/zamzar-python
Author: Zamzar
Author-email: api-sdks@zamzar.com
License: MIT
Keywords: Zamzar,Zamzar API,File Conversion,File Utilities,Convert
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3>=2.7.0
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: pydantic>=2.5.3
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Python file converter library for Zamzar

[![@zamzar on Twitter](https://img.shields.io/badge/twitter-zamzar-blue)](https://twitter.com/zamzar)
[![pypi version](https://img.shields.io/pypi/v/zamzar.svg)](https://pypi.python.org/pypi/zamzar)
[![GitHub License](https://img.shields.io/github/license/zamzar/zamzar-python)](https://github.com/zamzar/zamzar-python/blob/main/LICENSE)

Easy to use Python file conversion API with support for 2.0.1+ file conversions - convert documents, audio, images,
video, eBooks and more. Use `zamzar-python` to convert files between different formats as part of your Python
application with the [Zamzar file conversion API](https://developers.zamzar.com). Common use cases include:

- Convert Microsoft Word (DOCX, DOC) to PDF
- Convert Powerpoint (PPT, PPTX) to JPG
- Extract text from PDF files
- Archive email (MSG files) to PDF

This is the official Python SDK for the [Zamzar API](https://developers.zamzar.com).

Jump to:

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Resources](#resources)

## Requirements

- Before you begin, signup for a Zamzar API Account or retrieve your existing API Key from
  the [Zamzar Developers Homepage](https://developers.zamzar.com/user)
- Python 3.11 and later. (See [Compatibility](#compatibility) for more information).

## Installation

You can install the Zamzar Python SDK using pip:

```bash
pip install --upgrade zamzar
```

## Usage

### Getting Started

Please follow the [installation](#installation) instructions and execute the following Python code:

```python
from zamzar import ZamzarClient

zamzar = ZamzarClient("YOUR_API_KEY_GOES_HERE")

zamzar.convert("/tmp/example.docx", "pdf").store("/tmp/").delete_all_files()
```

See the [examples](https://github.com/zamzar/zamzar-python/tree/main/examples) to learn more
about how to use the Zamzar Python SDK.

### Using the sandbox environment

Whilst developing your application, you can use the lZamzar sandbox environment to test your code without consuming
production credits:

```python
from zamzar import ZamzarClient, Environment

zamzar = ZamzarClient("YOUR_API_KEY_GOES_HERE", environment=Environment.SANDBOX)
```

The Zamzar Python SDK uses the production environment by default, but you can also specify it explicitly:

```python
from zamzar import ZamzarClient, Environment

zamzar = ZamzarClient("YOUR_API_KEY_GOES_HERE", environment=Environment.PRODUCTION)
```

### Logging

By default, the Zamzar Python SDK does not log HTTP requests and responses. To enable logging, configure a
[logging.Logger](https://docs.python.org/3/library/logging.html#logging.Logger) for `urllib3`:

```python
import logging

from zamzar import ZamzarClient

# Configure logging as needed. Here we configure a simple console logger
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG)  # Set the logging level for the console handler
console_formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
console_handler.setFormatter(console_formatter)
root_logger = logging.getLogger()
root_logger.addHandler(console_handler)
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

# Enable logging for urllib3 to see HTTP requests
urllib3_logger = logging.getLogger('urllib3')
urllib3_logger.setLevel(logging.DEBUG)

# Make a request to the Zamzar API
zamzar = ZamzarClient("YOUR_API_KEY_GOES_HERE")
zamzar.account.get()
```

### Configuring timeouts and retries

The Zamzar Python SDK will automatically:

* time out long-running requests
* retry requests that fail or time out

The default settings are defined
in [ZamzarClient](https://github.com/zamzar/zamzar-python/blob/main/zamzar/facade/zamzar_client.py).

To override these defaults, configure your
own [urllib3.Retry](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html#urllib3.util.Retry) and pass it
to the `ZamzarClient` constructor:

```python
import urllib3

from zamzar import ZamzarClient

# Configure a custom retry policy
custom_policy = urllib3.Retry(
    total=5,  # Maximum number of retries
    backoff_factor=1,  # Exponential backoff factor
    backoff_max=60,  # Maximum backoff time
    status_forcelist=[429, 502, 503, 504],  # HTTP status codes to retry
    allowed_methods=None  # retry all request methods
)

# Make a request to the Zamzar API
zamzar = ZamzarClient("YOUR_API_KEY_GOES_HERE", retries=custom_policy)
```

## Resources

[Code Samples](https://github.com/zamzar/zamzar-python/tree/main/examples) - Copy/Paste from
examples which demonstrate all key areas of functionality.

[Developer Docs](https://developers.zamzar.com/docs) - For more information about API operations, parameters, and
responses. Use this if you need additional context on all areas of functionality.

## Compatibility

This SDK requires Python 3.11 or later. Earlier SDK versions support older Python versions (see below), but those SDK
releases are no longer maintained. We encourage you to upgrade to a supported Python and SDK version wherever possible.

| Zamzar Python Version | Compatible Python Versions |
|-----------------------|----------------------------|
| 1.x                   | 3.7 to 3.14                |
| 2.x                   | 3.11 or later              |
