simpro-py-sdk 0.1.1__tar.gz → 0.2.0__tar.gz

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simpro-py-sdk
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python client for the SimPro Cloud REST API (v1.0).
 Project-URL: Homepage, https://github.com/xuanpablo/simpro-py
 Project-URL: Changelog, https://github.com/xuanpablo/simpro-py/releases

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simpro-py-sdk"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python client for the SimPro Cloud REST API (v1.0)."
 readme = "README.md"
 license = { file = "LICENCE.txt" }

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/src/simpro/__init__.py

@@ -17,15 +17,19 @@ from simpro.exceptions import (
     SimproRateLimitError,
     SimproValidationError,
 )
+from simpro.ratelimit import DEFAULT_RATE_LIMIT, RateLimiter, SlidingWindowRateLimiter
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = [
+    "DEFAULT_RATE_LIMIT",
+    "RateLimiter",
     "SimproAuthError",
     "SimproClient",
     "SimproError",
     "SimproNotFound",
     "SimproRateLimitError",
     "SimproValidationError",
+    "SlidingWindowRateLimiter",
     "__version__",
 ]

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/src/simpro/client.py

@@ -25,7 +25,8 @@ from simpro.exceptions import (
     SimproRateLimitError,
     SimproValidationError,
 )
-from simpro.resources import Companies, Customers, Jobs, Sites
+from simpro.ratelimit import DEFAULT_RATE_LIMIT, RateLimiter, SlidingWindowRateLimiter
+from simpro.resources import Companies, Customers, Jobs, Leads, Sites
 
 DEFAULT_TIMEOUT = 30.0
 
@@ -39,6 +40,14 @@ class SimproClient:
         api_key: API key bearer token (SimPro > Administration > API Keys).
         timeout: Per-request timeout in seconds.
         transport: Optional ``httpx`` transport override (testing/proxies).
+        rate_limit: Built-in pacing ceiling in requests/second. The
+            limiter starts no more than this many requests in any sliding
+            second. ``None`` disables pacing. Default 9.0 — just under
+            SimPro's documented limit of 10/second per build and IP,
+            which is shared across all integrations on the build.
+        rate_limiter: Explicit limiter, overriding ``rate_limit``. Pass
+            one shared instance to several clients pointed at the same
+            build so they count against a single budget.
     """
 
     def __init__(
@@ -48,9 +57,14 @@ class SimproClient:
         *,
         timeout: float = DEFAULT_TIMEOUT,
         transport: httpx.BaseTransport | None = None,
+        rate_limit: float | None = DEFAULT_RATE_LIMIT,
+        rate_limiter: RateLimiter | None = None,
     ) -> None:
         base = base_url.rstrip("/").removesuffix(API_PREFIX)
         self._base = base
+        if rate_limiter is None and rate_limit is not None:
+            rate_limiter = SlidingWindowRateLimiter(rate_limit)
+        self._limiter = rate_limiter
         self._http = httpx.Client(
             timeout=timeout,
             headers={
@@ -64,6 +78,7 @@ class SimproClient:
         self.customers = Customers(self)
         self.sites = Sites(self)
         self.jobs = Jobs(self)
+        self.leads = Leads(self)
 
     def __enter__(self) -> Self:
         return self
@@ -89,6 +104,8 @@ class SimproClient:
         e.g. ``/companies/0/customers/``. A 304 (If-Modified-Since hit) is
         returned to the caller as a normal response.
         """
+        if self._limiter is not None:
+            self._limiter.acquire()
         url = f"{self._base}{API_PREFIX}{path}"
         try:
             response = self._http.request(method, url, params=params, headers=headers)

simpro_py_sdk-0.2.0/src/simpro/ratelimit.py

@@ -0,0 +1,86 @@
+"""Client-side request pacing for SimPro's per-build rate limit.
+
+SimPro enforces 10 API calls per second, per build and per IP (announced
+August 2022, strictly enforced since 17 April 2025), and the budget is
+shared across every integration hitting the build — not just this client.
+``SlidingWindowRateLimiter`` keeps this SDK inside the ceiling by starting
+no more than ``rate_limit`` requests in any trailing second.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from typing import Protocol
+
+# SimPro's documented ceiling is 10 requests/second per build + IP, shared
+# with all other integrations and UI traffic on the build. The default
+# stays just under it to leave headroom for that other traffic.
+DEFAULT_RATE_LIMIT = 9.0
+
+Timer = Callable[[], float]
+Sleeper = Callable[[float], None]
+
+
+class RateLimiter(Protocol):
+    """Anything with an ``acquire()`` that blocks until a request may start.
+
+    Implement this protocol to plug in a custom limiter and pass it as
+    ``SimproClient(rate_limiter=...)``.
+    """
+
+    def acquire(self) -> None: ...
+
+
+class SlidingWindowRateLimiter:
+    """Start at most ``rate_limit`` acquisitions per second, sliding window.
+
+    Keeps timestamps of recent acquisitions in a trailing window; when the
+    window is full, ``acquire`` sleeps until the oldest timestamp expires.
+    A burst first spends the whole budget immediately, then requests pace
+    at ``rate_limit`` per second.
+
+    A lock serialises ``acquire`` across threads sharing one limiter, so
+    multi-threaded pulls through one client (or several clients on the
+    same build) count against a single budget.
+
+    Args:
+        rate_limit: Allowed acquisitions per second. Must be positive.
+            Values below 1 stretch the window (0.5 -> one call per 2s).
+        timer: Clock callable (seconds, monotonic); injectable for tests.
+        sleeper: Sleep callable; injectable for tests.
+    """
+
+    def __init__(
+        self,
+        rate_limit: float,
+        *,
+        timer: Timer = time.monotonic,
+        sleeper: Sleeper = time.sleep,
+    ) -> None:
+        if rate_limit <= 0:
+            raise ValueError(f"rate_limit must be positive, got {rate_limit!r}")
+        self._max_events = max(1, int(rate_limit))
+        self._window = self._max_events / rate_limit
+        self._timer = timer
+        self._sleeper = sleeper
+        self._starts: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        """Block until one acquisition fits inside the rate budget."""
+        with self._lock:
+            now = self._prune(self._timer())
+            while len(self._starts) >= self._max_events:
+                sleep_for = self._window - (now - self._starts[0])
+                if sleep_for > 0:
+                    self._sleeper(sleep_for)
+                now = self._prune(self._timer())
+            self._starts.append(now)
+
+    def _prune(self, now: float) -> float:
+        while self._starts and now - self._starts[0] >= self._window:
+            self._starts.popleft()
+        return now

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/src/simpro/resources/__init__.py

@@ -3,6 +3,7 @@
 from simpro.resources.companies import Companies
 from simpro.resources.customers import Customers
 from simpro.resources.jobs import Jobs
+from simpro.resources.leads import Leads
 from simpro.resources.sites import Sites
 
-__all__ = ["Companies", "Customers", "Jobs", "Sites"]
+__all__ = ["Companies", "Customers", "Jobs", "Leads", "Sites"]

simpro_py_sdk-0.2.0/src/simpro/resources/leads.py

@@ -0,0 +1,16 @@
+"""Leads endpoints: ``GET /api/v1.0/companies/{companyID}/leads/``.
+
+List items are minimal (``ID`` + nested ``Customer``/``Site`` objects);
+extra fields (``LeadName``, ``Stage``, dates, ``Forecast``…) come via the
+``columns`` csv query param — e.g. ``client.leads.list(0, columns="ID,LeadName,Stage")``.
+"""
+
+from __future__ import annotations
+
+from simpro.resources._base import CompanyScopedResource
+
+
+class Leads(CompanyScopedResource):
+    """Leads (pre-sale requests for quote)."""
+
+    _resource = "leads"

simpro_py_sdk-0.2.0/tests/test_rate_limiting.py

@@ -0,0 +1,96 @@
+"""Client-level rate limiting: built-in pacing, injection, opt-out."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+import pytest
+
+from simpro import (
+    DEFAULT_RATE_LIMIT,
+    RateLimiter,
+    SimproClient,
+    SlidingWindowRateLimiter,
+)
+
+
+class FakeClock:
+    """Deterministic timer/sleeper pair: sleeping advances the clock."""
+
+    def __init__(self) -> None:
+        self.now = 1000.0
+        self.sleeps: list[float] = []
+
+    def timer(self) -> float:
+        return self.now
+
+    def sleeper(self, seconds: float) -> None:
+        self.sleeps.append(seconds)
+        self.now += seconds
+
+
+class CountingLimiter:
+    """Duck-typed RateLimiter that records acquire() calls."""
+
+    def __init__(self) -> None:
+        self.acquires = 0
+
+    def acquire(self) -> None:
+        self.acquires += 1
+
+
+def ok_handler(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(200, json=[])
+
+
+def make_client(**kwargs: Any) -> SimproClient:
+    kwargs.setdefault("transport", httpx.MockTransport(ok_handler))
+    return SimproClient("https://t.simprosuite.com", "k", **kwargs)
+
+
+def test_default_client_paces_at_default_rate_limit() -> None:
+    client = make_client()
+    assert isinstance(client._limiter, SlidingWindowRateLimiter)
+    assert DEFAULT_RATE_LIMIT == 9.0
+
+
+def test_rate_limit_none_disables_pacing() -> None:
+    client = make_client(rate_limit=None)
+    assert client._limiter is None
+    for _ in range(50):  # rapid burst: no exception, and no limiter to sleep
+        client.companies.list()
+
+
+def test_invalid_rate_limit_rejected() -> None:
+    with pytest.raises(ValueError, match="positive"):
+        make_client(rate_limit=0)
+
+
+def test_requests_are_paced_by_injected_limiter() -> None:
+    clock = FakeClock()
+    limiter = SlidingWindowRateLimiter(9, timer=clock.timer, sleeper=clock.sleeper)
+    client = make_client(rate_limiter=limiter)
+    for _ in range(10):
+        client.companies.list()
+    # 9 free at t=1000; the 10th waits one second for the window to clear.
+    assert clock.sleeps == [1.0]
+
+
+def test_limiter_shared_across_clients_shares_one_budget() -> None:
+    clock = FakeClock()
+    limiter = SlidingWindowRateLimiter(9, timer=clock.timer, sleeper=clock.sleeper)
+    a = make_client(rate_limiter=limiter)
+    b = make_client(rate_limiter=limiter)
+    for _ in range(9):
+        a.companies.list()
+    b.companies.list()  # 10th acquisition overall: must wait.
+    assert clock.sleeps == [1.0]
+
+
+def test_custom_limiter_protocol_accepted() -> None:
+    limiter: RateLimiter = CountingLimiter()
+    client = make_client(rate_limiter=limiter)
+    client.companies.list()
+    client.customers.get(0, 7)
+    assert limiter.acquires == 2

simpro_py_sdk-0.2.0/tests/test_ratelimit.py

@@ -0,0 +1,72 @@
+"""Sliding-window rate limiter unit behaviour (fake clock, no real sleeps)."""
+
+from __future__ import annotations
+
+import pytest
+
+from simpro.ratelimit import DEFAULT_RATE_LIMIT, SlidingWindowRateLimiter
+
+
+class FakeClock:
+    """Deterministic timer/sleeper pair: sleeping advances the clock."""
+
+    def __init__(self) -> None:
+        self.now = 1000.0
+        self.sleeps: list[float] = []
+
+    def timer(self) -> float:
+        return self.now
+
+    def sleeper(self, seconds: float) -> None:
+        self.sleeps.append(seconds)
+        self.now += seconds
+
+
+def make_limiter(rate: float) -> tuple[SlidingWindowRateLimiter, FakeClock]:
+    clock = FakeClock()
+    return SlidingWindowRateLimiter(rate, timer=clock.timer, sleeper=clock.sleeper), clock
+
+
+def test_default_rate_limit_just_under_simpro_ceiling() -> None:
+    # SimPro's documented ceiling is 10/s shared across ALL integrations on
+    # the build — the default leaves headroom for that other traffic.
+    assert DEFAULT_RATE_LIMIT == 9.0
+
+
+def test_burst_up_to_budget_needs_no_sleep() -> None:
+    limiter, clock = make_limiter(9)
+    for _ in range(9):
+        limiter.acquire()
+    assert clock.sleeps == []
+
+
+def test_request_beyond_budget_waits_for_oldest_to_expire() -> None:
+    limiter, clock = make_limiter(9)
+    for _ in range(9):
+        limiter.acquire()
+    limiter.acquire()
+    # Window is 1.0s wide and full of timestamps at t=1000: the 10th call
+    # must wait exactly one second for them to age out.
+    assert clock.sleeps == [1.0]
+
+
+def test_budget_resets_each_window_for_long_pulls() -> None:
+    limiter, clock = make_limiter(3)
+    for _ in range(12):
+        limiter.acquire()
+    # 3 free at t=1000, then one 1s wait per exhausted window: calls 4, 7, 10.
+    assert clock.sleeps == [1.0, 1.0, 1.0]
+
+
+def test_fractional_rate_stretches_the_window() -> None:
+    limiter, clock = make_limiter(0.5)  # -> 1 event per 2.0s window
+    limiter.acquire()
+    limiter.acquire()
+    assert clock.sleeps == [2.0]
+
+
+def test_non_positive_rate_limit_rejected() -> None:
+    with pytest.raises(ValueError, match="positive"):
+        SlidingWindowRateLimiter(0)
+    with pytest.raises(ValueError, match="positive"):
+        SlidingWindowRateLimiter(-5)

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/tests/test_resources.py

@@ -11,7 +11,9 @@ from simpro import SimproClient, SimproNotFound
 
 
 def make_client(handler: Any) -> SimproClient:
-    return SimproClient("https://t.simprosuite.com", "k", transport=httpx.MockTransport(handler))
+    return SimproClient(
+        "https://t.simprosuite.com", "k", transport=httpx.MockTransport(handler)
+    )
 
 
 def full_url(request: httpx.Request) -> str:
@@ -72,7 +74,9 @@ def test_customer_get_falls_back_to_individuals_on_404() -> None:
         requests.append(request)
         if request.url.path.endswith("/customers/companies/7"):
             return httpx.Response(404, json={"message": "Not found"})
-        return httpx.Response(200, json={"ID": 7, "GivenName": "Jane", "FamilyName": "Doe"})
+        return httpx.Response(
+            200, json={"ID": 7, "GivenName": "Jane", "FamilyName": "Doe"}
+        )
 
     client = make_client(handler)
     result = client.customers.get(0, 7)
@@ -101,8 +105,14 @@ def test_sites_and_jobs_get_urls() -> None:
     client = make_client(handler)
     client.sites.get(0, 12)
     client.jobs.get(0, 34)
-    assert str(requests[0].url) == "https://t.simprosuite.com/api/v1.0/companies/0/sites/12"
-    assert full_url(requests[1]) == "https://t.simprosuite.com/api/v1.0/companies/0/jobs/34"
+    assert (
+        str(requests[0].url)
+        == "https://t.simprosuite.com/api/v1.0/companies/0/sites/12"
+    )
+    assert (
+        full_url(requests[1])
+        == "https://t.simprosuite.com/api/v1.0/companies/0/jobs/34"
+    )
 
 
 def test_sites_and_jobs_list_urls() -> None:
@@ -115,5 +125,51 @@ def test_sites_and_jobs_list_urls() -> None:
     client = make_client(handler)
     client.sites.list(0)
     client.jobs.list(0)
-    assert full_url(requests[0]) == "https://t.simprosuite.com/api/v1.0/companies/0/sites/"
-    assert full_url(requests[1]) == "https://t.simprosuite.com/api/v1.0/companies/0/jobs/"
+    assert (
+        full_url(requests[0]) == "https://t.simprosuite.com/api/v1.0/companies/0/sites/"
+    )
+    assert (
+        full_url(requests[1]) == "https://t.simprosuite.com/api/v1.0/companies/0/jobs/"
+    )
+
+
+def test_leads_list_url_and_columns_filter() -> None:
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return httpx.Response(200, json=[])
+
+    client = make_client(handler)
+    client.leads.list(0, columns="ID,LeadName,Stage")
+    assert (
+        full_url(requests[0]) == "https://t.simprosuite.com/api/v1.0/companies/0/leads/"
+    )
+    assert requests[0].url.params["columns"] == "ID,LeadName,Stage"
+
+
+def test_leads_get_url() -> None:
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        return httpx.Response(200, json={"ID": 5, "Stage": "Open"})
+
+    client = make_client(handler)
+    assert client.leads.get(0, 5)["Stage"] == "Open"
+    assert (
+        full_url(requests[0])
+        == "https://t.simprosuite.com/api/v1.0/companies/0/leads/5"
+    )
+
+
+def test_leads_iter_all_walks_pages() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        page = request.url.params.get("page", "1")
+        body = [{"ID": 1}, {"ID": 2}] if page == "1" else [{"ID": 3}]
+        return httpx.Response(200, json=body, headers={"Result-Pages": "2"})
+
+    client = SimproClient(
+        "https://t.simprosuite.com", "k", transport=httpx.MockTransport(handler)
+    )
+    assert [lead["ID"] for lead in client.leads.iter_all(0)] == [1, 2, 3]

{simpro_py_sdk-0.1.1 → simpro_py_sdk-0.2.0}/uv.lock

@@ -399,7 +399,7 @@ wheels = [
 
 [[package]]
 name = "simpro-py-sdk"
-version = "0.1.1"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },