Skip to content

Commit 0ff68dc

Browse files
fguillotfguillot
committed
docs: update README with context manager, timeout, and error handling
- Use context manager in all examples to prevent resource leaks - Replace deprecated asyncio.get_event_loop() with asyncio.run() - Add timeout configuration section - Add error handling section showing ClientError usage - Use RST warning directive for insecure SSL option - Remove stale Python 2.7/3.7/3.8 deprecation notes
1 parent 2df90cc commit 0ff68dc

File tree

1 file changed

+70
-45
lines changed

1 file changed

+70
-45
lines changed

‎README.rst‎

Lines changed: 70 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@ Installation
1616
1717
1818
- This library is compatible with Python >= 3.9.
19-
- Python 2.7 is no longer supported since version 1.1.0.
20-
- Python 3.7 and 3.8 are no longer supported since version 1.1.7.
2119

2220
On Fedora (36 and later), you can install the package using DNF:
2321

@@ -43,8 +41,8 @@ Creating a new team project
4341
4442
import kanboard
4543
46-
kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token")
47-
project_id = kb.create_project(name="My project")
44+
with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb:
45+
project_id = kb.create_project(name="My project")
4846
4947
5048
Authenticate as user
@@ -54,24 +52,25 @@ Authenticate as user
5452
5553
import kanboard
5654
57-
kb = kanboard.Client("http://localhost/jsonrpc.php", "admin", "secret")
58-
kb.get_my_projects()
55+
with kanboard.Client("http://localhost/jsonrpc.php", "admin", "secret") as kb:
56+
kb.get_my_projects()
5957
6058
Use a custom authentication header
61-
----------------------------------
59+
-----------------------------------
6260

63-
If your Kanboard instance is configured to use a custom authentication header (for example, by setting ``define('API_AUTHENTICATION_HEADER', 'X-My-Custom-Auth-Header');`` in your Kanboard configuration), you can authenticate using the following code:
61+
If your Kanboard instance uses a custom authentication header
62+
(for example, ``define('API_AUTHENTICATION_HEADER', 'X-My-Custom-Auth-Header');``
63+
in your Kanboard configuration):
6464

6565
.. code-block:: python
6666
6767
import kanboard
6868
69-
kb = kanboard.Client(url="http://localhost/jsonrpc.php",
69+
with kanboard.Client(url="http://localhost/jsonrpc.php",
7070
username="demo",
7171
password="secret",
72-
auth_header="X-My-Custom-Auth-Header")
73-
74-
kb.get_me()
72+
auth_header="X-My-Custom-Auth-Header") as kb:
73+
kb.get_me()
7574
7675
Create a new task
7776
-----------------
@@ -80,9 +79,9 @@ Create a new task
8079
8180
import kanboard
8281
83-
kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token")
84-
project_id = kb.create_project(name="My project")
85-
task_id = kb.create_task(project_id=project_id, title="My task title")
82+
with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb:
83+
project_id = kb.create_project(name="My project")
84+
task_id = kb.create_task(project_id=project_id, title="My task title")
8685
8786
Use a personalized user agent
8887
-----------------------------
@@ -91,10 +90,44 @@ Use a personalized user agent
9190
9291
import kanboard
9392
94-
kb = kanboard.Client(url="http://localhost/jsonrpc.php",
93+
with kanboard.Client(url="http://localhost/jsonrpc.php",
9594
username="admin",
9695
password="secret",
97-
user_agent="My Kanboard client")
96+
user_agent="My Kanboard client") as kb:
97+
kb.get_my_projects()
98+
99+
Request timeout
100+
---------------
101+
102+
By default, requests time out after 30 seconds. You can change this with the
103+
``timeout`` parameter (in seconds), or set it to ``None`` to disable the timeout:
104+
105+
.. code-block:: python
106+
107+
import kanboard
108+
109+
# Custom 60-second timeout
110+
with kanboard.Client(url="http://localhost/jsonrpc.php",
111+
username="admin",
112+
password="secret",
113+
timeout=60) as kb:
114+
kb.get_my_projects()
115+
116+
Error handling
117+
--------------
118+
119+
The client raises ``kanboard.ClientError`` for API errors, network failures,
120+
and malformed responses:
121+
122+
.. code-block:: python
123+
124+
import kanboard
125+
126+
with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb:
127+
try:
128+
kb.create_project(name="My project")
129+
except kanboard.ClientError as e:
130+
print(e)
98131
99132
SSL connection and self-signed certificates
100133
===========================================
@@ -105,45 +138,48 @@ Example with a valid certificate:
105138
106139
import kanboard
107140
108-
kb = kanboard.Client("https://example.org/jsonrpc.php", "admin", "secret")
109-
kb.get_my_projects()
141+
with kanboard.Client("https://example.org/jsonrpc.php", "admin", "secret") as kb:
142+
kb.get_my_projects()
110143
111144
Example with a custom certificate:
112145

113146
.. code-block:: python
114147
115148
import kanboard
116149
117-
kb = kanboard.Client(url="https://example.org/jsonrpc.php",
150+
with kanboard.Client(url="https://example.org/jsonrpc.php",
118151
username="admin",
119152
password="secret",
120-
cafile="/path/to/my/cert.pem")
121-
kb.get_my_projects()
153+
cafile="/path/to/my/cert.pem") as kb:
154+
kb.get_my_projects()
122155
123156
Example with a custom certificate and hostname mismatch:
124157

125158
.. code-block:: python
126159
127160
import kanboard
128161
129-
kb = kanboard.Client(url="https://example.org/jsonrpc.php",
162+
with kanboard.Client(url="https://example.org/jsonrpc.php",
130163
username="admin",
131164
password="secret",
132165
cafile="/path/to/my/cert.pem",
133-
ignore_hostname_verification=True)
134-
kb.get_my_projects()
166+
ignore_hostname_verification=True) as kb:
167+
kb.get_my_projects()
135168
136-
Ignore invalid/expired certificates and hostname mismatches, which will make your application vulnerable to man-in-the-middle (MitM) attacks:
169+
.. warning::
170+
171+
Setting ``insecure=True`` disables all certificate validation and hostname
172+
checks, making your application vulnerable to man-in-the-middle (MitM) attacks:
137173

138174
.. code-block:: python
139175
140176
import kanboard
141177
142-
kb = kanboard.Client(url="https://example.org/jsonrpc.php",
178+
with kanboard.Client(url="https://example.org/jsonrpc.php",
143179
username="admin",
144180
password="secret",
145-
insecure=True)
146-
kb.get_my_projects()
181+
insecure=True) as kb:
182+
kb.get_my_projects()
147183
148184
Asynchronous I/O
149185
================
@@ -159,23 +195,12 @@ to ``create_project`` can be made asynchronous by calling ``create_project_async
159195
import asyncio
160196
import kanboard
161197
162-
kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token")
163-
164-
loop = asyncio.get_event_loop()
165-
project_id = loop.run_until_complete(kb.create_project_async(name="My project"))
166-
167-
168-
.. code-block:: python
169-
170-
import asyncio
171-
import kanboard
172-
173-
async def call_within_function():
174-
kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token")
175-
return await kb.create_project_async(name="My project")
198+
async def main():
199+
with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb:
200+
project_id = await kb.create_project_async(name="My project")
201+
print(project_id)
176202
177-
loop = asyncio.get_event_loop()
178-
project_id = loop.run_until_complete(call_within_function())
203+
asyncio.run(main())
179204
180205
181206
See the `official API documentation <https://docs.kanboard.org/v1/api/>`_ for the complete list of

0 commit comments

Comments
 (0)