{"id":23537504,"url":"https://github.com/py-package/masonite-permission","last_synced_at":"2025-08-03T10:07:30.557Z","repository":{"id":38079856,"uuid":"470087755","full_name":"py-package/masonite-permission","owner":"py-package","description":"Associate users with roles and permissions","archived":false,"fork":false,"pushed_at":"2024-02-05T16:50:35.000Z","size":207,"stargazers_count":10,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-23T14:14:40.047Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/py-package.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":null,"patreon":"yubarajshrestha","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-03-15T09:27:32.000Z","updated_at":"2024-08-22T12:40:09.000Z","dependencies_parsed_at":"2023-01-31T00:31:05.059Z","dependency_job_id":"fbdc387f-f66b-4659-a0f0-998664987609","html_url":"https://github.com/py-package/masonite-permission","commit_stats":null,"previous_names":["yubarajshrestha/masonite-permission"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/py-package%2Fmasonite-permission","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/py-package%2Fmasonite-permission/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/py-package%2Fmasonite-permission/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/py-package%2Fmasonite-permission/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/py-package","download_url":"https://codeload.github.com/py-package/masonite-permission/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250447979,"owners_count":21432165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-26T03:16:11.409Z","updated_at":"2025-04-23T14:14:40.897Z","avatar_url":"https://github.com/py-package.png","language":"Python","funding_links":["https://patreon.com/yubarajshrestha"],"categories":[],"sub_categories":[],"readme":"# Masonite Permission\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://banners.beyondco.de/Masonite%20Permission.png?theme=light\u0026packageManager=pip+install\u0026packageName=masonite-permission\u0026pattern=charlieBrown\u0026style=style_2\u0026description=Associate+users+with+roles+and+permissions.\u0026md=1\u0026showWatermark=1\u0026fontSize=100px\u0026images=adjustments\u0026widths=50\u0026heights=50\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \n  \u003cimg alt=\"GitHub Workflow Status\" src=\"https://github.com/py-package/masonite-permission/actions/workflows/pythonapp.yml/badge.svg\"\u003e\n\n  \u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/masonite-permission\"\u003e\n  \u003cimg alt=\"issues\" src=\"https://img.shields.io/github/issues/py-package/masonite-permission\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.7+-blue.svg\" alt=\"Python Version\"\u003e\n  \u003cimg alt=\"GitHub release (latest by date including pre-releases)\" src=\"https://img.shields.io/github/v/release/py-package/masonite-permission\"\u003e\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/py-package/masonite-permission\"\u003e\n  \u003ca href=\"https://github.com/py-package/masonite-permission/stargazers\"\u003e\u003cimg alt=\"star\" src=\"https://img.shields.io/github/stars/py-package/masonite-permission\" /\u003e\u003c/a\u003e\n  \u003cimg alt=\"downloads\" src=\"https://img.shields.io/pypi/dm/masonite-permission?style=flat\" /\u003e\n  \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Introduction\n\nAssociate users with roles and permissions to control access to your application.\n\n## Getting Started\n\nInstall the package using pip:\n\n```bash\npip install masonite-permission\n```\n\nAdd PermissionProvider to your project in `config/providers.py`:\n\n```python\n# config/providers.py\n# ...\nfrom masonite_permission import PermissionProvider\n\n# ...\nPROVIDERS = [\n    # ...\n    # Third Party Providers\n    PermissionProvider,\n    # ...\n]\n```\n\nPublish the package configuration files.\n\n```bash\npython craft package:publish masonite-permission\n```\n\nThis will add migrations and other `masonite-permission` related configuration to your project. Run your migrations to create the related database tables.\n\n```bash\npython craft migrate\n```\n\nNow, extend `User` model class with `HasRoles` mixin.\n\n```python\nfrom masoniteorm.models import Model\nfrom masoniteorm.scopes import SoftDeletesMixin\nfrom masonite.authentication import Authenticates\nfrom src.masonite_permission.mixins import (HasPermissions, HasRoles)\n\nclass User(Model, SoftDeletesMixin, Authenticates, HasRoles, HasPermissions):\n    \"\"\"User Model.\"\"\"\n\n    __fillable__ = [\"name\", \"email\", \"password\"]\n    __hidden__ = [\"password\"]\n    __auth__ = \"email\"\n```\n\n## Usage\n\n#### Working with Role\n\n**Creating Roles**\n\n```python\n\n\"\"\" Creating Role\n    Arguments:\n        name: The name of the role\n        slug: The slug of the role, must be unique\n\"\"\"\nfrom masonite_permission.models import Role\n\nrole = Role.create({\n    \"name\": \"Admin\",\n    \"slug\": \"admin\"\n})\n\n```\n\n**Add permissions into roles**\n\n```python\n\"\"\" Add permissions into roles\n    Available Methods:\n        1. sync_permissions: Syncs the permissions with the role\n            arguments: Takes a list/tuple of permission slugs\n        2. attach_permission: Adds a permission to a role\n            arguments: Takes permission model object or permission slug\n        3. detach_permission: Removes a permission from the role\n            arguments: Takes permission model object or permission slug\n\"\"\"\n```\n\n```python\n\"\"\" Syncing permissions with role, adds provided permissions and removes all other permissions\n    Arguments:\n        permissions: Takes a list/tuple of permission slugs\n\"\"\"\nrole.sync_permissions([\"create-post\", \"read-post\", \"update-post\", \"delete-post\"])\n# or\nrole.sync_permissions(\"create-post\", \"read-post\", \"update-post\", \"delete-post\")\n# or\nrole.sync_permissions([]) # clears all permissions from role\n```\n\n```python\n\"\"\" Attach permission, this will add new permission into role if already not added\n    Arguments:\n        permission: Takes permission model object or permission slug\n\"\"\"\nrole.attach_permission(\"create-post\")\n# or\nrole.attach_permission(Permission.first())\n```\n\n```python\n\"\"\" Detach permission, this will remove permission from role if already added\n    Arguments:\n        permission: Takes permission model object or permission slug\n\"\"\"\n\nrole.detach_permission(\"create-post\")\n# or\nrole.detach_permission(Permission.first())\n```\n\n#### Working with Permission\n\n**Creating Permission**\n\n```python\n\"\"\" Creating Permission\n    Arguments:\n        name: The name of the permission\n        slug: The slug of the permission, must be unique\n\"\"\"\nfrom masonite_permission.models import Permission\npermission = Permission.create({\n  \"name\": \"Create Post\",\n  \"slug\": \"create-post\" # must be unique\n})\n```\n\n**Add permissions into roles**\n\n```python\n\"\"\" Add permissions into roles\n    Available Methods:\n        1. sync_roles: Syncs the roles with the permission\n            arguments: Takes a list/tuple of role slugs\n        2. attach_role: Adds a permission to a role\n            arguments: Takes role model object or role slug\n        3. detach_role: Removes a permission from a role\n            arguments: Takes role model object or role slug\n\"\"\"\n```\n\n```python\n\"\"\" Syncing permissions with role, adds provided roles and removes all other roles\n    Arguments:\n        roles: Takes a list of role ids or role collection\n\"\"\"\npermission.sync_roles(['admin', 'editor'])\n# or\npermission.sync_roles('admin', 'editor')\n# or\npermission.sync_roles([]) # clears all role from permission\n```\n\n```python\n\"\"\" Attach role, this will add new permission into role if already not added\n    Arguments:\n        role: Takes role model object or role slug\n\"\"\"\nrole = Role.first()\n\npermission.attach_role(role)\n# or\npermission.attach_role('admin')\n```\n\n```python\n\"\"\" Detach role, this will remove permission from role if already added\n    Arguments:\n        role: Takes role model object or role id\n\"\"\"\nrole = Role.first()\n\npermission.detach_role(role)\n# or\npermission.detach_role('admin')\n```\n\n#### Working with User\n\n```python\nuser = User.first()\n```\n\n**Adding/Removing single role**\n\n```python\n# Add/Remove single role\nrole = Role.first()\n\nuser.assign_role(role) # or you can pass role id\nuser.revoke_role(role) # or you can pass role id\n```\n\n**Adding/Removing multiple roles**\n\n```python\n# add/remove multiple roles\nroles = Role.all()\n\nuser.sync_roles(roles) # or you can also pass list of ids...\nuser.sync_roles([]) # clears all roles from user\n```\n\n**Checking if user has roles**\n\n```python\n# check if user has role\nuser.has_role_of(\"admin\") # returns boolean\n\n# check if user has any of the roles\nuser.has_any_role([\"admin\", \"editor\"]) # returns boolean\n# or\nuser.has_any_role(\"admin\", \"editor\")\n\n# check if user has all of the roles\nuser.has_all_roles([\"admin\", \"editor\"]) # returns boolean\n# or\nuser.has_all_roles(\"admin\", \"editor\")\n```\n\n**Adding/Removing single direct permission**\n\n```python\n# Add/Remove single permission\nuser.give_permission_to(\"read-post\", \"edit-post\") # this can be a tuple or a list\n# or\nuser.give_permission_to([\"read-post\", \"edit-post\"])\n\nuser.revoke_permission_to(\"read-post\", \"edit-post\") # this can be a tuple or a list\n# or\nuser.revoke_permission_to([\"read-post\", \"edit-post\"])\n```\n\n**Adding/Removing multiple direct permissions**\n\n```python\n# add/remove multiple direct permissions\npermissions = Permission.all().pluck(\"slug\")\n\nuser.sync_permissions(permissions) # tuples or list of permission slug\nuser.sync_permissions([]) # clears all permissions from user\n```\n\n**Checking if user has permissions**\n\n```python\n\n# check if user has permission (for single permission)\nuser.has_permission_to(\"read-post\") # returns boolean\n\n# check if user has any of the permissions\nuser.has_any_permission([\"read-post\", \"edit-post\"]) # returns boolean\n# or\nuser.has_any_permission(\"read-post\", \"edit-post\")\n\n# check if user has all of the permissions\nuser.has_all_permissions([\"read-post\", \"edit-post\"]) # returns boolean\n# or\nuser.has_all_permissions(\"read-post\", \"edit-post\") # returns boolean\n\n```\n\n## Using in Template\n\n**In case of Roles**\nChecking if user has role.\n\n```jinja2\n{% if user.is_(\"admin\") %}\n    \u003cp\u003eYou are an admin\u003c/p\u003e\n{% endif %}\n```\n\nChecking if user has any of the roles\n\n```jinja2\n{% if user.is_(\"admin|editor|truck-driver\") %}\n    \u003cp\u003eYou can be either admin, editor, truck driver or all of those\u003c/p\u003e\n{% endif %}\n```\n\nChecking if user has all of the roles\n\n```jinja2\n{% if user.is_(\"admin,editor,truck-driver\") %}\n    \u003cp\u003eYou are an admin, editor and also truck-driver\u003c/p\u003e\n{% endif %}\n```\n\n**In case of Permissions**\nChecking if user can do {permission}.\n\n```jinja2\n{% if user.can_(\"edit-post\") %}\n    \u003cp\u003eYou can edit post\u003c/p\u003e\n{% endif %}\n```\n\nChecking if user can do any one or more of the {permissions}\n\n```jinja2\n{% if user.can_(\"edit-post|delete-post\") %}\n    \u003cp\u003eYou can either edit-post, delete-post or both.\u003c/p\u003e\n{% endif %}\n```\n\nChecking if user can do all of the {permissions}\n\n```jinja2\n{% if user.can_(\"edit-post,delete-post\") %}\n    \u003cp\u003eYou can edit post and also delete post.\u003c/p\u003e\n{% endif %}\n```\n\n\n## License\n\nMasonite Permission is open-sourced software licensed under the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpy-package%2Fmasonite-permission","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpy-package%2Fmasonite-permission","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpy-package%2Fmasonite-permission/lists"}