diff --git a/README.rst b/README.rst index 9746e88..dd65374 100644 --- a/README.rst +++ b/README.rst @@ -16,8 +16,6 @@ Installation - This library is compatible with Python >= 3.9. -- Python 2.7 is no longer supported since version 1.1.0. -- Python 3.7 and 3.8 are no longer supported since version 1.1.7. On Fedora (36 and later), you can install the package using DNF: @@ -43,8 +41,8 @@ Creating a new team project import kanboard - kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") - project_id = kb.create_project(name="My project") + with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb: + project_id = kb.create_project(name="My project") Authenticate as user @@ -54,24 +52,25 @@ Authenticate as user import kanboard - kb = kanboard.Client("http://localhost/jsonrpc.php", "admin", "secret") - kb.get_my_projects() + with kanboard.Client("http://localhost/jsonrpc.php", "admin", "secret") as kb: + kb.get_my_projects() Use a custom authentication header ----------------------------------- +----------------------------------- -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: +If your Kanboard instance uses a custom authentication header +(for example, ``define('API_AUTHENTICATION_HEADER', 'X-My-Custom-Auth-Header');`` +in your Kanboard configuration): .. code-block:: python import kanboard - kb = kanboard.Client(url="http://localhost/jsonrpc.php", + with kanboard.Client(url="http://localhost/jsonrpc.php", username="demo", password="secret", - auth_header="X-My-Custom-Auth-Header") - - kb.get_me() + auth_header="X-My-Custom-Auth-Header") as kb: + kb.get_me() Create a new task ----------------- @@ -80,9 +79,9 @@ Create a new task import kanboard - kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") - project_id = kb.create_project(name="My project") - task_id = kb.create_task(project_id=project_id, title="My task title") + with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb: + project_id = kb.create_project(name="My project") + task_id = kb.create_task(project_id=project_id, title="My task title") Use a personalized user agent ----------------------------- @@ -91,10 +90,44 @@ Use a personalized user agent import kanboard - kb = kanboard.Client(url="http://localhost/jsonrpc.php", + with kanboard.Client(url="http://localhost/jsonrpc.php", username="admin", password="secret", - user_agent="My Kanboard client") + user_agent="My Kanboard client") as kb: + kb.get_my_projects() + +Request timeout +--------------- + +By default, requests time out after 30 seconds. You can change this with the +``timeout`` parameter (in seconds), or set it to ``None`` to disable the timeout: + +.. code-block:: python + + import kanboard + + # Custom 60-second timeout + with kanboard.Client(url="http://localhost/jsonrpc.php", + username="admin", + password="secret", + timeout=60) as kb: + kb.get_my_projects() + +Error handling +-------------- + +The client raises ``kanboard.ClientError`` for API errors, network failures, +and malformed responses: + +.. code-block:: python + + import kanboard + + with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb: + try: + kb.create_project(name="My project") + except kanboard.ClientError as e: + print(e) SSL connection and self-signed certificates =========================================== @@ -105,8 +138,8 @@ Example with a valid certificate: import kanboard - kb = kanboard.Client("https://example.org/jsonrpc.php", "admin", "secret") - kb.get_my_projects() + with kanboard.Client("https://example.org/jsonrpc.php", "admin", "secret") as kb: + kb.get_my_projects() Example with a custom certificate: @@ -114,11 +147,11 @@ Example with a custom certificate: import kanboard - kb = kanboard.Client(url="https://example.org/jsonrpc.php", + with kanboard.Client(url="https://example.org/jsonrpc.php", username="admin", password="secret", - cafile="/path/to/my/cert.pem") - kb.get_my_projects() + cafile="/path/to/my/cert.pem") as kb: + kb.get_my_projects() Example with a custom certificate and hostname mismatch: @@ -126,24 +159,27 @@ Example with a custom certificate and hostname mismatch: import kanboard - kb = kanboard.Client(url="https://example.org/jsonrpc.php", + with kanboard.Client(url="https://example.org/jsonrpc.php", username="admin", password="secret", cafile="/path/to/my/cert.pem", - ignore_hostname_verification=True) - kb.get_my_projects() + ignore_hostname_verification=True) as kb: + kb.get_my_projects() -Ignore invalid/expired certificates and hostname mismatches, which will make your application vulnerable to man-in-the-middle (MitM) attacks: +.. warning:: + + Setting ``insecure=True`` disables all certificate validation and hostname + checks, making your application vulnerable to man-in-the-middle (MitM) attacks: .. code-block:: python import kanboard - kb = kanboard.Client(url="https://example.org/jsonrpc.php", + with kanboard.Client(url="https://example.org/jsonrpc.php", username="admin", password="secret", - insecure=True) - kb.get_my_projects() + insecure=True) as kb: + kb.get_my_projects() Asynchronous I/O ================ @@ -159,23 +195,12 @@ to ``create_project`` can be made asynchronous by calling ``create_project_async import asyncio import kanboard - kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") - - loop = asyncio.get_event_loop() - project_id = loop.run_until_complete(kb.create_project_async(name="My project")) - - -.. code-block:: python - - import asyncio - import kanboard - - async def call_within_function(): - kb = kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") - return await kb.create_project_async(name="My project") + async def main(): + with kanboard.Client("http://localhost/jsonrpc.php", "jsonrpc", "your_api_token") as kb: + project_id = await kb.create_project_async(name="My project") + print(project_id) - loop = asyncio.get_event_loop() - project_id = loop.run_until_complete(call_within_function()) + asyncio.run(main()) See the `official API documentation `_ for the complete list of