From 8995651aa1d0e815674a38c96cf99bb18f37ecbc Mon Sep 17 00:00:00 2001 From: Dave Gaeddert Date: Fri, 21 Jun 2024 15:11:10 -0500 Subject: [PATCH] Flags, auth, db readmes --- bolt-auth/README.md | 115 +++++++++++++++++++++--- bolt-auth/bolt/auth/README.md | 115 +++++++++++++++++++++--- bolt-db/README.md | 90 ++++++++++++++++++- bolt-db/bolt/db/README.md | 90 ++++++++++++++++++- bolt-db/bolt/db/backends/README.md | 1 + bolt-db/bolt/db/migrations/README.md | 1 + bolt-db/bolt/db/models/fields/README.md | 1 + bolt-flags/README.md | 11 +++ bolt-flags/bolt/flags/README.md | 11 +++ 9 files changed, 407 insertions(+), 28 deletions(-) create mode 100644 bolt-db/bolt/db/backends/README.md create mode 100644 bolt-db/bolt/db/migrations/README.md create mode 100644 bolt-db/bolt/db/models/fields/README.md diff --git a/bolt-auth/README.md b/bolt-auth/README.md index b317958fd6..c456660a92 100644 --- a/bolt-auth/README.md +++ b/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 %} +

Hello, {{ request.user.email }}!

+{% else %} +

You are not logged in.

+{% 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!") ``` diff --git a/bolt-auth/bolt/auth/README.md b/bolt-auth/bolt/auth/README.md index 3b6a11eaf5..cefc9507ea 100644 --- a/bolt-auth/bolt/auth/README.md +++ b/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 %} +

Hello, {{ request.user.email }}!

+{% else %} +

You are not logged in.

+{% 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!") ``` diff --git a/bolt-db/README.md b/bolt-db/README.md index a4a2b5e1a0..1393a5bf9b 100644 --- a/bolt-db/README.md +++ b/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="test@example.com", + password="password", +) + +# Update a user +user.email = "new@example.com" +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 diff --git a/bolt-db/bolt/db/README.md b/bolt-db/bolt/db/README.md index 84de429d1f..5ca80ba390 100644 --- a/bolt-db/bolt/db/README.md +++ b/bolt-db/bolt/db/README.md @@ -2,7 +2,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="test@example.com", + password="password", +) + +# Update a user +user.email = "new@example.com" +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.](./backends/README.md) + +## Querying + +## Migrations + +[Migration docs](./migrations/README.md) + +## Fields + +[Field docs](./fields/README.md) + +## Validation + +## Indexes and constraints + +## Managers + +## Forms diff --git a/bolt-db/bolt/db/backends/README.md b/bolt-db/bolt/db/backends/README.md new file mode 100644 index 0000000000..817deaba43 --- /dev/null +++ b/bolt-db/bolt/db/backends/README.md @@ -0,0 +1 @@ +# Backends diff --git a/bolt-db/bolt/db/migrations/README.md b/bolt-db/bolt/db/migrations/README.md new file mode 100644 index 0000000000..b7693a288f --- /dev/null +++ b/bolt-db/bolt/db/migrations/README.md @@ -0,0 +1 @@ +# Migrations diff --git a/bolt-db/bolt/db/models/fields/README.md b/bolt-db/bolt/db/models/fields/README.md new file mode 100644 index 0000000000..cb06804d37 --- /dev/null +++ b/bolt-db/bolt/db/models/fields/README.md @@ -0,0 +1 @@ +# Fields diff --git a/bolt-flags/README.md b/bolt-flags/README.md index 1c8e523e23..ddc46ed679 100644 --- a/bolt-flags/README.md +++ b/bolt-flags/README.md @@ -45,6 +45,17 @@ import flags print(flags.FooEnabled(user).value) ``` +## Installation + +```python +INSTALLED_PACKAGES = [ + ... + "bolt.flags", +] +``` + +Create a `flags.py` at the top of your `app` (or point `settings.FLAGS_MODULE` to a different location). + ## Advanced usage Ultimately you can do whatever you want inside of `get_key` and `get_value`. diff --git a/bolt-flags/bolt/flags/README.md b/bolt-flags/bolt/flags/README.md index e39b71a9d5..1bc1586fe7 100644 --- a/bolt-flags/bolt/flags/README.md +++ b/bolt-flags/bolt/flags/README.md @@ -43,6 +43,17 @@ import flags print(flags.FooEnabled(user).value) ``` +## Installation + +```python +INSTALLED_PACKAGES = [ + ... + "bolt.flags", +] +``` + +Create a `flags.py` at the top of your `app` (or point `settings.FLAGS_MODULE` to a different location). + ## Advanced usage Ultimately you can do whatever you want inside of `get_key` and `get_value`.