Skip to content

Commit 13d8b37

Browse files
mekilismekilis
committed
docs: rewrite readme for 1.0 generated client
also harden the pypi publish workflow (sha-pinned actions, release tag checkout, pinned build).
1 parent 51b71e5 commit 13d8b37

2 files changed

Lines changed: 75 additions & 88 deletions

File tree

‎.github/workflows/python-publish.yml‎

Lines changed: 21 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
1-
# This workflow will upload a Python Package using Twine when a release is created
2-
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
3-
4-
# This workflow uses actions that are not certified by GitHub.
5-
# They are provided by a third-party and are governed by
6-
# separate terms of service, privacy policy, and support
7-
# documentation.
1+
# Upload to PyPI when a GitHub release is published.
2+
# https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
83

94
name: Upload Python Package
105

@@ -17,23 +12,25 @@ permissions:
1712

1813
jobs:
1914
deploy:
20-
2115
runs-on: ubuntu-latest
2216

2317
steps:
24-
- uses: actions/checkout@v3
25-
- name: Set up Python
26-
uses: actions/setup-python@v3
27-
with:
28-
python-version: '3.x'
29-
- name: Install dependencies
30-
run: |
31-
python -m pip install --upgrade pip
32-
pip install build
33-
- name: Build package
34-
run: python -m build
35-
- name: Publish package
36-
uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
37-
with:
38-
user: __token__
39-
password: ${{ secrets.PYPI_API_TOKEN }}
18+
- uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
19+
with:
20+
ref: ${{ github.event.release.tag_name }}
21+
- name: Set up Python
22+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
23+
with:
24+
python-version: "3.12"
25+
- name: Install dependencies
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install build==1.5.0
29+
- name: Build package
30+
run: python -m build
31+
- name: Publish package
32+
# pypa/gh-action-pypi-publish@v1.12.4
33+
uses: pypa/gh-action-pypi-publish@7f25271a4aa483500f742f9492b2ab5648d61011
34+
with:
35+
user: __token__
36+
password: ${{ secrets.PYPI_API_TOKEN }}

‎README.md‎

Lines changed: 54 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,83 @@
11
# convoy-python
22

3-
This is the official Convoy Python SDK. It contains methods for easily interacting with Convoy's API. Below are examples to get you started. See our [API Reference](https://getconvoy.io/docs/api-reference/welcome) for more.
3+
Official Convoy Python SDK: an OpenAPI-generated API client plus hand-written webhook signature verification. See the [API Reference](https://getconvoy.io/docs/api-reference/welcome) for endpoint details.
4+
5+
Requires **Python 3.11+**.
46

57
## Installation
68

7-
Install convoy-python with
9+
`1.0.0a1` is a pre-release. Plain `pip install convoy-python` still resolves to `0.2.0` until a final `1.0.0` is published.
810

911
```bash
10-
pip install convoy-python
12+
pip install --pre convoy-python
13+
# or pin explicitly:
14+
pip install convoy-python==1.0.0a1
1115
```
1216

17+
If you are upgrading from `0.2.0`, see [MIGRATION.md](./MIGRATION.md) and the release notes for the breaking changes.
18+
1319
## Setup Client
1420

15-
Import the `convoy` module and set it up with your instance URL, API key, and project ID. Both the API key and project ID are available from your **Project Settings** page.
21+
Construct an `AuthenticatedClient` with your instance API root and API key. The project ID is passed per call (it is not embedded in the client).
1622

1723
```python
18-
from convoy import Convoy
24+
from convoy import AuthenticatedClient
1925

20-
convoy = Convoy({
21-
"api_key": "your_api_key",
22-
"uri": "https://us.getconvoy.cloud/api/v1",
23-
"project_id": "your_project_id",
24-
})
26+
client = AuthenticatedClient(
27+
base_url="https://us.getconvoy.cloud/api", # no /v1, no project id
28+
token="your_api_key",
29+
)
30+
project_id = "your_project_id"
2531
```
2632

27-
Your instance URL depends on where your project lives:
33+
Your base URL depends on where your project lives:
2834

29-
- Convoy Cloud (US): `https://us.getconvoy.cloud/api/v1`
30-
- Convoy Cloud (EU): `https://eu.getconvoy.cloud/api/v1`
31-
- Self-hosted: `https://your-instance/api/v1`
35+
- Convoy Cloud (US): `https://us.getconvoy.cloud/api`
36+
- Convoy Cloud (EU): `https://eu.getconvoy.cloud/api`
37+
- Self-hosted: `https://your-instance/api`
3238

3339
## Usage
3440

35-
Each method takes a query dict and returns a `(response, status)` tuple.
41+
Each operation lives under `convoy.api.*` and exposes `sync`, `sync_detailed`, `asyncio`, and `asyncio_detailed`. Request bodies use typed models from `convoy.models`.
3642

3743
### Create an Endpoint
3844

39-
An endpoint represents a target URL to receive events.
40-
4145
```python
42-
endpoint_data = {
43-
"name": "default-endpoint",
44-
"url": "https://example.com/webhooks/convoy",
45-
"description": "Default Endpoint",
46-
"secret": "endpoint-secret",
47-
}
48-
49-
(response, status) = convoy.endpoint.create({}, endpoint_data)
50-
endpoint_id = response["data"]["uid"]
51-
```
52-
53-
### Create a Subscription
54-
55-
Subscriptions route events from a source to an endpoint.
56-
57-
```python
58-
subscription_data = {
59-
"name": "event-sub",
60-
"endpoint_id": endpoint_id,
61-
}
62-
63-
(response, status) = convoy.subscription.create({}, subscription_data)
46+
from convoy.api.endpoints import create_endpoint
47+
from convoy.models import ModelsCreateEndpoint
48+
49+
result = create_endpoint.sync(
50+
project_id,
51+
client=client,
52+
body=ModelsCreateEndpoint(
53+
name="default-endpoint",
54+
url="https://example.com/webhooks/convoy",
55+
secret="endpoint-secret",
56+
),
57+
)
58+
endpoint_id = result.data.uid
6459
```
6560

6661
### Send an Event
6762

68-
To send an event, you'll need the `uid` of the endpoint we created earlier.
69-
7063
```python
71-
event_data = {
72-
"endpoint_id": endpoint_id,
73-
"event_type": "payment.success",
74-
"data": {
75-
"status": "Completed",
76-
"description": "Transaction Successful",
77-
},
78-
}
79-
80-
(response, status) = convoy.event.create({}, event_data)
81-
```
82-
83-
To fan an event out to all endpoints with the same `owner_id`, or broadcast to every endpoint in the project:
84-
85-
```python
86-
(response, status) = convoy.event.fanout({}, {"owner_id": "owner-1", "event_type": "payment.success", "data": {}})
87-
(response, status) = convoy.event.broadcast({}, {"event_type": "payment.success", "data": {}})
64+
from convoy.api.events import create_endpoint_event
65+
from convoy.models import ModelsCreateEvent, ModelsCreateEventDataType0
66+
67+
body = ModelsCreateEvent(
68+
endpoint_id=endpoint_id,
69+
event_type="payment.success",
70+
data=ModelsCreateEventDataType0.from_dict({"status": "Completed"}),
71+
)
72+
73+
result = create_endpoint_event.sync(project_id, client=client, body=body)
74+
# async:
75+
# result = await create_endpoint_event.asyncio(project_id, client=client, body=body)
8876
```
8977

9078
### Verify Webhook Signatures
9179

92-
Verify with the raw request body, before parsing it. `verify_signature` returns `True` for a valid signature and `False` otherwise (it fails closed), so a plain boolean check is safe.
80+
Verify with the raw request body, before parsing it. `verify_signature` returns a strict `True` / `False` (never a truthy error string).
9381

9482
```python
9583
from convoy.utils.webhook import Webhook
@@ -107,9 +95,15 @@ if not webhook.verify_signature(payload, signature):
10795
## Testing
10896

10997
```bash
110-
pytest test/test.py
98+
pytest test/
11199
```
112100

101+
## Generated API client
102+
103+
The HTTP API client under `src/convoy/api/` and `src/convoy/models/` is generated from Convoy's OpenAPI spec via [openapi-python-client](https://github.com/openapi-generators/openapi-python-client). **Do not edit generated files by hand**; regenerate with `./scripts/generate.sh` (CI on `frain-dev/convoy` dispatches this when the spec changes).
104+
105+
Webhook signature verification remains hand-written (`src/convoy/utils/webhook.py`) and is covered by shared `test/signature-vectors.json`.
106+
113107
## Contributing
114108

115109
Please see [CONTRIBUTING](CONTRIBUTING.MD) for details.
@@ -121,7 +115,3 @@ Please see [CONTRIBUTING](CONTRIBUTING.MD) for details.
121115
## License
122116

123117
The MIT License (MIT). Please see [License File](LICENSE) for more information.
124-
125-
## Generated API client
126-
127-
The HTTP API client is generated from Convoy's OpenAPI spec via [openapi-python-client](https://github.com/openapi-generators/openapi-python-client). **Webhook signature verification remains hand-written** (`convoy/utils/webhook.py`) and is covered by shared `test/signature-vectors.json`. See [MIGRATION.md](./MIGRATION.md).

0 commit comments

Comments
 (0)