plain.auth 0.24.0__py3-none-any.whl → 0.25.1__py3-none-any.whl

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/README.md

@@ -9,14 +9,16 @@
     - [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)
@@ -26,7 +28,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
@@ -63,7 +65,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
@@ -83,14 +85,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
@@ -111,7 +112,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() %}
@@ -121,7 +122,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
@@ -135,7 +136,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
@@ -165,6 +166,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/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.dist-info → plain_auth-0.25.1.dist-info}/METADATA

@@ -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.dist-info → plain_auth-0.25.1.dist-info}/RECORD

@@ -1,14 +1,14 @@
-plain/auth/CHANGELOG.md,sha256=VeYgWu5r6BNrYZjcPfSSif2vs7WM8wFRBHNQEINk6KY,8901
-plain/auth/README.md,sha256=wL184DYe9n6FqYR4IzBlN6h-EQsSy-gZA-c9x1w7e7U,4026
+plain/auth/CHANGELOG.md,sha256=t2aRedYSsMgZ-zW_Iq8H_bPmesQpYO21HLBWcGuOL7U,9464
+plain/auth/README.md,sha256=nq4CJ43yBNkeKWUNdajx7PCNr4i6qxKb8dkfqo0bxG4,6566
 plain/auth/__init__.py,sha256=CrOsS74CPGN1nPTTfie13mPgdyVLRyZ1YwDPIA77uaA,179
 plain/auth/default_settings.py,sha256=65VzDn3j61OMn78Lg6Zuds4A8QKzJJ_0G9KoFqAOIRo,466
 plain/auth/requests.py,sha256=jUlMTOWFt0qfDF_uVkOqaP9rZiCLrAofsmirCwyRGEE,880
-plain/auth/sessions.py,sha256=xDp1EiB0cV5w3L5XioqO8vs77wnF8cvreExms3-e744,6015
+plain/auth/sessions.py,sha256=p3aW_3FsjFLZ1Nk2OHejqL-rhAX5NHSE7aigr_z8L3U,6029
 plain/auth/templates.py,sha256=CVtuIdBgOgYB2o61zpOPJb6nMx_gU61i_3PDQx8FjVs,770
 plain/auth/test.py,sha256=SHawhwarJEMVfaLkjpiuFVSWZoGIMwhzXreU_T1zvCE,1599
 plain/auth/utils.py,sha256=9kKWh1QqxA8Esct-jBvTCdjBYOHpO_Tg1YeV9WxYmxg,1362
 plain/auth/views.py,sha256=Nu4adJ9bhFdiPkGOVqt7BbIA150HG1ojSFEqAnIO3P8,4923
-plain_auth-0.24.0.dist-info/METADATA,sha256=6tF2zaZLavS1aiZN6FVw3keWoBakjmxPRRtEQdcHxjw,4419
-plain_auth-0.24.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-plain_auth-0.24.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain_auth-0.24.0.dist-info/RECORD,,
+plain_auth-0.25.1.dist-info/METADATA,sha256=Xmt3JziZGcZnLH6BQG9-duU8OEmx-6JYXxSZf-29cAo,6959
+plain_auth-0.25.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+plain_auth-0.25.1.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain_auth-0.25.1.dist-info/RECORD,,