Improved code snippets for debugging

[mlucas-NU]

🚀 Feature

Help users debug python SDK calls by making errors easier to find when the user is using Appwrite's example code.

Have you spent some time to check if this issue has been raised before?

Yes.

Have you read the Code of Conduct?

Yes.

Pitch

The python code examples provided in Appwrite documentation are great if everything is setup correctly and the request body is well-formatted. However, exceptions encountered with these examples do not display the Response body, which is useful for debugging errors.

Current State

Let's say I have a collection with two rules "testField" and "testIndex" (both required). These are the last two suggested lines from the Database - Create Document] snippet, but note that the document body leaves out a required field ("testIndex"):

...
database = Database(client)

result = database.create_document('[COLLECTION_ID]', {"testField": "asdf"}, [], [])

The output only tells us the HTTP response code, but not the reason for the error:

Traceback (most recent call last):
  File "/masked_dir/populate_appwrite.py", line 94, in <module>
    result = database.create_document(
  File "/pip_dir/lib/python3.9/site-packages/appwrite/services/database.py", line 105, in create_document
    return self.client.call('post', path, {
  File "/pip_dir/lib/python3.9/site-packages/appwrite/client.py", line 81, in call
    response.raise_for_status()
  File "/pip_dir/lib/python3.9/site-packages/requests/models.py", line 943, in raise_for_status
    raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 400 Client Error: Bad Request for url: https://{server_url}/v1/database/collections/{collection_id}/documents

Proposal

The response body is available when we catch the exception, so one idea would be to add try/excepts to all example snippets:

import requests
...
database = Database(client)

try:
  result = database.create_document('[COLLECTION_ID]', {"testField": "asdf"}, [], [])
except requests.exceptions.HTTPError as e:
  print(e)
  print(e.response.content)  # Provides great debug info, but not an obvious idea to new python developers
  print(e.response.json())  # If the response body is JSON, it can be easily parsed into python dicts/lists

This time, we get the

400 Client Error: Bad Request for url: https://appwrite.schnoodle.house/v1/database/collections/601904087f110/documents
b'{"message":"Bad structure. Invalid document structure: Missing required key \\"testIndex\\"","code":400,"version":"dev"}'
{'message': 'Bad structure. Invalid document structure: Missing required key "testIndex"', 'code': 400, 'version': 'dev'}

If this makes the snippets too ugly, a higher-effort solution would be to catch errors within the Appwrite SDK and raise a custom Appwrite exception that contains important response details including the body.

[eldadfux]

Hey @mlucas-NU, we're just about to start working on this RFC this week: https://github.com/appwrite/rfc/blob/main/013-custom-exception-on-all-sdks.md

Please let me know if it sounds like a solution to the issues you're raising and feel free to submit any comments you might have. This RFC will also be followed by a planned RFC for structured response interfaces based on our REST API result objects.

[mlucas-NU]

Yeah, that's a fantastic RFC! It covers everything requested here and quite a bit more.