plain.oauth 0.24.1__py3-none-any.whl → 0.24.2__py3-none-any.whl

plain/oauth/CHANGELOG.md

@@ -1,5 +1,17 @@
 # plain-oauth changelog
 
+## [0.24.2](https://github.com/dropseed/plain/releases/plain-oauth@0.24.2) (2025-08-05)
+
+### What's changed
+
+- Updated documentation to use `plain` commands instead of `python manage.py` references ([8071854](https://github.com/dropseed/plain/commit/8071854d61))
+- Improved README with better structure, table of contents, and more comprehensive examples ([4ebecd1](https://github.com/dropseed/plain/commit/4ebecd1856))
+- Fixed router setup documentation in URLs section ([48caf10](https://github.com/dropseed/plain/commit/48caf105da))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.24.1](https://github.com/dropseed/plain/releases/plain-oauth@0.24.1) (2025-07-23)
 
 ### What's changed

plain/oauth/README.md

@@ -1,6 +1,18 @@
 # plain.oauth
 
-Let users log in with OAuth providers.
+**Let users log in with OAuth providers.**
+
+- [Overview](#overview)
+- [Usage](#usage)
+    - [Basic setup example](#basic-setup-example)
+    - [Handling OAuth errors](#handling-oauth-errors)
+    - [Connecting and disconnecting OAuth accounts](#connecting-and-disconnecting-oauth-accounts)
+    - [Using a saved access token](#using-a-saved-access-token)
+    - [Using the Django system check](#using-the-django-system-check)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
 
 [Watch on YouTube (3 mins) →](https://www.youtube.com/watch?v=UxbxBa6AFsU)
 
@@ -17,11 +29,9 @@ There are three OAuth flows that it makes possible:
 
 ## Usage
 
-Install the package from PyPi:
+### Basic setup example
 
-```sh
-pip install plain-oauth
-```
+Here's a complete example showing how to set up OAuth login with GitHub:
 
 Add `plain.oauth` to your `INSTALLED_PACKAGES` in `settings.py`:
 
@@ -32,19 +42,24 @@ INSTALLED_PACKAGES = [
 ]
 ```
 
-In your `urls.py`, include `plain.oauth.urls`:
+In your `urls.py`, include the [`OAuthRouter`](./urls.py#OAuthRouter):
 
 ```python
-urlpatterns = [
-    path("oauth/", include("plain.oauth.urls")),
-    ...
-]
+from plain.oauth.urls import OAuthRouter
+from plain.urls import Router, include
+
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("oauth/", OAuthRouter),
+        # ...
+    ]
 ```
 
 Then run migrations:
 
 ```sh
-python manage.py migrate plain.oauth
+plain migrate plain.oauth
 ```
 
 Create a new OAuth provider ([or copy one from our examples](https://github.com/forgepackages/plain-oauth/tree/master/provider_examples)):
@@ -56,12 +71,12 @@ import requests
 from plain.oauth.providers import OAuthProvider, OAuthToken, OAuthUser
 
 
-class ExampleOAuthProvider(OAuthProvider):
-    authorization_url = "https://example.com/login/oauth/authorize"
+class GitHubOAuthProvider(OAuthProvider):
+    authorization_url = "https://github.com/login/oauth/authorize"
 
     def get_oauth_token(self, *, code, request):
         response = requests.post(
-            "https://example.com/login/oauth/token",
+            "https://github.com/login/oauth/access_token",
             headers={
                 "Accept": "application/json",
             },
@@ -79,7 +94,7 @@ class ExampleOAuthProvider(OAuthProvider):
 
     def get_oauth_user(self, *, oauth_token):
         response = requests.get(
-            "https://example.com/api/user",
+            "https://api.github.com/user",
             headers={
                 "Accept": "application/json",
                 "Authorization": f"token {oauth_token.access_token}",
@@ -136,8 +151,6 @@ your OAuth callback will be something like `https://example.com/oauth/{provider}
 
 That's pretty much it!
 
-## Advanced usage
-
 ### Handling OAuth errors
 
 The most common error you'll run into is if an existing user clicks a login button,
@@ -202,7 +215,7 @@ Hello {{ request.user }}!
 {% endblock %}
 ```
 
-The `get_provider_keys` function can help populate the list of options:
+The [`get_provider_keys`](./providers.py#get_provider_keys) function can help populate the list of options:
 
 ```python
 from plain.oauth.providers import get_provider_keys
@@ -241,12 +254,12 @@ This library comes with a Django system check to ensure you don't _remove_ a pro
 You do need to specify the `--database` for this to run when using the check command by itself:
 
 ```sh
-python manage.py check --database default
+plain check --database default
 ```
 
 ## FAQs
 
-### How is this different from [Django OAuth libraries](https://djangopackages.org/grids/g/oauth/)?
+#### How is this different from [Django OAuth libraries](https://djangopackages.org/grids/g/oauth/)?
 
 The short answer is that _it does less_.
 
@@ -265,7 +278,7 @@ and the implications for doing it one way or another.
 The other popular OAuth libraries have similar issues,
 and I think their _weight_ outweighs their usefulness for 80% of the use cases.
 
-### Why aren't providers included in the library itself?
+#### Why aren't providers included in the library itself?
 
 One thing you'll notice is that we don't have a long list of pre-configured providers in this library.
 Instead, we have some examples (which you can usually just copy, paste, and use) and otherwise encourage you to wire up the provider yourself.
@@ -288,7 +301,7 @@ You don't need to try to run changes through us or wait for an upstream update.
 You're welcome to contribute an example to this repo,
 and there won't be an expectation that it "works perfectly for every use case until the end of time".
 
-### Redirect/callback URL mismatch in local development?
+#### Redirect/callback URL mismatch in local development?
 
 If you're doing local development through a proxy/tunnel like [ngrok](https://ngrok.com/),
 then the callback URL might be automatically built as `http` instead of `https`.
@@ -298,3 +311,22 @@ This is the Django setting you're probably looking for:
 ```python
 HTTPS_PROXY_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
 ```
+
+## Installation
+
+Install the `plain.oauth` package from [PyPI](https://pypi.org/project/plain.oauth/):
+
+```bash
+uv add plain.oauth
+```
+
+After installation, follow the basic setup example in the [Usage](#usage) section above to:
+
+1. Add `plain.oauth` to your `INSTALLED_PACKAGES`
+2. Include the OAuth router in your URLs
+3. Run migrations
+4. Create an OAuth provider class
+5. Configure OAuth settings
+6. Add login buttons to your templates
+
+For a complete working example, see the [Basic setup example](#basic-setup-example) which shows how to set up GitHub OAuth login.

plain/oauth/models.py

@@ -160,7 +160,7 @@ class OAuthConnection(models.Model):
         A system check for ensuring that provider_keys in the database are also present in settings.
 
         Note that the --database flag is required for this to work:
-          python manage.py check --database default
+          plain check --database default
         """
         errors = super().check(**kwargs)
 
@@ -175,7 +175,7 @@ class OAuthConnection(models.Model):
                 cls.objects.values_list("provider_key", flat=True).distinct()
             )
         except (OperationalError, ProgrammingError):
-            # Check runs on manage.py migrate, and the table may not exist yet
+            # Check runs on plain migrate, and the table may not exist yet
             # or it may not be installed on the particular database intentionally
             return errors
 

{plain_oauth-0.24.1.dist-info → plain_oauth-0.24.2.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plain.oauth
-Version: 0.24.1
-Summary: OAuth login and API access for Plain.
+Version: 0.24.2
+Summary: Let users log in with OAuth providers.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
 License-File: LICENSE
@@ -14,7 +14,19 @@ Description-Content-Type: text/markdown
 
 # plain.oauth
 
-Let users log in with OAuth providers.
+**Let users log in with OAuth providers.**
+
+- [Overview](#overview)
+- [Usage](#usage)
+    - [Basic setup example](#basic-setup-example)
+    - [Handling OAuth errors](#handling-oauth-errors)
+    - [Connecting and disconnecting OAuth accounts](#connecting-and-disconnecting-oauth-accounts)
+    - [Using a saved access token](#using-a-saved-access-token)
+    - [Using the Django system check](#using-the-django-system-check)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
 
 [Watch on YouTube (3 mins) →](https://www.youtube.com/watch?v=UxbxBa6AFsU)
 
@@ -31,11 +43,9 @@ There are three OAuth flows that it makes possible:
 
 ## Usage
 
-Install the package from PyPi:
+### Basic setup example
 
-```sh
-pip install plain-oauth
-```
+Here's a complete example showing how to set up OAuth login with GitHub:
 
 Add `plain.oauth` to your `INSTALLED_PACKAGES` in `settings.py`:
 
@@ -46,19 +56,24 @@ INSTALLED_PACKAGES = [
 ]
 ```
 
-In your `urls.py`, include `plain.oauth.urls`:
+In your `urls.py`, include the [`OAuthRouter`](./urls.py#OAuthRouter):
 
 ```python
-urlpatterns = [
-    path("oauth/", include("plain.oauth.urls")),
-    ...
-]
+from plain.oauth.urls import OAuthRouter
+from plain.urls import Router, include
+
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("oauth/", OAuthRouter),
+        # ...
+    ]
 ```
 
 Then run migrations:
 
 ```sh
-python manage.py migrate plain.oauth
+plain migrate plain.oauth
 ```
 
 Create a new OAuth provider ([or copy one from our examples](https://github.com/forgepackages/plain-oauth/tree/master/provider_examples)):
@@ -70,12 +85,12 @@ import requests
 from plain.oauth.providers import OAuthProvider, OAuthToken, OAuthUser
 
 
-class ExampleOAuthProvider(OAuthProvider):
-    authorization_url = "https://example.com/login/oauth/authorize"
+class GitHubOAuthProvider(OAuthProvider):
+    authorization_url = "https://github.com/login/oauth/authorize"
 
     def get_oauth_token(self, *, code, request):
         response = requests.post(
-            "https://example.com/login/oauth/token",
+            "https://github.com/login/oauth/access_token",
             headers={
                 "Accept": "application/json",
             },
@@ -93,7 +108,7 @@ class ExampleOAuthProvider(OAuthProvider):
 
     def get_oauth_user(self, *, oauth_token):
         response = requests.get(
-            "https://example.com/api/user",
+            "https://api.github.com/user",
             headers={
                 "Accept": "application/json",
                 "Authorization": f"token {oauth_token.access_token}",
@@ -150,8 +165,6 @@ your OAuth callback will be something like `https://example.com/oauth/{provider}
 
 That's pretty much it!
 
-## Advanced usage
-
 ### Handling OAuth errors
 
 The most common error you'll run into is if an existing user clicks a login button,
@@ -216,7 +229,7 @@ Hello {{ request.user }}!
 {% endblock %}
 ```
 
-The `get_provider_keys` function can help populate the list of options:
+The [`get_provider_keys`](./providers.py#get_provider_keys) function can help populate the list of options:
 
 ```python
 from plain.oauth.providers import get_provider_keys
@@ -255,12 +268,12 @@ This library comes with a Django system check to ensure you don't _remove_ a pro
 You do need to specify the `--database` for this to run when using the check command by itself:
 
 ```sh
-python manage.py check --database default
+plain check --database default
 ```
 
 ## FAQs
 
-### How is this different from [Django OAuth libraries](https://djangopackages.org/grids/g/oauth/)?
+#### How is this different from [Django OAuth libraries](https://djangopackages.org/grids/g/oauth/)?
 
 The short answer is that _it does less_.
 
@@ -279,7 +292,7 @@ and the implications for doing it one way or another.
 The other popular OAuth libraries have similar issues,
 and I think their _weight_ outweighs their usefulness for 80% of the use cases.
 
-### Why aren't providers included in the library itself?
+#### Why aren't providers included in the library itself?
 
 One thing you'll notice is that we don't have a long list of pre-configured providers in this library.
 Instead, we have some examples (which you can usually just copy, paste, and use) and otherwise encourage you to wire up the provider yourself.
@@ -302,7 +315,7 @@ You don't need to try to run changes through us or wait for an upstream update.
 You're welcome to contribute an example to this repo,
 and there won't be an expectation that it "works perfectly for every use case until the end of time".
 
-### Redirect/callback URL mismatch in local development?
+#### Redirect/callback URL mismatch in local development?
 
 If you're doing local development through a proxy/tunnel like [ngrok](https://ngrok.com/),
 then the callback URL might be automatically built as `http` instead of `https`.
@@ -312,3 +325,22 @@ This is the Django setting you're probably looking for:
 ```python
 HTTPS_PROXY_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
 ```
+
+## Installation
+
+Install the `plain.oauth` package from [PyPI](https://pypi.org/project/plain.oauth/):
+
+```bash
+uv add plain.oauth
+```
+
+After installation, follow the basic setup example in the [Usage](#usage) section above to:
+
+1. Add `plain.oauth` to your `INSTALLED_PACKAGES`
+2. Include the OAuth router in your URLs
+3. Run migrations
+4. Create an OAuth provider class
+5. Configure OAuth settings
+6. Add login buttons to your templates
+
+For a complete working example, see the [Basic setup example](#basic-setup-example) which shows how to set up GitHub OAuth login.

{plain_oauth-0.24.1.dist-info → plain_oauth-0.24.2.dist-info}/RECORD

@@ -1,18 +1,18 @@
-plain/oauth/CHANGELOG.md,sha256=1UEW4Nz9VxdFVC_Na9WbiypJpK5ejJaqbTCR8vLMimE,1400
-plain/oauth/README.md,sha256=N8getAUUhLX6P4mg-5P0V41gk5EKBGb8v904OfP2Z9E,9961
+plain/oauth/CHANGELOG.md,sha256=t9_ijwUrVBdQq1kwWZflh-91sqJccWrcc8e-Ovg8Oec,1986
+plain/oauth/README.md,sha256=SUIbWnuka9mAJFOPTkrtW2KmKLAOYn5vMpT1VesPWPk,11156
 plain/oauth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/oauth/admin.py,sha256=9DAku8ubV6a_ByFer6UBS0G1cC_gGGHiI_iRP0b78nE,1310
 plain/oauth/config.py,sha256=0Q4IILBKQbIaxqeL9WRTH5Cka-BO3c3SOj1AdQIAJgc,167
 plain/oauth/default_settings.py,sha256=dlN1J9vSOjjxPNLp-0qe-cLTqwM4E69ZAx_8lpxMhaM,28
 plain/oauth/exceptions.py,sha256=yoZsq8XgzstuwbE2ihoet0nzpw_sVZgDrwUauh6hhUs,546
-plain/oauth/models.py,sha256=T8VqqxeYGC4xKRVzUKAnc0OU3GN0otDAShDS6CPJhJs,6754
+plain/oauth/models.py,sha256=iCh_cyi2ajBN2IO8xBIHLyAyjk4OMgB4ziwDQymvwJo,6739
 plain/oauth/providers.py,sha256=YDftJUMyyfXgsDCkyTNxGwrbwXAowL0Hg6KrwrAN5S0,7793
 plain/oauth/urls.py,sha256=FYzpQwhvZdcat8n3f7RyA-1Q21finKb8JEyakSOjXXg,696
 plain/oauth/views.py,sha256=J2NCa37YediBTi82CfRlmsb45hFT6gWN6zMaFHhsDMM,2410
 plain/oauth/migrations/0001_initial.py,sha256=0NjfF7F3szhUXkpK3JvN10Xkat1QR-VvnX6Oed9iFmo,1940
 plain/oauth/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/oauth/templates/oauth/callback.html,sha256=4CJG0oAN0xYjw2IPkjaL7B4hwlf9um9LI4CTu50E-yE,173
-plain_oauth-0.24.1.dist-info/METADATA,sha256=PhCCDkhGZDc4_WZSFc2uSVhDsU5E95AhYYeiK5ru6Ho,10365
-plain_oauth-0.24.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain_oauth-0.24.1.dist-info/licenses/LICENSE,sha256=cvKM3OlqHx3ijD6e34zsSUkPvzl-ya3Dd63A6EHL94U,1500
-plain_oauth-0.24.1.dist-info/RECORD,,
+plain_oauth-0.24.2.dist-info/METADATA,sha256=4wEMvZsEaJXj9V8-FnSVQt7dGhLExWZFKjhw0O1ObII,11561
+plain_oauth-0.24.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_oauth-0.24.2.dist-info/licenses/LICENSE,sha256=cvKM3OlqHx3ijD6e34zsSUkPvzl-ya3Dd63A6EHL94U,1500
+plain_oauth-0.24.2.dist-info/RECORD,,