plain.auth 0.24.0__tar.gz → 0.25.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.auth
-Version: 0.24.0
+Version: 0.25.0
 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,15 @@ 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)
+- [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 +40,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 +77,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 +97,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 +124,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 +134,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 +148,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 +178,71 @@ 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)
+```
+
+## 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.0}/plain/auth/CHANGELOG.md

@@ -1,5 +1,15 @@
 # plain-auth changelog
 
+## [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.24.0 → plain_auth-0.25.0}/plain/auth/README.md

@@ -9,14 +9,15 @@
     - [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)
+- [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 +27,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 +64,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 +84,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 +111,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 +121,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 +135,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 +165,71 @@ 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)
+```
+
+## 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.0}/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.0}/pyproject.toml

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