simpro-py-sdk 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- simpro/__init__.py +31 -0
- simpro/_util.py +19 -0
- simpro/client.py +152 -0
- simpro/exceptions.py +49 -0
- simpro/resources/__init__.py +8 -0
- simpro/resources/_base.py +155 -0
- simpro/resources/companies.py +44 -0
- simpro/resources/customers.py +34 -0
- simpro/resources/jobs.py +11 -0
- simpro/resources/sites.py +11 -0
- simpro_py_sdk-0.1.0.dist-info/METADATA +171 -0
- simpro_py_sdk-0.1.0.dist-info/RECORD +14 -0
- simpro_py_sdk-0.1.0.dist-info/WHEEL +4 -0
- simpro_py_sdk-0.1.0.dist-info/licenses/LICENCE.txt +21 -0
simpro/__init__.py
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""simpro-py: a thin Python client for the SimPro Cloud REST API (v1.0).
|
|
2
|
+
|
|
3
|
+
Quickstart::
|
|
4
|
+
|
|
5
|
+
from simpro import SimproClient
|
|
6
|
+
|
|
7
|
+
client = SimproClient("https://yourtenant.simprosuite.com", "API_KEY")
|
|
8
|
+
for customer in client.customers.iter_all(0):
|
|
9
|
+
print(customer["ID"], customer.get("CompanyName"))
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from simpro.client import SimproClient
|
|
13
|
+
from simpro.exceptions import (
|
|
14
|
+
SimproAuthError,
|
|
15
|
+
SimproError,
|
|
16
|
+
SimproNotFound,
|
|
17
|
+
SimproRateLimitError,
|
|
18
|
+
SimproValidationError,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
__version__ = "0.1.0"
|
|
22
|
+
|
|
23
|
+
__all__ = [
|
|
24
|
+
"SimproAuthError",
|
|
25
|
+
"SimproClient",
|
|
26
|
+
"SimproError",
|
|
27
|
+
"SimproNotFound",
|
|
28
|
+
"SimproRateLimitError",
|
|
29
|
+
"SimproValidationError",
|
|
30
|
+
"__version__",
|
|
31
|
+
]
|
simpro/_util.py
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Internal helpers shared by the client and the resource modules."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from datetime import UTC, datetime
|
|
6
|
+
from email.utils import format_datetime
|
|
7
|
+
|
|
8
|
+
API_PREFIX = "/api/v1.0"
|
|
9
|
+
MAX_PAGE_SIZE = 250
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def format_http_date(dt: datetime) -> str:
|
|
13
|
+
"""Format ``dt`` as an RFC 1123 date string (UTC), for ``If-Modified-Since``.
|
|
14
|
+
|
|
15
|
+
Naive datetimes are treated as UTC.
|
|
16
|
+
"""
|
|
17
|
+
if dt.tzinfo is None:
|
|
18
|
+
dt = dt.replace(tzinfo=UTC)
|
|
19
|
+
return format_datetime(dt.astimezone(UTC), usegmt=True)
|
simpro/client.py
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
"""The SimPro Cloud REST API client.
|
|
2
|
+
|
|
3
|
+
Every request URL is built in one place (``_request``) as
|
|
4
|
+
``{base}/api/v1.0{path}``; if ``base_url`` already ends with ``/api/v1.0``
|
|
5
|
+
the prefix is stripped first, so the well-known doubling trap (simPRO
|
|
6
|
+
answers 404 ``Invalid route``) is impossible by construction.
|
|
7
|
+
|
|
8
|
+
The client is intentionally thin: no retry, no rate limiting, no caching.
|
|
9
|
+
SimPro allows roughly 10 requests/second per key — callers with bulk pulls
|
|
10
|
+
should pace requests and retry 429s/transport errors themselves.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from collections.abc import Mapping
|
|
16
|
+
from typing import Any, Self
|
|
17
|
+
|
|
18
|
+
import httpx
|
|
19
|
+
|
|
20
|
+
from simpro._util import API_PREFIX
|
|
21
|
+
from simpro.exceptions import (
|
|
22
|
+
SimproAuthError,
|
|
23
|
+
SimproError,
|
|
24
|
+
SimproNotFound,
|
|
25
|
+
SimproRateLimitError,
|
|
26
|
+
SimproValidationError,
|
|
27
|
+
)
|
|
28
|
+
from simpro.resources import Companies, Customers, Jobs, Sites
|
|
29
|
+
|
|
30
|
+
DEFAULT_TIMEOUT = 30.0
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class SimproClient:
|
|
34
|
+
"""Synchronous client for the SimPro Cloud REST API (v1.0).
|
|
35
|
+
|
|
36
|
+
Args:
|
|
37
|
+
base_url: Tenant root, e.g. ``https://yourtenant.simprosuite.com``.
|
|
38
|
+
A trailing ``/api/v1.0`` is tolerated and stripped.
|
|
39
|
+
api_key: API key bearer token (SimPro > Administration > API Keys).
|
|
40
|
+
timeout: Per-request timeout in seconds.
|
|
41
|
+
transport: Optional ``httpx`` transport override (testing/proxies).
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
def __init__(
|
|
45
|
+
self,
|
|
46
|
+
base_url: str,
|
|
47
|
+
api_key: str,
|
|
48
|
+
*,
|
|
49
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
50
|
+
transport: httpx.BaseTransport | None = None,
|
|
51
|
+
) -> None:
|
|
52
|
+
base = base_url.rstrip("/").removesuffix(API_PREFIX)
|
|
53
|
+
self._base = base
|
|
54
|
+
self._http = httpx.Client(
|
|
55
|
+
timeout=timeout,
|
|
56
|
+
headers={
|
|
57
|
+
"Authorization": f"Bearer {api_key}",
|
|
58
|
+
"Accept": "application/json",
|
|
59
|
+
},
|
|
60
|
+
transport=transport,
|
|
61
|
+
)
|
|
62
|
+
# Resource namespaces.
|
|
63
|
+
self.companies = Companies(self)
|
|
64
|
+
self.customers = Customers(self)
|
|
65
|
+
self.sites = Sites(self)
|
|
66
|
+
self.jobs = Jobs(self)
|
|
67
|
+
|
|
68
|
+
def __enter__(self) -> Self:
|
|
69
|
+
return self
|
|
70
|
+
|
|
71
|
+
def __exit__(self, *exc_info: object) -> None:
|
|
72
|
+
self.close()
|
|
73
|
+
|
|
74
|
+
def close(self) -> None:
|
|
75
|
+
"""Close the underlying connection pool."""
|
|
76
|
+
self._http.close()
|
|
77
|
+
|
|
78
|
+
def _request(
|
|
79
|
+
self,
|
|
80
|
+
method: str,
|
|
81
|
+
path: str,
|
|
82
|
+
*,
|
|
83
|
+
params: Mapping[str, Any] | None = None,
|
|
84
|
+
headers: Mapping[str, str] | None = None,
|
|
85
|
+
) -> httpx.Response:
|
|
86
|
+
"""Perform one API request and map failures to typed exceptions.
|
|
87
|
+
|
|
88
|
+
``path`` is relative to the API prefix and starts with ``/``,
|
|
89
|
+
e.g. ``/companies/0/customers/``. A 304 (If-Modified-Since hit) is
|
|
90
|
+
returned to the caller as a normal response.
|
|
91
|
+
"""
|
|
92
|
+
url = f"{self._base}{API_PREFIX}{path}"
|
|
93
|
+
try:
|
|
94
|
+
response = self._http.request(method, url, params=params, headers=headers)
|
|
95
|
+
except httpx.HTTPError as exc:
|
|
96
|
+
raise SimproError(f"SimPro request failed: {exc}") from exc
|
|
97
|
+
_raise_for_status(response)
|
|
98
|
+
return response
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _raise_for_status(response: httpx.Response) -> None:
|
|
102
|
+
status = response.status_code
|
|
103
|
+
if status < 400 or status == 304:
|
|
104
|
+
return
|
|
105
|
+
if status in (401, 403):
|
|
106
|
+
raise SimproAuthError(
|
|
107
|
+
f"SimPro rejected the credentials (HTTP {status})", status_code=status
|
|
108
|
+
)
|
|
109
|
+
if status == 404:
|
|
110
|
+
raise SimproNotFound(f"SimPro resource not found: {response.url}", status_code=status)
|
|
111
|
+
if status == 429:
|
|
112
|
+
raise SimproRateLimitError(
|
|
113
|
+
"SimPro rate limit exceeded; retry after a pause", status_code=status
|
|
114
|
+
)
|
|
115
|
+
if status == 422:
|
|
116
|
+
message, details = _parse_validation_body(response)
|
|
117
|
+
raise SimproValidationError(message, details=details, status_code=status)
|
|
118
|
+
raise SimproError(
|
|
119
|
+
f"SimPro request failed with HTTP {status}: {response.text[:200]}",
|
|
120
|
+
status_code=status,
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _parse_validation_body(
|
|
125
|
+
response: httpx.Response,
|
|
126
|
+
) -> tuple[str, list[dict[str, Any]]]:
|
|
127
|
+
"""Extract a message and error details from a 422 body.
|
|
128
|
+
|
|
129
|
+
SimPro 422 bodies are ``{"errors": [{"path", "message", "value"}, ...]}``
|
|
130
|
+
— but the ``errors`` key may be absent, and the body may not be JSON at
|
|
131
|
+
all. Both shapes degrade gracefully.
|
|
132
|
+
"""
|
|
133
|
+
try:
|
|
134
|
+
body: Any = response.json()
|
|
135
|
+
except ValueError:
|
|
136
|
+
body = None
|
|
137
|
+
if isinstance(body, dict):
|
|
138
|
+
errors = body.get("errors")
|
|
139
|
+
details = [e for e in errors if isinstance(e, dict)] if isinstance(errors, list) else []
|
|
140
|
+
message = body.get("message") if isinstance(body.get("message"), str) else None
|
|
141
|
+
if message is None:
|
|
142
|
+
message = "SimPro rejected the request payload (HTTP 422)"
|
|
143
|
+
if details:
|
|
144
|
+
summary = "; ".join(
|
|
145
|
+
f"{d.get('path', '?')}: {d.get('message', '')}" for d in details[:5]
|
|
146
|
+
)
|
|
147
|
+
message = f"{message} — {summary}"
|
|
148
|
+
return message, details
|
|
149
|
+
if isinstance(body, list):
|
|
150
|
+
details = [e for e in body if isinstance(e, dict)]
|
|
151
|
+
return "SimPro rejected the request payload (HTTP 422)", details
|
|
152
|
+
return f"SimPro rejected the request payload (HTTP 422): {response.text[:200]}", []
|
simpro/exceptions.py
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""Exception hierarchy for the simpro client.
|
|
2
|
+
|
|
3
|
+
Every HTTP failure is mapped to one of these types in one place
|
|
4
|
+
(``simpro.client``); transport-level failures raise ``SimproError``.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class SimproError(Exception):
|
|
13
|
+
"""Base error for all simpro failures (transport or HTTP)."""
|
|
14
|
+
|
|
15
|
+
def __init__(self, message: str, *, status_code: int | None = None) -> None:
|
|
16
|
+
super().__init__(message)
|
|
17
|
+
self.status_code = status_code
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class SimproAuthError(SimproError):
|
|
21
|
+
"""SimPro rejected the request as unauthenticated or unauthorised (401/403)."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class SimproNotFound(SimproError):
|
|
25
|
+
"""The requested SimPro resource does not exist (404)."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class SimproRateLimitError(SimproError):
|
|
29
|
+
"""SimPro rate limit exceeded (429). Retry after a pause; the SDK does not retry."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class SimproValidationError(SimproError):
|
|
33
|
+
"""SimPro rejected the request payload (422).
|
|
34
|
+
|
|
35
|
+
``details`` carries the raw error list when the response body provides
|
|
36
|
+
one: SimPro returns ``{"errors": [{"path", "message", "value"}, ...]}``
|
|
37
|
+
but the ``errors`` key may be absent, in which case ``details`` is empty
|
|
38
|
+
and the message carries whatever the body offered.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
def __init__(
|
|
42
|
+
self,
|
|
43
|
+
message: str,
|
|
44
|
+
*,
|
|
45
|
+
details: list[dict[str, Any]] | None = None,
|
|
46
|
+
status_code: int | None = None,
|
|
47
|
+
) -> None:
|
|
48
|
+
super().__init__(message, status_code=status_code)
|
|
49
|
+
self.details = details if details is not None else []
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""Resource namespaces attached to :class:`~simpro.SimproClient`."""
|
|
2
|
+
|
|
3
|
+
from simpro.resources.companies import Companies
|
|
4
|
+
from simpro.resources.customers import Customers
|
|
5
|
+
from simpro.resources.jobs import Jobs
|
|
6
|
+
from simpro.resources.sites import Sites
|
|
7
|
+
|
|
8
|
+
__all__ = ["Companies", "Customers", "Jobs", "Sites"]
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
"""Resource namespace base classes.
|
|
2
|
+
|
|
3
|
+
``CompanyScopedResource`` implements the shared GET/list/iter_all shape for
|
|
4
|
+
resources under ``/companies/{companyID}/<resource>/``. Pagination follows
|
|
5
|
+
the SimPro convention: ``page`` + ``pageSize`` query params, list bodies are
|
|
6
|
+
plain JSON arrays, and the continuation signal is the ``Result-Pages``
|
|
7
|
+
response header (total page count). When the header is absent the walk falls
|
|
8
|
+
back to stopping on a short page.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from collections.abc import Iterator
|
|
14
|
+
from datetime import datetime
|
|
15
|
+
from typing import TYPE_CHECKING, Any
|
|
16
|
+
|
|
17
|
+
from simpro._util import MAX_PAGE_SIZE, format_http_date
|
|
18
|
+
|
|
19
|
+
if TYPE_CHECKING:
|
|
20
|
+
from simpro.client import SimproClient
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class Resource:
|
|
24
|
+
"""A resource namespace attached to a :class:`~simpro.SimproClient`."""
|
|
25
|
+
|
|
26
|
+
def __init__(self, client: SimproClient) -> None:
|
|
27
|
+
self._client = client
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class CompanyScopedResource(Resource):
|
|
31
|
+
"""GET-only resource under ``/companies/{companyID}/``."""
|
|
32
|
+
|
|
33
|
+
_resource: str
|
|
34
|
+
|
|
35
|
+
def list(
|
|
36
|
+
self,
|
|
37
|
+
company_id: int,
|
|
38
|
+
*,
|
|
39
|
+
search: str | None = None,
|
|
40
|
+
page: int = 1,
|
|
41
|
+
per_page: int = 250,
|
|
42
|
+
modified_since: datetime | None = None,
|
|
43
|
+
**filters: Any,
|
|
44
|
+
) -> list[dict[str, Any]]:
|
|
45
|
+
"""Fetch one page of results.
|
|
46
|
+
|
|
47
|
+
Args:
|
|
48
|
+
company_id: SimPro company ID (0 unless multi-company).
|
|
49
|
+
search: Verbatim ``search`` query param — SimPro's documented
|
|
50
|
+
values are ``"all"``/``"any"`` (match mode for the field
|
|
51
|
+
filters passed via ``**filters``).
|
|
52
|
+
page: 1-based page number.
|
|
53
|
+
per_page: Page size, clamped to SimPro's max of 250.
|
|
54
|
+
modified_since: Watermark for list endpoints — sent as an
|
|
55
|
+
``If-Modified-Since`` header; a 304 answer yields ``[]``.
|
|
56
|
+
**filters: Extra query params, passed through verbatim
|
|
57
|
+
(e.g. ``Name="Acme"``).
|
|
58
|
+
"""
|
|
59
|
+
response = self._list_page(
|
|
60
|
+
company_id,
|
|
61
|
+
page=page,
|
|
62
|
+
per_page=per_page,
|
|
63
|
+
search=search,
|
|
64
|
+
modified_since=modified_since,
|
|
65
|
+
**filters,
|
|
66
|
+
)
|
|
67
|
+
if response.status_code == 304:
|
|
68
|
+
return []
|
|
69
|
+
data: Any = response.json()
|
|
70
|
+
return data if isinstance(data, list) else [data]
|
|
71
|
+
|
|
72
|
+
def get(self, company_id: int, resource_id: int) -> dict[str, Any]:
|
|
73
|
+
"""Fetch one record by ID."""
|
|
74
|
+
response = self._client._request(
|
|
75
|
+
"GET", f"/companies/{company_id}/{self._resource}/{resource_id}"
|
|
76
|
+
)
|
|
77
|
+
data: Any = response.json()
|
|
78
|
+
return data
|
|
79
|
+
|
|
80
|
+
def iter_all(
|
|
81
|
+
self,
|
|
82
|
+
company_id: int,
|
|
83
|
+
*,
|
|
84
|
+
per_page: int = MAX_PAGE_SIZE,
|
|
85
|
+
modified_since: datetime | None = None,
|
|
86
|
+
**filters: Any,
|
|
87
|
+
) -> Iterator[dict[str, Any]]:
|
|
88
|
+
"""Yield every record, walking pages until exhausted.
|
|
89
|
+
|
|
90
|
+
Stops when the page number reaches the ``Result-Pages`` response
|
|
91
|
+
header, or — if that header is missing — when a page comes back
|
|
92
|
+
shorter than ``per_page``.
|
|
93
|
+
"""
|
|
94
|
+
page_size = _clamp_page_size(per_page)
|
|
95
|
+
page = 1
|
|
96
|
+
while True:
|
|
97
|
+
response = self._list_page(
|
|
98
|
+
company_id,
|
|
99
|
+
page=page,
|
|
100
|
+
per_page=page_size,
|
|
101
|
+
search=None,
|
|
102
|
+
modified_since=modified_since,
|
|
103
|
+
**filters,
|
|
104
|
+
)
|
|
105
|
+
if response.status_code == 304:
|
|
106
|
+
return
|
|
107
|
+
data: Any = response.json()
|
|
108
|
+
items = data if isinstance(data, list) else [data]
|
|
109
|
+
yield from items
|
|
110
|
+
if not _has_more_pages(response, page, len(items), page_size):
|
|
111
|
+
return
|
|
112
|
+
page += 1
|
|
113
|
+
|
|
114
|
+
def _list_page(
|
|
115
|
+
self,
|
|
116
|
+
company_id: int,
|
|
117
|
+
*,
|
|
118
|
+
page: int,
|
|
119
|
+
per_page: int,
|
|
120
|
+
search: str | None,
|
|
121
|
+
modified_since: datetime | None,
|
|
122
|
+
**filters: Any,
|
|
123
|
+
) -> Any:
|
|
124
|
+
params: dict[str, Any] = {
|
|
125
|
+
"page": page,
|
|
126
|
+
"pageSize": _clamp_page_size(per_page),
|
|
127
|
+
}
|
|
128
|
+
if search is not None:
|
|
129
|
+
params["search"] = search
|
|
130
|
+
params.update(filters)
|
|
131
|
+
headers: dict[str, str] | None = None
|
|
132
|
+
if modified_since is not None:
|
|
133
|
+
headers = {"If-Modified-Since": format_http_date(modified_since)}
|
|
134
|
+
return self._client._request(
|
|
135
|
+
"GET",
|
|
136
|
+
f"/companies/{company_id}/{self._resource}/",
|
|
137
|
+
params=params,
|
|
138
|
+
headers=headers,
|
|
139
|
+
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def _clamp_page_size(per_page: int) -> int:
|
|
143
|
+
return max(1, min(per_page, MAX_PAGE_SIZE))
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _has_more_pages(response: Any, page: int, items_on_page: int, page_size: int) -> bool:
|
|
147
|
+
raw = response.headers.get("Result-Pages")
|
|
148
|
+
if raw is not None:
|
|
149
|
+
try:
|
|
150
|
+
total_pages = int(raw)
|
|
151
|
+
except ValueError:
|
|
152
|
+
total_pages = 0
|
|
153
|
+
if total_pages > 0:
|
|
154
|
+
return page < total_pages
|
|
155
|
+
return items_on_page >= page_size
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Companies endpoints: ``GET /api/v1.0/companies/``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from datetime import datetime
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
from simpro._util import format_http_date
|
|
9
|
+
from simpro.resources._base import Resource
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Companies(Resource):
|
|
13
|
+
"""The companies the API key can see (usually exactly one)."""
|
|
14
|
+
|
|
15
|
+
def list(
|
|
16
|
+
self,
|
|
17
|
+
*,
|
|
18
|
+
search: str | None = None,
|
|
19
|
+
modified_since: datetime | None = None,
|
|
20
|
+
**filters: Any,
|
|
21
|
+
) -> list[dict[str, Any]]:
|
|
22
|
+
"""List companies.
|
|
23
|
+
|
|
24
|
+
SimPro does not document ``page``/``pageSize`` for this endpoint; the
|
|
25
|
+
response is a single unpaginated array. ``**filters`` and
|
|
26
|
+
``modified_since`` behave as on other resources.
|
|
27
|
+
"""
|
|
28
|
+
params: dict[str, Any] = dict(filters)
|
|
29
|
+
if search is not None:
|
|
30
|
+
params["search"] = search
|
|
31
|
+
headers: dict[str, str] | None = None
|
|
32
|
+
if modified_since is not None:
|
|
33
|
+
headers = {"If-Modified-Since": format_http_date(modified_since)}
|
|
34
|
+
response = self._client._request("GET", "/companies/", params=params, headers=headers)
|
|
35
|
+
if response.status_code == 304:
|
|
36
|
+
return []
|
|
37
|
+
data: Any = response.json()
|
|
38
|
+
return data if isinstance(data, list) else [data]
|
|
39
|
+
|
|
40
|
+
def get(self, company_id: int) -> dict[str, Any]:
|
|
41
|
+
"""Fetch one company by ID."""
|
|
42
|
+
response = self._client._request("GET", f"/companies/{company_id}")
|
|
43
|
+
data: Any = response.json()
|
|
44
|
+
return data
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""Customers endpoints: ``GET /api/v1.0/companies/{companyID}/customers/``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
from simpro.exceptions import SimproNotFound
|
|
8
|
+
from simpro.resources._base import CompanyScopedResource
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class Customers(CompanyScopedResource):
|
|
12
|
+
"""Customers (company and individual)."""
|
|
13
|
+
|
|
14
|
+
_resource = "customers"
|
|
15
|
+
|
|
16
|
+
def get(self, company_id: int, customer_id: int) -> dict[str, Any]:
|
|
17
|
+
"""Fetch one customer by ID.
|
|
18
|
+
|
|
19
|
+
SimPro splits single-customer GETs by type: company customers live at
|
|
20
|
+
``/customers/companies/{ID}`` and individuals at
|
|
21
|
+
``/customers/individuals/{ID}``. This method tries the company path
|
|
22
|
+
first and falls back to individuals, so callers need not know the
|
|
23
|
+
type up front.
|
|
24
|
+
"""
|
|
25
|
+
try:
|
|
26
|
+
response = self._client._request(
|
|
27
|
+
"GET", f"/companies/{company_id}/customers/companies/{customer_id}"
|
|
28
|
+
)
|
|
29
|
+
except SimproNotFound:
|
|
30
|
+
response = self._client._request(
|
|
31
|
+
"GET", f"/companies/{company_id}/customers/individuals/{customer_id}"
|
|
32
|
+
)
|
|
33
|
+
data: Any = response.json()
|
|
34
|
+
return data
|
simpro/resources/jobs.py
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Jobs endpoints: ``GET /api/v1.0/companies/{companyID}/jobs/``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from simpro.resources._base import CompanyScopedResource
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Jobs(CompanyScopedResource):
|
|
9
|
+
"""Jobs (work orders / projects)."""
|
|
10
|
+
|
|
11
|
+
_resource = "jobs"
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Sites endpoints: ``GET /api/v1.0/companies/{companyID}/sites/``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from simpro.resources._base import CompanyScopedResource
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Sites(CompanyScopedResource):
|
|
9
|
+
"""Sites (addresses where work is performed)."""
|
|
10
|
+
|
|
11
|
+
_resource = "sites"
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: simpro-py-sdk
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python client for the SimPro Cloud REST API (v1.0).
|
|
5
|
+
Project-URL: Homepage, https://github.com/xuanpablo/simpro-py
|
|
6
|
+
Project-URL: Changelog, https://github.com/xuanpablo/simpro-py/releases
|
|
7
|
+
Author: Paul Millar
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2016 Bradley McElroy
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
License-File: LICENCE.txt
|
|
30
|
+
Keywords: api,client,construction,simpro,simprosuite
|
|
31
|
+
Classifier: Development Status :: 4 - Beta
|
|
32
|
+
Classifier: Intended Audience :: Developers
|
|
33
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
34
|
+
Classifier: Programming Language :: Python :: 3
|
|
35
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
36
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
37
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
38
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
39
|
+
Requires-Python: >=3.12
|
|
40
|
+
Requires-Dist: httpx>=0.27
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
# simpro-py
|
|
44
|
+
|
|
45
|
+
A thin Python client for the [SimPro Cloud REST API (v1.0)](https://www.simprogroup.com).
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from simpro import SimproClient
|
|
49
|
+
|
|
50
|
+
client = SimproClient("https://yourtenant.simprosuite.com", "YOUR_API_KEY")
|
|
51
|
+
|
|
52
|
+
for customer in client.customers.iter_all(0):
|
|
53
|
+
print(customer["ID"], customer.get("CompanyName") or customer.get("FamilyName"))
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The distribution is `simpro-py-sdk`; the import name is `simpro`.
|
|
57
|
+
|
|
58
|
+
## Install
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install simpro-py-sdk
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Requires Python 3.12+. The only runtime dependency is `httpx`.
|
|
65
|
+
|
|
66
|
+
## Authentication
|
|
67
|
+
|
|
68
|
+
SimPro API keys are bearer tokens — create one in SimPro under
|
|
69
|
+
**Administration > API Keys** and pass it with your tenant base URL:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
client = SimproClient("https://yourtenant.simprosuite.com", "YOUR_API_KEY")
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Every request is sent to `{base_url}/api/v1.0/...`. If your `base_url` already
|
|
76
|
+
ends with `/api/v1.0` it is stripped automatically, so the well-known
|
|
77
|
+
doubled-prefix 404 (`Invalid route`) cannot happen.
|
|
78
|
+
|
|
79
|
+
## Resources
|
|
80
|
+
|
|
81
|
+
0.1.x ships read-only access to the first-slice resources, one namespace per
|
|
82
|
+
resource, hung off the client:
|
|
83
|
+
|
|
84
|
+
| Namespace | Endpoints |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `client.companies` | `list(*, search=None, modified_since=None, **filters)`, `get(company_id)` |
|
|
87
|
+
| `client.customers` | `list(company_id, ...)`, `get(company_id, customer_id)`, `iter_all(company_id, **filters)` |
|
|
88
|
+
| `client.sites` | `list(company_id, ...)`, `get(company_id, site_id)`, `iter_all(company_id, **filters)` |
|
|
89
|
+
| `client.jobs` | `list(company_id, ...)`, `get(company_id, job_id)`, `iter_all(company_id, **filters)` |
|
|
90
|
+
|
|
91
|
+
`company_id` is `0` unless your build uses SimPro multi-company.
|
|
92
|
+
|
|
93
|
+
Notes:
|
|
94
|
+
|
|
95
|
+
- **Single-customer GETs are type-split in SimPro** (company vs individual).
|
|
96
|
+
`client.customers.get(company_id, customer_id)` tries the company path first
|
|
97
|
+
and falls back to individuals, so callers never need the type up front.
|
|
98
|
+
- **`search`** is SimPro's documented match-mode param (`"all"`/`"any"`) that
|
|
99
|
+
combines with field filters. Field filters themselves are passed verbatim as
|
|
100
|
+
extra keyword arguments, e.g. `client.customers.list(0, Name="Acme")`.
|
|
101
|
+
- All methods return plain dicts/lists — no DTO layer by design.
|
|
102
|
+
|
|
103
|
+
## Pagination
|
|
104
|
+
|
|
105
|
+
`list()` fetches a single page (`page`, `per_page`, capped at SimPro's maximum
|
|
106
|
+
of 250). `iter_all()` walks every page for you:
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
for job in client.jobs.iter_all(0):
|
|
110
|
+
...
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Page continuation follows the SimPro convention: the `Result-Pages` response
|
|
114
|
+
header carries the total page count; if it is absent, the walk stops on a
|
|
115
|
+
short page.
|
|
116
|
+
|
|
117
|
+
## Incremental pulls
|
|
118
|
+
|
|
119
|
+
List endpoints honour the `If-Modified-Since` watermark. Pass
|
|
120
|
+
`modified_since=<datetime>` and the client formats the header (RFC 1123, UTC)
|
|
121
|
+
and maps a `304 Not Modified` answer to an empty result:
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
since = last_sync_run_at # aware datetime; naive values are treated as UTC
|
|
125
|
+
new_customers = client.customers.list(0, modified_since=since)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Errors
|
|
129
|
+
|
|
130
|
+
All failures raise a subclass of `SimproError`:
|
|
131
|
+
|
|
132
|
+
| Exception | HTTP status |
|
|
133
|
+
|---|---|
|
|
134
|
+
| `SimproAuthError` | 401, 403 |
|
|
135
|
+
| `SimproNotFound` | 404 |
|
|
136
|
+
| `SimproValidationError` | 422 (`.details` holds the raw error list) |
|
|
137
|
+
| `SimproRateLimitError` | 429 |
|
|
138
|
+
| `SimproError` | anything else, including transport failures |
|
|
139
|
+
|
|
140
|
+
SimPro 422 bodies are normally `{"errors": [{"path", "message", "value"}, ...]}`
|
|
141
|
+
but the `errors` key may be absent — both shapes are handled, and
|
|
142
|
+
`SimproValidationError.details` is always a list.
|
|
143
|
+
|
|
144
|
+
## Deliberate omissions
|
|
145
|
+
|
|
146
|
+
- **No retry, no rate limiting, no caching.** SimPro allows roughly 10
|
|
147
|
+
requests/second per key; callers doing bulk pulls should pace requests and
|
|
148
|
+
retry 429s/transport errors themselves.
|
|
149
|
+
- **No write endpoints** in 0.1.x — read-only first.
|
|
150
|
+
- **No DTO layer** — responses are plain JSON dicts, so SDK releases never
|
|
151
|
+
lag the API.
|
|
152
|
+
|
|
153
|
+
## Lineage
|
|
154
|
+
|
|
155
|
+
This package is a clean rewrite of [`limx0/simpro-py`](https://github.com/limx0/simpro-py)
|
|
156
|
+
(MIT), which wrapped SimPro's legacy on-prem JSON-RPC API. The rewrite targets
|
|
157
|
+
the SimPro Cloud REST API and shares no code with the original; the MIT
|
|
158
|
+
licence and lineage are retained with thanks.
|
|
159
|
+
|
|
160
|
+
## Development
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
uv sync
|
|
164
|
+
uv run pytest -q
|
|
165
|
+
uv run ruff check . && uv run ruff format --check .
|
|
166
|
+
uv run mypy
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Licence
|
|
170
|
+
|
|
171
|
+
MIT — see [LICENCE.txt](LICENCE.txt).
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
simpro/__init__.py,sha256=jOr3e-5Q90xcnnbCT5VlYWW0-WNzSsrRofFEIJhbRdc,696
|
|
2
|
+
simpro/_util.py,sha256=w8YSQqZG69ZjRDoSW3oDPepMP3mhA-lou6vnN1FzznM,526
|
|
3
|
+
simpro/client.py,sha256=3s6UeJXH_B4QO8i5qoeZvhz3CLB4MjAb2FMapOi0scw,5261
|
|
4
|
+
simpro/exceptions.py,sha256=EIDWEPFB_E_t8h5VVTT5QSXkmA2P13iPqm5N6C07OGI,1531
|
|
5
|
+
simpro/resources/__init__.py,sha256=VxSftq5kuRFaC3q8cAw5pUVT7BXRk1qetsGXgfviKKE,303
|
|
6
|
+
simpro/resources/_base.py,sha256=NR8WlxYJXlKzwUG6FoaxFCVDGsDamu8srOf46limgUU,5007
|
|
7
|
+
simpro/resources/companies.py,sha256=YW4VH-pKmYb8dNVPwvLtkEe978QmTg_UXBs6R6kEmxA,1505
|
|
8
|
+
simpro/resources/customers.py,sha256=n18GrpSE7yBvimXU-oe2uQcmUlnJP9onU2xyOaGL3uM,1180
|
|
9
|
+
simpro/resources/jobs.py,sha256=FfSZ6x0j0D9mblSuF_OptdTy7Mn6hxT57Y8qUnvV_1s,265
|
|
10
|
+
simpro/resources/sites.py,sha256=G5MSuSkRs1y9duOisEmNNyN6m3S2UbefaLykeWq6X4o,281
|
|
11
|
+
simpro_py_sdk-0.1.0.dist-info/METADATA,sha256=0UO-vXMjjGm37h3G03UjM7izPgvtRj57jFweqAoJCjQ,6378
|
|
12
|
+
simpro_py_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
13
|
+
simpro_py_sdk-0.1.0.dist-info/licenses/LICENCE.txt,sha256=XnrdgBHxcaM6KE4rdWQb-3oJH2_I2OlEsi1s66bfkT4,1071
|
|
14
|
+
simpro_py_sdk-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2016 Bradley McElroy
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|