sidequest_bot.lib.roles
=======================

.. py:module:: sidequest_bot.lib.roles

.. autoapi-nested-parse::

   Rules for roles the bot hands out on its own (level rewards, auto-role, self-serve role menus).

   Two independent checks, both required:

   * :func:`grant_block_reason` - is the role itself safe for the bot to give away? Checked when the role is configured
     AND again right before every grant, because an admin can add permissions to a role after it was configured.
   * :func:`configure_block_reason` - may this member set the role up to be handed out? Without it, anyone with Manage
     Server could configure a role above their own and escalate through the bot's permissions.



Attributes
----------

.. autoapisummary::

   sidequest_bot.lib.roles.DANGEROUS_PERMISSIONS


Functions
---------

.. autoapisummary::

   sidequest_bot.lib.roles.configure_block_reason
   sidequest_bot.lib.roles.dangerous_permissions
   sidequest_bot.lib.roles.grant_block_reason


Module Contents
---------------

.. py:function:: configure_block_reason(member: discord.Member, role: discord.Role) -> str | None

   Why ``member`` may not configure ``role`` to be handed out by the bot, or None if they may.

   Requires Manage Roles and that the role sits below the member's highest role (the server owner is exempt).


.. py:function:: dangerous_permissions(permissions: discord.Permissions) -> list[str]

   Names of the dangerous permissions set in ``permissions``, sorted.


.. py:function:: grant_block_reason(role: discord.Role) -> str | None

   Why the bot must not hand out ``role`` automatically, or None if it may.


.. py:data:: DANGEROUS_PERMISSIONS

   Permissions a role must not carry if the bot grants it automatically or on request.