workwire 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0](https://github.com/workwire/workwire-python/compare/v0.4.0...v0.5.0) (2026-10-24)
+
+
+### Features
+
+* **WOR-511:** backend v1.62.0's spec — unit_type on locations and jobs, the kind_rank reason ([#24](https://github.com/workwire/workwire-python/issues/24)) ([c97d486](https://github.com/workwire/workwire-python/commit/c97d4860acfe7a73598c6c3407ccc9dc5d666be2))
+
 ## [0.4.0](https://github.com/workwire/workwire-python/compare/v0.3.0...v0.4.0) (2026-10-18)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workwire
-Version: 0.4.0
+Version: 0.5.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
@@ -107,15 +107,28 @@ 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")]),
-])
+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
-)])
+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)
 ```
@@ -125,6 +138,17 @@ one `client.jobs.update` returns — carries `location_name`, `location_kind` an
 `location_path` (the ancestors, root first), so a sub reads its scope without
 the GC's tree; `client.jobs.list` rows had them already.
 
+A tree only descends: `site` › `building`/`house` › `floor` ›
+`unit`/`common_area` › `room`, levels skippable but never repeated or
+reversed. A node that breaks the rank raises `InvalidRequestError` with code
+`invalid_parent` and `details` `{"reason": "kind_rank", "child_kind": ...,
+"parent_kind": ...}`.
+
+`LocationNode(..., unit_type="C1.1 (2 Bedroom)")` (or
+`locations.create(..., unit_type=...)`) labels a unit's plan; every
+`Location` reads it back as `unit_type`, and a Job as `location_unit_type` —
+`None` when unset.
+
 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

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

@@ -84,15 +84,28 @@ 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")]),
-])
+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
-)])
+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)
 ```
@@ -102,6 +115,17 @@ one `client.jobs.update` returns — carries `location_name`, `location_kind` an
 `location_path` (the ancestors, root first), so a sub reads its scope without
 the GC's tree; `client.jobs.list` rows had them already.
 
+A tree only descends: `site` › `building`/`house` › `floor` ›
+`unit`/`common_area` › `room`, levels skippable but never repeated or
+reversed. A node that breaks the rank raises `InvalidRequestError` with code
+`invalid_parent` and `details` `{"reason": "kind_rank", "child_kind": ...,
+"parent_kind": ...}`.
+
+`LocationNode(..., unit_type="C1.1 (2 Bedroom)")` (or
+`locations.create(..., unit_type=...)`) labels a unit's plan; every
+`Location` reads it back as `unit_type`, and a Job as `location_unit_type` —
+`None` when unset.
+
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workwire"
-version = "0.4.0"
+version = "0.5.0"
 description = "Official Python SDK for the Workwire API"
 readme = "README.md"
 license = "MIT"

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

@@ -96,9 +96,7 @@ class BaseClient:
         return {
             "Authorization": f"Bearer {self._api_key}",
             "Accept": "application/json",
-            "User-Agent": (
-                f"workwire-python/{__version__} python/{platform.python_version()}"
-            ),
+            "User-Agent": (f"workwire-python/{__version__} python/{platform.python_version()}"),
             "X-Workwire-Client-User-Agent": telemetry,
         }
 
@@ -248,5 +246,3 @@ class BaseClient:
             headers={k.lower(): v for k, v in response.headers.items()},
             body=body,
         )
-
-

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

@@ -66,7 +66,7 @@ OPERATIONS: dict[str, dict[str, object]] = {
     "createProjectLocation": {
         "method": "POST",
         "path": "/v1/projects/{id}/locations",
-        "request_fields": {"parent_id", "kind", "name"},
+        "request_fields": {"parent_id", "kind", "name", "unit_type"},
         "query_params": set(),
         "response_model": _models.Location,
     },

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

@@ -19,7 +19,7 @@ from __future__ import annotations
 
 from collections.abc import Iterator, Mapping, Sequence
 from collections.abc import Set as AbstractSet
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Literal
 
 __all__ = [
@@ -186,7 +186,8 @@ class PartyJob(WorkwireObject):
     (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."""
+    other side's. ``location_unit_type`` is the location's ``unit_type`` — the
+    label a builder gives a unit's plan, ``None`` when unset."""
 
     _nested = {"location_path": JobPathLocation}
 
@@ -195,6 +196,7 @@ class PartyJob(WorkwireObject):
     location_id: str
     location_name: str
     location_kind: str
+    location_unit_type: str | None
     location_path: list[JobPathLocation]
     your_reference: str | None
     quantity: str | None
@@ -313,13 +315,16 @@ class PartnershipListItem(WorkwireObject):
 
 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``)."""
+    first (empty on the root, whose ``parent_id`` is ``None``). ``unit_type``
+    is the label a builder gives a unit's plan — ``None`` when unset; always
+    ``None`` on a split."""
 
     id: str
     project_id: str
     parent_id: str | None
     kind: str
     name: str
+    unit_type: str | None
     path: list[str]
     archived_at: str | None
     created_at: str
@@ -361,7 +366,9 @@ class JobMilestones(WorkwireObject):
 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."""
+    ``checked_at`` are your org's own fields, never the other side's.
+    ``location_unit_type`` is the location's ``unit_type`` — the label a
+    builder gives a unit's plan, ``None`` when unset."""
 
     _nested = {"location_path": JobPathLocation, "milestones": JobMilestones}
 
@@ -380,6 +387,7 @@ class JobRow(WorkwireObject):
     location_id: str
     location_name: str
     location_kind: str
+    location_unit_type: str | None
     location_path: list[JobPathLocation]
     counterparty_org_id: str | None
     counterparty_name: str | None
@@ -453,13 +461,20 @@ class ColdInvite:
 
 @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,
+    """One location of a tree being created — its ``kind``, its ``name``, its
+    optional ``unit_type`` (the label a builder gives a unit's plan, "C1.1
+    (2 Bedroom)"), and the ``children`` nested beneath it. A tree only
+    descends — each kind ranks strictly below its parent's, ``site`` ›
+    ``building``/``house`` › ``floor`` › ``unit``/``common_area`` › ``room``,
+    levels skippable but never repeated or reversed, else
+    ``InvalidRequestError`` code ``invalid_parent`` with
+    ``details["reason"] == "kind_rank"``. At most 500 locations per request,
     counted over every level."""
 
     kind: LocationKind
     name: str
+    # Keyword-only, so a positional third argument is still ``children``.
+    unit_type: str | None = field(default=None, kw_only=True)
     children: Sequence[LocationNode] | None = None
 
     def __post_init__(self) -> None:
@@ -475,6 +490,8 @@ class LocationNode:
 
     def to_payload(self) -> dict[str, Any]:
         payload: dict[str, Any] = {"kind": self.kind, "name": self.name}
+        if self.unit_type is not None:  # absent, never null: the bytes stay as before
+            payload["unit_type"] = self.unit_type
         if self.children is not None:
             payload["children"] = [child.to_payload() for child in self.children]
         return payload
@@ -524,9 +541,7 @@ class Party:
 
     def __init__(self, payload: dict[str, Any], *, _guard: object = None) -> None:
         if _guard is not _PARTY_GUARD:
-            raise TypeError(
-                "Construct with Party.partnered(...) or Party.cold_invite(...)"
-            )
+            raise TypeError("Construct with Party.partnered(...) or Party.cold_invite(...)")
         self._payload = payload
 
     @classmethod

{workwire-0.4.0 → workwire-0.5.0}/src/workwire/resources/jobs.py

@@ -43,11 +43,11 @@ def _quantity(value: str | Decimal | None) -> str | None:
         return format(value, "f")
     if isinstance(value, float):
         raise TypeError(
-            "quantity must be a decimal string (\"12.5\") or a decimal.Decimal, "
+            '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, "
+        'quantity must be a decimal string ("12.5") or a decimal.Decimal, '
         f"not {type(value).__name__} — pass str(n) or Decimal(n)"
     )
 

{workwire-0.4.0 → workwire-0.5.0}/src/workwire/resources/locations.py

@@ -3,7 +3,8 @@
 
 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 —
+units, rooms and common areas, each kind ranked below its parent's (see
+:class:`~workwire.LocationNode`). 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.
@@ -76,6 +77,7 @@ class ProjectLocations:
         *,
         kind: LocationKind,
         name: str,
+        unit_type: str | None = None,
         parent_id: str | None = None,
         idempotency_key: str | None = None,
         timeout: float | None = None,
@@ -83,13 +85,22 @@ class ProjectLocations:
         """Add one location beneath ``parent_id`` — absent, the project's
         root. Requires ``projects:write``.
 
+        ``unit_type`` is the label a builder gives a unit's plan ("C1.1
+        (2 Bedroom)"); left ``None``, it is not sent.
+
         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``).
+        raises ``InvalidRequestError`` (code ``invalid_parent``), and so does
+        a ``kind`` that does not rank below the parent's (``site`` ›
+        ``building``/``house`` › ``floor`` › ``unit``/``common_area`` ›
+        ``room``) — that refusal's ``details`` are ``{"reason": "kind_rank",
+        "child_kind": ..., "parent_kind": ...}``. 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 unit_type is not None:
+            body["unit_type"] = unit_type
         if parent_id is not None:
             body["parent_id"] = parent_id
         data, request_id = self._client._request(
@@ -117,7 +128,10 @@ class ProjectLocations:
         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
+        (``invalid_location_kind``) and a node whose kind does not rank below
+        its own parent's (``invalid_parent``, with ``details`` ``{"reason":
+        "kind_rank", "child_kind": ..., "parent_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``.

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

@@ -45,10 +45,13 @@ class Projects:
         (``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.
+        (``invalid_location_kind``) ranked below its parent's
+        (``invalid_parent``, with ``details`` ``{"reason": "kind_rank",
+        "child_kind": ..., "parent_kind": ...}`` — see :class:`LocationNode`);
+        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:

{workwire-0.4.0 → workwire-0.5.0}/src/workwire/resources/wires.py

@@ -46,8 +46,7 @@ class Wires:
         for party in parties:
             if not isinstance(party, Party):
                 raise TypeError(
-                    "parties must be built with Party.partnered(...) or "
-                    "Party.cold_invite(...)"
+                    "parties must be built with Party.partnered(...) or Party.cold_invite(...)"
                 )
         body: dict[str, Any] = {
             "project_id": project_id,
@@ -70,9 +69,7 @@ class Wires:
     def retrieve(self, wire_id: str, *, timeout: float | None = None) -> Wire:
         """Fetch one wire with embedded parties, milestones, and POs.
         Requires ``wires:read``."""
-        data, request_id = self._client._request(
-            "GET", f"/v1/wires/{wire_id}", timeout=timeout
-        )
+        data, request_id = self._client._request("GET", f"/v1/wires/{wire_id}", timeout=timeout)
         return Wire(data, request_id=request_id)
 
     def go_live(