This PR adds the functionality of restricting access to handlers to

• specified users (by id)
• specified chats (by id)
• chat admins
• chat creators

Builds upon #1757 (see below)
Closes #1151, #1562

Example usage:

updater = Updater('TOKEN')
dp = updater.dispatcher
roles = updater.dispatcher.roles

roles.add_admin('authors_user_id')
roles.add_role(name='my_role_1')
my_role_1 = roles['my_role_1']
roles.add_role(name='my_role_2', parent_roles=roles['my_role_1'])
my_role_2 = roles['my_role_2']

def add_to_my_role_2(update, context):
    user = update.effective_user
    context.roles['my_role_2'].add_member(user.id)
    
def add_to_my_role_1(update, context):
    user_id = update.message.text
    context.roles['my_role_1'].add_member(user_id)

....

# Anyone can add themself to my_role_2
dp.add_handler(TypeHandler(Update, add_to_my_role_2))

# Only the admin can add users to my_role_1
dp.add_handler(MessageHandler(Filters.message, add_to_my_role_1, roles=roles.ADMINS))

# This will be accessable by my_role_2, my_role_1 and the admin
dp.add_handler(SomeHandler(..., roles=my_role_2))

# This will be accessable by my_role_1 and the admin
dp.add_handler(SomeHandler(..., roles=my_role_1))

# This will be accessable by anyone except my_role_1 and my_role_2
dp.add_handler(SomeHandler(..., roles=~my_role_1))

# This will be accessable by users, who are in my_role_2 bot not in my_role_1
dp.add_handler(SomeHandler(..., roles=~my_role_1 & my_role_2))

# This will be accessable only by the admins of the group the update was sent in
dp.add_handler(SomeHandler(..., roles=roles.CHAT_ADMINS))

# This will be accessable only by the creator of the group the update was sent in
dp.add_handler(SomeHandler(..., roles=roles.CHAT_CREATOR))

# You can compare the roles regarding hierarchy:
roles.ADMINS >=  roles['my_role_1'] #True
roles.ADMINS >=  roles['my_role_2'] #True
roles['my_role_1'] < roles['my_role_2'] #False
roles.ADMINS >= Role(...) #False, since neither of those is a parent of the other

How does it work

Added Classes

Role

• Inherits from Filters.user (This is, where Allow updating user_ids/usernames of a running filters.user #1757 comes in. Can be changed to inherinting from BaseFilter if the reviewer want that)
• Can be combined by bitwise operations (This is why I'm Inheriting from Filters)
• Can be compared w.r.t. hierarchy. E.g. in above example: my_role_1 > my_role_2
• Dynamically add/kick members

Roles

A container for multiple roles

• Inherits from dict to allow accessing the roles by roles['role_name']
• Roles.ADMINS is parent to every role
• Roles.CHAT_ADMINS, Roles.CHAT_CREATOR as shortcuts for restricting acces in group chats
• Dynamically add/remove admins and roles

Integration with handlers

The base class Handler now has a __new__ method that makes sure, that check_update is called only, if the roles checked out. Alternatives approaches would be

• Make Handler.check_update check the roles directly and call super().check_updater in all the specific handlers. This means that custom handlers would have to change their check_update implementation. Then again, they may have to be adjusted to accept the roles argument anyway
• Add a metho Handler.check_update_with_roles that calles Handler.check_update after checking the roles. In the current code base, replace all calls to check_update with check_update_with_role. This would leave current implementation of check_update untouched.

Integration with dispatcher

• Dispatcher.roles is the Roles instance managing the roles
• Dispatcher.roles is available as context.roles to allow editing roles in callbacks
• store_roles is added to persistence to allow keeping track of roles over restarts. I know that adding stuff to persistence should be done with care. But if we want dynamic access control (and I do), we need persistence here.

ToDo

• Add roles to new PollAnswerHandler. As Poll updates have neither user nor chat, we don't need roles with PollHandler

• Cache chat admins and creators (timeout is customizable via roles.CHAT_ADMINS.timeout = ...)

• Handle private chats correctly with roles.CHAT_ADMINS/CHAT_CREATOR (this is as easy if checking chat.id == user.id)

• When merged, we should create a wiki page. Important points to mention there:

  • Hard coding dp.roles.add_admin(id) will always add the user to admins on start up with persistence, even if they are removed by dynamic access control. Thus, only the author of the bot should be hard coded as admin.
  • Admins should only be in roles.ADMINS, else they might be excluded by roles=~roles['my_role'], if they are in my_role
  • Hard coding dp.roles.add_role(name='my_group') will lead to ValueError on restart with persistence because after restoring the data, the role my_group will already be set. Use 'my_group' in dp.roles to check for that before adding the group.

• Depending on how long it will take to merge this:

  • Don't use all in persistence (see Don't use builtin function names as variables #1766)
  • Use tempfile module in persistence tests (see Use tempfile module in tests #1765)
  • Add type hinting (see Type-hinting for IDEs #1373)