docs: add code formatting

Author: Tom Nijboer

README.md

@@ -2,11 +2,11 @@
 
 clearskies is a very opinionated Python framework intended for developing microservices in the cloud via declarative programming principles.  It is mainly intended for backend services and so is designed for RESTful API endpoints, queue listeners, scheduled tasks, and the like.
 
-# Installation, Documentation, and Usage
+## Installation, Documentation, and Usage
 
 To install:
 
-```
+```bash
 pip3 install clear-skies
 ```
 

docs/models_and_columns.md

@@ -1,6 +1,6 @@
 Models are configured by attaching columns as properties:
 
-```
+```python
 import clearskies.
 def SomeModel:
     name = columns.String(required=True)

src/clearskies/authentication/secret_bearer.py

@@ -21,7 +21,7 @@ class SecretBearer(Authentication, clearskies.di.InjectableProperties):
     environment variable which is set in the code itself.  Normally you wouldn't set environment variables like this,
     but it's done here to create a self-contained example that is easy to run:
 
-    ```
+    ```python
     import os
     import clearskies
 
@@ -37,7 +37,7 @@ class SecretBearer(Authentication, clearskies.di.InjectableProperties):
     ```
     We can then call it with and without the authentication header:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080' -H 'Authorization: SUPERSECRET' | jq
     {
         "status": "success",
@@ -73,7 +73,7 @@ class SecretBearer(Authentication, clearskies.di.InjectableProperties):
     The secret bearer class can also be attached to an API Backend to provide authentication to remote APIs.  To
     demonstrate, here is an example server that expects a secret token in the authorization header:
 
-    ```
+    ```python
     import os
     import clearskies
     from clearskies import columns
@@ -111,7 +111,7 @@ class Widget(clearskies.Model):
     Then here is a client app (you can launch the above server and then run this in a new terminal) that
     similarly uses the secret bearer class to authenticate to the server:
 
-    ```
+    ```python
     import os
     import clearskies
     from clearskies import columns
@@ -160,7 +160,7 @@ def api_demo(widgets: Widget) -> Widget:
     writeable columns, the API would return an input error.  If you launch the above server/API and then run
     the given client script, you'll see output like this:
 
-    ```
+    ```json
     {
         "status": "success",
         "error": "",
@@ -200,7 +200,7 @@ def api_demo(widgets: Widget) -> Widget:
     Of course, to use `secret_key`, you must also provide a secret manager.  The below example uses the dependency
     injection system to create a faux secret manager to demonstrate how it works in general:
 
-    ```
+    ```python
     from types import SimpleNamespace
     import clearskies
 
@@ -225,7 +225,7 @@ def fetch_secret(path):
 
     And when invoked:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
     {
         "status": "success",
@@ -258,7 +258,7 @@ def fetch_secret(path):
     be accepted and you can migrate your applications to only send the new secret.  Once they are all updated,
     remove the alternate_secret_key:
 
-    ```
+    ```python
     from types import SimpleNamespace
     import clearskies
 
@@ -288,7 +288,7 @@ def fetch_secret(path):
 
     And when invoked:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
     {
         "status": "success",
@@ -337,7 +337,7 @@ def fetch_secret(path):
     to use the new key and, once they are all migrated, remove the old key from the application
     configuration.  Here's an example:
 
-    ```
+    ```python
     import os
     import clearskies
 
@@ -358,7 +358,7 @@ def fetch_secret(path):
 
     And when invoked:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080/' -H "Authorization: SUPERSECRET" | jq
     {
         "status": "success",
@@ -403,7 +403,7 @@ def fetch_secret(path):
     to provide such a prefix.  Note that the prefix is case-insensitive and it does not assume a space between the
     prefix and the token (so, if you want a space, you must explicitly put it in the prefix).  Here's an example:
 
-    ```
+    ```python
     import os
     import clearskies
 
@@ -423,7 +423,7 @@ def fetch_secret(path):
 
     And then usage:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080/' -H "Authorization: SECRET-TOKEN SUPERSECRET" | jq
     {
         "status": "success",

src/clearskies/backends/__init__.py

@@ -33,7 +33,7 @@
 See the documentation for each backend to understand how to configure and use it.  In all cases though, you specify
 the backend by instantiating the backend and attaching it to the model class via the `backend` attribute:
 
-```
+```python
 import clearskies
 
 

src/clearskies/backends/api_backend.py

@@ -73,7 +73,7 @@ class ApiBackend(clearskies.configurable.Configurable, Backend, InjectableProper
 
     Here's an example of how to use the API Backend to integrate with the Github API:
 
-    ```
+    ```python
     import clearskies
 
 
@@ -191,7 +191,7 @@ def fetch_user(users: User, user_repos: UserRepo):
     other model.  Note that the following example is re-using the above models and backend, I have just omitted them for the sake
     of brevity:
 
-    ```
+    ```python
     wsgi = clearskies.contexts.WsgiRef(
         clearskies.endpoints.List(
             model_class=User,
@@ -209,7 +209,7 @@ def fetch_user(users: User, user_repos: UserRepo):
 
     And if you invoke it:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080' | jq
     {
         "status": "success",
@@ -281,8 +281,8 @@ def fetch_user(users: User, user_repos: UserRepo):
     makes API calls.  It also tracks pagination as expected, so you can use the data in `pagination.next_page` to
     fetch the next set of results, just as you would if this were backed by a database, e.g.:
 
-    ```
-    curl http://localhost:8080?since=19
+    ```bash
+    $ curl http://localhost:8080?since=19
     ```
 
     ## Mapping from Queries to API calls
@@ -343,7 +343,7 @@ def fetch_user(users: User, user_repos: UserRepo):
     request will succeed and the service will continue to operate successfully with only a slight delay in response time
     caused by refreshing the cache.
 
-    ```
+    ```python
     import clearskies
 
     class GithubBackend(clearskies.backends.ApiBackend):
@@ -409,7 +409,7 @@ def destination_name(cls):
     example, these parameters are used to convert from the snake_casing native to the Github API into the
     TitleCasing used in the model class:
 
-    ```
+    ```python
     import clearskies
 
     class User(clearskies.Model):
@@ -448,8 +448,8 @@ class User(clearskies.Model):
 
     and when executed:
 
-    ```
-$ curl http://localhost:8080 | jq
+    ```bash
+    $ curl http://localhost:8080 | jq
     {
         "Status": "Success",
         "Error": "",
@@ -495,7 +495,7 @@ class User(clearskies.Model):
     is the name of the column in the model.  The API Backend will use this to match the API data to your model.
     In the example below, `html_url` from the API has been mapped to `profile_url` in the model:
 
-    ```
+    ```python
     import clearskies
 
     class User(clearskies.Model):
@@ -528,8 +528,8 @@ class User(clearskies.Model):
 
     And if you invoke it:
 
-    ```
-$ curl http://localhost:8080 | jq
+    ```bash
+    $ curl http://localhost:8080 | jq
     {
         "status": "success",
         "error": "",
@@ -606,7 +606,7 @@ def finalize_url(self, url: str, available_routing_data: dict[str, str], operati
 
         For example, consider a base URL of `/my/api/{record_id}/:other_id` and then this is called as so:
 
-        ```
+        ```python
         (url, used_routing_parameters) = api_backend.finalize_url(
             "entries",
             {
@@ -1001,8 +1001,11 @@ def build_response_to_model_map(self, columns: dict[str, clearskies.column.Colum
         return self._response_to_model_map
 
     def set_next_page_data_from_response(
-        self, next_page_data: dict[str, Any], query: clearskies.query.Query, response: requests.models.Response
-    ) -> None:  # type: ignore
+        self,
+        next_page_data: dict[str, Any],
+        query: clearskies.query.Query,
+        response: requests.Response,  # type: ignore
+    ) -> None:
         """
         Update the next_page_data dictionary with the appropriate data needed to fetch the next page of records.
 
@@ -1011,13 +1014,13 @@ def set_next_page_data_from_response(
         information is necessary.  Note that this relies on next_page_data being passed by reference, hence the need to update
         it in place.  That means that you can do this:
 
-        ```
+        ```python
         next_page_data["some_key"] = "some_value"
         ```
 
         but if you do this:
 
-        ```
+        ```python
         next_page_data = {"some_key": "some_value"}
         ```
 

src/clearskies/backends/cursor_backend.py

@@ -17,7 +17,7 @@ class CursorBackend(Backend, InjectableProperties):
     clearskies uses PyMySQL to manage the database connection and make queries.  This is not installed by default,
     but is a named extra that you can install when needed via:
 
-    ```
+    ```bash
     pip install clear-skies[mysql]
     ```
 
@@ -37,7 +37,7 @@ class CursorBackend(Backend, InjectableProperties):
     However, you can fully control the credential provisioning process by declaring a dependency named `connection_details` and
     setting it to a dictionary with the above keys, minus the `db_` prefix:
 
-    ```
+    ```python
     class ConnectionDetails(clearskies.di.AdditionalConfig):
         provide_connection_details(self, secrets):
             return {
@@ -68,7 +68,7 @@ class ConnectionDetails(clearskies.di.AdditionalConfig):
     class named `UserPreference` then the cursor backend will look for a table called `user_preferences`.  If this
     isn't what you want, then you can simply override `destination_name` to return whatever table you want:
 
-    ```
+    ```python
     class UserPreference(clearskies.Model):
         @classmethod
         def destination_name(cls):
@@ -84,7 +84,7 @@ def destination_name(cls):
      2. The `table_prefix` argument to the CursorBackend constructor adds a prefix of `configuration_`
      3. The `global_table_prefix` binding sets a prefix of `user_`, wihch goes before everything else.
 
-    ```
+    ```python
     import clearskies
 
 

src/clearskies/backends/memory_backend.py

@@ -260,7 +260,7 @@ class MemoryBackend(Backend, InjectableProperties):
     but when you run this code it will actually end up with the memory backend, so the code will run even without
     attempting to connect to a database.
 
-    ```
+    ```python
     import clearskies
 
 
@@ -314,7 +314,7 @@ class UserPreference(clearskies.Model):
     can be helpful in testing to setup your tests, and is occassionally helpful for keeping track of data in
     fixed, read-only tables.  Here's an example:
 
-    ```
+    ```python
     import clearskies
 
 
@@ -378,7 +378,7 @@ class Pet(clearskies.Model):
 
     And if you invoke it:
 
-    ```
+    ```bash
     $ curl 'http://localhost:8080' | jq
     {
         "status": "success",
@@ -420,7 +420,6 @@ class Pet(clearskies.Model):
         "input_errors": {}
     }
     ```
-
     """
 
     default_data = inject.ByName("memory_backend_default_data")
@@ -672,7 +671,7 @@ def join_rows(
 
         `rows` should be something like:
 
-        ```
+        ```python
         [
             {
                 "table_1": {"table_1_row_1"},