Skip to content

Commit 8995651

Browse files
davegaeddertdavegaeddert
committed
Flags, auth, db readmes
1 parent a25e45f commit 8995651

File tree

9 files changed

+407
-28
lines changed

9 files changed

+407
-28
lines changed

‎bolt-auth/README.md

Lines changed: 103 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,33 +2,124 @@
22

33
# bolt-auth
44

5-
Create users and authenticate them.
5+
Add users to your app and define which views they can access.
66

7-
[link](https://boltframework.dev/docs/bolt-auth/bolt/auth/config.py)
7+
To log a user in, you'll want to pair this package with:
88

9-
## Installation
9+
- `bolt-passwords`
10+
- `bolt-oauth`
11+
- `bolt-passkeys` (TBD)
12+
- `bolt-passlinks` (TBD)
1013

11-
- install bolt-auth
12-
- install bolt-sessions
13-
- optionally bolt-passwords, etc.
14-
- add bolt.auth to installed packages
14+
## Installation
1515

1616
```python
17+
# app/settings.py
1718
INSTALLED_PACKAGES = [
1819
# ...
1920
"bolt.auth",
21+
"bolt.sessions",
22+
"bolt.passwords",
2023
]
21-
```
2224

23-
```
24-
# settings.py
2525
MIDDLEWARE = [
2626
"bolt.middleware.security.SecurityMiddleware",
2727
"bolt.assets.whitenoise.middleware.WhiteNoiseMiddleware",
28-
"bolt.sessions.middleware.SessionMiddleware", # <-- Add SessionMiddleware
28+
"bolt.sessions.middleware.SessionMiddleware", # <--
2929
"bolt.middleware.common.CommonMiddleware",
3030
"bolt.csrf.middleware.CsrfViewMiddleware",
31-
"bolt.auth.middleware.AuthenticationMiddleware", # <-- Add AuthenticationMiddleware
31+
"bolt.auth.middleware.AuthenticationMiddleware", # <--
3232
"bolt.middleware.clickjacking.XFrameOptionsMiddleware",
3333
]
34+
35+
AUTH_USER_MODEL = "users.User"
36+
AUTH_LOGIN_URL = "login"
37+
```
38+
39+
Create your own user model (`bolt create users`).
40+
41+
```python
42+
# app/users/models.py
43+
from bolt.db import models
44+
from bolt.passwords.models import PasswordField
45+
46+
47+
class User(models.Model):
48+
email = models.EmailField(unique=True)
49+
password = PasswordField()
50+
is_staff = models.BooleanField(default=False)
51+
created_at = models.DateTimeField(auto_now_add=True)
52+
53+
def __str__(self):
54+
return self.email
55+
```
56+
57+
Define your URL/view where users can log in.
58+
59+
```python
60+
# app/urls.py
61+
from bolt.auth.views import LoginView, LogoutView
62+
from bolt.urls import include, path
63+
from bolt.passwords.views import PasswordLoginView
64+
65+
66+
class LoginView(PasswordLoginView):
67+
template_name = "login.html"
68+
69+
70+
urlpatterns = [
71+
path("logout/", LogoutView, name="logout"),
72+
path("login/", LoginView, name="login"),
73+
]
74+
```
75+
76+
77+
## Checking if a user is logged in
78+
79+
A `request.user` will either be `None` or point to an instance of a your `AUTH_USER_MODEL`.
80+
81+
So in templates you can do:
82+
83+
```html
84+
{% if request.user %}
85+
<p>Hello, {{ request.user.email }}!</p>
86+
{% else %}
87+
<p>You are not logged in.</p>
88+
{% endif %}
89+
```
90+
91+
Or in Python:
92+
93+
```python
94+
if request.user:
95+
print(f"Hello, {request.user.email}!")
96+
else:
97+
print("You are not logged in.")
98+
```
99+
100+
101+
## Restricting views
102+
103+
Use the `AuthViewMixin` to restrict views to logged in users, staff users, or custom logic.
104+
105+
```python
106+
from bolt.auth.views import AuthViewMixin
107+
from bolt.exceptions import PermissionDenied
108+
from bolt.views import View
109+
110+
111+
class LoggedInView(AuthViewMixin, View):
112+
login_required = True
113+
114+
115+
class StaffOnlyView(AuthViewMixin, View):
116+
login_required = True
117+
staff_required = True
118+
119+
120+
class CustomPermissionView(AuthViewMixin, View):
121+
def check_auth(self):
122+
super().check_auth()
123+
if not self.request.user.is_special:
124+
raise PermissionDenied("You're not special!")
34125
```

‎bolt-auth/bolt/auth/README.md

Lines changed: 103 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,123 @@
11
# bolt-auth
22

3-
Create users and authenticate them.
3+
Add users to your app and define which views they can access.
44

5-
[link](./config.py)
5+
To log a user in, you'll want to pair this package with:
66

7-
## Installation
7+
- `bolt-passwords`
8+
- `bolt-oauth`
9+
- `bolt-passkeys` (TBD)
10+
- `bolt-passlinks` (TBD)
811

9-
- install bolt-auth
10-
- install bolt-sessions
11-
- optionally bolt-passwords, etc.
12-
- add bolt.auth to installed packages
12+
## Installation
1313

1414
```python
15+
# app/settings.py
1516
INSTALLED_PACKAGES = [
1617
# ...
1718
"bolt.auth",
19+
"bolt.sessions",
20+
"bolt.passwords",
1821
]
19-
```
2022

21-
```
22-
# settings.py
2323
MIDDLEWARE = [
2424
"bolt.middleware.security.SecurityMiddleware",
2525
"bolt.assets.whitenoise.middleware.WhiteNoiseMiddleware",
26-
"bolt.sessions.middleware.SessionMiddleware", # <-- Add SessionMiddleware
26+
"bolt.sessions.middleware.SessionMiddleware", # <--
2727
"bolt.middleware.common.CommonMiddleware",
2828
"bolt.csrf.middleware.CsrfViewMiddleware",
29-
"bolt.auth.middleware.AuthenticationMiddleware", # <-- Add AuthenticationMiddleware
29+
"bolt.auth.middleware.AuthenticationMiddleware", # <--
3030
"bolt.middleware.clickjacking.XFrameOptionsMiddleware",
3131
]
32+
33+
AUTH_USER_MODEL = "users.User"
34+
AUTH_LOGIN_URL = "login"
35+
```
36+
37+
Create your own user model (`bolt create users`).
38+
39+
```python
40+
# app/users/models.py
41+
from bolt.db import models
42+
from bolt.passwords.models import PasswordField
43+
44+
45+
class User(models.Model):
46+
email = models.EmailField(unique=True)
47+
password = PasswordField()
48+
is_staff = models.BooleanField(default=False)
49+
created_at = models.DateTimeField(auto_now_add=True)
50+
51+
def __str__(self):
52+
return self.email
53+
```
54+
55+
Define your URL/view where users can log in.
56+
57+
```python
58+
# app/urls.py
59+
from bolt.auth.views import LoginView, LogoutView
60+
from bolt.urls import include, path
61+
from bolt.passwords.views import PasswordLoginView
62+
63+
64+
class LoginView(PasswordLoginView):
65+
template_name = "login.html"
66+
67+
68+
urlpatterns = [
69+
path("logout/", LogoutView, name="logout"),
70+
path("login/", LoginView, name="login"),
71+
]
72+
```
73+
74+
75+
## Checking if a user is logged in
76+
77+
A `request.user` will either be `None` or point to an instance of a your `AUTH_USER_MODEL`.
78+
79+
So in templates you can do:
80+
81+
```html
82+
{% if request.user %}
83+
<p>Hello, {{ request.user.email }}!</p>
84+
{% else %}
85+
<p>You are not logged in.</p>
86+
{% endif %}
87+
```
88+
89+
Or in Python:
90+
91+
```python
92+
if request.user:
93+
print(f"Hello, {request.user.email}!")
94+
else:
95+
print("You are not logged in.")
96+
```
97+
98+
99+
## Restricting views
100+
101+
Use the `AuthViewMixin` to restrict views to logged in users, staff users, or custom logic.
102+
103+
```python
104+
from bolt.auth.views import AuthViewMixin
105+
from bolt.exceptions import PermissionDenied
106+
from bolt.views import View
107+
108+
109+
class LoggedInView(AuthViewMixin, View):
110+
login_required = True
111+
112+
113+
class StaffOnlyView(AuthViewMixin, View):
114+
login_required = True
115+
staff_required = True
116+
117+
118+
class CustomPermissionView(AuthViewMixin, View):
119+
def check_auth(self):
120+
super().check_auth()
121+
if not self.request.user.is_special:
122+
raise PermissionDenied("You're not special!")
32123
```

‎bolt-db/README.md

Lines changed: 88 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,93 @@
44

55
Model your data and store it in a database.
66

7+
```python
8+
# app/users/models.py
9+
from bolt.db import models
10+
from bolt.passwords.models import PasswordField
11+
12+
13+
class User(models.Model):
14+
email = models.EmailField(unique=True)
15+
password = PasswordField()
16+
is_staff = models.BooleanField(default=False)
17+
created_at = models.DateTimeField(auto_now_add=True)
18+
19+
def __str__(self):
20+
return self.email
21+
```
22+
23+
Create, update, and delete instances of your models:
24+
25+
```python
26+
from .models import User
27+
28+
29+
# Create a new user
30+
user = User.objects.create(
31+
email="[email protected]",
32+
password="password",
33+
)
34+
35+
# Update a user
36+
user.email = "[email protected]"
37+
user.save()
38+
39+
# Delete a user
40+
user.delete()
41+
42+
# Query for users
43+
staff_users = User.objects.filter(is_staff=True)
44+
```
45+
746
## Installation
847

9-
- install pkg
10-
- add to INSTALLED_APPS
48+
```python
49+
# app/settings.py
50+
INSTALLED_PACKAGES = [
51+
...
52+
"bolt.db",
53+
]
54+
```
55+
56+
To connect to a database, you can provide a `DATABASE_URL` environment variable.
57+
58+
```sh
59+
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
60+
```
61+
62+
Or you can manually define the `DATABASES` setting.
63+
64+
```python
65+
# app/settings.py
66+
DATABASES = {
67+
"default": {
68+
"ENGINE": "bolt.db.backends.postgresql",
69+
"NAME": "dbname",
70+
"USER": "user",
71+
"PASSWORD": "password",
72+
"HOST": "localhost",
73+
"PORT": "5432",
74+
}
75+
}
76+
```
77+
78+
[Multiple backends are supported, including Postgres, MySQL, and SQLite.](https://boltframework.dev/docs/bolt-db/bolt/db/backends/README.md)
79+
80+
## Querying
81+
82+
## Migrations
83+
84+
[Migration docs](https://boltframework.dev/docs/bolt-db/bolt/db/migrations/README.md)
85+
86+
## Fields
87+
88+
[Field docs](https://boltframework.dev/docs/bolt-db/bolt/db/fields/README.md)
89+
90+
## Validation
91+
92+
## Indexes and constraints
93+
94+
## Managers
95+
96+
## Forms

0 commit comments

Comments
 (0)