plain.auth 0.24.0__tar.gz → 0.25.1__tar.gz

{plain_auth-0.24.0 → plain_auth-0.25.1}/.gitignore

@@ -17,5 +17,5 @@ plain*/tests/.plain
 .plain
 
 .vscode
-/.claude
+/.claude/skills/plain-*
 /.benchmarks

{plain_auth-0.24.0 → plain_auth-0.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.auth
-Version: 0.24.0
+Version: 0.25.1
 Summary: Add users to your app and decide what they can access.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -22,14 +22,16 @@ Description-Content-Type: text/markdown
     - [Login views](#login-views)
 - [Checking if a user is logged in](#checking-if-a-user-is-logged-in)
 - [Restricting views](#restricting-views)
+- [Testing with authenticated users](#testing-with-authenticated-users)
+- [Settings](#settings)
+- [FAQs](#faqs)
 - [Installation](#installation)
 
 ## Overview
 
-The `plain.auth` package provides user authentication and authorization for Plain applications. Here's a basic example of checking if a user is logged in:
+The `plain.auth` package handles user authentication and authorization for Plain applications. You can check if a user is logged in like this:
 
 ```python
-# In a view
 from plain.auth import get_request_user
 
 user = get_request_user(request)
@@ -39,7 +41,7 @@ else:
     print("You are not logged in.")
 ```
 
-And restricting a view to logged-in users:
+You can restrict a view to logged-in users using [`AuthViewMixin`](./views.py#AuthViewMixin):
 
 ```python
 from plain.auth.views import AuthViewMixin
@@ -76,7 +78,7 @@ AUTH_LOGIN_URL = "login"
 
 ### Creating a user model
 
-Create your own user model using `plain create users` or manually:
+You can create your own user model using `plain create users` or manually:
 
 ```python
 # app/users/models.py
@@ -96,14 +98,13 @@ class User(models.Model):
 
 ### Login views
 
-To log users in, you'll need to pair this package with an authentication method:
+To log users in, you need to pair this package with an authentication method:
 
-- `plain-passwords` - Username/password authentication
-- `plain-oauth` - OAuth provider authentication
-- `plain-passkeys` (TBD) - WebAuthn/passkey authentication
-- `plain-passlinks` (TBD) - Magic link authentication
+- [plain.passwords](../../plain-passwords/plain/passwords/README.md) - Username/password authentication
+- [plain.oauth](../../plain-oauth/plain/oauth/README.md) - OAuth provider authentication
+- [plain.loginlink](../../plain-loginlink/plain/loginlink/README.md) - Magic link authentication
 
-Example with password authentication:
+Here's an example with password authentication:
 
 ```python
 # app/urls.py
@@ -124,7 +125,7 @@ urlpatterns = [
 
 ## Checking if a user is logged in
 
-In templates, use the `get_current_user()` function:
+In templates, you can use the `get_current_user()` function:
 
 ```html
 {% if get_current_user() %}
@@ -134,7 +135,7 @@ In templates, use the `get_current_user()` function:
 {% endif %}
 ```
 
-In Python code, use `get_request_user()`:
+In Python code, use [`get_request_user()`](./requests.py#get_request_user):
 
 ```python
 from plain.auth import get_request_user
@@ -148,7 +149,7 @@ else:
 
 ## Restricting views
 
-Use the [`AuthViewMixin`](./views.py#AuthViewMixin) to restrict views to logged-in users, admin users, or custom logic:
+You can use [`AuthViewMixin`](./views.py#AuthViewMixin) to restrict views to logged-in users, admin users, or custom logic:
 
 ```python
 from plain.auth.views import AuthViewMixin
@@ -178,6 +179,81 @@ The [`AuthViewMixin`](./views.py#AuthViewMixin) provides:
 - `admin_required` - Requires `user.is_admin` to be True
 - `check_auth()` - Override for custom authorization logic
 
+## Testing with authenticated users
+
+When writing tests, you can use [`login_client()`](./test.py#login_client) to simulate an authenticated user:
+
+```python
+from plain.auth.test import login_client
+from plain.test import Client
+
+from app.users.models import User
+
+
+def test_profile_view():
+    user = User.objects.create(email="test@example.com")
+    client = Client()
+    login_client(client, user)
+
+    response = client.get("/profile/")
+    assert response.status_code == 200
+```
+
+You can also log out a test user with [`logout_client()`](./test.py#logout_client):
+
+```python
+from plain.auth.test import login_client, logout_client
+
+# ... after logging in
+logout_client(client)
+```
+
+## Settings
+
+| Setting                        | Default              | Env var                              |
+| ------------------------------ | -------------------- | ------------------------------------ |
+| `AUTH_USER_MODEL`              | Required             | `PLAIN_AUTH_USER_MODEL`              |
+| `AUTH_LOGIN_URL`               | Required             | `PLAIN_AUTH_LOGIN_URL`               |
+| `AUTH_USER_SESSION_HASH_FIELD` | `"password"` or `""` | `PLAIN_AUTH_USER_SESSION_HASH_FIELD` |
+
+See [`default_settings.py`](./default_settings.py) for more details.
+
+## FAQs
+
+#### How do I log in a user programmatically?
+
+You can use the [`login()`](./sessions.py#login) function to log in a user:
+
+```python
+from plain.auth.sessions import login
+
+login(request, user)
+```
+
+#### How do I log out a user programmatically?
+
+You can use the [`logout()`](./sessions.py#logout) function:
+
+```python
+from plain.auth.sessions import logout
+
+logout(request)
+```
+
+#### How do I invalidate sessions when a user changes their password?
+
+By default, if you have [plain.passwords](../../plain-passwords/plain/passwords/README.md) installed, sessions are automatically invalidated when the `password` field changes. This is controlled by the `AUTH_USER_SESSION_HASH_FIELD` setting. You can change this to a different field name, or set it to an empty string to disable this feature.
+
+#### How do I get the user model class?
+
+You can use the [`get_user_model()`](./sessions.py#get_user_model) function:
+
+```python
+from plain.auth.sessions import get_user_model
+
+User = get_user_model()
+```
+
 ## Installation
 
 Install the `plain.auth` package from [PyPI](https://pypi.org/project/plain.auth/):

{plain_auth-0.24.0 → plain_auth-0.25.1}/plain/auth/CHANGELOG.md

@@ -1,5 +1,25 @@
 # plain-auth changelog
 
+## [0.25.1](https://github.com/dropseed/plain/releases/plain-auth@0.25.1) (2026-01-28)
+
+### What's changed
+
+- Added Settings section to README ([803fee1ad5](https://github.com/dropseed/plain/commit/803fee1ad5))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.25.0](https://github.com/dropseed/plain/releases/plain-auth@0.25.0) (2026-01-13)
+
+### What's changed
+
+- Improved README documentation with better examples and consistent structure ([da37a78](https://github.com/dropseed/plain/commit/da37a78fbb))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.24.0](https://github.com/dropseed/plain/releases/plain-auth@0.24.0) (2026-01-13)
 
 ### What's changed

plain_auth-0.25.1/plain/auth/README.md

@@ -0,0 +1,250 @@
+# plain.auth
+
+**Add users to your app and decide what they can access.**
+
+- [Overview](#overview)
+- [Authentication setup](#authentication-setup)
+    - [Settings configuration](#settings-configuration)
+    - [Creating a user model](#creating-a-user-model)
+    - [Login views](#login-views)
+- [Checking if a user is logged in](#checking-if-a-user-is-logged-in)
+- [Restricting views](#restricting-views)
+- [Testing with authenticated users](#testing-with-authenticated-users)
+- [Settings](#settings)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+The `plain.auth` package handles user authentication and authorization for Plain applications. You can check if a user is logged in like this:
+
+```python
+from plain.auth import get_request_user
+
+user = get_request_user(request)
+if user:
+    print(f"Hello, {user.email}!")
+else:
+    print("You are not logged in.")
+```
+
+You can restrict a view to logged-in users using [`AuthViewMixin`](./views.py#AuthViewMixin):
+
+```python
+from plain.auth.views import AuthViewMixin
+from plain.views import View
+
+class ProfileView(AuthViewMixin, View):
+    login_required = True
+
+    def get(self):
+        return f"Welcome, {self.user.email}!"
+```
+
+## Authentication setup
+
+### Settings configuration
+
+Configure your authentication settings in `app/settings.py`:
+
+```python
+INSTALLED_PACKAGES = [
+    # ...
+    "plain.auth",
+    "plain.sessions",
+    "plain.passwords",  # Or another auth method
+]
+
+MIDDLEWARE = [
+    "plain.sessions.middleware.SessionMiddleware",
+]
+
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+```
+
+### Creating a user model
+
+You can create your own user model using `plain create users` or manually:
+
+```python
+# app/users/models.py
+from plain import models
+from plain.passwords.models import PasswordField
+
+
+class User(models.Model):
+    email = models.EmailField()
+    password = PasswordField()
+    is_admin = models.BooleanField(default=False)
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.email
+```
+
+### Login views
+
+To log users in, you need to pair this package with an authentication method:
+
+- [plain.passwords](../../plain-passwords/plain/passwords/README.md) - Username/password authentication
+- [plain.oauth](../../plain-oauth/plain/oauth/README.md) - OAuth provider authentication
+- [plain.loginlink](../../plain-loginlink/plain/loginlink/README.md) - Magic link authentication
+
+Here's an example with password authentication:
+
+```python
+# app/urls.py
+from plain.auth.views import LogoutView
+from plain.urls import path
+from plain.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
+
+In templates, you can use the `get_current_user()` function:
+
+```html
+{% if get_current_user() %}
+    <p>Hello, {{ get_current_user().email }}!</p>
+{% else %}
+    <p>You are not logged in.</p>
+{% endif %}
+```
+
+In Python code, use [`get_request_user()`](./requests.py#get_request_user):
+
+```python
+from plain.auth import get_request_user
+
+user = get_request_user(request)
+if user:
+    print(f"Hello, {user.email}!")
+else:
+    print("You are not logged in.")
+```
+
+## Restricting views
+
+You can use [`AuthViewMixin`](./views.py#AuthViewMixin) to restrict views to logged-in users, admin users, or custom logic:
+
+```python
+from plain.auth.views import AuthViewMixin
+from plain.http import ForbiddenError403
+from plain.views import View
+
+
+class LoggedInView(AuthViewMixin, View):
+    login_required = True
+
+
+class AdminOnlyView(AuthViewMixin, View):
+    login_required = True
+    admin_required = True
+
+
+class CustomPermissionView(AuthViewMixin, View):
+    def check_auth(self):
+        super().check_auth()
+        if not self.user.is_special:
+            raise ForbiddenError403("You're not special!")
+```
+
+The [`AuthViewMixin`](./views.py#AuthViewMixin) provides:
+
+- `login_required` - Requires a logged-in user
+- `admin_required` - Requires `user.is_admin` to be True
+- `check_auth()` - Override for custom authorization logic
+
+## Testing with authenticated users
+
+When writing tests, you can use [`login_client()`](./test.py#login_client) to simulate an authenticated user:
+
+```python
+from plain.auth.test import login_client
+from plain.test import Client
+
+from app.users.models import User
+
+
+def test_profile_view():
+    user = User.objects.create(email="test@example.com")
+    client = Client()
+    login_client(client, user)
+
+    response = client.get("/profile/")
+    assert response.status_code == 200
+```
+
+You can also log out a test user with [`logout_client()`](./test.py#logout_client):
+
+```python
+from plain.auth.test import login_client, logout_client
+
+# ... after logging in
+logout_client(client)
+```
+
+## Settings
+
+| Setting                        | Default              | Env var                              |
+| ------------------------------ | -------------------- | ------------------------------------ |
+| `AUTH_USER_MODEL`              | Required             | `PLAIN_AUTH_USER_MODEL`              |
+| `AUTH_LOGIN_URL`               | Required             | `PLAIN_AUTH_LOGIN_URL`               |
+| `AUTH_USER_SESSION_HASH_FIELD` | `"password"` or `""` | `PLAIN_AUTH_USER_SESSION_HASH_FIELD` |
+
+See [`default_settings.py`](./default_settings.py) for more details.
+
+## FAQs
+
+#### How do I log in a user programmatically?
+
+You can use the [`login()`](./sessions.py#login) function to log in a user:
+
+```python
+from plain.auth.sessions import login
+
+login(request, user)
+```
+
+#### How do I log out a user programmatically?
+
+You can use the [`logout()`](./sessions.py#logout) function:
+
+```python
+from plain.auth.sessions import logout
+
+logout(request)
+```
+
+#### How do I invalidate sessions when a user changes their password?
+
+By default, if you have [plain.passwords](../../plain-passwords/plain/passwords/README.md) installed, sessions are automatically invalidated when the `password` field changes. This is controlled by the `AUTH_USER_SESSION_HASH_FIELD` setting. You can change this to a different field name, or set it to an empty string to disable this feature.
+
+#### How do I get the user model class?
+
+You can use the [`get_user_model()`](./sessions.py#get_user_model) function:
+
+```python
+from plain.auth.sessions import get_user_model
+
+User = get_user_model()
+```
+
+## Installation
+
+Install the `plain.auth` package from [PyPI](https://pypi.org/project/plain.auth/):
+
+```bash
+uv add plain.auth
+```

{plain_auth-0.24.0 → plain_auth-0.25.1}/plain/auth/sessions.py

@@ -16,8 +16,8 @@ from .requests import get_request_user, set_request_user
 if TYPE_CHECKING:
     from plain.http import Request
 
-USER_ID_SESSION_KEY = "_auth_user_id"
-USER_HASH_SESSION_KEY = "_auth_user_hash"
+_USER_ID_SESSION_KEY = "_auth_user_id"
+_USER_HASH_SESSION_KEY = "_auth_user_hash"
 
 
 def get_session_auth_hash(user: Any) -> str:
@@ -40,10 +40,10 @@ def update_session_auth_hash(request: Request, user: Any) -> None:
     session = get_request_session(request)
     session.cycle_key()
     if get_request_user(request) == user:
-        session[USER_HASH_SESSION_KEY] = get_session_auth_hash(user)
+        session[_USER_HASH_SESSION_KEY] = get_session_auth_hash(user)
 
 
-def get_session_auth_fallback_hash(user: Any) -> Generator[str, None, None]:
+def _get_session_auth_fallback_hash(user: Any) -> Generator[str, None, None]:
     for fallback_secret in settings.SECRET_KEY_FALLBACKS:
         yield _get_session_auth_hash(user, secret=fallback_secret)
 
@@ -71,14 +71,14 @@ def login(request: Request, user: Any) -> None:
     else:
         session_auth_hash = ""
 
-    if USER_ID_SESSION_KEY in session:
-        if int(session[USER_ID_SESSION_KEY]) != user.id:
+    if _USER_ID_SESSION_KEY in session:
+        if int(session[_USER_ID_SESSION_KEY]) != user.id:
             # To avoid reusing another user's session, create a new, empty
             # session if the existing session corresponds to a different
             # authenticated user.
             session.flush()
         elif session_auth_hash and not hmac.compare_digest(
-            force_bytes(session.get(USER_HASH_SESSION_KEY, "")),
+            force_bytes(session.get(_USER_HASH_SESSION_KEY, "")),
             force_bytes(session_auth_hash),
         ):
             # If the session hash does not match the current hash, reset the
@@ -89,8 +89,8 @@ def login(request: Request, user: Any) -> None:
         # typically done after user login to prevent session fixation attacks.
         session.cycle_key()
 
-    session[USER_ID_SESSION_KEY] = user.id
-    session[USER_HASH_SESSION_KEY] = session_auth_hash
+    session[_USER_ID_SESSION_KEY] = user.id
+    session[_USER_HASH_SESSION_KEY] = session_auth_hash
     set_request_user(request, user)
 
 
@@ -129,12 +129,12 @@ def get_user(request: Request) -> Any | None:
     """
     session = get_request_session(request)
 
-    if USER_ID_SESSION_KEY not in session:
+    if _USER_ID_SESSION_KEY not in session:
         return None
 
     UserModel = get_user_model()
     try:
-        user = UserModel.query.get(id=session[USER_ID_SESSION_KEY])
+        user = UserModel.query.get(id=session[_USER_ID_SESSION_KEY])
     except UserModel.DoesNotExist:
         return None
 
@@ -145,7 +145,7 @@ def get_user(request: Request) -> Any | None:
     # If it has changed (i.e. password changed), then the session
     # is no longer valid and cleared out.
     if settings.AUTH_USER_SESSION_HASH_FIELD:
-        session_hash = session.get(USER_HASH_SESSION_KEY)
+        session_hash = session.get(_USER_HASH_SESSION_KEY)
         if not session_hash:
             session_hash_verified = False
         else:
@@ -161,10 +161,10 @@ def get_user(request: Request) -> Any | None:
                 hmac.compare_digest(
                     force_bytes(session_hash), force_bytes(fallback_auth_hash)
                 )
-                for fallback_auth_hash in get_session_auth_fallback_hash(user)
+                for fallback_auth_hash in _get_session_auth_fallback_hash(user)
             ):
                 session.cycle_key()
-                session[USER_HASH_SESSION_KEY] = session_auth_hash
+                session[_USER_HASH_SESSION_KEY] = session_auth_hash
             else:
                 session.flush()
                 user = None

{plain_auth-0.24.0 → plain_auth-0.25.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.auth"
-version = "0.24.0"
+version = "0.25.1"
 description = "Add users to your app and decide what they can access."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"

plain_auth-0.24.0/plain/auth/README.md

@@ -1,174 +0,0 @@
-# plain.auth
-
-**Add users to your app and decide what they can access.**
-
-- [Overview](#overview)
-- [Authentication setup](#authentication-setup)
-    - [Settings configuration](#settings-configuration)
-    - [Creating a user model](#creating-a-user-model)
-    - [Login views](#login-views)
-- [Checking if a user is logged in](#checking-if-a-user-is-logged-in)
-- [Restricting views](#restricting-views)
-- [Installation](#installation)
-
-## Overview
-
-The `plain.auth` package provides user authentication and authorization for Plain applications. Here's a basic example of checking if a user is logged in:
-
-```python
-# In a view
-from plain.auth import get_request_user
-
-user = get_request_user(request)
-if user:
-    print(f"Hello, {user.email}!")
-else:
-    print("You are not logged in.")
-```
-
-And restricting a view to logged-in users:
-
-```python
-from plain.auth.views import AuthViewMixin
-from plain.views import View
-
-class ProfileView(AuthViewMixin, View):
-    login_required = True
-
-    def get(self):
-        return f"Welcome, {self.user.email}!"
-```
-
-## Authentication setup
-
-### Settings configuration
-
-Configure your authentication settings in `app/settings.py`:
-
-```python
-INSTALLED_PACKAGES = [
-    # ...
-    "plain.auth",
-    "plain.sessions",
-    "plain.passwords",  # Or another auth method
-]
-
-MIDDLEWARE = [
-    "plain.sessions.middleware.SessionMiddleware",
-]
-
-AUTH_USER_MODEL = "users.User"
-AUTH_LOGIN_URL = "login"
-```
-
-### Creating a user model
-
-Create your own user model using `plain create users` or manually:
-
-```python
-# app/users/models.py
-from plain import models
-from plain.passwords.models import PasswordField
-
-
-class User(models.Model):
-    email = models.EmailField()
-    password = PasswordField()
-    is_admin = models.BooleanField(default=False)
-    created_at = models.DateTimeField(auto_now_add=True)
-
-    def __str__(self):
-        return self.email
-```
-
-### Login views
-
-To log users in, you'll need to pair this package with an authentication method:
-
-- `plain-passwords` - Username/password authentication
-- `plain-oauth` - OAuth provider authentication
-- `plain-passkeys` (TBD) - WebAuthn/passkey authentication
-- `plain-passlinks` (TBD) - Magic link authentication
-
-Example with password authentication:
-
-```python
-# app/urls.py
-from plain.auth.views import LogoutView
-from plain.urls import path
-from plain.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
-
-In templates, use the `get_current_user()` function:
-
-```html
-{% if get_current_user() %}
-    <p>Hello, {{ get_current_user().email }}!</p>
-{% else %}
-    <p>You are not logged in.</p>
-{% endif %}
-```
-
-In Python code, use `get_request_user()`:
-
-```python
-from plain.auth import get_request_user
-
-user = get_request_user(request)
-if user:
-    print(f"Hello, {user.email}!")
-else:
-    print("You are not logged in.")
-```
-
-## Restricting views
-
-Use the [`AuthViewMixin`](./views.py#AuthViewMixin) to restrict views to logged-in users, admin users, or custom logic:
-
-```python
-from plain.auth.views import AuthViewMixin
-from plain.http import ForbiddenError403
-from plain.views import View
-
-
-class LoggedInView(AuthViewMixin, View):
-    login_required = True
-
-
-class AdminOnlyView(AuthViewMixin, View):
-    login_required = True
-    admin_required = True
-
-
-class CustomPermissionView(AuthViewMixin, View):
-    def check_auth(self):
-        super().check_auth()
-        if not self.user.is_special:
-            raise ForbiddenError403("You're not special!")
-```
-
-The [`AuthViewMixin`](./views.py#AuthViewMixin) provides:
-
-- `login_required` - Requires a logged-in user
-- `admin_required` - Requires `user.is_admin` to be True
-- `check_auth()` - Override for custom authorization logic
-
-## Installation
-
-Install the `plain.auth` package from [PyPI](https://pypi.org/project/plain.auth/):
-
-```bash
-uv add plain.auth
-```