mediawiki_dump_tools/Mediawiki-Utilities/mw/api/collections/user_contribs.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.user_contribs")
   8
   9
  10 class UserContribs(Collection):
  11     """
  12     A collection of revisions indexes by user.
  13     """
  14
  15     PROPERTIES = {'ids', 'title', 'timestamp', 'comment', 'parsedcomment',
  16                   'size', 'sizediff', 'flags', 'patrolled', 'tags'}
  17
  18     SHOW = {'minor', '!minor', 'patrolled', '!patrolled'}
  19
  20     MAX_REVISIONS = 50
  21
  22     def query(self, *args, limit=None, **kwargs):
  23         """
  24         Get a user's revisions.
  25         See `<https://www.mediawiki.org/wiki/API:Usercontribs>`_
  26
  27         :Parameters:
  28             limit : int
  29                 The maximum number of contributions to return.
  30             start : :class:`mw.Timestamp`
  31                 The start timestamp to return from
  32             end : :class:`mw.Timestamp`
  33                 The end timestamp to return to
  34             user : set(str)
  35                 The users to retrieve contributions for.  Maximum number of values 50 (500 for bots)
  36             userprefix : set(str)
  37                 Retrieve contributions for all users whose names begin with this value.
  38             direction : str
  39                 "newer" or "older"
  40             namespace : int
  41                 Only list contributions in these namespaces
  42             properties :
  43                 Include additional pieces of information
  44
  45                 * ids            - Adds the page ID and revision ID
  46                 * title          - Adds the title and namespace ID of the page
  47                 * timestamp      - Adds the timestamp of the edit
  48                 * comment        - Adds the comment of the edit
  49                 * parsedcomment  - Adds the parsed comment of the edit
  50                 * size           - Adds the new size of the edit
  51                 * sizediff       - Adds the size delta of the edit against its parent
  52                 * flags          - Adds flags of the edit
  53                 * patrolled      - Tags patrolled edits
  54                 * tags           - Lists tags for the edit
  55             show : set(str)
  56                 Show only items that meet thse criteria, e.g. non minor edits only: ucshow=!minor.
  57                 NOTE: If ucshow=patrolled or ucshow=!patrolled is set, revisions older than
  58                 $wgRCMaxAge (2592000) won't be shown
  59
  60                 * minor
  61                 * !minor,
  62                 * patrolled,
  63                 * !patrolled,
  64                 * top,
  65                 * !top,
  66                 * new,
  67                 * !new
  68             tag : str
  69                 Only list revisions tagged with this tag
  70             toponly : bool
  71                 DEPRECATED! Only list changes which are the latest revision
  72         """
  73         limit = none_or(limit, int)
  74
  75         revisions_yielded = 0
  76         done = False
  77         while not done:
  78
  79             if limit is None:
  80                 kwargs['limit'] = self.MAX_REVISIONS
  81             else:
  82                 kwargs['limit'] = min(limit - revisions_yielded, self.MAX_REVISIONS)
  83
  84             uc_docs, uccontinue = self._query(*args, **kwargs)
  85
  86             for doc in uc_docs:
  87                 yield doc
  88                 revisions_yielded += 1
  89
  90                 if limit is not None and revisions_yielded >= limit:
  91                     done = True
  92                     break
  93
  94             if uccontinue is None or len(uc_docs) == 0:
  95                 done = True
  96             else:
  97                 kwargs['uccontinue'] = uccontinue
  98
  99     def _query(self, user=None, userprefix=None, limit=None, start=None,
 100                end=None, direction=None, namespace=None, properties=None,
 101                show=None, tag=None, toponly=None,
 102                uccontinue=None):
 103
 104         params = {
 105             'action': "query",
 106             'list': "usercontribs"
 107         }
 108         params['uclimit'] = none_or(limit, int)
 109         params['ucstart'] = self._check_timestamp(start)
 110         params['ucend'] = self._check_timestamp(end)
 111         if uccontinue is not None:
 112             params.update(uccontinue)
 113         params['ucuser'] = self._items(user, type=str)
 114         params['ucuserprefix'] = self._items(userprefix, type=str)
 115         params['ucdir'] = self._check_direction(direction)
 116         params['ucnamespace'] = none_or(namespace, int)
 117         params['ucprop'] = self._items(properties, levels=self.PROPERTIES)
 118         params['ucshow'] = self._items(show, levels=self.SHOW)
 119
 120         doc = self.session.get(params)
 121         try:
 122             if 'query-continue' in doc:
 123                 uccontinue = doc['query-continue']['usercontribs']
 124             else:
 125                 uccontinue = None
 126
 127             uc_docs = doc['query']['usercontribs']
 128
 129             return uc_docs, uccontinue
 130
 131         except KeyError as e:
 132             raise MalformedResponse(str(e), doc)