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 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
@@ -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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.32.4
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.