Fluff updates. (#1177)

Tried out copilot to look at docs and tests. A few suggestions on making things more consistent - but nothing really worth the time spent.

Author: jwag956

CHANGES.rst

@@ -492,7 +492,7 @@ Backwards Compatibility Concerns
 
 - To align with the W3C WebAuthn Level2 and 3 spec - transports are now part of the registration response.
   This has been changed BOTH in the server code (using webauthn data structures) as well as the sample
-  javascript code. If an application has their own javascript front end code - it might need to be changed.
+  JavaScript code. If an application has their own JavaScript front end code - it might need to be changed.
 - The tf_validity feature :py:data:`SECURITY_TWO_FACTOR_ALWAYS_VALIDATE` used to set a cookie if the request was
   form based, and return the token as part of a JSON response. Now, this feature is ONLY cookie based and the token
   is no longer returned as part of any response.

docs/api.rst

@@ -178,7 +178,7 @@ Utils
 
 .. py:class:: OauthCbType[oauth: OAuth, token: t.Any]
 
-    This callback is called when the oauth
+    This callback is called when the OAuth
     redirect happens. It must take the response from the provider and return
     a tuple of <user_model_field_name, value> - which will be used
     to look up the user in the datastore.

docs/configuration.rst

@@ -148,7 +148,7 @@ These configuration keys are used globally across all features.
 
 .. py:data:: SECURITY_REDIRECT_BEHAVIOR
 
-    Passwordless login, confirmation, reset password, unified signin, change_email, and oauth signin
+    Passwordless login, confirmation, reset password, unified signin, change_email, and OAuth signin
     have GET endpoints that validate the passed token and redirect to an action form.
     For Single-Page-Applications style UIs which need to control their own internal URL routing these redirects
     need to not contain forms, but contain relevant information as query parameters.

docs/features.rst

@@ -284,7 +284,7 @@ registered. They can be completely disabled or their names can be changed.
 Run ``flask --help`` and look for users and roles.
 
 
-Social/Oauth Authentication
+Social/OAuth Authentication
 ----------------------------
 Flask-Security provides a thin layer which integrates `authlib`_ with Flask-Security
 views and features (such as two-factor authentication). Flask-Security is shipped

docs/index.rst

@@ -22,7 +22,7 @@ Flask application. They include:
 6. Username management (configuration, recovery, change) (optional)
 7. Two-factor authentication via email, SMS, authenticator (optional)
 8. WebAuthn Support (optional)
-9. 'social'/Oauth for authentication (e.g. google, github, ..) (optional)
+9. 'social'/OAuth for authentication (e.g. google, github, ..) (optional)
 10. Change email (optional)
 11. Login tracking (optional)
 12. JSON/Ajax Support

docs/models.rst

@@ -40,7 +40,7 @@ The provided models are versioned since they represent actual DB models, and any
 changes require a schema migration (and perhaps a data migration). Applications
 must specifically import the version they want (and handle any required migration).
 
-There are 2 available models - one when using Flask-SQLAlchemy and one when
+There are two available models - one when using Flask-SQLAlchemy and one when
 using 'raw' sqlalchemy or Flask-SQLAlchemy-Lite.
 
 .. note::
@@ -49,7 +49,8 @@ using 'raw' sqlalchemy or Flask-SQLAlchemy-Lite.
 
 Flask-SQLAlchemy
 ^^^^^^^^^^^^^^^^
-Your application code should import just the required version e.g.::
+Your application code should import just the required version e.g.:
+.. code-block:: python
 
     from flask_security.models import fsqla_v3 as fsqla
     from flask_sqlalchemy import SQLAlchemy
@@ -71,7 +72,9 @@ DB instance. This is only needed if you use the packaged models.
 
 Flask-SQLAlchemy-Lite
 ^^^^^^^^^^^^^^^^^^^^^
-Your application code should import just the required version e.g.::
+Your application code should import just the required version e.g.:
+
+.. code-block:: python
 
     from flask_security.models import sqla as sqla
     from flask_sqlalchemy_lite import SQLAlchemy
@@ -222,7 +225,12 @@ Flask-Security must be able to locate a User record based on a credential id.
     It is important that you maintain data consistency when deleting WebAuthn
     records or users.
 
-The 'WebAuthn' model requires the following fields:
+The `User` model needs the following additional field:
+
+* ``fs_webauthn_user_handle`` (string, 64 bytes, unique).
+  This is used as the `PublicKeyCredentialUserEntity` `id` value.
+
+The `WebAuthn` model requires the following fields:
 
 * ``id`` (primary key)
 * ``credential_id`` (binary, 1024 bytes, indexed, non-nullable, unique)
@@ -239,58 +247,66 @@ The 'WebAuthn' model requires the following fields:
 There needs to be a bi-directional relationship between the WebAuthn record and
 the User record (since we need to look up the ``User`` based on a WebAuthn ``credential_id``.
 
-**For SQLAlchemy**::
+**For SQLAlchemy**:
 
-    Add the following to the WebAuthn model (assuming your primary key is named ``id``):
+    - Add the following to the WebAuthn model (assuming your primary key is named ``id``):
 
-        @declared_attr
-        def user_id(cls) -> Mapped[int]:
-            return mapped_column(
-                ForeignKey("user.id", ondelete="CASCADE")
-            )
+        .. code-block:: python
 
-    Add the following to the User model:
+            @declared_attr
+            def user_id(cls) -> Mapped[int]:
+                return mapped_column(
+                    ForeignKey("user.id", ondelete="CASCADE")
+                )
 
-        @declared_attr
-        def webauthn(cls):
-            return relationship(
-                "WebAuthn", back_populates="user", cascade="all, delete"
-            )
+    - Add the following to the User model:
 
-**For mongoengine**::
+        .. code-block:: python
 
-    Add the following to the WebAuthn model:
+            @declared_attr
+            def webauthn(cls):
+                return relationship(
+                    "WebAuthn", back_populates="user", cascade="all, delete"
+                )
+
+**For mongoengine**:
 
-        user = ReferenceField("User")
-        def get_user_mapping(self) -> dict[str, str]:
-            """Return the mapping from webauthn back to User"""
-            return dict(id=self.user.id)
+    - Add the following to the WebAuthn model:
 
-    Add the following to the User model:
+        .. code-block:: python
 
-        webauthn = ListField(ReferenceField(WebAuthn, reverse_delete_rule=PULL), default=[])
+            user = ReferenceField("User")
+            def get_user_mapping(self) -> dict[str, str]:
+                """Return the mapping from webauthn back to User"""
+                return dict(id=self.user.id)
 
-    To make sure all WebAuthn objects are deleted if the User is deleted:
+    - Add the following to the User model:
 
-        User.register_delete_rule(WebAuthn, "user", CASCADE)
+        .. code-block:: python
 
+            webauthn = ListField(ReferenceField(WebAuthn, reverse_delete_rule=PULL), default=[])
 
-**For peewee**::
+    - To make sure all WebAuthn objects are deleted if the User is deleted:
+
+        .. code-block:: python
+
+            User.register_delete_rule(WebAuthn, "user", CASCADE)
+
+
+**For peewee**:
 
     Add the following to the WebAuthn model:
 
-        user = ForeignKeyField(User, backref="webauthn")
+        .. code-block:: python
+
+            user = ForeignKeyField(User, backref="webauthn")
 
     This will add a column called ``user_id`` that references the User model's
     ``id`` primary key field. It will also create a virtual column ``webauthn``
     as part of the User model. Note that the default Peewee datastore implementation
     calls ``delete_instance(recursive=True)`` which correctly deals with ensuring
     that WebAuthn records get deleted if a User is deleted.
 
-The `User` model needs the following additional fields:
-
-* ``fs_webauthn_user_handle`` (string, 64 bytes, unique).
-  This is used as the `PublicKeyCredentialUserEntity` `id` value.
 
 Recovery Codes
 ^^^^^^^^^^^^^^^

docs/patterns.rst

@@ -44,7 +44,7 @@ of handling all authorization errors. A simple way to do this is to use a specia
 class that you can raise either in response to Flask-Security authorization failures, or in your
 own code. Then use Flask's ``errorhandler`` to catch that exception and create the appropriate API response::
 
-    Class MyForbiddenException(Exception):
+    class MyForbiddenException(Exception):
         def __init__(self, msg='Not permitted with your privileges', status=http.HTTPStatus.FORBIDDEN):
             self.info = {'status': status, 'msgs': [msg]}
 
@@ -262,7 +262,7 @@ with actually retrieving and using a CSRF token. There are 2 normal ways to do t
 
  * Have the csrf-token available via a JSON GET request that can be attached as a
    header in every mutating request.
- * Have a cookie that can be read via javascript whose value is the csrf-token that
+ * Have a cookie that can be read via JavaScript whose value is the csrf-token that
    can be attached as a header in every mutating request.
 
 Flask-Security supports both solutions.
@@ -337,7 +337,7 @@ Using a Cookie
 --------------
 You can instruct Flask-Security to send a cookie that contains the csrf token.
 The cookie will be set on a call to ``GET /login`` or ``GET /us-signin`` - as well as after a successful authentication.
-This can be very convenient since various javascript AJAX packages are pre-configured to extract the contents of a cookie
+This can be very convenient since various JavaScript AJAX packages are pre-configured to extract the contents of a cookie
 and send it on every mutating request as an HTTP header. `axios`_ for example has a default configuration
 that it will look for a cookie named ``XSRF-TOKEN`` and will send the contents of that back
 in an HTTP header called ``X-XSRF-Token``. This means that if you use that package you don't need to make

docs/spa.rst

@@ -1,10 +1,10 @@
 Working with Single Page Applications
 ======================================
-`Single Page Applications (spa)`_ are a popular model for both separating
+`Single Page Applications (SPAs)`_ are a popular model for both separating
 user interface from application/backend code as well as providing a responsive
-user experience. Angular and Vue are popular Javascript frameworks for writing SPAs.
+user experience. Angular and Vue are popular JavaScript frameworks for writing SPAs.
 An added benefit is that the UI can be developed completely independently (in a separate repo)
-and take advantage of the latest Javascript packing and bundling technologies that are
+and take advantage of the latest JavaScript packing and bundling technologies that are
 evolving rapidly, and not make the Flask application have to deal with things
 like Flask-Webpack or webassets.
 
@@ -26,7 +26,9 @@ For the purposes of this application note - this implies:
 
 Configuration
 ~~~~~~~~~~~~~
-An example configuration::
+An example configuration:
+
+.. code-block:: python
 
     # no forms so no concept of flashing
     SECURITY_FLASH_MESSAGES = False
@@ -77,7 +79,9 @@ An example configuration::
     security.unauthz_handler(<your unauth handler>)
 
 When in development mode, the Flask application will run by default on port 5000.
-The UI might want to run on port 8080. In order to test redirects you need to set::
+The UI might want to run on port 8080. In order to test redirects you need to set:
+
+.. code-block:: python
 
     SECURITY_REDIRECT_HOST = 'localhost:8080'
 
@@ -104,15 +108,15 @@ standard security headers such as:
     * ``X-XSS-Protection``
     * ``Referrer policy``
 
-There are a lot of different ways to host a SPA as the javascript part itself is quit easily hosted from any static
+There are a lot of different ways to host a SPA as the JavaScript part itself is quit easily hosted from any static
 webserver. A couple of deployment options and their configurations will be describer here.
 
 Nginx
 ~~~~~
 When serving a SPA from a Nginx webserver the Flask backend, with Flask-Security, will probably be served via
-Nginx's reverse proxy feature. The javascript is served from Nginx itself and all calls to a certain path will be routed
+Nginx's reverse proxy feature. The JavaScript is served from Nginx itself and all calls to a certain path will be routed
 to the reversed proxy. The example below routes all http requests to *"/api/"* to the Flask backend and handles all other
-requests directly from javascript. This has a couple of benefits as all the requests happen within the same domain so you
+requests directly from JavaScript. This has a couple of benefits as all the requests happen within the same domain so you
 don't have to worry about `CORS`_ problems::
 
     server {
@@ -164,11 +168,13 @@ Most Flask apps can be deployed to Amazon's lambda gateway without much hassle b
 You'll get automatic horizontal scaling, seamless upgrades, automatic SSL certificate renewal and a very cheap way of
 hosting a backend without being responsible for any infrastructure. Depending on how you design your app you could
 choose to host your backend from an api specific domain: e.g. *api.example.com*. When your SPA deployment structure is
-capable of routing the AJAX/XHR request from your javascript app to the separate backend; use it. When you want to use
+capable of routing the AJAX/XHR request from your JavaScript app to the separate backend; use it. When you want to use
 the backend from another e.g. *www.example.com* you have some deal with some `CORS`_ setup as your browser will block
 cross-domain POST requests. There is a Flask package for that: `Flask-CORS`_.
 
-The setup of CORS is simple::
+The setup of CORS is simple:
+
+.. code-block:: python
 
     CORS(
         app,
@@ -179,7 +185,7 @@ The setup of CORS is simple::
         expose_headers="Authorization,Content-Type,Authentication-Token,XSRF-TOKEN",
     )
 
-You can then host your javascript app from an S3 bucket, with or without Cloudfront, GH-pages or from any static webserver.
+You can then host your JavaScript app from an S3 bucket, with or without Cloudfront, GH-pages or from any static webserver.
 
 Some background material:
 
@@ -188,7 +194,7 @@ Some background material:
     * `Flask-Talisman`_ - useful if serving everything from your Flask application - also
       useful as a good list of things to consider.
 
-.. _Single Page Applications (spa): https://en.wikipedia.org/wiki/Single-page_application
+.. _Single Page Applications (SPAs): https://en.wikipedia.org/wiki/Single-page_application
 .. _Nginx: https://www.nginx.com/
 .. _S3: https://www.savjee.be/2018/05/Content-security-policy-and-aws-s3-cloudfront/
 .. _Flask-Talisman: https://pypi.org/project/flask-talisman/

docs/two_factor_configurations.rst

@@ -31,7 +31,7 @@ Two-factor Application
 The following code sample illustrates how to get started as quickly as
 possible using SQLAlchemy:
 
-::
+.. code-block:: python
 
     import os
     from flask import Flask, current_app, render_template_string
@@ -133,7 +133,9 @@ You need to install additional packages::
 
     pip install phonenumberslite twilio
 
-And set additional configuration variables::
+And set additional configuration variables:
+
+.. code-block:: python
 
     app.config["SECURITY_TWO_FACTOR_ENABLED_METHODS"] = ['email',
       'authenticator', 'sms']
@@ -206,6 +208,6 @@ Fine-Grained Control of Two-Factor
 +++++++++++++++++++++++++++++++++++
 The decision whether to require a second factor after primary authentication is made in :py:meth:`.UserMixin.check_tf_required`.
 The default implementation returns True if :py:data:`SECURITY_TWO_FACTOR_REQUIRED` is set OR the user has a two-factor method already setup AND
-and recent two-factor authentication isn't 'valid' (see above).
+recent two-factor authentication isn't 'valid' (see above).
 
 This method can be overridden in the applications User class. A common use case might be to require two-factor for any user with the 'admin' role.

docs/webauthn.rst

@@ -40,9 +40,9 @@ there is at least one second-factor authentication method setup that is NOT plat
 Flask-Security requires that when registering a WebAuthn key, the user must specify whether the key
 will be used for first/primary authentication or for multi-factor/second authentication.
 
-It should be noted the the current spec REQUIRES javascript to communicate from your front-end to the browser.
+It should be noted the the current spec REQUIRES JavaScript to communicate from your front-end to the browser.
 Flask-Security ships with the basic required JS (static/{webauthn.js,base64.js}).
-An application should be able to simply wire those into their templates or javascript.
+An application should be able to simply wire those into their templates or JavaScript.
 
 
 Configuration