Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 14 additions & 12 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ PlaneClient
- `plane/client/` — `PlaneClient` (API key / access token auth) and `OAuthClient` (OAuth 2.0 flows).
- `plane/errors/` — `PlaneError` → `HttpError`, `ConfigurationError`.
- `plane/config.py` — `Configuration` and `RetryConfig` dataclasses.
- `plane/api/v2/` — the v2 surface (`client.v2`). **Migration complete**: all 93
- `plane/api/v2/` — the v2 surface (`client.v2`). **Migration complete**: all 95
`V2Resource` subclasses in the package (`tests/v2/tree_walk.py`'s
`all_resource_classes()`) are on the flat shape and swept by the rule tests.
`tests/v2/tree_walk.py`'s `UNMIGRATED_RESOURCES` — the opt-out list the sweeps
Expand All @@ -90,25 +90,26 @@ PlaneClient
never grow, so it cannot silently regain a member. Count resources, not
grouping nodes: `wiki` and `group_sync` hold no `V2Resource` base, `path` or
`operations` of their own — they only group children (`wiki.pages`,
`wiki.collections`, `group_sync.config`) — so neither is in the 93.
`wiki.collections`, `group_sync.config`) — so neither is in the 95.

The whole project band is wired onto `client.v2.workspaces.projects`:
`states`, `labels`, `work_items`, `cycles`, `milestones`, `modules`,
`estimates`, `intakes`, `members`, `views`, `features`, `permissions`,
`work_item_templates`, `worklogs`, `pages`, `automations`,
`work_item_properties`, `work_item_types` and `workflows` — nineteen
children, and a fetched project reaches every one of them that is itself
navigable (`project.cycles.list()`, `project.permissions.me()`). Twenty of
the 93 classes are navigable — `workspaces`, `projects`, `work_items`,
navigable (`project.cycles.list()`, `project.permissions.me()`). Twenty-one of
the 95 classes are navigable — `workspaces`, `projects`, `work_items`,
`cycles`, `milestones`, `modules`, `estimates`, `webhooks`, `collections`,
`customers`, `initiatives`, `releases`, `work_item_types`,
`work_item_properties`, `automations`, `workflows` and `agent_runs` (three of those —
`work_item_properties`, `automations`, `workflows`, `dashboards` and `agent_runs`
(three of those —
automations, work item types and work item properties — each have a separate
project-scoped and workspace-scoped resource class, each independently
navigable, which is where 17 families become 20 classes) — a fetched row
navigable, which is where 18 families become 21 classes) — a fetched row
reaches its child with no ids repeated. `workspaces` is the root of that set
and the last to join it: `client.v2.workspaces.retrieve("acme")` answers a
`LoadedWorkspace` reaching all 27 workspace-scoped families
`LoadedWorkspace` reaching all 28 workspace-scoped families
(`workspace.projects.list()`), and its children address it by `slug`, never
the UUID `id`, which that path segment does not accept. `estimates`' child is
`estimate_points`, not `points` — `Estimate.points` is itself an API field,
Expand Down Expand Up @@ -165,8 +166,9 @@ PlaneClient
- **Loaded rows.** A resource with children (`projects`, `work_items`,
`cycles`, `milestones`, `modules`, `estimates`, `webhooks`, `collections`,
`customers`, `initiatives`, `releases`, `work_item_types`,
`work_item_properties`, `automations`, `workflows`, `workspaces`, `agent_runs` — 20 of
the 93 classes) returns a `Loaded` row from `retrieve`/`list`/`iterate`, not a bare
`work_item_properties`, `automations`, `workflows`, `dashboards`, `workspaces`,
`agent_runs` — 21 of the 95 classes) returns a `Loaded` row from
`retrieve`/`list`/`iterate`, not a bare
pydantic model: it carries its own data and reaches its own children with none of the
ids repeated (`project.states.list()`, `work_item.comments.list()`,
`cycle.work_items.add(["w1"])`).
Expand Down Expand Up @@ -248,10 +250,10 @@ PlaneClient
per `Loaded` subclass — `project.py`, `work_item.py`, `cycle.py`,
`milestone.py`, `module.py`, `estimate.py`, `webhook.py`, `collection.py`,
`customer.py`, `initiative.py`, `release.py`, `work_item_type.py`,
`work_item_property.py`, `automation.py`, `workflow.py`, `workspace.py`,
`agent_run.py`; copy
`work_item_property.py`, `automation.py`, `workflow.py`, `dashboard.py`,
`workspace.py`, `agent_run.py`; copy
whichever is closest in shape (single bridge-only child vs. several plain-CRUD
children). `workspace.py` is the `bind1` exemplar and the widest, at 27
children). `workspace.py` is the `bind1` exemplar and the widest, at 28
children; the two grouping nodes (`wiki`, `group_sync`) are deliberately not
among them — neither holds a `V2Resource` base, so neither is a child a row can
bind, and they are reached from the namespace instead.
Expand Down
47 changes: 39 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,17 +200,18 @@ work_items = client.work_items.list(

`client.v2` reaches the v2 surface. v1 resources on the client are unchanged.

The v2 surface is complete: every one of the 93 `V2Resource` subclasses in the
The v2 surface is complete: every one of the 95 `V2Resource` subclasses in the
package (`tests/v2/tree_walk.py`'s `all_resource_classes()`, the enumeration the
test suite itself sweeps) is on the flat shape described below and reachable
through `client.v2`. Counting resources means not counting grouping nodes:
`wiki` and `group_sync` hold no `V2Resource` base, `path` or `operations` of
their own — they only group children (`wiki.pages`, `wiki.collections`,
`group_sync.config`) — and are outside the 93.
`group_sync.config`) — and are outside the 95.

Wired directly on `client.v2.workspaces`: `agent_runs` (with `.activities`),
`agent_run_activities`, `artifacts`, `assets`, `audit_logs`,
`automations`, `customer_properties`, `customers`, `features`, `initiatives`,
`automations`, `customer_properties`, `customers`, `dashboards` (`.widgets`),
`features`, `initiatives`,
`invitations`, `members`, `permission_schemes`, `permissions`, `projects`,
`releases` (`.labels`, `.tags`, `.comments`, `.links`, `.changelog`,
`.work_items`), `roles`, `stickies`, `teamspaces`, `views`, `webhooks` (with
Expand Down Expand Up @@ -278,8 +279,9 @@ client.v2.workspaces.projects.states.list(slug="acme", project="ENG")
A resource with children (`projects`, `work_items`, `cycles`, `milestones`,
`modules`, `estimates`, `webhooks`, `collections`, `customers`, `initiatives`,
`releases`, `work_item_types`, `work_item_properties`, `automations`,
`workflows` and `agent_runs` — 20 of the 93 classes, some families having a separate
project-scoped and workspace-scoped resource, each independently navigable)
`workflows`, `dashboards`, `workspaces` and `agent_runs` — 21 of the 95 classes, some
families having a separate project-scoped and workspace-scoped resource, each
independently navigable)
doesn't just hand back a bare pydantic model from `retrieve`/`list`/`iterate` —
it hands back a row that carries its own data *and* already knows where it
lives, so the row's own children are reached with none of the ids repeated:
Expand Down Expand Up @@ -311,8 +313,8 @@ log; `collections` via `.members`/`.pages`; `customers` via `.requests`,
`.changelog`, `.work_items`; `work_item_types` via `.properties`;
`work_item_properties` via `.property_options` (plus `.contexts` on the
workspace-scoped resource only); `automations` via `.edges`, `.nodes`,
`.activities`; `workflows` via `.states`, `.transitions`; and `agent_runs` via
`.activities`, the run's log. A work item
`.activities`; `workflows` via `.states`, `.transitions`; `dashboards` via
`.widgets`; and `agent_runs` via `.activities`, the run's log. A work item
itself reaches all seven of its own children this way — `comments`,
`attachments`, `links`, `worklogs`, `activities`, `relations`, `dependencies`.

Expand All @@ -327,6 +329,35 @@ class that declares a `loaded_model` and fails if its row's navigation
properties don't match its resource's own children exactly — see
[the four rules the tests enforce](#the-four-rules-the-tests-enforce) below.

### Dashboards and widgets

A dashboard is a workspace-level page of charts over the work items in its projects; each
widget is one chart. A fetched dashboard reaches its widgets directly, and `chart()` returns
the data the widget displays (its shape depends on the chart type):

```python
from plane.models.v2 import CreateDashboard, CreateWidget

dashboards = client.v2.workspaces.dashboards
dashboard = dashboards.create("acme", CreateDashboard(name="Engineering", project_ids=[project_id]))

widget = dashboard.widgets.create(
CreateWidget(
name="By priority",
chart_type="BAR_CHART",
chart_model="STACKED",
x_axis_property="PRIORITY",
y_axis_metric="WORK_ITEM_COUNT",
group_by="STATE_GROUPS",
)
)
chart = dashboard.widgets.chart(widget.id) # chart.data, chart.chart_schema, paging fields
chart = dashboard.widgets.chart(widget.id, page=2)
everything = dashboard.widgets.charts() # every widget's first page in one call
dashboards.widget_types("acme") # chart types, their models, plan availability
dashboards.copy("acme", dashboard.id) # copies settings, filters and widgets
```

### Sparse responses raise, they don't lie

Every read field except `id` is optional at the model level, because `?fields=`
Expand Down Expand Up @@ -371,7 +402,7 @@ scripts to prove it, rather than trusting it by inspection.
### The five rules the tests enforce

Five properties of the surface are each enforced by a sweep in `tests/v2/`, over
every one of the 93 resource classes (`tests/v2/tree_walk.py`'s
every one of the 95 resource classes (`tests/v2/tree_walk.py`'s
`all_resource_classes()`) rather than a hand-picked subset — so a newly added
resource is covered the moment it exists, with nothing to remember to add it to:

Expand Down
5 changes: 5 additions & 0 deletions plane/api/v2/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
from ._loaded.collection import LoadedCollection
from ._loaded.customer import LoadedCustomer
from ._loaded.cycle import LoadedCycle
from ._loaded.dashboard import LoadedDashboard
from ._loaded.estimate import LoadedEstimate
from ._loaded.initiative import LoadedInitiative
from ._loaded.milestone import LoadedMilestone
Expand All @@ -48,6 +49,7 @@
from .customer_properties import CustomerProperties
from .customers import Customers
from .cycles import Cycles
from .dashboards import Dashboards, Widgets
from .estimates import Estimates
from .features import ProjectFeatures, WorkspaceFeatures
from .group_sync import GroupSync
Expand Down Expand Up @@ -104,6 +106,7 @@ def __init__(self, config: Configuration) -> None:
"Customers",
"CustomerProperties",
"Cycles",
"Dashboards",
"Estimates",
"FieldError",
"FieldNotRequested",
Expand All @@ -116,6 +119,7 @@ def __init__(self, config: Configuration) -> None:
"LoadedCollection",
"LoadedCustomer",
"LoadedCycle",
"LoadedDashboard",
"LoadedEstimate",
"LoadedInitiative",
"LoadedMilestone",
Expand Down Expand Up @@ -156,6 +160,7 @@ def __init__(self, config: Configuration) -> None:
"Users",
"V2Namespace",
"Webhooks",
"Widgets",
"WorkspaceAgentRunActivities",
"Wiki",
"WikiPages",
Expand Down
Loading
Loading