[pull] master from Corvia:master

.github/workflows/test.yml

@@ -71,6 +71,7 @@ jobs:
           poetry run pytest
           poetry check
           poetry run pip check
+          poetry run rstfmt --check .
         env:
           DJANGO_DATABASE_PORT: ${{ job.services.postgres.ports[5432] }}
 

README.rst

@@ -1,74 +1,81 @@
-===================
-django-tenant-users
-===================
+#####################
+ django-tenant-users
+#####################
 
 .. image:: https://github.com/Corvia/django-tenant-users/actions/workflows/test.yml/badge.svg
-    :alt: Build Status
-    :target: https://github.com/Corvia/django-tenant-users/actions/workflows/test.yml
+   :alt: Build Status
+   :target: https://github.com/Corvia/django-tenant-users/actions/workflows/test.yml
 
 .. image:: https://codecov.io/gh/Corvia/django-tenant-users/branch/master/graph/badge.svg?token=PRS5HhOYPl
-    :alt: codecov
-    :target: https://codecov.io/gh/Corvia/django-tenant-users
+   :alt: codecov
+   :target: https://codecov.io/gh/Corvia/django-tenant-users
 
 .. image:: https://img.shields.io/pypi/v/django-tenant-users.svg?maxAge=180
-    :alt: PyPI Package
-    :target: https://pypi.org/project/django-tenant-users/
+   :alt: PyPI Package
+   :target: https://pypi.org/project/django-tenant-users/
 
 .. image:: https://img.shields.io/pypi/pyversions/django-tenant-users.svg?maxAge=180
-    :alt: Python Versions
-    :target: https://pypi.org/project/django-tenant-users/
+   :alt: Python Versions
+   :target: https://pypi.org/project/django-tenant-users/
 
 .. image:: https://img.shields.io/pypi/djversions/django-tenant-users.svg?maxAge=180
-    :alt: Django Versions
-    :target: https://pypi.org/project/django-tenant-users/
+   :alt: Django Versions
+   :target: https://pypi.org/project/django-tenant-users/
 
 .. image:: https://img.shields.io/pypi/dm/django-tenant-users.svg?maxAge=180
-    :alt: PyPI Monthly Downloads
-    :target: https://pypi.org/project/django-tenant-users/
+   :alt: PyPI Monthly Downloads
+   :target: https://pypi.org/project/django-tenant-users/
 
+Welcome to ``django-tenant-users``, the sidekick to ``django-tenants``
+that sorts out user management in a multi-tenant Django world. 🚀
 
-Welcome to ``django-tenant-users``, the sidekick to ``django-tenants`` that sorts
-out user management in a multi-tenant Django world. 🚀
+**********
+ Overview
+**********
 
-
-Overview
---------
-
-Building on the solid foundation of ``django-tenants``, ``django-tenant-users``
-focuses on the nuances of user management across tenants. It ensures users can
-authenticate globally but have permissions tailored to each specific tenant. In
-essence, it's the bridge that sorts out the user stuff in a multi-tenant setup.
+Building on the solid foundation of ``django-tenants``,
+``django-tenant-users`` focuses on the nuances of user management across
+tenants. It ensures users can authenticate globally but have permissions
+tailored to each specific tenant. In essence, it's the bridge that sorts
+out the user stuff in a multi-tenant setup.
 
 🔍 **Key Features**:
 
-* **Global Authentication with Tenant-Specific Permissions**: Authenticate once, act
-  based on tenant rules.
-* **Distinct Schema Permissions**: Separate permissions for each tenant a user belongs
-  to.
-* **Seamless Integration**: Works harmoniously with Django's built-in user and
-  permissions frameworks.
-
+-  **Global Authentication with Tenant-Specific Permissions**:
+   Authenticate once, act based on tenant rules.
+-  **Distinct Schema Permissions**: Separate permissions for each tenant
+   a user belongs to.
+-  **Seamless Integration**: Works harmoniously with Django's built-in
+   user and permissions frameworks.
 
-Getting Started
----------------
+*****************
+ Getting Started
+*****************
 
-#. **Installation**: Dive into our `Installation Guide <https://django-tenant-users.rtfd.io/en/latest/pages/installation.html>`_
+#. **Installation**: Dive into our `Installation Guide
+   <https://django-tenant-users.rtfd.io/en/latest/pages/installation.html>`_
    to get ``django-tenant-users`` up and running.
-#. **Usage**: Check out the `Using Guide <https://django-tenant-users.rtfd.io/en/latest/pages/using.html>`_ to see how
-   to make the most of the package.
-#. **Core Concepts**: If you're curious about the ideas driving our design, the
-   `Core Concepts <https://django-tenant-users.rtfd.io/en/latest/pages/concepts.html>`_ page is a great place to start.
 
+#. **Usage**: Check out the `Using Guide
+   <https://django-tenant-users.rtfd.io/en/latest/pages/using.html>`_ to
+   see how to make the most of the package.
 
-Contribute
-----------
+#. **Core Concepts**: If you're curious about the ideas driving our
+   design, the `Core Concepts
+   <https://django-tenant-users.rtfd.io/en/latest/pages/concepts.html>`_
+   page is a great place to start.
 
-We ❤️ contributions! Whether it's a bug report, a new feature, or feedback on the
-project, we'd love to hear from you.
+************
+ Contribute
+************
 
+We ❤️ contributions! Whether it's a bug report, a new feature, or
+feedback on the project, we'd love to hear from you.
 
-License
--------
+*********
+ License
+*********
 
-``django-tenant-users`` is open-source and is licensed under the
-`MIT License <https://raw.githubusercontent.com/Corvia/django-tenant-users/master/LICENSE>`_.
+``django-tenant-users`` is open-source and is licensed under the `MIT
+License
+<https://raw.githubusercontent.com/Corvia/django-tenant-users/master/LICENSE>`_.

docs/index.rst

@@ -1,50 +1,57 @@
-django-tenant-users Documentation
-=================================
+###################################
+ django-tenant-users Documentation
+###################################
 
-``django-tenant-users`` enhances `django-tenants <https://django-tenants.readthedocs.io/>`_ by refining user management in
-multi-tenancy setups. This application ensures users authenticate globally while having
-permissions specific to each tenant.
+``django-tenant-users`` enhances `django-tenants
+<https://django-tenants.readthedocs.io/>`_ by refining user management
+in multi-tenancy setups. This application ensures users authenticate
+globally while having permissions specific to each tenant.
 
+******************************
+ Why use django-tenant-users?
+******************************
 
-Why use django-tenant-users?
-----------------------------
+-  **Global Authentication**:
 
-- **Global Authentication**:
+      Users can authenticate once and gain access to multiple tenants.
+      This provides a streamlined login experience, eliminating the need
+      for multiple account setups.
 
-    Users can authenticate once and gain access to multiple tenants. This provides a
-    streamlined login experience, eliminating the need for multiple account setups.
+-  **Tenant-Specific Permissions**:
 
-- **Tenant-Specific Permissions**:
+      Even though users can authenticate globally, their permissions are
+      tailored to each specific tenant they interact with. This ensures
+      that a user's actions are always in line with the specific rules
+      and roles of each tenant, including specific permissions for the
+      public tenant.
 
-    Even though users can authenticate globally, their permissions are tailored to each
-    specific tenant they interact with. This ensures that a user's actions are always
-    in line with the specific rules and roles of each tenant, including specific
-    permissions for the public tenant.
+-  **Seamless Integration with Django**:
 
-- **Seamless Integration with Django**:
+      ``django-tenant-users`` is designed to gel seamlessly with
+      Django's built-in user and permissions frameworks.
 
-    ``django-tenant-users`` is designed to gel seamlessly with Django's built-in user
-    and permissions frameworks.
+**************
+ Dependencies
+**************
 
+While ``django-tenant-users`` offers specialized user management for
+multi-tenancy, it's built on the solid foundation of ``django-tenants``.
+If you're new to ``django-tenants``, check out their `official
+documentation <https://django-tenants.readthedocs.io/>`_ to get the full
+picture.
 
-Dependencies
-------------
-
-While ``django-tenant-users`` offers specialized user management for multi-tenancy,
-it's built on the solid foundation of ``django-tenants``. If you're new to
-``django-tenants``, check out their `official documentation <https://django-tenants.readthedocs.io/>`_ to get the full picture.
-
-
-Table of Contents
-=================
+###################
+ Table of Contents
+###################
 
 .. toctree::
-    :caption: Contents
-    :maxdepth: 2
-
-    pages/installation
-    pages/using
-    pages/concepts
-    pages/models
-    pages/permissions
-    pages/utilities
+   :caption: Contents
+   :maxdepth: 2
+
+   pages/installation
+   pages/using
+   pages/concepts
+   pages/models
+   pages/permissions
+   pages/utilities
+   pages/conributing

docs/pages/concepts.rst

@@ -1,80 +1,91 @@
-Core Concepts
-=============
+###############
+ Core Concepts
+###############
 
-Understanding the foundational concepts behind ``django-tenant-users`` can help you make
-the most of its features and contribute more effectively to its development.
+Understanding the foundational concepts behind ``django-tenant-users``
+can help you make the most of its features and contribute more
+effectively to its development.
 
+*****************************************
+ TenantBase: Extending Tenant Management
+*****************************************
 
-TenantBase: Extending Tenant Management
----------------------------------------
-
-``TenantBase`` builds upon the ``TenantMixin`` from ``django-tenants`` by adding
-additional features to enhance tenant management of user permissions.
+``TenantBase`` builds upon the ``TenantMixin`` from ``django-tenants``
+by adding additional features to enhance tenant management of user
+permissions.
 
 Key Additions in ``TenantBase``:
 
-- **Tenant Ownership**:
-    Each tenant has an associated owner.
-
-- **User Management Methods**:
-    Functions to add or remove users from a tenant.
-
-- **Ownership Transfer**:
-    Utilities to change the owner of a tenant.
-
-- **Deletion Mechanism**:
-    Instead of outright deletion, tenants are handled to maintain data integrity.
-    Refer to the deletion section for more details.
-
-
-The Need for a Custom User Model
---------------------------------
-
-In multi-tenancy applications, a single user might need to interact with multiple
-tenants. To facilitate this, ``django-tenant-users`` requires a custom user model that
-can associate users with specific tenants while maintaining a global authentication
-mechanism. This design ensures data isolation at the tenant level while providing a
-seamless authentication experience.
-
-
-Custom Authentication Backend: UserBackend
-------------------------------------------
-
-The ``UserBackend`` class in ``django-tenant-users`` is designed to handle user
-authentication across multiple tenants. While it ensures global-level authentication,
-it also maintains tenant-specific data for each user. This backend leverages
-``UserProfile`` for authentication and ``UserTenantPermissions`` for authorization.
-The magic behind this functionality lies in the facade classes, which direct requests to
-the appropriate locations.
-
-
-Handling User and Tenant "Deletion"
------------------------------------
-
-In ``django-tenant-users``, we've adopted a strategy to preserve data integrity
-while still giving the appearance of deletion to end-users. Here's how we manage
-the "deletion" of users and tenants:
-
-- **User "Deletion"**:
-    - Instead of permanently removing a user, we set their ``is_active``,
-      ``is_staff``, and ``is_superuser`` attributes to ``False``.
-    - We disassociate the user from any tenants they own and remove all their
-      permissions across all associated tenants.
-
-- **Tenant "Deletion"**:
-    - A tenant can be "deleted" either manually by a user or automatically if
-      a "deleted" user owns it.
-    - During "deletion", we disassociate all users from the tenant and transfer
-      the ownership of the tenant's schema to the public schema's owner.
-    - The tenant's URL is renamed to a format like ``ownerid-timestamp-originalurl``.
-      This retains some history of the tenant's ownership and also frees up the
-      URL for future use.
-
-- **Unique Schema Naming**:
-    - To avoid conflicts at the database schema level, every tenant's schema name
-      is appended with a timestamp (seconds since the epoch). This ensures each
-      schema is unique.
-
-This approach ensures that while users and tenants might seem "deleted" from an
-operational perspective, the underlying data remains intact, allowing for potential
-recovery or analysis in the future.
+-  **Tenant Ownership**:
+      Each tenant has an associated owner.
+
+-  **User Management Methods**:
+      Functions to add or remove users from a tenant.
+
+-  **Ownership Transfer**:
+      Utilities to change the owner of a tenant.
+
+-  **Deletion Mechanism**:
+      Instead of outright deletion, tenants are handled to maintain data
+      integrity. Refer to the deletion section for more details.
+
+**********************************
+ The Need for a Custom User Model
+**********************************
+
+In multi-tenancy applications, a single user might need to interact with
+multiple tenants. To facilitate this, ``django-tenant-users`` requires a
+custom user model that can associate users with specific tenants while
+maintaining a global authentication mechanism. This design ensures data
+isolation at the tenant level while providing a seamless authentication
+experience.
+
+********************************************
+ Custom Authentication Backend: UserBackend
+********************************************
+
+The ``UserBackend`` class in ``django-tenant-users`` is designed to
+handle user authentication across multiple tenants. While it ensures
+global-level authentication, it also maintains tenant-specific data for
+each user. This backend leverages ``UserProfile`` for authentication and
+``UserTenantPermissions`` for authorization. The magic behind this
+functionality lies in the facade classes, which direct requests to the
+appropriate locations.
+
+*************************************
+ Handling User and Tenant "Deletion"
+*************************************
+
+In ``django-tenant-users``, we've adopted a strategy to preserve data
+integrity while still giving the appearance of deletion to end-users.
+Here's how we manage the "deletion" of users and tenants:
+
+-  **User "Deletion"**:
+      -  Instead of permanently removing a user, we set their
+         ``is_active``, ``is_staff``, and ``is_superuser`` attributes to
+         ``False``.
+
+      -  We disassociate the user from any tenants they own and remove
+         all their permissions across all associated tenants.
+
+-  **Tenant "Deletion"**:
+      -  A tenant can be "deleted" either manually by a user or
+         automatically if a "deleted" user owns it.
+
+      -  During "deletion", we disassociate all users from the tenant
+         and transfer the ownership of the tenant's schema to the public
+         schema's owner.
+
+      -  The tenant's URL is renamed to a format like
+         ``ownerid-timestamp-originalurl``. This retains some history of
+         the tenant's ownership and also frees up the URL for future
+         use.
+
+-  **Unique Schema Naming**:
+      -  To avoid conflicts at the database schema level, every tenant's
+         schema name is appended with a timestamp (seconds since the
+         epoch). This ensures each schema is unique.
+
+This approach ensures that while users and tenants might seem "deleted"
+from an operational perspective, the underlying data remains intact,
+allowing for potential recovery or analysis in the future.