mediawiki_dump_tools/Mediawiki-Utilities/mw/api/collections/users.py

   1 import logging
   2
   3 from ...util import none_or
   4 from ..errors import MalformedResponse
   5 from .collection import Collection
   6
   7 logger = logging.getLogger("mw.api.collections.users")
   8
   9
  10 class Users(Collection):
  11     """
  12     A collection of information about users
  13     """
  14
  15     PROPERTIES = {'blockinfo', 'implicitgroups', 'groups', 'registration',
  16                   'emailable', 'editcount', 'gender'}
  17
  18     SHOW = {'minor', '!minor', 'patrolled', '!patrolled'}
  19
  20     MAX_REVISIONS = 50
  21
  22     def query(self, *args, **kwargs):
  23         """
  24         Get a user's metadata.
  25         See `<https://www.mediawiki.org/wiki/API:Users>`_
  26
  27         :Parameters:
  28             users : str
  29                 The usernames of the users to be retrieved.
  30
  31             properties : set(str)
  32                 Include additional pieces of information
  33
  34                 blockinfo      - Tags if the user is blocked, by whom, and
  35                                  for what reason
  36                 groups         - Lists all the groups the user(s) belongs to
  37                 implicitgroups - Lists all the groups a user is automatically
  38                                  a member of
  39                 rights         - Lists all the rights the user(s) has
  40                 editcount      - Adds the user's edit count
  41                 registration   - Adds the user's registration timestamp
  42                 emailable      - Tags if the user can and wants to receive
  43                                  email through [[Special:Emailuser]]
  44                 gender         - Tags the gender of the user. Returns "male",
  45                                  "female", or "unknown"
  46         """
  47         done = False
  48         while not done:
  49
  50             us_docs, query_continue = self._query(*args, **kwargs)
  51
  52             for doc in us_docs:
  53                 yield doc
  54
  55             if query_continue is None or len(us_docs) == 0:
  56                 done = True
  57             else:
  58                 kwargs['query_continue'] = query_continue
  59
  60     def _query(self, users, query_continue=None, properties=None):
  61
  62         params = {
  63             'action': "query",
  64             'list': "users"
  65         }
  66         params['ususers'] = self._items(users, type=str)
  67         params['usprop'] = self._items(properties, levels=self.PROPERTIES)
  68         if query_continue is not None:
  69             params.update(query_continue)
  70
  71         doc = self.session.get(params)
  72         try:
  73             if 'query-continue' in doc:
  74                 query_continue = doc['query-continue']['users']
  75             else:
  76                 query_continue = None
  77
  78             us_docs = doc['query']['users']
  79
  80             return us_docs, query_continue
  81
  82         except KeyError as e:
  83             raise MalformedResponse(str(e), doc)