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.dispatcherroles=updater.dispatcher.rolesroles.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']defadd_to_my_role_2(update,context):user=update.effective_usercontext.roles['my_role_2'].add_member(user.id)defadd_to_my_role_1(update,context):user_id=update.message.textcontext.roles['my_role_1'].add_member(user_id)....# Anyone can add themself to my_role_2dp.add_handler(TypeHandler(Update,add_to_my_role_2))# Only the admin can add users to my_role_1dp.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 admindp.add_handler(SomeHandler(...,roles=my_role_2))# This will be accessable by my_role_1 and the admindp.add_handler(SomeHandler(...,roles=my_role_1))# This will be accessable by anyone except my_role_1 and my_role_2dp.add_handler(SomeHandler(...,roles=~my_role_1))# This will be accessable by users, who are in my_role_2 bot not in my_role_1dp.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 indp.add_handler(SomeHandler(...,roles=roles.CHAT_ADMINS))# This will be accessable only by the creator of the group the update was sent indp.add_handler(SomeHandler(...,roles=roles.CHAT_CREATOR))# You can compare the roles regarding hierarchy:roles.ADMINS>=roles['my_role_1']#Trueroles.ADMINS>=roles['my_role_2']#Trueroles['my_role_1']<roles['my_role_2']#Falseroles.ADMINS>=Role(...)#False, since neither of those is a parent of the other

How does it work

Added Classes

Role

• Inherits fromFilters.user (This is, whereAllow updating user_ids/usernames of a running filters.user #1757 comes in. Can be changed to inherinting fromBaseFilter if the reviewer want that)
• Can be combined by bitwise operations (This is why I'm Inheriting fromFilters)
• 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 fromdict to allow accessing the roles byroles['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 classHandler now has a__new__ method that makes sure, thatcheck_update is called only, if the roles checked out. Alternatives approaches would be

• MakeHandler.check_update check the roles directly and callsuper().check_updater in all the specific handlers. This means that custom handlers would have to change theircheck_update implementation. Then again, they may have to be adjusted to accept theroles argument anyway
• Add a methoHandler.check_update_with_roles that callesHandler.check_update after checking the roles. In the current code base, replace all calls tocheck_update withcheck_update_with_role. This would leave current implementation ofcheck_update untouched.

Integration with dispatcher

• Dispatcher.roles is theRoles instance managing the roles
• Dispatcher.roles is available ascontext.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 newPollAnswerHandler. AsPoll updates have neither user nor chat, we don't need roles withPollHandler

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

• Handle private chats correctly withroles.CHAT_ADMINS/CHAT_CREATOR (this is as easy if checkingchat.id == user.id)

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

  • Hard codingdp.roles.add_admin(id) willalways 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 shouldonly be inroles.ADMINS, else they might be excluded byroles=~roles['my_role'], if they are inmy_role
  • Hard codingdp.roles.add_role(name='my_group') will lead toValueError on restart with persistence because after restoring the data, the rolemy_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 useall in persistence (seeDon't use builtin function names as variables #1766)
  • Usetempfile module in persistence tests (seeUse tempfile module in tests #1765)
  • Add type hinting (seeType-hinting for IDEs #1373)