Dev

.flake8

@@ -0,0 +1,2 @@
+[flake8]
+per-file-ignores = __init__.py:F401

README.md

@@ -22,14 +22,14 @@
 
 Associate users with roles and permissions
 
-## Installation
+## Getting Started
+
+Install the package using pip:
 
 ```bash
 pip install masonite-permission
 ```
 
-## Configuration
-
 Add PermissionProvider to your project in `config/providers.py`:
 
 ```python
@@ -46,19 +46,25 @@ PROVIDERS = [
 ]
 ```
 
-Then you can publish the package resources (if needed) by doing:
+Publish the package configuration files.
 
 ```bash
 python craft package:publish masonite-permission
 ```
 
-Finally, extend `User` model class with `HasRoles`.
+This will add migrations and other `masonite-permission` related configuration to your project. Run your migrations to create the related database tables.
+
+```bash
+python craft migrate
+```
+
+Now, extend `User` model class with `HasRoles` mixin.
 
 ```python
 from masoniteorm.models import Model
 from masoniteorm.scopes import SoftDeletesMixin
 from masonite.authentication import Authenticates
-from masonite_permission.models.has_roles import HasRoles
+from masonite_permission.mixins import HasRoles
 
 class User(Model, SoftDeletesMixin, Authenticates, HasRoles):
     """User Model."""
@@ -70,94 +76,187 @@ class User(Model, SoftDeletesMixin, Authenticates, HasRoles):
 
 ## Usage
 
-**Role**
+#### Working with Role
 
-Methods that can be used in role model object:
+<details>
+<summary style="font-weight: bolder">Creating Role</summary>
 
 ```python
-""" Creating Role """
+
+""" Creating Role
+    Arguments:
+        name: The name of the role
+        slug: The slug of the role, must be unique
+"""
+from masonite_permission.models import Role
+
 role = Role.create({
-  "name": "Admin",
-  "slug": "admin" # must be unique
+    "name": "Admin",
+    "slug": "admin"
 })
 
-""" collection can be synced """
+```
+
+</details>
+
+<details>
+<summary style="font-weight: bolder">Add permissions into roles</summary>
+
+```python
+""" Add permissions into roles
+    Available Methods:
+        1. sync_permissions: Syncs the permissions with the role
+            arguments: Takes a list of permission ids or permission collection
+        2. attach_permission: Adds a permission to a role
+            arguments: Takes permission model object or permission id
+        3. detach_permission: Removes a permission from the role
+            arguments: Takes permission model object or permission id
+"""
+```
+
+```python
+""" Syncing permissions with role, adds provided permissions and removes all other permissions
+    Arguments:
+        permissions: Takes a list of permission ids or permission collection
+"""
 permission_collection = Permission.all()
+permission_ids = [1, 2, 3, 4, ...]
 
 role.sync_permissions(permission_collection)
-
-""" id will also work """
-permission_ids = [1,2,3,4,5]
+# or
 role.sync_permissions(permission_ids)
+# or
+role.sync_permissions([]) # clears all permissions from role
+```
 
-""" clear related data """
-role.sync_permissions([])
+```python
+""" Attach permission, this will add new permission into role if already not added
+    Arguments:
+        permission: Takes permission model object or permission id
+"""
+permission = Permission.first()
 
+role.attach_permission(permission)
+# or
+role.attach_permission(1)
+```
 
-""" Attach/Detatch Permission """
+```python
+""" Detach permission, this will remove permission from role if already added
+    Arguments:
+        permission: Takes permission model object or permission id
+"""
 permission = Permission.first()
-role.attach_permission(permission) # add permission to role, ignores if permission already exists
-role.detach_permission(permission) # remove permission from role, ignores if permission doesn't exist
 
-""" this can also be done """
-role.attach_permission(1) # passing permission id instead of object, ignores if permission already exists
-role.detatch_permission(1) # passing permission id instead of object, ignores if permission doesn't exist
+role.detach_permission(permission)
+# or
+role.detach_permission(1)
 ```
 
-**Permission**
+</details>
 
-Methods that can be used in permission model object:
+<br/>
+
+#### Working with Permission
+
+<details>
+<summary style="font-weight: bolder">Creating Permission</summary>
 
 ```python
-""" Creating Permission """
+""" Creating Permission
+    Arguments:
+        name: The name of the permission
+        slug: The slug of the permission, must be unique
+"""
+from masonite_permission.models import Permission
 permission = Permission.create({
   "name": "Create Post",
   "slug": "create-post" # must be unique
 })
+```
 
-""" collection can be synced """
-roles_collection = Role.all()
+</details>
 
-permission.sync_roles(role_collection)
+<details>
+<summary style="font-weight: bold;">Add permissions into roles</summary>
 
-""" id will also work """
-role_ids = [1,2,3,4,5]
+```python
+""" Add permissions into roles
+    Available Methods:
+        1. sync_roles: Syncs the roles with the permission
+            arguments: Takes a list of role ids or role collection
+        2. attach_role: Adds a permission to a role
+            arguments: Takes role model object or role id
+        3. detach_role: Removes a permission from a role
+            arguments: Takes role model object or role id
+"""
+```
+
+```python
+""" Syncing permissions with role, adds provided roles and removes all other roles
+    Arguments:
+        roles: Takes a list of role ids or role collection
+"""
+role_collection = Role.all()
+role_ids = [1, 2, 3, 4, ...]
+
+permission.sync_roles(role_collection)
+# or
 permission.sync_roles(role_ids)
+# or
+permission.sync_roles([]) # clears all role from permission
+```
 
-""" clear related data """
-permissioin.sync_roles([])
+```python
+""" Attach role, this will add new permission into role if already not added
+    Arguments:
+        role: Takes role model object or role id
+"""
+role = Role.first()
 
+permission.attach_role(role)
+# or
+permission.attach_role(1)
+```
 
-""" Attach/Detatch Role """
+```python
+""" Detach role, this will remove permission from role if already added
+    Arguments:
+        role: Takes role model object or role id
+"""
 role = Role.first()
-permission.attach_role(role) # add role to permission, ignores if role already exists
-permission.detach_role(role) # remove role from permission, ignores if role doesn't exist
 
-""" this can also be done """
-permission.attach_role(1) # passing role id instead of object, ignores if role already exists
-permission.detatch_role(1) # passing role id instead of object, ignores if role doesn't exist
+permission.detach_role(role)
+# or
+permission.detach_role(1)
 ```
 
-**User**
+</details>
+<br/>
 
-Methods that can be used in user model object:
+#### Working with User
 
 ```python
 user = User.first()
+```
 
+```python
 # Add/Remove single role
 role = Role.first()
 
 user.assign_role(role) # or you can pass role id
-user.remove_role(role) # or you can pass role id
+user.revoke_role(role) # or you can pass role id
+```
 
-# if you want to add multiple roles
+```python
+# add/remove multiple roles
 roles = Role.all()
 
 user.sync_roles(roles) # or you can also pass list of ids...
+user.sync_roles([]) # clears all roles from user
+```
 
-# remove all roles from user at once
-user.sync_roles([])
+```python
 
 # check if user has role
 user.has_role("role-1") # returns boolean