cholaka 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.
- cholaka-0.1.0/.gitignore +6 -0
- cholaka-0.1.0/PKG-INFO +221 -0
- cholaka-0.1.0/README.md +208 -0
- cholaka-0.1.0/pyproject.toml +28 -0
- cholaka-0.1.0/src/cholaka/__init__.py +128 -0
- cholaka-0.1.0/src/cholaka/_client.py +176 -0
- cholaka-0.1.0/src/cholaka/_errors.py +115 -0
- cholaka-0.1.0/src/cholaka/_models.py +215 -0
- cholaka-0.1.0/src/cholaka/_resources.py +393 -0
- cholaka-0.1.0/src/cholaka/_version.py +1 -0
- cholaka-0.1.0/src/cholaka/py.typed +0 -0
- cholaka-0.1.0/tests/test_client.py +450 -0
cholaka-0.1.0/.gitignore
ADDED
cholaka-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: cholaka
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Python SDK for the Cholaka posting and scheduling API
|
|
5
|
+
Keywords: cholaka,facebook,instagram,scheduling,social media
|
|
6
|
+
Classifier: Programming Language :: Python :: 3
|
|
7
|
+
Classifier: Typing :: Typed
|
|
8
|
+
Requires-Python: >=3.9
|
|
9
|
+
Requires-Dist: httpx<1,>=0.24
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
|
|
14
|
+
# Cholaka Python SDK
|
|
15
|
+
|
|
16
|
+
Create, schedule and publish posts to your Cholaka organization's connected
|
|
17
|
+
Facebook Pages and Instagram accounts from Python.
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install cholaka
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Requires Python 3.9+.
|
|
24
|
+
|
|
25
|
+
## Get an API token
|
|
26
|
+
|
|
27
|
+
In Cholaka, an organization admin opens **Settings → Integrations → New token**
|
|
28
|
+
and grants:
|
|
29
|
+
|
|
30
|
+
- `posts:read` to list accounts and read posts
|
|
31
|
+
- `posts:write` to upload media and create, change or delete posts
|
|
32
|
+
|
|
33
|
+
The token (`cho_…`) is shown once. Store it as a secret, for example in the
|
|
34
|
+
`CHOLAKA_API_KEY` environment variable.
|
|
35
|
+
|
|
36
|
+
## Quick start
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from datetime import datetime, timedelta, timezone
|
|
40
|
+
from cholaka import Cholaka
|
|
41
|
+
|
|
42
|
+
client = Cholaka() # reads CHOLAKA_API_KEY
|
|
43
|
+
|
|
44
|
+
# 1. Pick the accounts to post to.
|
|
45
|
+
for account in client.accounts.list():
|
|
46
|
+
print(account.id, account.platform, account.name)
|
|
47
|
+
|
|
48
|
+
page = client.accounts.list(platform="fb_page")[0]
|
|
49
|
+
|
|
50
|
+
# 2. Upload media (optional).
|
|
51
|
+
photo = client.media.upload("launch.jpg")
|
|
52
|
+
|
|
53
|
+
# 3. Schedule the post.
|
|
54
|
+
post = client.posts.create(
|
|
55
|
+
"We launch tomorrow!",
|
|
56
|
+
account_ids=[page.id],
|
|
57
|
+
media=[photo],
|
|
58
|
+
scheduled_at=datetime.now(timezone.utc) + timedelta(hours=2),
|
|
59
|
+
)
|
|
60
|
+
print(post.id, post.status) # "scheduled", or "pending_approval"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Publish straight away and wait for the result:
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
post = client.posts.create("Live now", account_ids=[page.id], publish_now=True)
|
|
67
|
+
post = client.posts.wait_for_publish(post, timeout=300)
|
|
68
|
+
|
|
69
|
+
if post.status == "published":
|
|
70
|
+
for target in post.targets:
|
|
71
|
+
print(target.account_name, target.permalink_url)
|
|
72
|
+
else:
|
|
73
|
+
for target in post.targets:
|
|
74
|
+
print(target.account_name, target.status, target.error)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Configuration
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
client = Cholaka(
|
|
81
|
+
api_key="cho_...", # default: CHOLAKA_API_KEY
|
|
82
|
+
base_url="https://api.cholaka.ai", # default: CHOLAKA_BASE_URL, then this
|
|
83
|
+
timeout=60.0, # seconds per request
|
|
84
|
+
max_retries=2,
|
|
85
|
+
)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`base_url` may be the host alone or end in `/api/v1`. Use `with Cholaka() as
|
|
89
|
+
client:` (or `client.close()`) to release connections. To use proxies or
|
|
90
|
+
custom TLS, pass your own `httpx.Client` as `http_client=`.
|
|
91
|
+
|
|
92
|
+
## Posts
|
|
93
|
+
|
|
94
|
+
| Call | What it does |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| `posts.create(content, account_ids=, media=, scheduled_at=, publish_now=, options=, media_meta=)` | Create a draft (neither time nor `publish_now`), a scheduled post, or publish now |
|
|
97
|
+
| `posts.get(id)` | One post with per-account status, error and permalink |
|
|
98
|
+
| `posts.list(status=, account_id=, date_from=, date_to=, limit=, cursor=)` | One page, newest first. `page.next_cursor` gets the next |
|
|
99
|
+
| `posts.iter(**filters)` | Every matching post across all pages |
|
|
100
|
+
| `posts.update(id, content=, account_ids=, media=, options=, scheduled_at=)` | Change a draft, scheduled or failed post. On a published post only `content` can change |
|
|
101
|
+
| `posts.schedule(id, at)` | Schedule or reschedule |
|
|
102
|
+
| `posts.unschedule(id)` | Back to draft |
|
|
103
|
+
| `posts.publish(id)` | Publish now |
|
|
104
|
+
| `posts.retry(id)` | Retry a failed post |
|
|
105
|
+
| `posts.duplicate(id)` | Copy into a new draft |
|
|
106
|
+
| `posts.delete(id)` | Delete (cancels a scheduled publish) |
|
|
107
|
+
| `posts.wait_for_publish(id, timeout=, poll_interval=)` | Poll until published, failed or rejected |
|
|
108
|
+
|
|
109
|
+
Any argument that takes an id also accepts the object itself (`Post`,
|
|
110
|
+
`Account`, `MediaAsset`).
|
|
111
|
+
|
|
112
|
+
**Times** must be timezone-aware `datetime`s or ISO 8601 strings. A naive
|
|
113
|
+
`datetime` raises `ValueError` rather than guessing the timezone. For local
|
|
114
|
+
time, use `datetime.now().astimezone()`.
|
|
115
|
+
|
|
116
|
+
**Statuses** (`cholaka.PostStatus`): `draft`, `scheduled`,
|
|
117
|
+
`pending_approval`, `publishing`, `published`, `failed`, `rejected`. If your
|
|
118
|
+
organization requires approval for the token's owner, scheduled and
|
|
119
|
+
publish-now posts wait in `pending_approval` until an admin approves them in
|
|
120
|
+
the app.
|
|
121
|
+
|
|
122
|
+
**Platform options** go in `options`, using the API's field names. For example:
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
client.posts.create("Story time", account_ids=[ig.id], media=[photo],
|
|
126
|
+
options={"igStory": True}, publish_now=True)
|
|
127
|
+
client.posts.create("Read this", account_ids=[page.id],
|
|
128
|
+
options={"fbLink": "https://example.com/post"})
|
|
129
|
+
client.posts.create("Reel", account_ids=[ig.id], media=[video],
|
|
130
|
+
options={"igShareToFeed": True, "igThumbOffsetMs": 1500})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Alt text and people tags go in `media_meta`:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
client.posts.create("Team day", account_ids=[ig.id], media=[photo],
|
|
137
|
+
media_meta=[{"assetId": photo.id, "altText": "Our team on the roof",
|
|
138
|
+
"userTags": [{"username": "cholaka", "x": 0.5, "y": 0.4}]}])
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The full list of options is in the API reference at
|
|
142
|
+
`https://<your-api-host>/api/public-docs`.
|
|
143
|
+
|
|
144
|
+
## Media
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
asset = client.media.upload("photo.png") # path
|
|
148
|
+
asset = client.media.upload(open("clip.mp4", "rb")) # file object
|
|
149
|
+
asset = client.media.upload(data, filename="banner.jpg") # bytes
|
|
150
|
+
client.media.delete(asset)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Supported: JPEG, PNG and WebP images up to 8 MB (stored as JPEG), and MP4 or
|
|
154
|
+
MOV video up to 100 MB.
|
|
155
|
+
|
|
156
|
+
## Accounts
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
client.accounts.list() # all connected accounts
|
|
160
|
+
client.accounts.list(platform="ig_business") # one platform
|
|
161
|
+
client.accounts.publishing_limit(ig) # Instagram's 24h quota
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Errors
|
|
165
|
+
|
|
166
|
+
Every error is a `cholaka.CholakaError`. Errors returned by the API are
|
|
167
|
+
`APIError`s with `status_code`, `message` and `messages` (one per validation
|
|
168
|
+
problem):
|
|
169
|
+
|
|
170
|
+
| Exception | Status | Typical cause |
|
|
171
|
+
| --- | --- | --- |
|
|
172
|
+
| `BadRequestError` | 400 | Invalid input, scheduled time in the past |
|
|
173
|
+
| `AuthenticationError` | 401 | Token missing, revoked or expired |
|
|
174
|
+
| `PermissionDeniedError` | 403 | Token lacks the scope, or the owner lacks the role |
|
|
175
|
+
| `NotFoundError` | 404 | Unknown post, media or account |
|
|
176
|
+
| `ConflictError` | 409 | The post's status doesn't allow the change |
|
|
177
|
+
| `UnprocessableEntityError` | 422 | Idempotency key reused with different data |
|
|
178
|
+
| `RateLimitError` | 429 | Too many requests (`.retry_after` seconds) |
|
|
179
|
+
| `InternalServerError` | 5xx | Server problem |
|
|
180
|
+
| `APIConnectionError` | – | Network failure |
|
|
181
|
+
| `PublishTimeoutError` | – | `wait_for_publish` timed out (`.post` has the last state) |
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
from cholaka import BadRequestError
|
|
185
|
+
|
|
186
|
+
try:
|
|
187
|
+
client.posts.create("Hi", account_ids=[page.id], scheduled_at="2020-01-01T00:00:00Z")
|
|
188
|
+
except BadRequestError as e:
|
|
189
|
+
print(e.messages) # ['Scheduled time is in the past']
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Retries, rate limits and duplicates
|
|
193
|
+
|
|
194
|
+
Each token may make 120 requests per minute by default. The SDK retries
|
|
195
|
+
automatically, up to `max_retries` times:
|
|
196
|
+
|
|
197
|
+
- **429 Too Many Requests**: waits for `Retry-After`, then retries any call.
|
|
198
|
+
The server refuses these before doing any work.
|
|
199
|
+
- **Connection refused**: retries any call.
|
|
200
|
+
- **502/503/504 and dropped connections**: retries reads, deletes and creates.
|
|
201
|
+
It does not retry updates, so a publish is never repeated without you
|
|
202
|
+
knowing.
|
|
203
|
+
|
|
204
|
+
`posts.create` and `posts.duplicate` send an `Idempotency-Key`, so a retried
|
|
205
|
+
request never creates the post twice. To stay safe across process restarts,
|
|
206
|
+
pass your own stable key, for example from your database row:
|
|
207
|
+
|
|
208
|
+
```python
|
|
209
|
+
client.posts.create("Weekly digest", account_ids=[page.id],
|
|
210
|
+
scheduled_at=when, idempotency_key=f"digest-{week_id}")
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
The same key with different content raises `UnprocessableEntityError`.
|
|
214
|
+
|
|
215
|
+
## Development
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
python -m venv .venv && . .venv/bin/activate
|
|
219
|
+
pip install -e ".[dev]"
|
|
220
|
+
pytest
|
|
221
|
+
```
|
cholaka-0.1.0/README.md
ADDED
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
# Cholaka Python SDK
|
|
2
|
+
|
|
3
|
+
Create, schedule and publish posts to your Cholaka organization's connected
|
|
4
|
+
Facebook Pages and Instagram accounts from Python.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
pip install cholaka
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Requires Python 3.9+.
|
|
11
|
+
|
|
12
|
+
## Get an API token
|
|
13
|
+
|
|
14
|
+
In Cholaka, an organization admin opens **Settings → Integrations → New token**
|
|
15
|
+
and grants:
|
|
16
|
+
|
|
17
|
+
- `posts:read` to list accounts and read posts
|
|
18
|
+
- `posts:write` to upload media and create, change or delete posts
|
|
19
|
+
|
|
20
|
+
The token (`cho_…`) is shown once. Store it as a secret, for example in the
|
|
21
|
+
`CHOLAKA_API_KEY` environment variable.
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
from datetime import datetime, timedelta, timezone
|
|
27
|
+
from cholaka import Cholaka
|
|
28
|
+
|
|
29
|
+
client = Cholaka() # reads CHOLAKA_API_KEY
|
|
30
|
+
|
|
31
|
+
# 1. Pick the accounts to post to.
|
|
32
|
+
for account in client.accounts.list():
|
|
33
|
+
print(account.id, account.platform, account.name)
|
|
34
|
+
|
|
35
|
+
page = client.accounts.list(platform="fb_page")[0]
|
|
36
|
+
|
|
37
|
+
# 2. Upload media (optional).
|
|
38
|
+
photo = client.media.upload("launch.jpg")
|
|
39
|
+
|
|
40
|
+
# 3. Schedule the post.
|
|
41
|
+
post = client.posts.create(
|
|
42
|
+
"We launch tomorrow!",
|
|
43
|
+
account_ids=[page.id],
|
|
44
|
+
media=[photo],
|
|
45
|
+
scheduled_at=datetime.now(timezone.utc) + timedelta(hours=2),
|
|
46
|
+
)
|
|
47
|
+
print(post.id, post.status) # "scheduled", or "pending_approval"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Publish straight away and wait for the result:
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
post = client.posts.create("Live now", account_ids=[page.id], publish_now=True)
|
|
54
|
+
post = client.posts.wait_for_publish(post, timeout=300)
|
|
55
|
+
|
|
56
|
+
if post.status == "published":
|
|
57
|
+
for target in post.targets:
|
|
58
|
+
print(target.account_name, target.permalink_url)
|
|
59
|
+
else:
|
|
60
|
+
for target in post.targets:
|
|
61
|
+
print(target.account_name, target.status, target.error)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Configuration
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
client = Cholaka(
|
|
68
|
+
api_key="cho_...", # default: CHOLAKA_API_KEY
|
|
69
|
+
base_url="https://api.cholaka.ai", # default: CHOLAKA_BASE_URL, then this
|
|
70
|
+
timeout=60.0, # seconds per request
|
|
71
|
+
max_retries=2,
|
|
72
|
+
)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`base_url` may be the host alone or end in `/api/v1`. Use `with Cholaka() as
|
|
76
|
+
client:` (or `client.close()`) to release connections. To use proxies or
|
|
77
|
+
custom TLS, pass your own `httpx.Client` as `http_client=`.
|
|
78
|
+
|
|
79
|
+
## Posts
|
|
80
|
+
|
|
81
|
+
| Call | What it does |
|
|
82
|
+
| --- | --- |
|
|
83
|
+
| `posts.create(content, account_ids=, media=, scheduled_at=, publish_now=, options=, media_meta=)` | Create a draft (neither time nor `publish_now`), a scheduled post, or publish now |
|
|
84
|
+
| `posts.get(id)` | One post with per-account status, error and permalink |
|
|
85
|
+
| `posts.list(status=, account_id=, date_from=, date_to=, limit=, cursor=)` | One page, newest first. `page.next_cursor` gets the next |
|
|
86
|
+
| `posts.iter(**filters)` | Every matching post across all pages |
|
|
87
|
+
| `posts.update(id, content=, account_ids=, media=, options=, scheduled_at=)` | Change a draft, scheduled or failed post. On a published post only `content` can change |
|
|
88
|
+
| `posts.schedule(id, at)` | Schedule or reschedule |
|
|
89
|
+
| `posts.unschedule(id)` | Back to draft |
|
|
90
|
+
| `posts.publish(id)` | Publish now |
|
|
91
|
+
| `posts.retry(id)` | Retry a failed post |
|
|
92
|
+
| `posts.duplicate(id)` | Copy into a new draft |
|
|
93
|
+
| `posts.delete(id)` | Delete (cancels a scheduled publish) |
|
|
94
|
+
| `posts.wait_for_publish(id, timeout=, poll_interval=)` | Poll until published, failed or rejected |
|
|
95
|
+
|
|
96
|
+
Any argument that takes an id also accepts the object itself (`Post`,
|
|
97
|
+
`Account`, `MediaAsset`).
|
|
98
|
+
|
|
99
|
+
**Times** must be timezone-aware `datetime`s or ISO 8601 strings. A naive
|
|
100
|
+
`datetime` raises `ValueError` rather than guessing the timezone. For local
|
|
101
|
+
time, use `datetime.now().astimezone()`.
|
|
102
|
+
|
|
103
|
+
**Statuses** (`cholaka.PostStatus`): `draft`, `scheduled`,
|
|
104
|
+
`pending_approval`, `publishing`, `published`, `failed`, `rejected`. If your
|
|
105
|
+
organization requires approval for the token's owner, scheduled and
|
|
106
|
+
publish-now posts wait in `pending_approval` until an admin approves them in
|
|
107
|
+
the app.
|
|
108
|
+
|
|
109
|
+
**Platform options** go in `options`, using the API's field names. For example:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
client.posts.create("Story time", account_ids=[ig.id], media=[photo],
|
|
113
|
+
options={"igStory": True}, publish_now=True)
|
|
114
|
+
client.posts.create("Read this", account_ids=[page.id],
|
|
115
|
+
options={"fbLink": "https://example.com/post"})
|
|
116
|
+
client.posts.create("Reel", account_ids=[ig.id], media=[video],
|
|
117
|
+
options={"igShareToFeed": True, "igThumbOffsetMs": 1500})
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Alt text and people tags go in `media_meta`:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
client.posts.create("Team day", account_ids=[ig.id], media=[photo],
|
|
124
|
+
media_meta=[{"assetId": photo.id, "altText": "Our team on the roof",
|
|
125
|
+
"userTags": [{"username": "cholaka", "x": 0.5, "y": 0.4}]}])
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The full list of options is in the API reference at
|
|
129
|
+
`https://<your-api-host>/api/public-docs`.
|
|
130
|
+
|
|
131
|
+
## Media
|
|
132
|
+
|
|
133
|
+
```python
|
|
134
|
+
asset = client.media.upload("photo.png") # path
|
|
135
|
+
asset = client.media.upload(open("clip.mp4", "rb")) # file object
|
|
136
|
+
asset = client.media.upload(data, filename="banner.jpg") # bytes
|
|
137
|
+
client.media.delete(asset)
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Supported: JPEG, PNG and WebP images up to 8 MB (stored as JPEG), and MP4 or
|
|
141
|
+
MOV video up to 100 MB.
|
|
142
|
+
|
|
143
|
+
## Accounts
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
client.accounts.list() # all connected accounts
|
|
147
|
+
client.accounts.list(platform="ig_business") # one platform
|
|
148
|
+
client.accounts.publishing_limit(ig) # Instagram's 24h quota
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Errors
|
|
152
|
+
|
|
153
|
+
Every error is a `cholaka.CholakaError`. Errors returned by the API are
|
|
154
|
+
`APIError`s with `status_code`, `message` and `messages` (one per validation
|
|
155
|
+
problem):
|
|
156
|
+
|
|
157
|
+
| Exception | Status | Typical cause |
|
|
158
|
+
| --- | --- | --- |
|
|
159
|
+
| `BadRequestError` | 400 | Invalid input, scheduled time in the past |
|
|
160
|
+
| `AuthenticationError` | 401 | Token missing, revoked or expired |
|
|
161
|
+
| `PermissionDeniedError` | 403 | Token lacks the scope, or the owner lacks the role |
|
|
162
|
+
| `NotFoundError` | 404 | Unknown post, media or account |
|
|
163
|
+
| `ConflictError` | 409 | The post's status doesn't allow the change |
|
|
164
|
+
| `UnprocessableEntityError` | 422 | Idempotency key reused with different data |
|
|
165
|
+
| `RateLimitError` | 429 | Too many requests (`.retry_after` seconds) |
|
|
166
|
+
| `InternalServerError` | 5xx | Server problem |
|
|
167
|
+
| `APIConnectionError` | – | Network failure |
|
|
168
|
+
| `PublishTimeoutError` | – | `wait_for_publish` timed out (`.post` has the last state) |
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
from cholaka import BadRequestError
|
|
172
|
+
|
|
173
|
+
try:
|
|
174
|
+
client.posts.create("Hi", account_ids=[page.id], scheduled_at="2020-01-01T00:00:00Z")
|
|
175
|
+
except BadRequestError as e:
|
|
176
|
+
print(e.messages) # ['Scheduled time is in the past']
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Retries, rate limits and duplicates
|
|
180
|
+
|
|
181
|
+
Each token may make 120 requests per minute by default. The SDK retries
|
|
182
|
+
automatically, up to `max_retries` times:
|
|
183
|
+
|
|
184
|
+
- **429 Too Many Requests**: waits for `Retry-After`, then retries any call.
|
|
185
|
+
The server refuses these before doing any work.
|
|
186
|
+
- **Connection refused**: retries any call.
|
|
187
|
+
- **502/503/504 and dropped connections**: retries reads, deletes and creates.
|
|
188
|
+
It does not retry updates, so a publish is never repeated without you
|
|
189
|
+
knowing.
|
|
190
|
+
|
|
191
|
+
`posts.create` and `posts.duplicate` send an `Idempotency-Key`, so a retried
|
|
192
|
+
request never creates the post twice. To stay safe across process restarts,
|
|
193
|
+
pass your own stable key, for example from your database row:
|
|
194
|
+
|
|
195
|
+
```python
|
|
196
|
+
client.posts.create("Weekly digest", account_ids=[page.id],
|
|
197
|
+
scheduled_at=when, idempotency_key=f"digest-{week_id}")
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The same key with different content raises `UnprocessableEntityError`.
|
|
201
|
+
|
|
202
|
+
## Development
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
python -m venv .venv && . .venv/bin/activate
|
|
206
|
+
pip install -e ".[dev]"
|
|
207
|
+
pytest
|
|
208
|
+
```
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.24"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "cholaka"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Python SDK for the Cholaka posting and scheduling API"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
dependencies = ["httpx>=0.24,<1"]
|
|
12
|
+
keywords = ["cholaka", "social media", "scheduling", "facebook", "instagram"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Typing :: Typed",
|
|
16
|
+
]
|
|
17
|
+
|
|
18
|
+
[project.optional-dependencies]
|
|
19
|
+
dev = ["pytest>=7"]
|
|
20
|
+
|
|
21
|
+
[tool.hatch.version]
|
|
22
|
+
path = "src/cholaka/_version.py"
|
|
23
|
+
|
|
24
|
+
[tool.hatch.build.targets.wheel]
|
|
25
|
+
packages = ["src/cholaka"]
|
|
26
|
+
|
|
27
|
+
[tool.pytest.ini_options]
|
|
28
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
"""Python SDK for the Cholaka posting and scheduling API.
|
|
2
|
+
|
|
3
|
+
from datetime import datetime, timedelta, timezone
|
|
4
|
+
from cholaka import Cholaka
|
|
5
|
+
|
|
6
|
+
client = Cholaka() # reads CHOLAKA_API_KEY
|
|
7
|
+
page = client.accounts.list(platform="fb_page")[0]
|
|
8
|
+
photo = client.media.upload("launch.jpg")
|
|
9
|
+
post = client.posts.create(
|
|
10
|
+
"We launch tomorrow!",
|
|
11
|
+
account_ids=[page.id],
|
|
12
|
+
media=[photo],
|
|
13
|
+
scheduled_at=datetime.now(timezone.utc) + timedelta(hours=2),
|
|
14
|
+
)
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from typing import Optional
|
|
20
|
+
|
|
21
|
+
import httpx
|
|
22
|
+
|
|
23
|
+
from ._client import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, SyncAPIClient
|
|
24
|
+
from ._errors import (
|
|
25
|
+
APIConnectionError,
|
|
26
|
+
APIError,
|
|
27
|
+
AuthenticationError,
|
|
28
|
+
BadRequestError,
|
|
29
|
+
CholakaError,
|
|
30
|
+
ConflictError,
|
|
31
|
+
InternalServerError,
|
|
32
|
+
NotFoundError,
|
|
33
|
+
PermissionDeniedError,
|
|
34
|
+
PublishTimeoutError,
|
|
35
|
+
RateLimitError,
|
|
36
|
+
UnprocessableEntityError,
|
|
37
|
+
)
|
|
38
|
+
from ._models import (
|
|
39
|
+
FINAL_STATUSES,
|
|
40
|
+
Account,
|
|
41
|
+
MediaAsset,
|
|
42
|
+
Page,
|
|
43
|
+
Post,
|
|
44
|
+
PostStatus,
|
|
45
|
+
PostTarget,
|
|
46
|
+
PublishingLimit,
|
|
47
|
+
)
|
|
48
|
+
from ._resources import AccountsResource, MediaResource, PostsResource
|
|
49
|
+
from ._version import __version__
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class Cholaka:
|
|
53
|
+
"""Client for the Cholaka API.
|
|
54
|
+
|
|
55
|
+
:param api_key: An API token (``cho_...``) with the ``posts:read`` and/or
|
|
56
|
+
``posts:write`` scopes. Defaults to the ``CHOLAKA_API_KEY`` env var.
|
|
57
|
+
:param base_url: API root. Defaults to ``CHOLAKA_BASE_URL``, then
|
|
58
|
+
``https://api.cholaka.ai/api/v1``. ``https://host`` alone also works.
|
|
59
|
+
:param timeout: Seconds per HTTP request. Video uploads can be slow, so
|
|
60
|
+
the default is generous.
|
|
61
|
+
:param max_retries: How many times to retry rate-limited, unreachable or
|
|
62
|
+
temporarily unavailable requests.
|
|
63
|
+
:param http_client: Bring your own ``httpx.Client`` (proxies, custom TLS).
|
|
64
|
+
You remain responsible for closing it.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
def __init__(
|
|
68
|
+
self,
|
|
69
|
+
api_key: Optional[str] = None,
|
|
70
|
+
*,
|
|
71
|
+
base_url: Optional[str] = None,
|
|
72
|
+
timeout: float = DEFAULT_TIMEOUT,
|
|
73
|
+
max_retries: int = DEFAULT_MAX_RETRIES,
|
|
74
|
+
http_client: Optional[httpx.Client] = None,
|
|
75
|
+
) -> None:
|
|
76
|
+
self._client = SyncAPIClient(
|
|
77
|
+
api_key, base_url, timeout, max_retries, http_client
|
|
78
|
+
)
|
|
79
|
+
self.posts = PostsResource(self._client)
|
|
80
|
+
self.media = MediaResource(self._client)
|
|
81
|
+
self.accounts = AccountsResource(self._client)
|
|
82
|
+
|
|
83
|
+
@property
|
|
84
|
+
def base_url(self) -> str:
|
|
85
|
+
return self._client.base_url
|
|
86
|
+
|
|
87
|
+
def close(self) -> None:
|
|
88
|
+
"""Close the underlying HTTP connections."""
|
|
89
|
+
self._client.close()
|
|
90
|
+
|
|
91
|
+
def __enter__(self) -> "Cholaka":
|
|
92
|
+
return self
|
|
93
|
+
|
|
94
|
+
def __exit__(self, *exc: object) -> None:
|
|
95
|
+
self.close()
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
__all__ = [
|
|
99
|
+
"Cholaka",
|
|
100
|
+
"DEFAULT_BASE_URL",
|
|
101
|
+
"__version__",
|
|
102
|
+
# models
|
|
103
|
+
"Account",
|
|
104
|
+
"MediaAsset",
|
|
105
|
+
"Page",
|
|
106
|
+
"Post",
|
|
107
|
+
"PostStatus",
|
|
108
|
+
"PostTarget",
|
|
109
|
+
"PublishingLimit",
|
|
110
|
+
"FINAL_STATUSES",
|
|
111
|
+
# resources
|
|
112
|
+
"AccountsResource",
|
|
113
|
+
"MediaResource",
|
|
114
|
+
"PostsResource",
|
|
115
|
+
# errors
|
|
116
|
+
"CholakaError",
|
|
117
|
+
"APIConnectionError",
|
|
118
|
+
"APIError",
|
|
119
|
+
"BadRequestError",
|
|
120
|
+
"AuthenticationError",
|
|
121
|
+
"PermissionDeniedError",
|
|
122
|
+
"NotFoundError",
|
|
123
|
+
"ConflictError",
|
|
124
|
+
"UnprocessableEntityError",
|
|
125
|
+
"RateLimitError",
|
|
126
|
+
"InternalServerError",
|
|
127
|
+
"PublishTimeoutError",
|
|
128
|
+
]
|