wflow-api 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,204 @@
1
+ """DocumentProperties tag: custom property definitions, and the values set per document."""
2
+
3
+ from typing import Annotated
4
+
5
+ from pydantic import Field
6
+
7
+ from wflow_api.client import WflowClient
8
+ from wflow_api.guards import path_segment, query_params, write_definitions_json, write_json, write_json_list
9
+ from wflow_api.models import OrgSlug, PropertyUpdate, WriteResult
10
+ from wflow_api.models.documents import Property, PropertyDefinition
11
+ from wflow_api.operation import operation
12
+
13
+
14
+ @operation
15
+ async def get_document_properties(client: WflowClient, organization: OrgSlug, documentId: str) -> list[Property]:
16
+ """The custom property values set on one document.
17
+
18
+ A workspace defines its custom properties once with `list_document_property_definitions`;
19
+ this is what a specific document holds for each of them.
20
+
21
+ Fields:
22
+
23
+ - `name`, `type` — the definition this value belongs to
24
+ - `value` — what this document holds for the property
25
+ - `order`, `show`, `editable`, `kinds` — the definition's own presentation and
26
+ applicability settings, echoed alongside the value
27
+ """
28
+ payload = await client.request("GET", f"/api/{organization}/documents/{path_segment(documentId)}/properties") or []
29
+ return [Property.model_validate(item) for item in payload]
30
+
31
+
32
+ @operation
33
+ async def get_document_property_definition(client: WflowClient, organization: OrgSlug, id: str) -> PropertyDefinition:
34
+ """One custom property definition, by its id.
35
+
36
+ Use `list_document_property_definitions` to find the id, or resolve one already seen
37
+ on a document's `get_document_properties` result.
38
+
39
+ Fields:
40
+
41
+ - `name`, `type` — how the property is labelled and what kind of value it holds
42
+ - `order`, `show` — where it appears, and whether it is shown at all
43
+ - `editable` — whether a document's value for it can be changed
44
+ - `kinds` — which document kinds it applies to
45
+ """
46
+ payload = (
47
+ await client.request("GET", f"/api/{organization}/documents/properties/definition/{path_segment(id)}") or {}
48
+ )
49
+ return PropertyDefinition.model_validate(payload)
50
+
51
+
52
+ @operation
53
+ async def list_document_property_definitions(client: WflowClient, organization: OrgSlug) -> list[PropertyDefinition]:
54
+ """Every custom property defined in the workspace.
55
+
56
+ Call this to learn what custom fields exist before reading or interpreting the
57
+ values `get_document_properties` returns for a specific document.
58
+
59
+ Fields:
60
+
61
+ - `name`, `type` — how the property is labelled and what kind of value it holds
62
+ - `order`, `show` — where it appears, and whether it is shown at all
63
+ - `editable` — whether a document's value for it can be changed
64
+ - `kinds` — which document kinds it applies to
65
+ """
66
+ payload = await client.request("GET", f"/api/{organization}/documents/properties/definitions") or []
67
+ return [PropertyDefinition.model_validate(item) for item in payload]
68
+
69
+
70
+ @operation
71
+ async def delete_document_property(
72
+ client: WflowClient, organization: OrgSlug, documentId: str, propertyId: str
73
+ ) -> WriteResult:
74
+ """Clear one custom property value from one document.
75
+
76
+ Only this document's value goes; the definition stays and every other document keeps
77
+ its own value. Get `propertyId` from the `id` of the entry in
78
+ `get_document_properties`.
79
+
80
+ Fields: on the result —
81
+
82
+ - `action` — "deleted"
83
+ - `resource` — "documents/properties"
84
+ """
85
+ await client.request(
86
+ "DELETE", f"/api/{organization}/documents/{path_segment(documentId)}/properties/{path_segment(propertyId)}"
87
+ )
88
+ return WriteResult(action="deleted", resource="documents/properties")
89
+
90
+
91
+ @operation
92
+ async def delete_document_property_definition(client: WflowClient, organization: OrgSlug, id: str) -> WriteResult:
93
+ """Delete one custom property definition from the workspace.
94
+
95
+ This is the definition itself, not one document's value for it: the property stops
96
+ existing for every document at once. To clear a single document's value, use
97
+ `delete_document_property`. Get the id from `list_document_property_definitions`.
98
+
99
+ Fields: on the result —
100
+
101
+ - `action` — "deleted"
102
+ - `resource` — "documents/properties/definition"
103
+ """
104
+ await client.request("DELETE", f"/api/{organization}/documents/properties/definition/{path_segment(id)}")
105
+ return WriteResult(action="deleted", resource="documents/properties/definition")
106
+
107
+
108
+ @operation
109
+ async def update_document_properties(
110
+ client: WflowClient, organization: OrgSlug, documentId: str, properties: list[PropertyUpdate]
111
+ ) -> WriteResult:
112
+ """Replace the custom property values held on one document.
113
+
114
+ The list you send becomes the document's values, so a property you leave out is
115
+ cleared on this document. `get_document_properties` returns everything it currently
116
+ holds, in one array — read it first and send back the `id` and `value` of every entry
117
+ you mean to keep, and nothing else: the read also carries each definition's name, type
118
+ and presentation, which this operation does not write. To set a value for a property the
119
+ workspace has not defined yet, use `update_document_properties_with_definition`.
120
+
121
+ Fields: on the result —
122
+
123
+ - `action` — "updated"
124
+ - `resource` — "documents/properties"
125
+ """
126
+ await client.request(
127
+ "PUT",
128
+ f"/api/{organization}/documents/{path_segment(documentId)}/properties",
129
+ json=write_json_list(properties),
130
+ )
131
+ return WriteResult(action="updated", resource="documents/properties")
132
+
133
+
134
+ @operation
135
+ async def update_document_properties_with_definition(
136
+ client: WflowClient,
137
+ organization: OrgSlug,
138
+ documentId: str,
139
+ properties: list[Property],
140
+ addOnly: Annotated[
141
+ bool | None, Field(default=None, description="Leave an existing definition alone; defaults to true")
142
+ ] = None,
143
+ ) -> WriteResult:
144
+ """Define new custom properties and set their values on one document.
145
+
146
+ Every entry must carry `id`, `name`, `type` and `value`, whether the property is new to
147
+ the workspace or already defined: wflow refuses the whole list over an entry holding
148
+ only `id` and `value`, so such a list is refused here before anything is sent. An
149
+ already-defined property sent in full gets its value updated on this document; one
150
+ you leave out keeps its value. To set values without repeating definitions, use
151
+ `update_document_properties`. `id` is a free-form string you choose; wflow keeps at
152
+ most 30 characters of it and drops dashes, so a GUID comes back changed — pick a
153
+ short plain id. A definition sent with only those four fields is created hidden and
154
+ read-only (`order` 0, `show` false, `editable` false) — change that with
155
+ `update_document_property_definition`. A definition is workspace configuration, so that
156
+ part reaches every document. `addOnly` defaults to true, which leaves an existing
157
+ definition as it is; false rewrites it from what you send, for every document at once.
158
+
159
+ Fields: on the result —
160
+
161
+ - `action` — "updated"
162
+ - `resource` — "documents/properties/withdefinition"
163
+ """
164
+ await client.request(
165
+ "PUT",
166
+ f"/api/{organization}/documents/{path_segment(documentId)}/properties/withdefinition",
167
+ params=query_params(addOnly=addOnly),
168
+ json=write_definitions_json(properties, values_operation="update_document_properties"),
169
+ )
170
+ return WriteResult(action="updated", resource="documents/properties/withdefinition")
171
+
172
+
173
+ @operation
174
+ async def update_document_property_definition(
175
+ client: WflowClient, organization: OrgSlug, definition: PropertyDefinition
176
+ ) -> WriteResult:
177
+ """Define a custom property for documents, or replace an existing definition.
178
+
179
+ This is workspace configuration, not one document's value: every document sees the
180
+ change at once. **`id` is required and you choose it** — a free-form string, not a
181
+ GUID wflow mints; a definition sent without one creates nothing. wflow keeps at most
182
+ 30 characters of the id and drops dashes, so a GUID comes back changed — pick a short
183
+ plain id. The submitted object replaces the stored definition, so a field you
184
+ leave out can be cleared, and `kinds` and `data` are whole lists — omit a document
185
+ kind and the property stops applying there, omit a choice from `data` and it can no
186
+ longer be picked. `get_document_property_definition` returns the definition in full;
187
+ read it first when changing one that exists.
188
+
189
+ **`type` is not reliably stored.** A definition sent with `type: "Text"` can be
190
+ accepted as a success and read back as `type: "UNDEFINED"`; the set of values wflow
191
+ accepts is not documented. Read the definition back and check what landed rather
192
+ than trusting the write.
193
+
194
+ Fields: on the result —
195
+
196
+ - `action` — "updated"
197
+ - `resource` — "documents/properties/definition"
198
+ """
199
+ await client.request(
200
+ "PUT",
201
+ f"/api/{organization}/documents/properties/definition",
202
+ json=write_json(definition),
203
+ )
204
+ return WriteResult(action="updated", resource="documents/properties/definition")
@@ -0,0 +1,60 @@
1
+ """DocumentTags tag: the free-text labels attached to documents."""
2
+
3
+ from wflow_api.client import WflowClient
4
+ from wflow_api.guards import ensure_list, path_segment
5
+ from wflow_api.models import OrgSlug, WriteResult
6
+ from wflow_api.operation import operation
7
+
8
+
9
+ @operation
10
+ async def get_document_tags(client: WflowClient, organization: OrgSlug, documentId: str) -> list[str]:
11
+ """The tags attached to one document.
12
+
13
+ Fields: a bare array of tag strings.
14
+ """
15
+ path = f"/api/{organization}/documents/{path_segment(documentId)}/tags"
16
+ return ensure_list(path, await client.request("GET", path) or [])
17
+
18
+
19
+ @operation
20
+ async def list_document_tags(client: WflowClient, organization: OrgSlug) -> list[str]:
21
+ """Every tag in use across the workspace's documents.
22
+
23
+ Fields: a bare array of tag strings.
24
+ """
25
+ path = f"/api/{organization}/documents/tags"
26
+ return ensure_list(path, await client.request("GET", path) or [])
27
+
28
+
29
+ @operation
30
+ async def add_document_tag(client: WflowClient, organization: OrgSlug, documentId: str, tag: str) -> WriteResult:
31
+ """Put one tag on one document.
32
+
33
+ `tag` is the label itself, not an id: a label the workspace has never used is
34
+ created by being used here, so a misspelling makes a new tag rather than failing.
35
+ `list_document_tags` shows what is already in use.
36
+
37
+ Fields: on the result —
38
+
39
+ - `action` — "added"
40
+ - `resource` — "documents/tags"
41
+ """
42
+ await client.request("PUT", f"/api/{organization}/documents/{path_segment(documentId)}/tags/{path_segment(tag)}")
43
+ return WriteResult(action="added", resource="documents/tags")
44
+
45
+
46
+ @operation
47
+ async def delete_document_tag(client: WflowClient, organization: OrgSlug, documentId: str, tag: str) -> WriteResult:
48
+ """Take one tag off one document.
49
+
50
+ `tag` is the label itself, not an id — take it from `get_document_tags`. Other
51
+ documents keep the tag; it drops out of `list_document_tags` only once no document
52
+ carries it any more.
53
+
54
+ Fields: on the result —
55
+
56
+ - `action` — "deleted"
57
+ - `resource` — "documents/tags"
58
+ """
59
+ await client.request("DELETE", f"/api/{organization}/documents/{path_segment(documentId)}/tags/{path_segment(tag)}")
60
+ return WriteResult(action="deleted", resource="documents/tags")