Skip to content

Commit ee7cef6

Browse files
francescobiancofrancescobianco
committed
docs(readme): split usage into two steps, add installation and testing sections
1 parent 3bca4e9 commit ee7cef6

File tree

2 files changed

+146
-29
lines changed

2 files changed

+146
-29
lines changed

‎README.md‎

Lines changed: 44 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@
66
<h1>Openapi® client for Python</h1>
77
<h4>The perfect starting point to integrate <a href="https://openapi.com/">Openapi®</a> within your Python project</h4>
88

9-
[![Build Status](https://github.com/openapi/openapi-python-sdk/actions/workflows/python.yml/badge.svg)](https://github.com/openapi/openapi-python-sdk/actions/workflows/python.yml)
10-
[![Packagist Version](https://img.shields.io/packagist/v/openapi/openapi-sdk)](https://packagist.org/packages/openapi/openapi-sdk)
11-
[![PyPI Version](https://img.shields.io/packagist/python-v/openapi/openapi-sdk)](https://packagist.org/packages/openapi/openapi-sdk)
12-
[![License](https://img.shields.io/github/license/openapi/openapi-python-sdk?v=2)](LICENSE)
13-
[![Downloads](https://img.shields.io/packagist/dt/openapi/openapi-sdk)](https://packagist.org/packages/openapi/openapi-sdk)
9+
[![Build](https://github.com/openapi/openapi-python-sdk/actions/workflows/python.yml/badge.svg)](https://github.com/openapi/openapi-python-sdk/actions/workflows/python.yml)
10+
[![PyPI Version](https://img.shields.io/pypi/v/openapi-python-sdk)](https://pypi.org/project/openapi-python-sdk/)
11+
[![Python Versions](https://img.shields.io/pypi/pyversions/openapi-python-sdk)](https://pypi.org/project/openapi-python-sdk/)
12+
[![License](https://img.shields.io/github/license/openapi/openapi-python-sdk)](LICENSE)
13+
[![Downloads](https://img.shields.io/pypi/dm/openapi-python-sdk)](https://pypi.org/project/openapi-python-sdk/)
1414
<br>
1515
[![Linux Foundation Member](https://img.shields.io/badge/Linux%20Foundation-Silver%20Member-003778?logo=linux-foundation&logoColor=white)](https://www.linuxfoundation.org/about/members)
1616
</div>
@@ -43,35 +43,27 @@ With the Openapi Python Client, you can easily interact with a variety of servic
4343

4444
For a complete list of all available services, check out the [Openapi Marketplace](https://console.openapi.com/) 🌐
4545

46-
# OpenApi IT Python Client
47-
48-
This client is used to interact with the API found at [openapi.it](https://openapi.it/)
49-
50-
## Pre-requisites
51-
52-
Before using the OpenApi IT Python Client, you will need an account at [openapi.it](https://openapi.it/) and an API key to the sandbox and/or production environment
5346

5447
## Installation
5548

56-
You can install the OpenApi IT Python Client with the following command using go get:
57-
5849
```bash
59-
pip install openapi-cli-python
50+
pip install openapi-python-sdk
6051
```
61-
52+
6253
## Usage
6354

55+
Interaction with the Openapi platform happens in two distinct steps.
56+
57+
### Step 1 — Generate a token
58+
59+
Authenticate with your credentials and obtain a short-lived bearer token scoped to the endpoints you need.
6460

6561
```python
66-
from openapi.client import Client, OauthClient
62+
from openapi_python_sdk.client import OauthClient
6763

68-
# Initialize the oauth client on the sandbox environment
69-
oauth_client = OauthClient(
70-
username="<your_username>", apikey="<your_apikey>", test=True
71-
)
64+
oauth = OauthClient(username="<your_username>", apikey="<your_apikey>", test=True)
7265

73-
# Create a token for a list of scopes
74-
resp = oauth_client.create_token(
66+
resp = oauth.create_token(
7567
scopes=[
7668
"GET:test.imprese.openapi.it/advance",
7769
"POST:test.postontarget.com/fields/country",
@@ -80,25 +72,48 @@ resp = oauth_client.create_token(
8072
)
8173
token = resp["token"]
8274

83-
# Initialize the client
75+
# Revoke the token when done
76+
oauth.delete_token(id=token)
77+
```
78+
79+
### Step 2 — Call an API endpoint
80+
81+
Use the token to make authenticated requests to any Openapi service.
82+
83+
```python
84+
from openapi_python_sdk.client import Client
85+
8486
client = Client(token=token)
8587

86-
# Make a request with params
88+
# GET with query params
8789
resp = client.request(
8890
method="GET",
8991
url="https://test.imprese.openapi.it/advance",
9092
params={"denominazione": "altravia", "provincia": "RM", "codice_ateco": "6201"},
9193
)
9294

93-
# Make a request with a payload
95+
# POST with a JSON payload
9496
resp = client.request(
9597
method="POST",
9698
url="https://test.postontarget.com/fields/country",
97-
payload={"limit": 0, "query": { "country_code": "IT"}}
99+
payload={"limit": 0, "query": {"country_code": "IT"}},
98100
)
101+
```
102+
103+
## Testing
104+
105+
Install dev dependencies and run the test suite:
99106

100-
# Delete the token
101-
resp = oauth_client.delete_token(id=token)
107+
```bash
108+
pip install pytest
109+
pytest
110+
```
111+
112+
Or with Poetry:
113+
114+
```bash
115+
poetry install
116+
poetry run pytest
102117
```
103118

104119

‎docs/readme-pypi.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# openapi-python-sdk
2+
3+
A minimal Python SDK for [Openapi®](https://openapi.it) — the largest certified API marketplace in Italy.
4+
Provides the core HTTP primitives to authenticate and interact with any Openapi service, without API-specific coupling.
5+
6+
## Requirements
7+
8+
- Python 3.10+
9+
- An account on [console.openapi.com](https://console.openapi.com/) with a valid API key
10+
11+
## Installation
12+
13+
```bash
14+
pip install openapi-python-sdk
15+
```
16+
17+
## Usage
18+
19+
Interaction with the Openapi platform happens in two distinct steps.
20+
21+
### Step 1 — Generate a token
22+
23+
```python
24+
from openapi_python_sdk.client import OauthClient
25+
26+
oauth = OauthClient(username="<your_username>", apikey="<your_apikey>", test=True)
27+
28+
resp = oauth.create_token(
29+
scopes=[
30+
"GET:test.imprese.openapi.it/advance",
31+
"POST:test.postontarget.com/fields/country",
32+
],
33+
ttl=3600,
34+
)
35+
token = resp["token"]
36+
37+
# Revoke the token when done
38+
oauth.delete_token(id=token)
39+
```
40+
41+
### Step 2 — Call an API endpoint
42+
43+
```python
44+
from openapi_python_sdk.client import Client
45+
46+
client = Client(token=token)
47+
48+
# GET with query params
49+
resp = client.request(
50+
method="GET",
51+
url="https://test.imprese.openapi.it/advance",
52+
params={"denominazione": "altravia", "provincia": "RM", "codice_ateco": "6201"},
53+
)
54+
55+
# POST with a JSON payload
56+
resp = client.request(
57+
method="POST",
58+
url="https://test.postontarget.com/fields/country",
59+
payload={"limit": 0, "query": {"country_code": "IT"}},
60+
)
61+
```
62+
63+
## Testing
64+
65+
```bash
66+
pip install pytest
67+
pytest
68+
```
69+
70+
## OauthClient API
71+
72+
| Method | Description |
73+
|---|---|
74+
| `OauthClient(username, apikey, test=False)` | Initialize the OAuth client. Set `test=True` for sandbox. |
75+
| `create_token(scopes, ttl)` | Create a bearer token for the given scopes and TTL (seconds). |
76+
| `get_token(scope)` | Retrieve an existing token by scope. |
77+
| `delete_token(id)` | Revoke a token by ID. |
78+
| `get_scopes(limit=False)` | List available scopes. |
79+
| `get_counters(period, date)` | Retrieve usage counters for a given period and date. |
80+
81+
## Client API
82+
83+
| Method | Description |
84+
|---|---|
85+
| `Client(token)` | Initialize the client with a bearer token. |
86+
| `request(method, url, payload, params)` | Execute an HTTP request against any Openapi endpoint. |
87+
88+
## Links
89+
90+
- Homepage: [openapi.it](https://openapi.it)
91+
- Console & API keys: [console.openapi.com](https://console.openapi.com/)
92+
- GitHub: [github.com/openapi/openapi-python-sdk](https://github.com/openapi/openapi-python-sdk)
93+
- Issue tracker: [github.com/openapi/openapi-python-sdk/issues](https://github.com/openapi/openapi-python-sdk/issues)
94+
95+
## License
96+
97+
MIT — see [LICENSE](https://github.com/openapi/openapi-python-sdk/blob/main/LICENSE) for details.
98+
99+
## Authors
100+
101+
- Michael Cuffaro ([@maiku1008](https://github.com/maiku1008))
102+
- Openapi Team ([@openapi-it](https://github.com/openapi-it))

0 commit comments

Comments
 (0)