Added readme files for all examples

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
+```

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.

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

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.

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

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.

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)}'))

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.

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)}'))

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
 -------

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
+```

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
+```