mopux 0.1.0__tar.gz
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.
- mopux-0.1.0/.gitignore +12 -0
- mopux-0.1.0/CHANGELOG.md +15 -0
- mopux-0.1.0/LICENSE +21 -0
- mopux-0.1.0/PKG-INFO +233 -0
- mopux-0.1.0/README.md +206 -0
- mopux-0.1.0/pyproject.toml +76 -0
- mopux-0.1.0/src/mopux/__init__.py +57 -0
- mopux-0.1.0/src/mopux/_async/__init__.py +0 -0
- mopux-0.1.0/src/mopux/_async/client.py +102 -0
- mopux-0.1.0/src/mopux/_async/connector.py +119 -0
- mopux-0.1.0/src/mopux/_async/pagination.py +19 -0
- mopux-0.1.0/src/mopux/_async/resources.py +677 -0
- mopux-0.1.0/src/mopux/_base.py +196 -0
- mopux-0.1.0/src/mopux/_retry.py +47 -0
- mopux-0.1.0/src/mopux/_sync/__init__.py +1 -0
- mopux-0.1.0/src/mopux/_sync/client.py +103 -0
- mopux-0.1.0/src/mopux/_sync/connector.py +120 -0
- mopux-0.1.0/src/mopux/_sync/pagination.py +20 -0
- mopux-0.1.0/src/mopux/_sync/resources.py +670 -0
- mopux-0.1.0/src/mopux/_validate.py +76 -0
- mopux-0.1.0/src/mopux/_version.py +1 -0
- mopux-0.1.0/src/mopux/errors.py +165 -0
- mopux-0.1.0/src/mopux/models/__init__.py +103 -0
- mopux-0.1.0/src/mopux/models/_extra.py +102 -0
- mopux-0.1.0/src/mopux/models/_generated.py +730 -0
- mopux-0.1.0/src/mopux/page.py +74 -0
- mopux-0.1.0/src/mopux/py.typed +0 -0
- mopux-0.1.0/src/mopux/testing.py +129 -0
- mopux-0.1.0/src/mopux/upload.py +33 -0
mopux-0.1.0/.gitignore
ADDED
mopux-0.1.0/CHANGELOG.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `mopux` are documented here. The project follows [Semantic Versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## 0.1.0 - Unreleased
|
|
6
|
+
|
|
7
|
+
First release.
|
|
8
|
+
|
|
9
|
+
- Sync (`Mopux`) and async (`AsyncMopux`) clients for the Mopux API v1 (spec 1.2.0): all 71 operations.
|
|
10
|
+
- Pydantic models generated from the OpenAPI spec, tolerant of unknown and missing fields.
|
|
11
|
+
- `Mopux.login()`, token functions and `with_token()`.
|
|
12
|
+
- `Page` with lazy `iter…()` helpers; accepts Laravel pagination, page fields and the plain lists of API 1.1.
|
|
13
|
+
- Typed errors, including `AuthorizationError.is_plan_restriction()` / `is_billing_blocked()` and `UncertainWriteError`.
|
|
14
|
+
- Retries for 429 and failed reads; writes are never retried.
|
|
15
|
+
- `Upload` for task documents and comment attachments; `MockApi` in `mopux.testing`.
|
mopux-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 mopux
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
mopux-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: mopux
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Official Python SDK for the Mopux API
|
|
5
|
+
Project-URL: Homepage, https://www.mopux.com
|
|
6
|
+
Project-URL: Source, https://github.com/mopux/mopux-python
|
|
7
|
+
Project-URL: Issues, https://github.com/mopux/mopux-python/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/mopux/mopux-python/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Mopux <support@mopux.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: api,mopux,projects,sdk,tasks
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: httpx<1,>=0.27
|
|
23
|
+
Requires-Dist: pydantic<3,>=2.10; python_version < '3.14'
|
|
24
|
+
Requires-Dist: pydantic<3,>=2.12; python_version >= '3.14'
|
|
25
|
+
Requires-Dist: typing-extensions>=4.12
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# Mopux Python
|
|
29
|
+
|
|
30
|
+
Official Python client for the [Mopux](https://www.mopux.com) API (`/api/v1`).
|
|
31
|
+
|
|
32
|
+
- Every API operation covered (71/71), checked against the OpenAPI spec in CI.
|
|
33
|
+
- Sync (`Mopux`) and async (`AsyncMopux`) clients with the same API, built on `httpx`.
|
|
34
|
+
- Typed `pydantic` models generated from the OpenAPI spec; unknown fields are kept, so a newer API does not break the client.
|
|
35
|
+
- Safe by default: retries rate-limited requests and failed reads, **never** retries a write whose outcome is unknown.
|
|
36
|
+
- `MockApi` testing helper in `mopux.testing`.
|
|
37
|
+
|
|
38
|
+
## Requirements
|
|
39
|
+
|
|
40
|
+
Python 3.11 to 3.14. Only Python versions that still receive security fixes are supported.
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install mopux
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Quick start
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
from mopux import Mopux
|
|
52
|
+
|
|
53
|
+
with Mopux("https://acme.mopux.com", token) as mopux:
|
|
54
|
+
board = mopux.projects.board(12)
|
|
55
|
+
for group in board.task_groups or []:
|
|
56
|
+
print(f"{group.title}: {len(group.tasks or [])} open tasks")
|
|
57
|
+
|
|
58
|
+
task = mopux.tasks.create(
|
|
59
|
+
12, # project id
|
|
60
|
+
7, # group id
|
|
61
|
+
"Write the release notes",
|
|
62
|
+
priority=2,
|
|
63
|
+
hours_expected="2:30",
|
|
64
|
+
assignees=[3, 5],
|
|
65
|
+
)
|
|
66
|
+
mopux.tasks.update_status(task.id, 3)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Async:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from mopux import AsyncMopux
|
|
73
|
+
|
|
74
|
+
async with AsyncMopux("https://acme.mopux.com", token) as mopux:
|
|
75
|
+
tasks = await mopux.tasks.my()
|
|
76
|
+
async for project in mopux.projects.iter():
|
|
77
|
+
print(project.title)
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Authentication
|
|
81
|
+
|
|
82
|
+
The base URL is your Mopux installation (each installation has its own domain). The client adds `/api/v1/` itself.
|
|
83
|
+
|
|
84
|
+
**Personal access token.** Exchange credentials once and store the token (the API only shows it once):
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
mopux = Mopux.login("https://acme.mopux.com", email, password, token_name="my-app")
|
|
88
|
+
save_secret(mopux.token)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Later:
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
mopux = Mopux("https://acme.mopux.com", token)
|
|
95
|
+
mopux.auth.user() # the token's user
|
|
96
|
+
mopux.auth.logout() # revokes the token
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`token` also accepts a function called before every request (for tokens kept in a vault or refreshed elsewhere).
|
|
100
|
+
|
|
101
|
+
Each login creates a new token. List and revoke the user's API tokens; secrets are never returned:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
for api_token in mopux.auth.tokens.list():
|
|
105
|
+
print(api_token.id, api_token.name, "(this client)" if api_token.current else "")
|
|
106
|
+
mopux.auth.tokens.delete(leaked_token_id)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Changing or resetting the password revokes every token of the user, and API tokens unused for 90 days are deleted: log in again when you get an `AuthenticationError`.
|
|
110
|
+
|
|
111
|
+
The user needs the "API use" permission, and the installation's plan must include the API; otherwise the API answers `403` (`is_plan_restriction()` tells the plan case apart).
|
|
112
|
+
|
|
113
|
+
**OAuth.** Pass the access token the same way. Reads need the `mopux:read` scope and writes `mopux:write`. Tokens created for the MCP connector are rejected by the REST API.
|
|
114
|
+
|
|
115
|
+
**Several installations.** Create one client per installation, or derive one with another token with `mopux.with_token(token)` (it shares the HTTP connections).
|
|
116
|
+
|
|
117
|
+
## Resources
|
|
118
|
+
|
|
119
|
+
| Attribute | Covers |
|
|
120
|
+
| --- | --- |
|
|
121
|
+
| `mopux.auth` | `login`, `logout`, `user`, `tokens.list()` / `tokens.delete()` |
|
|
122
|
+
| `mopux.projects` | `list`, `iter`, `create`, `show`, `update`, `delete`, `board`, `activity`, `summary`, members |
|
|
123
|
+
| `mopux.task_groups` | `create` (optionally with up to 4 tasks), `reorder`, `rename`, `archive`, `move`, `copy`, `create_project`, `focus`, `status_summary` |
|
|
124
|
+
| `mopux.tasks` | `create`, `update`, `update_batch`, `my`, `show`, `delete`, single-field updates, `move`, `send_touch`, focus list, documents |
|
|
125
|
+
| `mopux.comments` | `list`, `iter`, `create` (with mentions and files), `update`, `delete`, `reply` |
|
|
126
|
+
| `mopux.notifications` | `list`, `iter`, `mark_read`, `mark_unread`, `mark_all_read`, `unread_count`, `delete` |
|
|
127
|
+
| `mopux.touches` | `list`, `reply` |
|
|
128
|
+
| `mopux.team` / `mopux.team_invitations` | installation users, invitations |
|
|
129
|
+
|
|
130
|
+
### Updating tasks
|
|
131
|
+
|
|
132
|
+
`update()` changes only the arguments you pass, atomically. `None` clears description, dates and hours; leaving an argument out keeps the value. Assignees are an explicit mutation:
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
mopux.tasks.update(
|
|
136
|
+
101,
|
|
137
|
+
date_end=None,
|
|
138
|
+
hours_inverted="1:15",
|
|
139
|
+
assignees={"operation": "add", "user_ids": [8]}, # or "remove" / "replace"
|
|
140
|
+
)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Hours are `HH:MM` (or minutes); the API returns them as `HH:MM:SS`. Status `-1` (delayed) is read only.
|
|
144
|
+
|
|
145
|
+
### Comments and documents
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
from mopux import Upload
|
|
149
|
+
|
|
150
|
+
mopux.comments.create(101, "Draft attached @Ada#5", files=[Upload.from_path("draft.pdf")])
|
|
151
|
+
attachment = mopux.tasks.upload_file(101, Upload.from_bytes("hello", "notes.txt"))
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Download URLs expire after 15 minutes.
|
|
155
|
+
|
|
156
|
+
### Pagination
|
|
157
|
+
|
|
158
|
+
Listings return a `Page` (`items`, `current_page`, `last_page`, `per_page`, `total`, `has_more()`, `next_page()`); the `iter…()` methods walk every page lazily. `tasks.my()` is not paginated. Prefer the aggregated endpoints (`projects.board()`, `projects.summary()`, `tasks.my()`) to fetching objects one by one.
|
|
159
|
+
|
|
160
|
+
## Errors
|
|
161
|
+
|
|
162
|
+
Every error extends `MopuxError`.
|
|
163
|
+
|
|
164
|
+
| Error | When |
|
|
165
|
+
| --- | --- |
|
|
166
|
+
| `AuthenticationError` | 401: missing, invalid or revoked token |
|
|
167
|
+
| `AuthorizationError` | 403: no permission, missing OAuth scope, plan restriction or blocked billing |
|
|
168
|
+
| `NotFoundError` | 404 |
|
|
169
|
+
| `ValidationError` | 422: `errors` holds the messages per field |
|
|
170
|
+
| `RateLimitError` | 429 after the retries; `retry_after` holds the seconds to wait |
|
|
171
|
+
| `ClientError` | other 4xx |
|
|
172
|
+
| `ServerError` | 5xx on a read |
|
|
173
|
+
| `UncertainWriteError` | 5xx on a write: the change **may have been applied** |
|
|
174
|
+
| `MopuxConnectionError` | network failure; `is_write_outcome_uncertain` is true for writes |
|
|
175
|
+
| `InvalidInputError` | rejected before sending (also a `ValueError`) |
|
|
176
|
+
| `MalformedResponseError` | unexpected response shape |
|
|
177
|
+
|
|
178
|
+
Every `ApiError` gives `status`, `body`, `api_message` and `code`, the stable machine-readable `data.code`. Branch on the code, never on the message: `is_plan_restriction()` (with `plan_feature`) and `is_billing_blocked()`.
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
from mopux import UncertainWriteError, ValidationError
|
|
182
|
+
|
|
183
|
+
try:
|
|
184
|
+
mopux.tasks.create(12, 7, "")
|
|
185
|
+
except ValidationError as error:
|
|
186
|
+
print(error.errors)
|
|
187
|
+
except UncertainWriteError:
|
|
188
|
+
... # Do not create the task again blindly: check whether it exists first.
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Retries
|
|
192
|
+
|
|
193
|
+
Enabled by default (2 retries, exponential backoff with jitter): `429` is retried for every method honouring `Retry-After` up to 60 seconds; network errors and `5xx` are retried for reads only; writes are **never** retried after a network error or a `5xx`.
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
from mopux import Mopux, RetryPolicy
|
|
197
|
+
|
|
198
|
+
Mopux(url, token, retry=RetryPolicy(max_retries=4))
|
|
199
|
+
Mopux(url, token, retry=RetryPolicy.none())
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Other options: `timeout` (seconds, default 30), `user_agent` (appended to the SDK one), `headers` and `http_client` (your own `httpx.Client` / `httpx.AsyncClient`, e.g. for proxies or custom certificates).
|
|
203
|
+
|
|
204
|
+
## Testing
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
from mopux import Mopux
|
|
208
|
+
from mopux.testing import MockApi
|
|
209
|
+
|
|
210
|
+
api = MockApi().push(MockApi.json([{"id": 1, "title": "Review"}]), MockApi.plan_restricted())
|
|
211
|
+
mopux = Mopux("https://acme.test", "test", http_client=api.client())
|
|
212
|
+
|
|
213
|
+
mopux.tasks.my()
|
|
214
|
+
api.assert_sent("GET", "tasks/my")
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Use `api.async_client()` with `AsyncMopux`. Helpers: `MockApi.json()`, `error()`, `validation()`, `plan_restricted()`, `network_error()`, `always()` and `assert_nothing_sent()`.
|
|
218
|
+
|
|
219
|
+
## Development
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
uv sync
|
|
223
|
+
uv run pytest # unit and contract tests (71/71 operations, sync and async)
|
|
224
|
+
uv run mypy src && uv run ruff check src tests scripts
|
|
225
|
+
uv run python scripts/generate.py # regenerate the models from spec/openapi.yaml
|
|
226
|
+
uv run python scripts/unasync.py # regenerate src/mopux/_sync from src/mopux/_async
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Only edit `src/mopux/_async`; the sync client is generated and CI fails if it is out of date. Integration tests run against a real installation: `MOPUX_INTEGRATION_URL=… MOPUX_INTEGRATION_TOKEN=… uv run pytest -m integration`.
|
|
230
|
+
|
|
231
|
+
## License
|
|
232
|
+
|
|
233
|
+
MIT. See [LICENSE](LICENSE).
|
mopux-0.1.0/README.md
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# Mopux Python
|
|
2
|
+
|
|
3
|
+
Official Python client for the [Mopux](https://www.mopux.com) API (`/api/v1`).
|
|
4
|
+
|
|
5
|
+
- Every API operation covered (71/71), checked against the OpenAPI spec in CI.
|
|
6
|
+
- Sync (`Mopux`) and async (`AsyncMopux`) clients with the same API, built on `httpx`.
|
|
7
|
+
- Typed `pydantic` models generated from the OpenAPI spec; unknown fields are kept, so a newer API does not break the client.
|
|
8
|
+
- Safe by default: retries rate-limited requests and failed reads, **never** retries a write whose outcome is unknown.
|
|
9
|
+
- `MockApi` testing helper in `mopux.testing`.
|
|
10
|
+
|
|
11
|
+
## Requirements
|
|
12
|
+
|
|
13
|
+
Python 3.11 to 3.14. Only Python versions that still receive security fixes are supported.
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install mopux
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from mopux import Mopux
|
|
25
|
+
|
|
26
|
+
with Mopux("https://acme.mopux.com", token) as mopux:
|
|
27
|
+
board = mopux.projects.board(12)
|
|
28
|
+
for group in board.task_groups or []:
|
|
29
|
+
print(f"{group.title}: {len(group.tasks or [])} open tasks")
|
|
30
|
+
|
|
31
|
+
task = mopux.tasks.create(
|
|
32
|
+
12, # project id
|
|
33
|
+
7, # group id
|
|
34
|
+
"Write the release notes",
|
|
35
|
+
priority=2,
|
|
36
|
+
hours_expected="2:30",
|
|
37
|
+
assignees=[3, 5],
|
|
38
|
+
)
|
|
39
|
+
mopux.tasks.update_status(task.id, 3)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Async:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
from mopux import AsyncMopux
|
|
46
|
+
|
|
47
|
+
async with AsyncMopux("https://acme.mopux.com", token) as mopux:
|
|
48
|
+
tasks = await mopux.tasks.my()
|
|
49
|
+
async for project in mopux.projects.iter():
|
|
50
|
+
print(project.title)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Authentication
|
|
54
|
+
|
|
55
|
+
The base URL is your Mopux installation (each installation has its own domain). The client adds `/api/v1/` itself.
|
|
56
|
+
|
|
57
|
+
**Personal access token.** Exchange credentials once and store the token (the API only shows it once):
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
mopux = Mopux.login("https://acme.mopux.com", email, password, token_name="my-app")
|
|
61
|
+
save_secret(mopux.token)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Later:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
mopux = Mopux("https://acme.mopux.com", token)
|
|
68
|
+
mopux.auth.user() # the token's user
|
|
69
|
+
mopux.auth.logout() # revokes the token
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`token` also accepts a function called before every request (for tokens kept in a vault or refreshed elsewhere).
|
|
73
|
+
|
|
74
|
+
Each login creates a new token. List and revoke the user's API tokens; secrets are never returned:
|
|
75
|
+
|
|
76
|
+
```python
|
|
77
|
+
for api_token in mopux.auth.tokens.list():
|
|
78
|
+
print(api_token.id, api_token.name, "(this client)" if api_token.current else "")
|
|
79
|
+
mopux.auth.tokens.delete(leaked_token_id)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Changing or resetting the password revokes every token of the user, and API tokens unused for 90 days are deleted: log in again when you get an `AuthenticationError`.
|
|
83
|
+
|
|
84
|
+
The user needs the "API use" permission, and the installation's plan must include the API; otherwise the API answers `403` (`is_plan_restriction()` tells the plan case apart).
|
|
85
|
+
|
|
86
|
+
**OAuth.** Pass the access token the same way. Reads need the `mopux:read` scope and writes `mopux:write`. Tokens created for the MCP connector are rejected by the REST API.
|
|
87
|
+
|
|
88
|
+
**Several installations.** Create one client per installation, or derive one with another token with `mopux.with_token(token)` (it shares the HTTP connections).
|
|
89
|
+
|
|
90
|
+
## Resources
|
|
91
|
+
|
|
92
|
+
| Attribute | Covers |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| `mopux.auth` | `login`, `logout`, `user`, `tokens.list()` / `tokens.delete()` |
|
|
95
|
+
| `mopux.projects` | `list`, `iter`, `create`, `show`, `update`, `delete`, `board`, `activity`, `summary`, members |
|
|
96
|
+
| `mopux.task_groups` | `create` (optionally with up to 4 tasks), `reorder`, `rename`, `archive`, `move`, `copy`, `create_project`, `focus`, `status_summary` |
|
|
97
|
+
| `mopux.tasks` | `create`, `update`, `update_batch`, `my`, `show`, `delete`, single-field updates, `move`, `send_touch`, focus list, documents |
|
|
98
|
+
| `mopux.comments` | `list`, `iter`, `create` (with mentions and files), `update`, `delete`, `reply` |
|
|
99
|
+
| `mopux.notifications` | `list`, `iter`, `mark_read`, `mark_unread`, `mark_all_read`, `unread_count`, `delete` |
|
|
100
|
+
| `mopux.touches` | `list`, `reply` |
|
|
101
|
+
| `mopux.team` / `mopux.team_invitations` | installation users, invitations |
|
|
102
|
+
|
|
103
|
+
### Updating tasks
|
|
104
|
+
|
|
105
|
+
`update()` changes only the arguments you pass, atomically. `None` clears description, dates and hours; leaving an argument out keeps the value. Assignees are an explicit mutation:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
mopux.tasks.update(
|
|
109
|
+
101,
|
|
110
|
+
date_end=None,
|
|
111
|
+
hours_inverted="1:15",
|
|
112
|
+
assignees={"operation": "add", "user_ids": [8]}, # or "remove" / "replace"
|
|
113
|
+
)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Hours are `HH:MM` (or minutes); the API returns them as `HH:MM:SS`. Status `-1` (delayed) is read only.
|
|
117
|
+
|
|
118
|
+
### Comments and documents
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
from mopux import Upload
|
|
122
|
+
|
|
123
|
+
mopux.comments.create(101, "Draft attached @Ada#5", files=[Upload.from_path("draft.pdf")])
|
|
124
|
+
attachment = mopux.tasks.upload_file(101, Upload.from_bytes("hello", "notes.txt"))
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Download URLs expire after 15 minutes.
|
|
128
|
+
|
|
129
|
+
### Pagination
|
|
130
|
+
|
|
131
|
+
Listings return a `Page` (`items`, `current_page`, `last_page`, `per_page`, `total`, `has_more()`, `next_page()`); the `iter…()` methods walk every page lazily. `tasks.my()` is not paginated. Prefer the aggregated endpoints (`projects.board()`, `projects.summary()`, `tasks.my()`) to fetching objects one by one.
|
|
132
|
+
|
|
133
|
+
## Errors
|
|
134
|
+
|
|
135
|
+
Every error extends `MopuxError`.
|
|
136
|
+
|
|
137
|
+
| Error | When |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| `AuthenticationError` | 401: missing, invalid or revoked token |
|
|
140
|
+
| `AuthorizationError` | 403: no permission, missing OAuth scope, plan restriction or blocked billing |
|
|
141
|
+
| `NotFoundError` | 404 |
|
|
142
|
+
| `ValidationError` | 422: `errors` holds the messages per field |
|
|
143
|
+
| `RateLimitError` | 429 after the retries; `retry_after` holds the seconds to wait |
|
|
144
|
+
| `ClientError` | other 4xx |
|
|
145
|
+
| `ServerError` | 5xx on a read |
|
|
146
|
+
| `UncertainWriteError` | 5xx on a write: the change **may have been applied** |
|
|
147
|
+
| `MopuxConnectionError` | network failure; `is_write_outcome_uncertain` is true for writes |
|
|
148
|
+
| `InvalidInputError` | rejected before sending (also a `ValueError`) |
|
|
149
|
+
| `MalformedResponseError` | unexpected response shape |
|
|
150
|
+
|
|
151
|
+
Every `ApiError` gives `status`, `body`, `api_message` and `code`, the stable machine-readable `data.code`. Branch on the code, never on the message: `is_plan_restriction()` (with `plan_feature`) and `is_billing_blocked()`.
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
from mopux import UncertainWriteError, ValidationError
|
|
155
|
+
|
|
156
|
+
try:
|
|
157
|
+
mopux.tasks.create(12, 7, "")
|
|
158
|
+
except ValidationError as error:
|
|
159
|
+
print(error.errors)
|
|
160
|
+
except UncertainWriteError:
|
|
161
|
+
... # Do not create the task again blindly: check whether it exists first.
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Retries
|
|
165
|
+
|
|
166
|
+
Enabled by default (2 retries, exponential backoff with jitter): `429` is retried for every method honouring `Retry-After` up to 60 seconds; network errors and `5xx` are retried for reads only; writes are **never** retried after a network error or a `5xx`.
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
from mopux import Mopux, RetryPolicy
|
|
170
|
+
|
|
171
|
+
Mopux(url, token, retry=RetryPolicy(max_retries=4))
|
|
172
|
+
Mopux(url, token, retry=RetryPolicy.none())
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Other options: `timeout` (seconds, default 30), `user_agent` (appended to the SDK one), `headers` and `http_client` (your own `httpx.Client` / `httpx.AsyncClient`, e.g. for proxies or custom certificates).
|
|
176
|
+
|
|
177
|
+
## Testing
|
|
178
|
+
|
|
179
|
+
```python
|
|
180
|
+
from mopux import Mopux
|
|
181
|
+
from mopux.testing import MockApi
|
|
182
|
+
|
|
183
|
+
api = MockApi().push(MockApi.json([{"id": 1, "title": "Review"}]), MockApi.plan_restricted())
|
|
184
|
+
mopux = Mopux("https://acme.test", "test", http_client=api.client())
|
|
185
|
+
|
|
186
|
+
mopux.tasks.my()
|
|
187
|
+
api.assert_sent("GET", "tasks/my")
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Use `api.async_client()` with `AsyncMopux`. Helpers: `MockApi.json()`, `error()`, `validation()`, `plan_restricted()`, `network_error()`, `always()` and `assert_nothing_sent()`.
|
|
191
|
+
|
|
192
|
+
## Development
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
uv sync
|
|
196
|
+
uv run pytest # unit and contract tests (71/71 operations, sync and async)
|
|
197
|
+
uv run mypy src && uv run ruff check src tests scripts
|
|
198
|
+
uv run python scripts/generate.py # regenerate the models from spec/openapi.yaml
|
|
199
|
+
uv run python scripts/unasync.py # regenerate src/mopux/_sync from src/mopux/_async
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Only edit `src/mopux/_async`; the sync client is generated and CI fails if it is out of date. Integration tests run against a real installation: `MOPUX_INTEGRATION_URL=… MOPUX_INTEGRATION_TOKEN=… uv run pytest -m integration`.
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "mopux"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Official Python SDK for the Mopux API"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "Mopux", email = "support@mopux.com" }]
|
|
9
|
+
requires-python = ">=3.11"
|
|
10
|
+
dependencies = [
|
|
11
|
+
"httpx>=0.27,<1",
|
|
12
|
+
"pydantic>=2.10,<3; python_version < '3.14'",
|
|
13
|
+
"pydantic>=2.12,<3; python_version >= '3.14'",
|
|
14
|
+
"typing-extensions>=4.12",
|
|
15
|
+
]
|
|
16
|
+
keywords = ["mopux", "api", "sdk", "projects", "tasks"]
|
|
17
|
+
classifiers = [
|
|
18
|
+
"Development Status :: 4 - Beta",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Programming Language :: Python :: 3.14",
|
|
25
|
+
"Typing :: Typed",
|
|
26
|
+
]
|
|
27
|
+
|
|
28
|
+
[project.urls]
|
|
29
|
+
Homepage = "https://www.mopux.com"
|
|
30
|
+
Source = "https://github.com/mopux/mopux-python"
|
|
31
|
+
Issues = "https://github.com/mopux/mopux-python/issues"
|
|
32
|
+
Changelog = "https://github.com/mopux/mopux-python/blob/main/CHANGELOG.md"
|
|
33
|
+
|
|
34
|
+
[dependency-groups]
|
|
35
|
+
dev = [
|
|
36
|
+
"datamodel-code-generator==0.100.0",
|
|
37
|
+
"mypy==2.4.1",
|
|
38
|
+
"pytest==9.2.0",
|
|
39
|
+
"pytest-asyncio==1.5.0",
|
|
40
|
+
"pyyaml>=6",
|
|
41
|
+
"ruff==0.17.6",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[build-system]
|
|
45
|
+
requires = ["hatchling==1.33.0"]
|
|
46
|
+
build-backend = "hatchling.build"
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.wheel]
|
|
49
|
+
packages = ["src/mopux"]
|
|
50
|
+
|
|
51
|
+
[tool.hatch.build.targets.sdist]
|
|
52
|
+
include = ["src/mopux", "README.md", "CHANGELOG.md", "LICENSE"]
|
|
53
|
+
|
|
54
|
+
[tool.ruff]
|
|
55
|
+
line-length = 120
|
|
56
|
+
target-version = "py311"
|
|
57
|
+
extend-exclude = ["src/mopux/models/_generated.py", "src/mopux/_sync"]
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint]
|
|
60
|
+
select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
|
|
61
|
+
|
|
62
|
+
[tool.mypy]
|
|
63
|
+
strict = true
|
|
64
|
+
python_version = "3.11"
|
|
65
|
+
plugins = ["pydantic.mypy"]
|
|
66
|
+
|
|
67
|
+
[[tool.mypy.overrides]]
|
|
68
|
+
module = ["yaml"]
|
|
69
|
+
ignore_missing_imports = true
|
|
70
|
+
|
|
71
|
+
[tool.pytest.ini_options]
|
|
72
|
+
testpaths = ["tests"]
|
|
73
|
+
asyncio_mode = "auto"
|
|
74
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
75
|
+
markers = ["integration: runs against a real installation (needs MOPUX_INTEGRATION_URL)"]
|
|
76
|
+
addopts = "-m 'not integration'"
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Official Python SDK for the Mopux API."""
|
|
2
|
+
|
|
3
|
+
from ._async.client import AsyncMopux
|
|
4
|
+
from ._async.connector import AsyncConnector
|
|
5
|
+
from ._base import UNSET, Unset
|
|
6
|
+
from ._retry import RetryPolicy
|
|
7
|
+
from ._sync.client import Mopux
|
|
8
|
+
from ._sync.connector import Connector
|
|
9
|
+
from ._version import __version__
|
|
10
|
+
from .errors import (
|
|
11
|
+
ApiError,
|
|
12
|
+
AuthenticationError,
|
|
13
|
+
AuthorizationError,
|
|
14
|
+
ClientError,
|
|
15
|
+
InvalidInputError,
|
|
16
|
+
MalformedResponseError,
|
|
17
|
+
MopuxConnectionError,
|
|
18
|
+
MopuxError,
|
|
19
|
+
NotFoundError,
|
|
20
|
+
RateLimitError,
|
|
21
|
+
ServerError,
|
|
22
|
+
UncertainWriteError,
|
|
23
|
+
ValidationError,
|
|
24
|
+
)
|
|
25
|
+
from .page import Page
|
|
26
|
+
from .upload import Upload
|
|
27
|
+
|
|
28
|
+
TaskStatuses = {"pending": 0, "in_progress": 1, "review": 2, "done": 3}
|
|
29
|
+
TaskPriorities = {"low": 0, "normal": 1, "high": 2, "maximum": 9}
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"UNSET",
|
|
33
|
+
"ApiError",
|
|
34
|
+
"AsyncConnector",
|
|
35
|
+
"AsyncMopux",
|
|
36
|
+
"AuthenticationError",
|
|
37
|
+
"AuthorizationError",
|
|
38
|
+
"ClientError",
|
|
39
|
+
"Connector",
|
|
40
|
+
"InvalidInputError",
|
|
41
|
+
"MalformedResponseError",
|
|
42
|
+
"Mopux",
|
|
43
|
+
"MopuxConnectionError",
|
|
44
|
+
"MopuxError",
|
|
45
|
+
"NotFoundError",
|
|
46
|
+
"Page",
|
|
47
|
+
"RateLimitError",
|
|
48
|
+
"RetryPolicy",
|
|
49
|
+
"ServerError",
|
|
50
|
+
"TaskPriorities",
|
|
51
|
+
"TaskStatuses",
|
|
52
|
+
"UncertainWriteError",
|
|
53
|
+
"Unset",
|
|
54
|
+
"Upload",
|
|
55
|
+
"ValidationError",
|
|
56
|
+
"__version__",
|
|
57
|
+
]
|
|
File without changes
|