Metadata-Version: 2.4
Name: gs-django-authplus
Version: 1.0.0
Summary: Reusable Django application that provides structured permission grouping
Author-email: Sandi Šaban <sandi.saban@gmail.com>
License: Copyright (c) 2025 Sandi Šaban
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of
        this software and associated documentation files (the “Software”), to deal in
        the Software without restriction, including without limitation the rights to
        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
        of the Software, and to permit persons to whom the Software is furnished to do
        so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: AUTHORS.md
License-File: LICENSE
Keywords: authentication,django,permissions
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: django>=4.1
Description-Content-Type: text/markdown

# gs-django-authplus

Reusable Django application `authplus` provides structured permission grouping.

When having a lot of defined models, managing permissions for users and groups can be quite a challenge. This application allows organizing permissions into permission packages, just like users are organized into groups. This makes it more natural than using groups for everything.

Organizing user groups into subgroups is also provided. User that is a member of a group is also member of all parent groups of that group.

## Installation

If using Astral's uv for virtual environment and project dependencies:

```
$ uv add gs-django-authplus
```

Or, with pip in your virtual environment:

```
$ pip install gs-django-authplus
```


## Quick setup

Add application to `settings.py`:

```
INSTALLED_APPS = [
    ...
    "authplus",
]
```


## Models

### PermissionsPackage

Permissions package is a generic way to categorize permissions.

Permissions packages are used for easier applying a bunch of related permissions to a user or user groups. This can also be achieved using `django.contrib.auth.models.Group`, but it seems more natural to separate permission groups and user groups.

`PermissionPackage` is based on abstract class `AbstractPermissionsPackage` to allow easier extension and customizations.


### UserGroup

User group is a generic way to categorize users.

User groups have a hierarchical structure so each group can have several subgroups. User that is a member of a group is also member of all parent groups of that group.

Permissions for user groups can be granted using individual permissions or permissions packages.

`UserGroup` is based on abstract class `AbstractUserGroup` to allow easier extension and customizations.


### AbstractUserPlus

Abstract class for project user which inherits from class `django.contrib.auth.models.AbstractUser` and allows using `PermissionsPackage` and `UserGroup` for defining permissions granted to user.


### User

Project user based on `AbstractUserPlus`.


## Translations

Package comes with translations to:

- Croatian (hr)

To create translations for new language:

```bash
$ git clone git@gitlab.com:gs-django-authplus.git
$ cd gs-django-authplus
$ uv sync
$ uv run django-admin makemessages -l language_code
# edit django.po file for the new language
$ make compilemessages
# build will also automatically compile messages
$ uv build
```
