Flags, auth, db readmes

bolt-auth/README.md

@@ -2,33 +2,124 @@
 
 # bolt-auth
 
-Create users and authenticate them.
+Add users to your app and define which views they can access.
 
-[link](https://boltframework.dev/docs/bolt-auth/bolt/auth/config.py)
+To log a user in, you'll want to pair this package with:
 
-## Installation
+- `bolt-passwords`
+- `bolt-oauth`
+- `bolt-passkeys` (TBD)
+- `bolt-passlinks` (TBD)
 
-- install bolt-auth
-- install bolt-sessions
-- optionally bolt-passwords, etc.
-- add bolt.auth to installed packages
+## Installation
 
 ```python
+# app/settings.py
 INSTALLED_PACKAGES = [
     # ...
     "bolt.auth",
+    "bolt.sessions",
+    "bolt.passwords",
 ]
-```
 
-```
-# settings.py
 MIDDLEWARE = [
     "bolt.middleware.security.SecurityMiddleware",
     "bolt.assets.whitenoise.middleware.WhiteNoiseMiddleware",
-    "bolt.sessions.middleware.SessionMiddleware",  # <-- Add SessionMiddleware
+    "bolt.sessions.middleware.SessionMiddleware",  # <--
     "bolt.middleware.common.CommonMiddleware",
     "bolt.csrf.middleware.CsrfViewMiddleware",
-    "bolt.auth.middleware.AuthenticationMiddleware",  # <-- Add AuthenticationMiddleware
+    "bolt.auth.middleware.AuthenticationMiddleware",  # <--
     "bolt.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
+
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+```
+
+Create your own user model (`bolt create users`).
+
+```python
+# app/users/models.py
+from bolt.db import models
+from bolt.passwords.models import PasswordField
+
+
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    password = PasswordField()
+    is_staff = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.email
+```
+
+Define your URL/view where users can log in.
+
+```python
+# app/urls.py
+from bolt.auth.views import LoginView, LogoutView
+from bolt.urls import include, path
+from bolt.passwords.views import PasswordLoginView
+
+
+class LoginView(PasswordLoginView):
+    template_name = "login.html"
+
+
+urlpatterns = [
+    path("logout/", LogoutView, name="logout"),
+    path("login/", LoginView, name="login"),
+]
+```
+
+
+## Checking if a user is logged in
+
+A `request.user` will either be `None` or point to an instance of a your `AUTH_USER_MODEL`.
+
+So in templates you can do:
+
+```html
+{% if request.user %}
+    <p>Hello, {{ request.user.email }}!</p>
+{% else %}
+    <p>You are not logged in.</p>
+{% endif %}
+```
+
+Or in Python:
+
+```python
+if request.user:
+    print(f"Hello, {request.user.email}!")
+else:
+    print("You are not logged in.")
+```
+
+
+## Restricting views
+
+Use the `AuthViewMixin` to restrict views to logged in users, staff users, or custom logic.
+
+```python
+from bolt.auth.views import AuthViewMixin
+from bolt.exceptions import PermissionDenied
+from bolt.views import View
+
+
+class LoggedInView(AuthViewMixin, View):
+    login_required = True
+
+
+class StaffOnlyView(AuthViewMixin, View):
+    login_required = True
+    staff_required = True
+
+
+class CustomPermissionView(AuthViewMixin, View):
+    def check_auth(self):
+        super().check_auth()
+        if not self.request.user.is_special:
+            raise PermissionDenied("You're not special!")
 ```

bolt-auth/bolt/auth/README.md

@@ -1,32 +1,123 @@
 # bolt-auth
 
-Create users and authenticate them.
+Add users to your app and define which views they can access.
 
-[link](./config.py)
+To log a user in, you'll want to pair this package with:
 
-## Installation
+- `bolt-passwords`
+- `bolt-oauth`
+- `bolt-passkeys` (TBD)
+- `bolt-passlinks` (TBD)
 
-- install bolt-auth
-- install bolt-sessions
-- optionally bolt-passwords, etc.
-- add bolt.auth to installed packages
+## Installation
 
 ```python
+# app/settings.py
 INSTALLED_PACKAGES = [
     # ...
     "bolt.auth",
+    "bolt.sessions",
+    "bolt.passwords",
 ]
-```
 
-```
-# settings.py
 MIDDLEWARE = [
     "bolt.middleware.security.SecurityMiddleware",
     "bolt.assets.whitenoise.middleware.WhiteNoiseMiddleware",
-    "bolt.sessions.middleware.SessionMiddleware",  # <-- Add SessionMiddleware
+    "bolt.sessions.middleware.SessionMiddleware",  # <--
     "bolt.middleware.common.CommonMiddleware",
     "bolt.csrf.middleware.CsrfViewMiddleware",
-    "bolt.auth.middleware.AuthenticationMiddleware",  # <-- Add AuthenticationMiddleware
+    "bolt.auth.middleware.AuthenticationMiddleware",  # <--
     "bolt.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
+
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+```
+
+Create your own user model (`bolt create users`).
+
+```python
+# app/users/models.py
+from bolt.db import models
+from bolt.passwords.models import PasswordField
+
+
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    password = PasswordField()
+    is_staff = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.email
+```
+
+Define your URL/view where users can log in.
+
+```python
+# app/urls.py
+from bolt.auth.views import LoginView, LogoutView
+from bolt.urls import include, path
+from bolt.passwords.views import PasswordLoginView
+
+
+class LoginView(PasswordLoginView):
+    template_name = "login.html"
+
+
+urlpatterns = [
+    path("logout/", LogoutView, name="logout"),
+    path("login/", LoginView, name="login"),
+]
+```
+
+
+## Checking if a user is logged in
+
+A `request.user` will either be `None` or point to an instance of a your `AUTH_USER_MODEL`.
+
+So in templates you can do:
+
+```html
+{% if request.user %}
+    <p>Hello, {{ request.user.email }}!</p>
+{% else %}
+    <p>You are not logged in.</p>
+{% endif %}
+```
+
+Or in Python:
+
+```python
+if request.user:
+    print(f"Hello, {request.user.email}!")
+else:
+    print("You are not logged in.")
+```
+
+
+## Restricting views
+
+Use the `AuthViewMixin` to restrict views to logged in users, staff users, or custom logic.
+
+```python
+from bolt.auth.views import AuthViewMixin
+from bolt.exceptions import PermissionDenied
+from bolt.views import View
+
+
+class LoggedInView(AuthViewMixin, View):
+    login_required = True
+
+
+class StaffOnlyView(AuthViewMixin, View):
+    login_required = True
+    staff_required = True
+
+
+class CustomPermissionView(AuthViewMixin, View):
+    def check_auth(self):
+        super().check_auth()
+        if not self.request.user.is_special:
+            raise PermissionDenied("You're not special!")
 ```

bolt-db/README.md

@@ -4,7 +4,93 @@
 
 Model your data and store it in a database.
 
+```python
+# app/users/models.py
+from bolt.db import models
+from bolt.passwords.models import PasswordField
+
+
+class User(models.Model):
+    email = models.EmailField(unique=True)
+    password = PasswordField()
+    is_staff = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.email
+```
+
+Create, update, and delete instances of your models:
+
+```python
+from .models import User
+
+
+# Create a new user
+user = User.objects.create(
+    email="[email protected]",
+    password="password",
+)
+
+# Update a user
+user.email = "[email protected]"
+user.save()
+
+# Delete a user
+user.delete()
+
+# Query for users
+staff_users = User.objects.filter(is_staff=True)
+```
+
 ## Installation
 
-- install pkg
-- add to INSTALLED_APPS
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    ...
+    "bolt.db",
+]
+```
+
+To connect to a database, you can provide a `DATABASE_URL` environment variable.
+
+```sh
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+```
+
+Or you can manually define the `DATABASES` setting.
+
+```python
+# app/settings.py
+DATABASES = {
+    "default": {
+        "ENGINE": "bolt.db.backends.postgresql",
+        "NAME": "dbname",
+        "USER": "user",
+        "PASSWORD": "password",
+        "HOST": "localhost",
+        "PORT": "5432",
+    }
+}
+```
+
+[Multiple backends are supported, including Postgres, MySQL, and SQLite.](https://boltframework.dev/docs/bolt-db/bolt/db/backends/README.md)
+
+## Querying
+
+## Migrations
+
+[Migration docs](https://boltframework.dev/docs/bolt-db/bolt/db/migrations/README.md)
+
+## Fields
+
+[Field docs](https://boltframework.dev/docs/bolt-db/bolt/db/fields/README.md)
+
+## Validation
+
+## Indexes and constraints
+
+## Managers
+
+## Forms