Metadata-Version: 2.3
Name: dtools-si
Version: 0.1.1
Summary: D-Tools System Integrator API Python interface
Author: Josh Valdeleon
Author-email: Josh Valdeleon <imjbmkz@gmail.com>
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: requests==2.32.5
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# dtools-si

Python interface for the D-Tools System Integrator (SI) API.

## Overview

`dtools-si` provides a lightweight client for working with the D-Tools SI endpoints, including subscribe APIs for:

- Projects
- Service Orders
- Service Plans
- Time Sheets
- Tasks

The package is built around a shared base client that handles authentication, request headers, and common query parameters.

## Requirements

- Python 3.11+
- `python-dotenv==1.2.1`
- `requests==2.32.5`

## Installation

Install from source or from a package repository if available:

```bash
pip install dtools-si
```

For editable development installs:

```bash
pip install -e dtools-si
```

## Configuration

The client requires a valid D-Tools SI API key.

Create a `.env` file in your project root:

```env
DTOOLS_API_KEY=your_api_key_here
```

Then load it in your application or tests using `python-dotenv`.

## Quick Start

```python
from dtools_si.subscribe.projects import SubscribeProjectsAPI
from dotenv import load_dotenv
from os import getenv

load_dotenv()
api_key = getenv("DTOOLS_API_KEY")

client = SubscribeProjectsAPI(api_key=api_key)
response = client.get_projects(include_archived=True)
print(response.status_code)
print(response.json())
```

## API Summary

### `DToolsSI`

Base client for the D-Tools SI API.

```python
from dtools_si import DToolsSI
client = DToolsSI(api_key="YOUR_API_KEY")
```

The client exposes internal helpers used by derived subscribe APIs:

- `_request(method, path, params)`
- `_get_resource(resource, ...)`
- `_get_resource_id(resource, id, ...)`
- `_mark_as_imported(resource, id, ...)`

### `SubscribeProjectsAPI`

Use this class to access project-related subscribe endpoints.

- `get_projects(...)`
- `get_project(project_id, co_number=None, aggregate_by=None, get_adjustments_by_item=None)`
- `get_project_comments(project_id, page_number=1, page_size=50)`
- `mark_project_as_imported(project_id, co_number=None)`

### `SubscribeServiceOrdersAPI`

Service order subscribe endpoints.

- `get_service_orders(...)`
- `get_service_order(service_order_id)`
- `get_mobile_install_site_notes(service_order_id)`
- `mark_service_order_as_imported(service_order_id)`

### `SubscribeServicePlansAPI`

Service plan subscribe endpoints.

- `get_service_plans(...)`
- `get_service_plan(service_plan_id)`
- `mark_service_plan_as_imported(service_plan_id)`

### `SubscribeTimeSheetsAPI`

Time sheet subscribe endpoints.

- `get_timesheets(...)`
- `get_timesheet(timesheet_id)`
- `mark_timesheet_as_imported(timesheet_id)`

### `SubscribeTasksAPI`

Task subscribe endpoints.

- `get_tasks(...)`
- `get_task(task_id)`
- `get_mobile_install_site_notes(task_id)`
- `get_tasks_by_project(project_id)`
- `mark_task_as_imported(task_id)`

### `utils.remove_none_values`

Utility helper that removes `None` values from request parameter dictionaries.

## Running Tests

The project includes basic initialization and API integration tests.

```bash
pytest
```

Tests use environment variables defined in `.env`:

- `DTOOLS_API_KEY`
- `DTOOLS_TEST_PROJECT_ID`
- `DTOOLS_TEST_PROJECT_CO_NUMBER`
- `DTOOLS_TEST_SERVICE_ORDER_ID`
- `DTOOLS_TEST_SERVICE_PLAN_ID`
- `DTOOLS_TEST_TIMESHEET_ID`
- `DTOOLS_TEST_TASKS_ID`

## Notes

- All request methods return a `requests.Response` object.
- The package communicates with the D-Tools SI API at `https://api.d-tools.com/SI`.
- Authentication is handled via the `X-DTSI-ApiKey` request header.
