# py-autotask
A comprehensive Python SDK for the Autotask REST API providing **100% complete API coverage** with 193 entity implementations.
[](https://badge.fury.io/py/py-autotask)
[](https://pypi.org/project/py-autotask/)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/gh/asachs01/py-autotask)
[](docs/API_COVERAGE.md)
[](docs/API_COVERAGE.md)
## Features
- **🎯 Complete Entity Coverage** - Implementation of all major Autotask REST API entities
- **🚀 Easy to Use** - Intuitive API that follows Python best practices
- **🔐 Automatic Authentication** - Handles zone detection and authentication seamlessly
- **📊 Full CRUD Operations** - Create, Read, Update, Delete for all Autotask entities
- **🔍 Flexible Filtering** - Support for multiple filter formats and complex queries
- **📄 Pagination Support** - Automatic handling of paginated API responses
- **⚡ Performance Optimized** - Intelligent retry logic and connection pooling
- **🛡️ Type Safe** - Full type hints for better IDE support and code reliability
- **🧪 Well Tested** - Comprehensive test suite with live API integration tests
- **💼 Production Ready** - Robust error handling and logging
## Quick Start
### Installation
```bash
pip install py-autotask
```
### Basic Usage
```python
from py_autotask import AutotaskClient
# Create client with credentials
client = AutotaskClient.create(
username="user@example.com",
integration_code="YOUR_INTEGRATION_CODE",
secret="YOUR_SECRET"
)
# Get a ticket
ticket = client.tickets.get(12345)
print(f"Ticket: {ticket['title']}")
# Query companies
companies = client.companies.query({
"filter": [{"op": "eq", "field": "isActive", "value": "true"}]
})
# Create a new contact
new_contact = client.contacts.create({
"firstName": "John",
"lastName": "Doe",
"emailAddress": "john.doe@example.com",
"companyID": 12345
})
```
### Environment Variables
You can also configure authentication using environment variables:
```bash
export AUTOTASK_USERNAME="user@example.com"
export AUTOTASK_INTEGRATION_CODE="YOUR_INTEGRATION_CODE"
export AUTOTASK_SECRET="YOUR_SECRET"
```
```python
from py_autotask import AutotaskClient
# Client will automatically use environment variables
client = AutotaskClient.from_env()
```
## Supported Entities
py-autotask supports all major Autotask entities:
- **Tickets** - Service desk tickets and related operations
- **Companies** - Customer and vendor company records
- **Contacts** - Individual contact records
- **Projects** - Project management and tracking
- **Resources** - User and technician records
- **Contracts** - Service contracts and agreements
- **Time Entries** - Time tracking and billing
- **Expenses** - Expense tracking and management
- **Products** - Product catalog and inventory
- **Services** - Service catalog management
### Error Handling
```python
from py_autotask.exceptions import (
AutotaskAuthError,
AutotaskAPIError,
AutotaskRateLimitError
)
try:
ticket = client.tickets.get(12345)
except AutotaskAuthError:
print("Authentication failed - check credentials")
except AutotaskRateLimitError as e:
print(f"Rate limit exceeded, retry after {e.retry_after} seconds")
except AutotaskAPIError as e:
print(f"API error: {e.message}")
```
### Batch Operations
```python
# Bulk create
contacts_data = [
{"firstName": "John", "lastName": "Doe", "companyID": 123},
{"firstName": "Jane", "lastName": "Smith", "companyID": 123}
]
# Create multiple contacts
results = []
for contact_data in contacts_data:
result = client.contacts.create(contact_data)
results.append(result)
```
## Configuration
### Request Configuration
```python
from py_autotask.types import RequestConfig
config = RequestConfig(
timeout=60, # Request timeout in seconds
max_retries=5, # Maximum retry attempts
retry_delay=2.0, # Base retry delay
retry_backoff=2.0 # Exponential backoff multiplier
)
client = AutotaskClient(auth, config)
```
### Logging
```python
import logging
# Enable debug logging
logging.getLogger('py_autotask').setLevel(logging.DEBUG)
# Configure custom logging
logger = logging.getLogger('py_autotask.client')
logger.addHandler(logging.FileHandler('autotask.log'))
```
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/asachs01/py-autotask.git
cd py-autotask
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=py_autotask --cov-report=html
# Run specific test file
pytest tests/test_client.py
# Run integration tests (requires API credentials)
pytest tests/integration/ --integration
```
### Code Quality
```bash
# Format code
black py_autotask tests
# Sort imports
isort py_autotask tests
# Lint code
flake8 py_autotask tests
# Type checking
mypy py_autotask
```
## API Reference
For detailed API documentation, see the inline docstrings and type hints in the source code.
### Core Classes
- **AutotaskClient** - Main client class for API operations
- **AutotaskAuth** - Authentication and zone detection
- **BaseEntity** - Base class for all entity operations
- **EntityManager** - Factory for entity handlers
### Exception Classes
- **AutotaskError** - Base exception class
- **AutotaskAPIError** - HTTP/API related errors
- **AutotaskAuthError** - Authentication failures
- **AutotaskValidationError** - Data validation errors
- **AutotaskRateLimitError** - Rate limiting errors
## Migration Guide
### From autotask-node (Node.js)
py-autotask provides similar functionality to the popular Node.js autotask library:
```javascript
// Node.js (autotask-node)
const autotask = require('autotask-node');
const at = new autotask(username, integration, secret);
at.tickets.get(12345).then(ticket => {
console.log(ticket.title);
});
```
```python
# Python (py-autotask)
from py_autotask import AutotaskClient
client = AutotaskClient.create(username, integration, secret)
ticket = client.tickets.get(12345)
print(ticket['title'])
```
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Reporting Issues
- Use the [GitHub Issues](https://github.com/asachs01/py-autotask/issues) page
- Include Python version, library version, and error details
- Provide minimal reproduction code when possible
### Feature Requests
- Open an issue with the "enhancement" label
- Describe the use case and expected behavior
- Include relevant Autotask API documentation references
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 💬 [GitHub Discussions](https://github.com/asachs01/py-autotask/discussions)
- 🐛 [Issue Tracker](https://github.com/asachs01/py-autotask/issues)
## Acknowledgments
- Autotask API team for excellent documentation
- Contributors to the autotask-node library for inspiration
- Python community for amazing libraries and tools
---
**Disclaimer**: This library is not officially affiliated with Datto/Autotask. It is an independent implementation of the Autotask REST API.
Raw data
{
"_id": null,
"home_page": "https://github.com/asachs01/py-autotask",
"name": "py-autotask",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Aaron Sachs <dev@sachshaus.net>",
"keywords": "autotask, psa, api, rest, integration",
"author": "Aaron Sachs",
"author_email": "Aaron Sachs <dev@sachshaus.net>",
"download_url": "https://files.pythonhosted.org/packages/88/66/da0da8eb8959520c71828770a8b1b0f59e866714bbb0cd7509158179d93f/py_autotask-2.0.0.tar.gz",
"platform": null,
"description": "# py-autotask\n\nA comprehensive Python SDK for the Autotask REST API providing **100% complete API coverage** with 193 entity implementations.\n\n[](https://badge.fury.io/py/py-autotask)\n[](https://pypi.org/project/py-autotask/)\n[](https://opensource.org/licenses/MIT)\n[](https://codecov.io/gh/asachs01/py-autotask)\n[](docs/API_COVERAGE.md)\n[](docs/API_COVERAGE.md)\n\n## Features\n\n- **\ud83c\udfaf Complete Entity Coverage** - Implementation of all major Autotask REST API entities\n- **\ud83d\ude80 Easy to Use** - Intuitive API that follows Python best practices\n- **\ud83d\udd10 Automatic Authentication** - Handles zone detection and authentication seamlessly \n- **\ud83d\udcca Full CRUD Operations** - Create, Read, Update, Delete for all Autotask entities\n- **\ud83d\udd0d Flexible Filtering** - Support for multiple filter formats and complex queries\n- **\ud83d\udcc4 Pagination Support** - Automatic handling of paginated API responses\n- **\u26a1 Performance Optimized** - Intelligent retry logic and connection pooling\n- **\ud83d\udee1\ufe0f Type Safe** - Full type hints for better IDE support and code reliability\n- **\ud83e\uddea Well Tested** - Comprehensive test suite with live API integration tests\n- **\ud83d\udcbc Production Ready** - Robust error handling and logging\n\n## Quick Start\n\n### Installation\n\n```bash\npip install py-autotask\n```\n\n### Basic Usage\n\n```python\nfrom py_autotask import AutotaskClient\n\n# Create client with credentials\nclient = AutotaskClient.create(\n username=\"user@example.com\",\n integration_code=\"YOUR_INTEGRATION_CODE\", \n secret=\"YOUR_SECRET\"\n)\n\n# Get a ticket\nticket = client.tickets.get(12345)\nprint(f\"Ticket: {ticket['title']}\")\n\n# Query companies\ncompanies = client.companies.query({\n \"filter\": [{\"op\": \"eq\", \"field\": \"isActive\", \"value\": \"true\"}]\n})\n\n# Create a new contact\nnew_contact = client.contacts.create({\n \"firstName\": \"John\",\n \"lastName\": \"Doe\", \n \"emailAddress\": \"john.doe@example.com\",\n \"companyID\": 12345\n})\n```\n\n### Environment Variables\n\nYou can also configure authentication using environment variables:\n\n```bash\nexport AUTOTASK_USERNAME=\"user@example.com\"\nexport AUTOTASK_INTEGRATION_CODE=\"YOUR_INTEGRATION_CODE\"\nexport AUTOTASK_SECRET=\"YOUR_SECRET\"\n```\n\n```python\nfrom py_autotask import AutotaskClient\n\n# Client will automatically use environment variables\nclient = AutotaskClient.from_env()\n```\n\n\n## Supported Entities\n\npy-autotask supports all major Autotask entities:\n\n- **Tickets** - Service desk tickets and related operations\n- **Companies** - Customer and vendor company records \n- **Contacts** - Individual contact records\n- **Projects** - Project management and tracking\n- **Resources** - User and technician records\n- **Contracts** - Service contracts and agreements\n- **Time Entries** - Time tracking and billing\n- **Expenses** - Expense tracking and management\n- **Products** - Product catalog and inventory\n- **Services** - Service catalog management\n\n\n### Error Handling\n\n```python\nfrom py_autotask.exceptions import (\n AutotaskAuthError,\n AutotaskAPIError,\n AutotaskRateLimitError\n)\n\ntry:\n ticket = client.tickets.get(12345)\nexcept AutotaskAuthError:\n print(\"Authentication failed - check credentials\")\nexcept AutotaskRateLimitError as e:\n print(f\"Rate limit exceeded, retry after {e.retry_after} seconds\")\nexcept AutotaskAPIError as e:\n print(f\"API error: {e.message}\")\n```\n\n### Batch Operations\n\n```python\n# Bulk create\ncontacts_data = [\n {\"firstName\": \"John\", \"lastName\": \"Doe\", \"companyID\": 123},\n {\"firstName\": \"Jane\", \"lastName\": \"Smith\", \"companyID\": 123}\n]\n\n# Create multiple contacts\nresults = []\nfor contact_data in contacts_data:\n result = client.contacts.create(contact_data)\n results.append(result)\n```\n\n## Configuration\n\n### Request Configuration\n\n```python\nfrom py_autotask.types import RequestConfig\n\nconfig = RequestConfig(\n timeout=60, # Request timeout in seconds\n max_retries=5, # Maximum retry attempts\n retry_delay=2.0, # Base retry delay\n retry_backoff=2.0 # Exponential backoff multiplier\n)\n\nclient = AutotaskClient(auth, config)\n```\n\n### Logging\n\n```python\nimport logging\n\n# Enable debug logging\nlogging.getLogger('py_autotask').setLevel(logging.DEBUG)\n\n# Configure custom logging\nlogger = logging.getLogger('py_autotask.client')\nlogger.addHandler(logging.FileHandler('autotask.log'))\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/asachs01/py-autotask.git\ncd py-autotask\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=py_autotask --cov-report=html\n\n# Run specific test file\npytest tests/test_client.py\n\n# Run integration tests (requires API credentials)\npytest tests/integration/ --integration\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack py_autotask tests\n\n# Sort imports\nisort py_autotask tests\n\n# Lint code\nflake8 py_autotask tests\n\n# Type checking\nmypy py_autotask\n```\n\n## API Reference\n\nFor detailed API documentation, see the inline docstrings and type hints in the source code.\n\n### Core Classes\n\n- **AutotaskClient** - Main client class for API operations\n- **AutotaskAuth** - Authentication and zone detection\n- **BaseEntity** - Base class for all entity operations\n- **EntityManager** - Factory for entity handlers\n\n### Exception Classes\n\n- **AutotaskError** - Base exception class\n- **AutotaskAPIError** - HTTP/API related errors\n- **AutotaskAuthError** - Authentication failures\n- **AutotaskValidationError** - Data validation errors\n- **AutotaskRateLimitError** - Rate limiting errors\n\n## Migration Guide\n\n### From autotask-node (Node.js)\n\npy-autotask provides similar functionality to the popular Node.js autotask library:\n\n```javascript\n// Node.js (autotask-node)\nconst autotask = require('autotask-node');\nconst at = new autotask(username, integration, secret);\n\nat.tickets.get(12345).then(ticket => {\n console.log(ticket.title);\n});\n```\n\n```python\n# Python (py-autotask)\nfrom py_autotask import AutotaskClient\n\nclient = AutotaskClient.create(username, integration, secret)\nticket = client.tickets.get(12345)\nprint(ticket['title'])\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Reporting Issues\n\n- Use the [GitHub Issues](https://github.com/asachs01/py-autotask/issues) page\n- Include Python version, library version, and error details\n- Provide minimal reproduction code when possible\n\n### Feature Requests\n\n- Open an issue with the \"enhancement\" label\n- Describe the use case and expected behavior\n- Include relevant Autotask API documentation references\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udcac [GitHub Discussions](https://github.com/asachs01/py-autotask/discussions)\n- \ud83d\udc1b [Issue Tracker](https://github.com/asachs01/py-autotask/issues)\n\n## Acknowledgments\n\n- Autotask API team for excellent documentation\n- Contributors to the autotask-node library for inspiration\n- Python community for amazing libraries and tools\n\n---\n\n**Disclaimer**: This library is not officially affiliated with Datto/Autotask. It is an independent implementation of the Autotask REST API. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for Autotask PSA REST API integration",
"version": "2.0.0",
"project_urls": {
"Changelog": "https://github.com/asachs01/py-autotask/blob/main/CHANGELOG.md",
"Documentation": "https://py-autotask.readthedocs.io/",
"Homepage": "https://github.com/asachs01/py-autotask",
"Issues": "https://github.com/asachs01/py-autotask/issues",
"Repository": "https://github.com/asachs01/py-autotask.git"
},
"split_keywords": [
"autotask",
" psa",
" api",
" rest",
" integration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "46b150d9010e56ad572b2d17d1a4474f2528fc9b8b3f35a0018ea4b9edc6070e",
"md5": "c4ebd9efa99453903d835d425b8ab3f0",
"sha256": "30172d653e7148e85da2abb8412d3dd0edd84dedd716dee6aeec9990019d46af"
},
"downloads": -1,
"filename": "py_autotask-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c4ebd9efa99453903d835d425b8ab3f0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 864443,
"upload_time": "2025-09-06T13:50:23",
"upload_time_iso_8601": "2025-09-06T13:50:23.983941Z",
"url": "https://files.pythonhosted.org/packages/46/b1/50d9010e56ad572b2d17d1a4474f2528fc9b8b3f35a0018ea4b9edc6070e/py_autotask-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8866da0da8eb8959520c71828770a8b1b0f59e866714bbb0cd7509158179d93f",
"md5": "73d5275400ea9b706402547370bbc0e7",
"sha256": "6bcb50d7fbeded022201841c70b6f271210232b714f268f389d945683a1aadee"
},
"downloads": -1,
"filename": "py_autotask-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "73d5275400ea9b706402547370bbc0e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 783212,
"upload_time": "2025-09-06T13:50:25",
"upload_time_iso_8601": "2025-09-06T13:50:25.584116Z",
"url": "https://files.pythonhosted.org/packages/88/66/da0da8eb8959520c71828770a8b1b0f59e866714bbb0cd7509158179d93f/py_autotask-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 13:50:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asachs01",
"github_project": "py-autotask",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "tenacity",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.24.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "redis",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "openpyxl",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "pyarrow",
"specs": [
[
">=",
"12.0.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
">=",
"4.65.0"
]
]
}
],
"lcname": "py-autotask"
}
JSON
