workwire 0.2.0__tar.gz → 0.4.0__tar.gz

{workwire-0.2.0 → workwire-0.4.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.0](https://github.com/workwire/workwire-python/compare/v0.3.0...v0.4.0) (2026-10-18)
+
+
+### Features
+
+* **WOR-471:** party jobs carry location_name, location_kind and location_path (backend v1.54.0) ([#20](https://github.com/workwire/workwire-python/issues/20)) ([14f1c08](https://github.com/workwire/workwire-python/commit/14f1c083a600747521087a3b4b572d44c69934ef))
+
+## [0.3.0](https://github.com/workwire/workwire-python/compare/v0.2.0...v0.3.0) (2026-10-16)
+
+
+### Features
+
+* **WOR-446:** wrap the v1.53.0 surface — project locations, party scope, Jobs lens and org-local fields ([#17](https://github.com/workwire/workwire-python/issues/17)) ([1072284](https://github.com/workwire/workwire-python/commit/107228458633e5f79266684055d3405d6c69dc91))
+
 ## [0.2.0](https://github.com/workwire/workwire-python/compare/v0.1.0...v0.2.0) (2026-09-04)
 
 

{workwire-0.2.0 → workwire-0.4.0}/PKG-INFO

@@ -1,36 +1,15 @@
 Metadata-Version: 2.5
 Name: workwire
-Version: 0.2.0
+Version: 0.4.0
 Summary: Official Python SDK for the Workwire API
 Project-URL: Homepage, https://github.com/workwire/workwire-python
 Project-URL: Changelog, https://github.com/workwire/workwire-python/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/workwire/workwire-python/issues
 Author-email: Workwire <support@workwire.com>
-License: MIT License
-        
-        Copyright (c) 2026 Workwire Inc.
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
+License-Expression: MIT
 License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -117,6 +96,40 @@ The quickstart is runnable as a script:
 drafts the wire above against a partnership you name, and only sends it
 with `--go-live`.
 
+## Locations and Jobs
+
+Every project has a location tree under one `site` root
+(`project.root_location_id`). A party's scope is the locations its work
+covers, and it gets one Job (`JOB-…`) per scope location. A Job's
+`your_reference`, `quantity` and `checked_at` are your org's own, never
+shown to the other side.
+
+```python
+from workwire import LocationNode, Party
+
+project = client.projects.create(name="Elm St. Townhomes", template="development", locations=[
+    LocationNode("building", "Bldg A", children=[LocationNode("floor", "Level 1")]),
+])
+tree = client.projects.locations.list(project.id).data  # the site root first
+level_1 = next(loc for loc in tree if loc.name == "Level 1")
+client.wires.create(project_id=project.id, title="Drywall — Level 1", parties=[Party.partnered(
+    partnership_id=partnership.id, trade="Drywall", scope_text="Level 1.",
+    contract_value="40000.00", scope_location_ids=[level_1.id],  # one Job per scope location
+)])
+page = client.jobs.list(project=project.id)  # page.quantity_unit is your org's unit
+client.jobs.update(page.data[0].id, your_reference="PO-4471-A", quantity="12.5", checked=True)
+```
+
+A party Job — each of `client.wires.retrieve(...).parties[i].jobs`, and the
+one `client.jobs.update` returns — carries `location_name`, `location_kind` and
+`location_path` (the ancestors, root first), so a sub reads its scope without
+the GC's tree; `client.jobs.list` rows had them already.
+
+Leave `scope_location_ids` out to scope a party to the whole project.
+`client.jobs.update` sends only the fields you pass: leave one out to keep
+it, pass `None` to clear it. Add to a tree later with
+`client.projects.locations.create(...)` or `.create_batch(...)`.
+
 ## Authentication
 
 An org admin issues an API key in the Workwire dashboard under **Settings →
@@ -176,8 +189,9 @@ idempotency codes), `RateLimitError` (429), `APIError` (5xx). Key on
 
 ## Retries and idempotency
 
-Every `POST` automatically carries an `Idempotency-Key` (a fresh UUID, or
-pass `idempotency_key=` to control replay across your own process restarts).
+Every `POST` and `PATCH` automatically carries an `Idempotency-Key` (a fresh
+UUID, or pass `idempotency_key=` to control replay across your own process
+restarts).
 That makes retries safe, so the SDK retries for you: connection errors,
 timeouts, 429s (honoring `Retry-After`), 5xx responses, and the one
 retryable 409 — `idempotency_in_flight`, where the API asks you to retry
@@ -202,6 +216,9 @@ for wire in client.wires.list(state="live").auto_paging_iter():
     ...
 ```
 
+A list's other envelope fields ride on the page: `client.jobs.list()`
+returns a `JobPage` with `.quantity_unit`.
+
 ## Responses
 
 Responses are typed objects with attribute access, `.to_dict()`, and

{workwire-0.2.0 → workwire-0.4.0}/README.md

@@ -73,6 +73,40 @@ The quickstart is runnable as a script:
 drafts the wire above against a partnership you name, and only sends it
 with `--go-live`.
 
+## Locations and Jobs
+
+Every project has a location tree under one `site` root
+(`project.root_location_id`). A party's scope is the locations its work
+covers, and it gets one Job (`JOB-…`) per scope location. A Job's
+`your_reference`, `quantity` and `checked_at` are your org's own, never
+shown to the other side.
+
+```python
+from workwire import LocationNode, Party
+
+project = client.projects.create(name="Elm St. Townhomes", template="development", locations=[
+    LocationNode("building", "Bldg A", children=[LocationNode("floor", "Level 1")]),
+])
+tree = client.projects.locations.list(project.id).data  # the site root first
+level_1 = next(loc for loc in tree if loc.name == "Level 1")
+client.wires.create(project_id=project.id, title="Drywall — Level 1", parties=[Party.partnered(
+    partnership_id=partnership.id, trade="Drywall", scope_text="Level 1.",
+    contract_value="40000.00", scope_location_ids=[level_1.id],  # one Job per scope location
+)])
+page = client.jobs.list(project=project.id)  # page.quantity_unit is your org's unit
+client.jobs.update(page.data[0].id, your_reference="PO-4471-A", quantity="12.5", checked=True)
+```
+
+A party Job — each of `client.wires.retrieve(...).parties[i].jobs`, and the
+one `client.jobs.update` returns — carries `location_name`, `location_kind` and
+`location_path` (the ancestors, root first), so a sub reads its scope without
+the GC's tree; `client.jobs.list` rows had them already.
+
+Leave `scope_location_ids` out to scope a party to the whole project.
+`client.jobs.update` sends only the fields you pass: leave one out to keep
+it, pass `None` to clear it. Add to a tree later with
+`client.projects.locations.create(...)` or `.create_batch(...)`.
+
 ## Authentication
 
 An org admin issues an API key in the Workwire dashboard under **Settings →
@@ -132,8 +166,9 @@ idempotency codes), `RateLimitError` (429), `APIError` (5xx). Key on
 
 ## Retries and idempotency
 
-Every `POST` automatically carries an `Idempotency-Key` (a fresh UUID, or
-pass `idempotency_key=` to control replay across your own process restarts).
+Every `POST` and `PATCH` automatically carries an `Idempotency-Key` (a fresh
+UUID, or pass `idempotency_key=` to control replay across your own process
+restarts).
 That makes retries safe, so the SDK retries for you: connection errors,
 timeouts, 429s (honoring `Retry-After`), 5xx responses, and the one
 retryable 409 — `idempotency_in_flight`, where the API asks you to retry
@@ -158,6 +193,9 @@ for wire in client.wires.list(state="live").auto_paging_iter():
     ...
 ```
 
+A list's other envelope fields ride on the page: `client.jobs.list()`
+returns a `JobPage` with `.quantity_unit`.
+
 ## Responses
 
 Responses are typed objects with attribute access, `.to_dict()`, and

{workwire-0.2.0 → workwire-0.4.0}/pyproject.toml

@@ -4,17 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workwire"
-version = "0.2.0"
+version = "0.4.0"
 description = "Official Python SDK for the Workwire API"
 readme = "README.md"
-license = { file = "LICENSE" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "Workwire", email = "support@workwire.com" }]
 requires-python = ">=3.10"
 dependencies = ["httpx>=0.24,<1"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.10",

{workwire-0.2.0 → workwire-0.4.0}/src/workwire/__init__.py

@@ -40,23 +40,35 @@ from ._client import (
     BaseClient,
 )
 from ._models import (
+    NOT_GIVEN,
     PO,
     ColdInvite,
+    JobMilestones,
+    JobPage,
+    JobPathLocation,
+    JobRow,
+    Location,
+    LocationBatch,
+    LocationKind,
+    LocationNode,
     Milestone,
     MilestoneSpec,
+    NotGiven,
     Page,
     Partnership,
     PartnershipDetail,
     PartnershipListItem,
     Party,
+    PartyJob,
     Project,
+    ProjectTemplate,
     Wire,
     WireListItem,
     WireParty,
     WorkwireObject,
 )
 from ._version import __version__
-from .resources import Partnerships, Projects, Wires
+from .resources import Jobs, Partnerships, Projects, Wires
 
 __all__ = [
     "Workwire",
@@ -66,18 +78,30 @@ __all__ = [
     "Party",
     "MilestoneSpec",
     "ColdInvite",
+    "LocationNode",
+    "LocationKind",
+    "ProjectTemplate",
+    "NOT_GIVEN",
+    "NotGiven",
     # response types
     "WorkwireObject",
     "Page",
+    "JobPage",
     "Project",
+    "Location",
+    "LocationBatch",
     "Wire",
     "WireListItem",
     "WireParty",
+    "PartyJob",
     "Milestone",
     "PO",
     "Partnership",
     "PartnershipDetail",
     "PartnershipListItem",
+    "JobRow",
+    "JobPathLocation",
+    "JobMilestones",
 ]
 
 
@@ -112,6 +136,7 @@ class Workwire(BaseClient):
         self.projects = Projects(self)
         self.wires = Wires(self)
         self.partnerships = Partnerships(self)
+        self.jobs = Jobs(self)
 
     def request(
         self,

{workwire-0.2.0 → workwire-0.4.0}/src/workwire/_client.py

@@ -2,9 +2,9 @@
 
 The transport invariants live here, and the test suite holds them:
 
-- Every POST carries an ``Idempotency-Key`` — caller-supplied or a generated
-  UUIDv4 — and every retry of that POST resends the **same key and the same
-  serialized bytes**. The server's replay fingerprint is a raw-byte hash of
+- Every POST and PATCH carries an ``Idempotency-Key`` — caller-supplied or a
+  generated UUIDv4 — and every retry of that request resends the **same key
+  and the same serialized bytes**. The server's replay fingerprint is a raw-byte hash of
   the body, so the body is serialized exactly once per logical request and
   the bytes are reused verbatim across attempts.
 - Retries: connection errors, timeouts, 429 (honoring ``Retry-After``),
@@ -46,6 +46,10 @@ _RETRY_AFTER_CAP = 30.0
 
 _RETRYABLE_STATUSES = frozenset({429})  # plus every 5xx, handled by range
 
+# The methods the served idempotency layer guards ("Every POST and PATCH
+# accepts an optional Idempotency-Key header").
+_KEYED_METHODS = frozenset({"POST", "PATCH"})
+
 
 class BaseClient:
     """HTTP plumbing shared by every resource. Not public API — customers
@@ -150,7 +154,7 @@ class BaseClient:
             content = json.dumps(json_body, separators=(",", ":")).encode("utf-8")
             headers["Content-Type"] = "application/json"
 
-        if method == "POST":
+        if method in _KEYED_METHODS:
             headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
 
         attempt = 0

{workwire-0.2.0 → workwire-0.4.0}/src/workwire/_coverage.py

@@ -19,14 +19,24 @@ from . import _models
 # operationId → coverage entry.
 # request_fields: top-level request-body properties the SDK can send.
 # query_params: query parameters the SDK can send.
-# response_schema → the model whose annotations mirror it (for list
-# operations: the page envelope fields are items_key + next_cursor and the
-# item schema maps to item_model).
+# response_model: the model the operation's response schema maps to.
+# For paginated lists: the envelope is items_key + next_cursor, plus any
+# extra field page_model annotates (default Page, which annotates none), and
+# the item schema maps to list_item_model. For a one-shot list envelope
+# (no cursor), envelope_key names its one field and envelope_item_model the
+# item schema's model.
 OPERATIONS: dict[str, dict[str, object]] = {
     "createProject": {
         "method": "POST",
         "path": "/v1/projects",
-        "request_fields": {"name", "address", "project_code", "external_metadata"},
+        "request_fields": {
+            "name",
+            "address",
+            "project_code",
+            "external_metadata",
+            "template",
+            "locations",
+        },
         "query_params": set(),
         "response_model": _models.Project,
     },
@@ -45,6 +55,29 @@ OPERATIONS: dict[str, dict[str, object]] = {
         "query_params": set(),
         "response_model": _models.Project,
     },
+    "listProjectLocations": {
+        "method": "GET",
+        "path": "/v1/projects/{id}/locations",
+        "request_fields": set(),
+        "query_params": {"cursor", "limit"},
+        "list_item_model": _models.Location,
+        "items_key": "locations",
+    },
+    "createProjectLocation": {
+        "method": "POST",
+        "path": "/v1/projects/{id}/locations",
+        "request_fields": {"parent_id", "kind", "name"},
+        "query_params": set(),
+        "response_model": _models.Location,
+    },
+    "createProjectLocationsBatch": {
+        "method": "POST",
+        "path": "/v1/projects/{id}/locations/batch",
+        "request_fields": {"parent_id", "locations"},
+        "query_params": set(),
+        "envelope_item_model": _models.Location,
+        "envelope_key": "locations",
+    },
     "createWire": {
         "method": "POST",
         "path": "/v1/wires",
@@ -102,6 +135,22 @@ OPERATIONS: dict[str, dict[str, object]] = {
         "query_params": set(),
         "response_model": _models.PartnershipDetail,
     },
+    "listJobs": {
+        "method": "GET",
+        "path": "/v1/jobs",
+        "request_fields": set(),
+        "query_params": {"status", "project", "counterparty", "checked", "cursor", "limit"},
+        "list_item_model": _models.JobRow,
+        "items_key": "jobs",
+        "page_model": _models.JobPage,
+    },
+    "updateJob": {
+        "method": "PATCH",
+        "path": "/v1/jobs/{id}",
+        "request_fields": {"your_reference", "quantity", "checked"},
+        "query_params": set(),
+        "response_model": _models.PartyJob,
+    },
 }
 
 # Component schema → the SDK type whose fields mirror it. Request-side types
@@ -109,8 +158,11 @@ OPERATIONS: dict[str, dict[str, object]] = {
 REQUEST_SCHEMA_TYPES: dict[str, type] = {
     "ComposeMilestone": _models.MilestoneSpec,
     "ColdInvitePartnership": _models.ColdInvite,
+    "LocationNode": _models.LocationNode,
 }
 
+# A dotted key names an inline object schema: "JobRow.milestones" is the
+# object JobRow's milestones property declares in place.
 RESPONSE_SCHEMA_MODELS: dict[str, type[_models.WorkwireObject]] = {
     "Project": _models.Project,
     "Wire": _models.Wire,
@@ -121,6 +173,11 @@ RESPONSE_SCHEMA_MODELS: dict[str, type[_models.WorkwireObject]] = {
     "Partnership": _models.Partnership,
     "PartnershipDetail": _models.PartnershipDetail,
     "PartnershipListItem": _models.PartnershipListItem,
+    "Location": _models.Location,
+    "PartyJob": _models.PartyJob,
+    "JobPathLocation": _models.JobPathLocation,
+    "JobRow": _models.JobRow,
+    "JobRow.milestones": _models.JobMilestones,
 }
 
 # ComposeParty is special-cased in the drift check: its fields are split
@@ -133,4 +190,5 @@ COMPOSE_PARTY_FIELDS = {
     "scope_text",
     "contract_value",
     "milestones",
+    "scope_location_ids",
 }

{workwire-0.2.0 → workwire-0.4.0}/src/workwire/_models.py

@@ -8,16 +8,19 @@ annotations on each subclass mirror the served response schema field-for-field
 they are documentation and typing aids, not a filter.
 
 Request-side constructors (:class:`Party`, :class:`MilestoneSpec`,
-:class:`ColdInvite`) make the composer contract structural: required fields
-are required arguments, and the partnered-XOR-cold-invite choice is which
-constructor you called.
+:class:`ColdInvite`, :class:`LocationNode`) make the composer contract
+structural: required fields are required arguments, the partnered-XOR-cold-
+invite choice is which constructor you called, and a location tree's nesting
+is the nesting of the objects you built. :data:`NOT_GIVEN` marks an argument
+as *not passed* where the API tells absent apart from ``null``.
 """
 
 from __future__ import annotations
 
 from collections.abc import Iterator, Mapping, Sequence
+from collections.abc import Set as AbstractSet
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Literal
 
 __all__ = [
     "WorkwireObject",
@@ -30,9 +33,22 @@ __all__ = [
     "Partnership",
     "PartnershipDetail",
     "PartnershipListItem",
+    "Location",
+    "LocationBatch",
+    "PartyJob",
+    "JobPathLocation",
+    "JobMilestones",
+    "JobRow",
+    "Page",
+    "JobPage",
     "Party",
     "MilestoneSpec",
     "ColdInvite",
+    "LocationNode",
+    "LocationKind",
+    "ProjectTemplate",
+    "NotGiven",
+    "NOT_GIVEN",
 ]
 
 
@@ -51,7 +67,8 @@ class WorkwireObject:
     served ``null``.
     """
 
-    # Nested field name → WorkwireObject subclass to wrap list items with.
+    # Nested field name → WorkwireObject subclass to wrap the field's object
+    # (or, for a list, each of its items) with.
     _nested: Mapping[str, type[WorkwireObject]] = {}
 
     def __init__(self, data: Mapping[str, Any], *, request_id: str | None = None) -> None:
@@ -93,8 +110,12 @@ class WorkwireObject:
 
     def _wrap(self, name: str, value: Any) -> Any:
         cls = self._nested.get(name)
-        if cls is not None and isinstance(value, list):
+        if cls is None:
+            return value
+        if isinstance(value, list):
             return [cls(item) if isinstance(item, Mapping) else item for item in value]
+        if isinstance(value, Mapping):
+            return cls(value)
         return value
 
     def __setattr__(self, name: str, value: Any) -> None:
@@ -150,8 +171,40 @@ class PO(WorkwireObject):
     created_at: str
 
 
+class JobPathLocation(WorkwireObject):
+    """One ancestor on a Job's ``location_path`` (a :class:`PartyJob`'s or a
+    :class:`JobRow`'s)."""
+
+    id: str
+    name: str
+    kind: str
+
+
+class PartyJob(WorkwireObject):
+    """One Job on a wire party (``JOB-…``) — the party's work at one location
+    of its scope. ``location_name``, ``location_kind`` and ``location_path``
+    (the ancestors, root first; empty at the site root) are the server's
+    description of where the Job sits in the GC's tree; ``your_reference``,
+    ``quantity`` and ``checked_at`` are **your org's own** fields, never the
+    other side's."""
+
+    _nested = {"location_path": JobPathLocation}
+
+    id: str
+    display_id: str
+    location_id: str
+    location_name: str
+    location_kind: str
+    location_path: list[JobPathLocation]
+    your_reference: str | None
+    quantity: str | None
+    checked_at: str | None
+    archived_at: str | None
+    created_at: str
+
+
 class WireParty(WorkwireObject):
-    _nested = {"milestones": Milestone, "pos": PO}
+    _nested = {"milestones": Milestone, "pos": PO, "jobs": PartyJob}
 
     id: str
     wire_id: str
@@ -177,6 +230,8 @@ class WireParty(WorkwireObject):
     milestones: list[Milestone] | None
     pos: list[PO] | None
     amendment_count: int | None
+    scope_locations: list[str] | None
+    jobs: list[PartyJob] | None
 
 
 class Project(WorkwireObject):
@@ -187,6 +242,7 @@ class Project(WorkwireObject):
     project_code: str | None
     status: str
     external_metadata: dict[str, Any] | None
+    root_location_id: str | None
     created_at: str
     updated_at: str
 
@@ -255,10 +311,108 @@ class PartnershipListItem(WorkwireObject):
     attested_at: str | None
 
 
+class Location(WorkwireObject):
+    """One location of a project's tree. ``path`` is the ancestor ids, root
+    first (empty on the root, whose ``parent_id`` is ``None``)."""
+
+    id: str
+    project_id: str
+    parent_id: str | None
+    kind: str
+    name: str
+    path: list[str]
+    archived_at: str | None
+    created_at: str
+    updated_at: str
+
+
+class LocationBatch(list[Location]):
+    """What ``projects.locations.create_batch`` returns: a plain ``list`` of
+    the created :class:`Location` objects, flat, every parent before its
+    children. The served envelope stays reachable — ``request_id`` and
+    ``to_dict()`` are the response's — so a field the API adds beside
+    ``locations`` is kept, not dropped."""
+
+    def __init__(self, data: Mapping[str, Any], *, request_id: str | None = None) -> None:
+        super().__init__(
+            Location(item, request_id=request_id) if isinstance(item, Mapping) else item
+            for item in data.get("locations") or []
+        )
+        self._data = dict(data)
+        self._request_id = request_id
+
+    @property
+    def request_id(self) -> str | None:
+        return self._request_id
+
+    def to_dict(self) -> dict[str, Any]:
+        import copy
+
+        return copy.deepcopy(self._data)
+
+
+class JobMilestones(WorkwireObject):
+    """A Job row's party milestone counts (repeated across the party's Jobs)."""
+
+    confirmed: int
+    total: int
+
+
+class JobRow(WorkwireObject):
+    """One row of :meth:`Jobs.list`: the Job with its party, wire, project,
+    location and counterparty context. ``your_reference``, ``quantity`` and
+    ``checked_at`` are your org's own fields, never the other side's."""
+
+    _nested = {"location_path": JobPathLocation, "milestones": JobMilestones}
+
+    id: str
+    display_id: str
+    your_reference: str | None
+    quantity: str | None
+    checked_at: str | None
+    wire_party_id: str
+    party_state: str
+    wire_id: str
+    wire_display_id: str
+    wire_state: str
+    project_id: str
+    project_name: str
+    location_id: str
+    location_name: str
+    location_kind: str
+    location_path: list[JobPathLocation]
+    counterparty_org_id: str | None
+    counterparty_name: str | None
+    milestones: JobMilestones
+    archived_at: str | None
+    created_at: str
+
+
 # --------------------------------------------------------------------------
 # Request-side typed constructors
 # --------------------------------------------------------------------------
 
+# The served enums, as typing aids — the server stays the referee (an unknown
+# kind is ``422 invalid_location_kind``). ``site`` is the root's alone,
+# created with the project, so it is not a kind you can send.
+LocationKind = Literal["house", "building", "floor", "unit", "room", "common_area"]
+ProjectTemplate = Literal["development", "single_home", "renovation"]
+
+
+class NotGiven:
+    """The type of :data:`NOT_GIVEN`: *this argument was not passed* — kept
+    apart from an explicit ``None``, which the API reads as *clear the
+    field*. Falsy, so ``if value:`` reads it as unset."""
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()
+
 
 @dataclass(frozen=True)
 class MilestoneSpec:
@@ -297,6 +451,57 @@ class ColdInvite:
         return payload
 
 
+@dataclass(frozen=True)
+class LocationNode:
+    """One location of a tree being created — its ``kind``, its ``name``, and
+    the ``children`` nested beneath it. Any nesting is allowed (a building
+    may hold floors or units directly). At most 500 locations per request,
+    counted over every level."""
+
+    kind: LocationKind
+    name: str
+    children: Sequence[LocationNode] | None = None
+
+    def __post_init__(self) -> None:
+        if self.children is None:
+            return
+        if isinstance(self.children, LocationNode):
+            raise TypeError("children must be a list of workwire.LocationNode")
+        children = tuple(_ordered(self.children, "children"))  # frozen all the way down
+        for child in children:
+            if not isinstance(child, LocationNode):
+                raise TypeError("children must be workwire.LocationNode objects")
+        object.__setattr__(self, "children", children)
+
+    def to_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"kind": self.kind, "name": self.name}
+        if self.children is not None:
+            payload["children"] = [child.to_payload() for child in self.children]
+        return payload
+
+
+def _ordered(items: Any, what: str) -> list[Any]:
+    # Read exactly once (an iterator must not be spent by a check). A str is
+    # a sequence of characters; a set or mapping has no order that holds
+    # across processes, so the same call would serialize to different bytes —
+    # a different idempotency fingerprint on a replay.
+    if isinstance(items, (str, bytes, AbstractSet, Mapping)):
+        raise TypeError(f"{what} must be a list or tuple, not {type(items).__name__}")
+    return list(items)
+
+
+def _location_payloads(locations: Sequence[LocationNode]) -> list[dict[str, Any]]:
+    nodes = _ordered(locations, "locations")
+    for node in nodes:
+        if not isinstance(node, LocationNode):
+            raise TypeError("locations must be built with workwire.LocationNode(...)")
+    return [node.to_payload() for node in nodes]
+
+
+def _scope_location_ids(ids: Sequence[str]) -> list[str]:
+    return _ordered(ids, "scope_location_ids")
+
+
 class Party:
     """One party on a wire being composed.
 
@@ -309,6 +514,12 @@ class Party:
 
     ``contract_value`` is a decimal string, e.g. ``"125000.00"``, visible
     only to the two sides of this party.
+
+    ``scope_location_ids`` names the locations of the project's tree this
+    party's work covers — the party gets one Job per location. Leave it
+    ``None`` (not sent) for the whole project. An empty list is sent as
+    given, never dropped — dropping it would widen the scope to the whole
+    project — and the server refuses it (``scope_empty``).
     """
 
     def __init__(self, payload: dict[str, Any], *, _guard: object = None) -> None:
@@ -327,6 +538,7 @@ class Party:
         scope_text: str,
         contract_value: str,
         milestones: Sequence[MilestoneSpec] | None = None,
+        scope_location_ids: Sequence[str] | None = None,
     ) -> Party:
         payload: dict[str, Any] = {
             "partnership_id": partnership_id,
@@ -336,6 +548,8 @@ class Party:
         }
         if milestones:
             payload["milestones"] = [m.to_payload() for m in milestones]
+        if scope_location_ids is not None:
+            payload["scope_location_ids"] = _scope_location_ids(scope_location_ids)
         return cls(payload, _guard=_PARTY_GUARD)
 
     @classmethod
@@ -348,6 +562,7 @@ class Party:
         scope_text: str,
         contract_value: str,
         milestones: Sequence[MilestoneSpec] | None = None,
+        scope_location_ids: Sequence[str] | None = None,
     ) -> Party:
         payload: dict[str, Any] = {
             "cold_invite": {
@@ -360,6 +575,8 @@ class Party:
         }
         if milestones:
             payload["milestones"] = [m.to_payload() for m in milestones]
+        if scope_location_ids is not None:
+            payload["scope_location_ids"] = _scope_location_ids(scope_location_ids)
         return cls(payload, _guard=_PARTY_GUARD)
 
     def to_payload(self) -> dict[str, Any]:
@@ -375,12 +592,14 @@ class Page(WorkwireObject):
     """One page of a cursor-paginated list.
 
     ``data`` is the page's items as typed objects (whatever the served key —
-    ``projects``, ``wires``, ``partnerships``); ``next_cursor`` is the served
-    cursor (``None`` at the end); ``has_more`` derives from it. Iteration
-    ends **only** on a null cursor — a short page with a live cursor is a
-    legal middle page.
-
-    ``auto_paging_iter()`` walks the whole list transparently.
+    ``projects``, ``wires``, ``partnerships``, ``locations``, ``jobs``);
+    ``next_cursor`` is the served cursor (``None`` at the end); ``has_more``
+    derives from it. Iteration ends **only** on a null cursor — a short page
+    with a live cursor is a legal middle page.
+
+    Any other envelope field rides on the page as an attribute, like every
+    served field; a subclass such as :class:`JobPage` declares the ones its
+    list serves. ``auto_paging_iter()`` walks the whole list transparently.
     """
 
     def __init__(
@@ -419,3 +638,11 @@ class Page(WorkwireObject):
             if page._fetch_next is None:
                 raise RuntimeError("this page cannot fetch further pages")
             page = page._fetch_next(page.next_cursor)
+
+
+class JobPage(Page):
+    """A page of :meth:`Jobs.list` — a :class:`Page` whose envelope also
+    carries ``quantity_unit``: your org's one unit label for every
+    ``quantity`` (``"sheets"``), set in the app; ``None`` until it is."""
+
+    quantity_unit: str | None

workwire-0.4.0/src/workwire/resources/__init__.py

@@ -0,0 +1,7 @@
+from .jobs import Jobs
+from .locations import ProjectLocations
+from .partnerships import Partnerships
+from .projects import Projects
+from .wires import Wires
+
+__all__ = ["Projects", "ProjectLocations", "Wires", "Partnerships", "Jobs"]

workwire-0.4.0/src/workwire/resources/jobs.py

@@ -0,0 +1,171 @@
+"""Jobs — one Wire party's work at one location of its scope (``JOB-…``,
+numbered per project).
+
+Jobs are derived: a party gets one per scope location
+(``scope_location_ids`` on ``Party.partnered(...)`` /
+``Party.cold_invite(...)``; absent, the whole project), and nothing creates,
+names or closes one. Each org keeps its own private fields on a Job —
+``your_reference``, ``quantity`` (in the org's ``quantity_unit``) and
+``checked_at`` — never shown to the other side.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+from .._models import NOT_GIVEN, JobPage, JobRow, NotGiven, PartyJob
+
+if TYPE_CHECKING:
+    from .._client import BaseClient
+
+
+# The served quantity grammar is at most 32 digits either side of the point.
+_QUANTITY_DIGITS = 32
+
+
+def _quantity(value: str | Decimal | None) -> str | None:
+    if value is None or isinstance(value, str):
+        return value
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError(f"quantity must be a finite decimal, got {value}")
+        exponent = value.as_tuple().exponent
+        assert isinstance(exponent, int)  # finite
+        if value.adjusted() >= _QUANTITY_DIGITS or exponent < -_QUANTITY_DIGITS:
+            # Far outside anything the API takes: fixed-point would expand it
+            # to as many digits as its exponent says. Send it compact and let
+            # the server refuse it.
+            return str(value)
+        # Fixed-point: identical to str() for an ordinary Decimal, but never
+        # exponent notation (str(Decimal("1E+2")) is "1E+2", which the API
+        # refuses).
+        return format(value, "f")
+    if isinstance(value, float):
+        raise TypeError(
+            "quantity must be a decimal string (\"12.5\") or a decimal.Decimal, "
+            "never a float: a binary float is not an exact quantity"
+        )
+    raise TypeError(
+        "quantity must be a decimal string (\"12.5\") or a decimal.Decimal, "
+        f"not {type(value).__name__} — pass str(n) or Decimal(n)"
+    )
+
+
+class Jobs:
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        project: str | None = None,
+        counterparty: str | None = None,
+        checked: bool | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+        timeout: float | None = None,
+    ) -> JobPage:
+        """List every Job your org is a side of — on a Wire your org created,
+        or on your org's party once that Wire is sent (a draft's Jobs stay
+        hidden from the sub) — newest first. Requires ``wire_parties:read``.
+
+        ``status`` is ``open`` (default: not archived, and the party has not
+        ended), ``ended``, or ``all``; ``project`` and ``counterparty`` are
+        ids; ``checked`` keeps only the Jobs your org has (``True``) or has
+        not (``False``) checked. The filters AND together. ``limit``
+        defaults to 50, max 250 (clamped by the server). Each row carries
+        your org's own fields, and the page's ``quantity_unit`` is your
+        org's unit for every ``quantity`` on it.
+
+        The app's per-user ``pinned`` filter is not offered: pins belong to
+        a user, an API key has none, and the server refuses ``?pinned``
+        (``InvalidRequestError``).
+        """
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if project is not None:
+            params["project"] = project
+        if counterparty is not None:
+            params["counterparty"] = counterparty
+        if checked is not None:
+            if not isinstance(checked, bool):
+                raise TypeError("checked must be True, False, or None")
+            params["checked"] = "true" if checked else "false"
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        data, request_id = self._client._request(
+            "GET", "/v1/jobs", params=params, timeout=timeout
+        )
+        return JobPage(
+            data,
+            request_id=request_id,
+            items_key="jobs",
+            item_cls=JobRow,
+            fetch_next=lambda next_cursor: self.list(
+                status=status,
+                project=project,
+                counterparty=counterparty,
+                checked=checked,
+                cursor=next_cursor,
+                limit=limit,
+                timeout=timeout,
+            ),
+        )
+
+    def update(
+        self,
+        job_id: str,
+        *,
+        your_reference: str | None | NotGiven = NOT_GIVEN,
+        quantity: str | Decimal | None | NotGiven = NOT_GIVEN,
+        checked: bool | None | NotGiven = NOT_GIVEN,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> PartyJob:
+        """Set your org's own fields on a Job. Requires
+        ``wire_parties:write``.
+
+        **Presence is the contract**: an argument you leave out is not sent
+        and the server keeps that field; an explicit ``None`` is sent as
+        ``null`` and clears it. At least one is required.
+
+        - ``your_reference`` — your own reference (≤200 characters).
+        - ``quantity`` — a decimal string (``"12.5"``) or a
+          ``decimal.Decimal``, in your org's ``quantity_unit``; at most 2
+          decimal places. Never a float.
+        - ``checked`` — ``True`` records your org's inspection now (again on
+          every ``True``); ``False`` or ``None`` clears it.
+
+        Never visible to the other side, and never the other side's. A Job
+        your org is not a side of — a draft's Job, for the sub — is a
+        ``NotFoundError``. Returns the Job as your org now sees it.
+        """
+        body: dict[str, Any] = {}
+        if not isinstance(your_reference, NotGiven):
+            if your_reference is not None and not isinstance(your_reference, str):
+                raise TypeError("your_reference must be a str or None")
+            body["your_reference"] = your_reference
+        if not isinstance(quantity, NotGiven):
+            body["quantity"] = _quantity(quantity)
+        if not isinstance(checked, NotGiven):
+            if checked is not None and not isinstance(checked, bool):
+                raise TypeError("checked must be True, False, or None")
+            body["checked"] = checked
+        if not body:
+            raise ValueError(
+                "pass at least one of your_reference, quantity, checked "
+                "(None clears a field; leaving one out keeps it)"
+            )
+        data, request_id = self._client._request(
+            "PATCH",
+            f"/v1/jobs/{job_id}",
+            json_body=body,
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+        )
+        return PartyJob(data, request_id=request_id)

workwire-0.4.0/src/workwire/resources/locations.py

@@ -0,0 +1,138 @@
+"""Project locations — a project's location tree, reached as
+``client.projects.locations``.
+
+Every project has one ``site`` root, created with the project
+(``Project.root_location_id``), and beneath it houses, buildings, floors,
+units, rooms and common areas, nested any way. Locations have stable ids —
+nothing references one by name or path. Seed a tree when you create the
+project (``projects.create(locations=...)``) or add to it here; renames,
+moves and archives happen in the Workwire app.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from .._models import (
+    Location,
+    LocationBatch,
+    LocationKind,
+    LocationNode,
+    Page,
+    _location_payloads,
+)
+
+if TYPE_CHECKING:
+    from .._client import BaseClient
+
+
+class ProjectLocations:
+    def __init__(self, client: BaseClient) -> None:
+        self._client = client
+
+    def list(
+        self,
+        project_id: str,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+        timeout: float | None = None,
+    ) -> Page:
+        """Read a project's location tree. Requires ``projects:read``.
+
+        Tree order is ``path``, then ``id``: the root first, every location
+        after its parent, siblings in creation order — each parent's
+        children together, not depth-first. Archived locations are not
+        listed. ``limit`` defaults to and maxes at 1,000 (clamped by the
+        server), and a full page always carries ``next_cursor``, so a
+        smaller tree is one page; a larger tree's later pages are each in
+        tree order on their own — sort every page's rows together by
+        ``path``, then ``id``, for the whole tree's order
+        (``auto_paging_iter()`` reads them all). Another org's project is a
+        ``NotFoundError``.
+        """
+        params: dict[str, Any] = {}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        data, request_id = self._client._request(
+            "GET", f"/v1/projects/{project_id}/locations", params=params, timeout=timeout
+        )
+        return Page(
+            data,
+            request_id=request_id,
+            items_key="locations",
+            item_cls=Location,
+            fetch_next=lambda next_cursor: self.list(
+                project_id, cursor=next_cursor, limit=limit, timeout=timeout
+            ),
+        )
+
+    def create(
+        self,
+        project_id: str,
+        *,
+        kind: LocationKind,
+        name: str,
+        parent_id: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> Location:
+        """Add one location beneath ``parent_id`` — absent, the project's
+        root. Requires ``projects:write``.
+
+        A parent that is not an unarchived location of this project's tree
+        raises ``InvalidRequestError`` (code ``invalid_parent``); an unknown
+        ``kind`` is checked with the body here — ``InvalidRequestError``
+        code ``validation_error``, ``fields["kind"]``. An archived project's
+        tree is read-only (``ConflictError``, code ``project_archived``).
+        """
+        body: dict[str, Any] = {"kind": kind, "name": name}
+        if parent_id is not None:
+            body["parent_id"] = parent_id
+        data, request_id = self._client._request(
+            "POST",
+            f"/v1/projects/{project_id}/locations",
+            json_body=body,
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+        )
+        return Location(data, request_id=request_id)
+
+    def create_batch(
+        self,
+        project_id: str,
+        *,
+        locations: Sequence[LocationNode],
+        parent_id: str | None = None,
+        idempotency_key: str | None = None,
+        timeout: float | None = None,
+    ) -> LocationBatch:
+        """Create a nested list of locations beneath ``parent_id`` — absent,
+        the project's root — in one transaction. Requires
+        ``projects:write``.
+
+        At most 500 locations, counted over every level: more raises
+        ``InvalidRequestError`` (code ``too_many_locations``, with
+        ``details["limit"]``), as does an unknown ``kind``
+        (``invalid_location_kind``); a refused node creates nothing. Returns
+        a :class:`LocationBatch` — a plain list of the created locations,
+        flat, every parent before its children, so you have every id; each
+        carries the response's ``request_id``.
+        """
+        payloads = _location_payloads(locations)
+        if not payloads:
+            raise ValueError("a batch needs at least one location")
+        body: dict[str, Any] = {"locations": payloads}
+        if parent_id is not None:
+            body["parent_id"] = parent_id
+        data, request_id = self._client._request(
+            "POST",
+            f"/v1/projects/{project_id}/locations/batch",
+            json_body=body,
+            idempotency_key=idempotency_key,
+            timeout=timeout,
+        )
+        return LocationBatch(data or {}, request_id=request_id)

{workwire-0.2.0 → workwire-0.4.0}/src/workwire/resources/projects.py

@@ -7,10 +7,11 @@ signatures keyword-only and mirroring the spec's schemas. The drift gate
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
-from .._models import Page, Project
+from .._models import LocationNode, Page, Project, ProjectTemplate, _location_payloads
+from .locations import ProjectLocations
 
 if TYPE_CHECKING:
     from .._client import BaseClient
@@ -19,6 +20,7 @@ if TYPE_CHECKING:
 class Projects:
     def __init__(self, client: BaseClient) -> None:
         self._client = client
+        self.locations = ProjectLocations(client)
 
     def create(
         self,
@@ -27,6 +29,8 @@ class Projects:
         address: str | None = None,
         project_code: str | None = None,
         external_metadata: Mapping[str, Any] | None = None,
+        template: ProjectTemplate | None = None,
+        locations: Sequence[LocationNode] | None = None,
         idempotency_key: str | None = None,
         timeout: float | None = None,
     ) -> Project:
@@ -36,6 +40,15 @@ class Projects:
         ``external_metadata`` (≤16 KB) round-trips verbatim — carry your own
         system's identifiers in it (keys beginning ``_workwire:`` are
         reserved).
+
+        The project is created with its location tree's ``site`` root
+        (``root_location_id``). ``locations`` seeds a tree beneath the root
+        in the same transaction — at most 500 locations counted over every
+        level (``too_many_locations``), each of a known kind
+        (``invalid_location_kind``); a refused node creates nothing, the
+        project included. ``template`` (``development``, ``single_home``,
+        ``renovation``) records the Project Type your tree follows in the
+        project's history only — the server seeds nothing from it.
         """
         body: dict[str, Any] = {"name": name}
         if address is not None:
@@ -44,6 +57,10 @@ class Projects:
             body["project_code"] = project_code
         if external_metadata is not None:
             body["external_metadata"] = dict(external_metadata)
+        if template is not None:
+            body["template"] = template
+        if locations is not None:
+            body["locations"] = _location_payloads(locations)
         data, request_id = self._client._request(
             "POST",
             "/v1/projects",

workwire-0.2.0/src/workwire/resources/__init__.py

@@ -1,5 +0,0 @@
-from .partnerships import Partnerships
-from .projects import Projects
-from .wires import Wires
-
-__all__ = ["Projects", "Wires", "Partnerships"]