From 65b0992db283857b9bb50fb58a6bfbb41ae46ab9 Mon Sep 17 00:00:00 2001
From: Miguel Grinberg <miguel.grinberg@gmail.com>
Date: Sat, 28 Oct 2023 20:08:49 +0100
Subject: [PATCH] Added readme files for all examples

---
 examples/aio-users/README.md         | 12 ++++++++++++
 examples/fastapi-multi-db/README.md  | 19 +++++++++++++++++++
 examples/fastapi-multi-db/app.py     |  5 +++--
 examples/fastapi-single-db/README.md | 19 +++++++++++++++++++
 examples/fastapi-single-db/app.py    |  3 ++-
 examples/flask-multi-db/README.md    | 21 +++++++++++++++++++++
 examples/flask-multi-db/app.py       |  5 +++--
 examples/flask-single-db/README.md   | 21 +++++++++++++++++++++
 examples/flask-single-db/app.py      |  5 +++--
 examples/flaskr/README.md            |  3 +--
 examples/multi-db/README.md          | 12 ++++++++++++
 examples/users/README.md             | 12 ++++++++++++
 12 files changed, 128 insertions(+), 9 deletions(-)
 create mode 100644 examples/aio-users/README.md
 create mode 100644 examples/fastapi-multi-db/README.md
 create mode 100644 examples/fastapi-single-db/README.md
 create mode 100644 examples/flask-multi-db/README.md
 create mode 100644 examples/flask-single-db/README.md
 create mode 100644 examples/multi-db/README.md
 create mode 100644 examples/users/README.md

diff --git a/examples/aio-users/README.md b/examples/aio-users/README.md
new file mode 100644
index 0000000..3785a71
--- /dev/null
+++ b/examples/aio-users/README.md
@@ -0,0 +1,12 @@
+# aio-users
+
+This example demonstrates how to create a simple database in a standalone
+Python script that is based on the `asyncio` module.
+
+## Usage
+
+To try this example, install `alchemical` and then run the code as follows:
+
+```bash
+$ python users.py
+```
diff --git a/examples/fastapi-multi-db/README.md b/examples/fastapi-multi-db/README.md
new file mode 100644
index 0000000..f2bf955
--- /dev/null
+++ b/examples/fastapi-multi-db/README.md
@@ -0,0 +1,19 @@
+# fastapi-multi-db
+
+This example demonstrates how to manage multiple databases in a FastAPI
+application using Alchemical.
+
+## Usage
+
+To try this example, install `alchemical` and `uvicorn`, and then run the
+following commands:
+
+```bash
+$ python app.py init                        # initialize the database
+$ python app.py add                         # add user and group to the db
+$ uvicorn --port 5000 app:app               # start the fastapi application
+```
+
+Once the FastAPI application is running, open `http://localhost:5000` in your
+web browser to see the contents of the database. You can invoke the `add`
+command additional times to insert more users and groups into the database.
diff --git a/examples/fastapi-multi-db/app.py b/examples/fastapi-multi-db/app.py
index 0304adf..35f773a 100644
--- a/examples/fastapi-multi-db/app.py
+++ b/examples/fastapi-multi-db/app.py
@@ -1,4 +1,5 @@
 import asyncio
+from random import randint
 import sys
 from fastapi import FastAPI
 from sqlalchemy import String
@@ -33,8 +34,8 @@ async def index():
 async def add():
     """Add test user and group."""
     async with db.begin() as session:
-        session.add(User(name='test'))
-        session.add(Group(name='group'))
+        session.add(User(name=f'user{randint(0, 9999)}'))
+        session.add(Group(name=f'group{randint(0, 9999)}'))
 
 
 arg = sys.argv[1] if len(sys.argv) > 1 else None
diff --git a/examples/fastapi-single-db/README.md b/examples/fastapi-single-db/README.md
new file mode 100644
index 0000000..f3e3fdd
--- /dev/null
+++ b/examples/fastapi-single-db/README.md
@@ -0,0 +1,19 @@
+# fastapi-single-db
+
+This example demonstrates how to manage a database in a FastAPI application
+using Alchemical.
+
+## Usage
+
+To try this example, install `alchemical` and `uvicorn`, and then run the
+following commands:
+
+```bash
+$ python app.py init                        # initialize the database
+$ python app.py add                         # add a user to the database
+$ uvicorn --port 5000 app:app               # start the fastapi application
+```
+
+Once the FastAPI application is running, open `http://localhost:5000` in your
+web browser to see the contents of the database. You can invoke the `add`
+command additional times to insert more users into the database.
diff --git a/examples/fastapi-single-db/app.py b/examples/fastapi-single-db/app.py
index a12165d..eff6eb5 100644
--- a/examples/fastapi-single-db/app.py
+++ b/examples/fastapi-single-db/app.py
@@ -1,4 +1,5 @@
 import asyncio
+from random import randint
 import sys
 from fastapi import FastAPI
 from sqlalchemy import String
@@ -25,7 +26,7 @@ async def index():
 async def add():
     """Add test user."""
     async with db.begin() as session:
-        session.add(User(name='test'))
+        session.add(User(name=f'user{randint(0, 9999)}'))
 
 
 arg = sys.argv[1] if len(sys.argv) > 1 else None
diff --git a/examples/flask-multi-db/README.md b/examples/flask-multi-db/README.md
new file mode 100644
index 0000000..b51f0af
--- /dev/null
+++ b/examples/flask-multi-db/README.md
@@ -0,0 +1,21 @@
+# flask-multi-db
+
+This example demonstrates how to manage multiple databases in a Flask
+application using Alchemical and Flask-Migrate.
+
+## Usage
+
+To try this example, install `alchemical`, `flask` and `flask-migrate`, and
+then run the following commands:
+
+```bash
+$ flask db init --multidb                   # initialize a migration repository
+$ flask db migrate -m "initial migration"   # create a database migration
+$ flask db upgrade                          # apply the migration changes
+$ flask add                                 # add user and group to the db
+$ flask run                                 # start the Flask application
+```
+
+Once the Flask application is running, open `http://localhost:5000` in your
+web browser to see the contents of the database. You can invoke the `flask add`
+command additional times to insert more users and groups into the database.
diff --git a/examples/flask-multi-db/app.py b/examples/flask-multi-db/app.py
index 9f1712b..eeb0c45 100644
--- a/examples/flask-multi-db/app.py
+++ b/examples/flask-multi-db/app.py
@@ -1,3 +1,4 @@
+from random import randint
 from flask import Flask
 from sqlalchemy import String
 from sqlalchemy.orm import Mapped, mapped_column
@@ -38,5 +39,5 @@ def index():
 def add():
     """Add test users."""
     with db.begin() as session:
-        session.add(User(name='test'))
-        session.add(Group(name='group'))
+        session.add(User(name=f'user{randint(0, 9999)}'))
+        session.add(Group(name=f'group{randint(0, 9999)}'))
diff --git a/examples/flask-single-db/README.md b/examples/flask-single-db/README.md
new file mode 100644
index 0000000..0590274
--- /dev/null
+++ b/examples/flask-single-db/README.md
@@ -0,0 +1,21 @@
+# flask-single-db
+
+This example demonstrates how to manage a database in a Flask application using
+Alchemical and Flask-Migrate.
+
+## Usage
+
+To try this example, install `alchemical`, `flask` and `flask-migrate`, and
+then run the following commands:
+
+```bash
+$ flask db init                             # initialize a migration repository
+$ flask db migrate -m "initial migration"   # create a database migration
+$ flask db upgrade                          # apply the migration changes
+$ flask add                                 # add a user to the database
+$ flask run                                 # start the Flask application
+```
+
+Once the Flask application is running, open `http://localhost:5000` in your
+web browser to see the contents of the database. You can invoke the `flask add`
+command additional times to insert more users into the database.
diff --git a/examples/flask-single-db/app.py b/examples/flask-single-db/app.py
index 8a786ca..8693535 100644
--- a/examples/flask-single-db/app.py
+++ b/examples/flask-single-db/app.py
@@ -1,3 +1,4 @@
+from random import randint
 from flask import Flask
 from sqlalchemy import String
 from sqlalchemy.orm import Mapped, mapped_column
@@ -25,6 +26,6 @@ def index():
 
 @app.cli.command()
 def add():
-    """Add test user."""
+    """Add a test user."""
     with db.begin() as session:
-        session.add(User(name='test'))
+        session.add(User(name=f'user{randint(0, 9999)}'))
diff --git a/examples/flaskr/README.md b/examples/flaskr/README.md
index baf78f5..66654b3 100644
--- a/examples/flaskr/README.md
+++ b/examples/flaskr/README.md
@@ -2,8 +2,7 @@ flaskr
 ======
 
 This is the "Flaskr" application from the tutorial section of the Flask
-documentation, adapted to work with Alchemical for its database. The
-Flask-Login extension is also used to maintain the logged in state of the user.
+documentation, adapted to work with Alchemical for its database.
 
 Install
 -------
diff --git a/examples/multi-db/README.md b/examples/multi-db/README.md
new file mode 100644
index 0000000..4b4d1f1
--- /dev/null
+++ b/examples/multi-db/README.md
@@ -0,0 +1,12 @@
+# multi-db
+
+This example demonstrates how to manage multiple databases from a standalone
+Python script.
+
+## Usage
+
+To try this example, install `alchemical` and then run the code as follows:
+
+```bash
+$ python users_and_groups.py
+```
diff --git a/examples/users/README.md b/examples/users/README.md
new file mode 100644
index 0000000..68c5def
--- /dev/null
+++ b/examples/users/README.md
@@ -0,0 +1,12 @@
+# users
+
+This example demonstrates how to create a simple database in a standalone
+Python script.
+
+## Usage
+
+To try this example, install `alchemical` and then run the code as follows:
+
+```bash
+$ python users.py
+```