mediawiki_dump_tools/Mediawiki-Utilities/mw/lib/sessions/functions.py

   1 import logging
   2
   3 from .cache import Cache
   4 from . import defaults
   5
   6 logger = logging.getLogger("mw.lib.sessions.functions")
   7
   8
   9 def cluster(user_events, cutoff=defaults.CUTOFF):
  10     """
  11     Clusters user sessions from a sequence of user events.  Note that,
  12     `event` data will simply be returned in the case of a revert.
  13
  14     This function serves as a convenience wrapper around calls to
  15     :class:`~mw.lib.sessions.Cache`'s :meth:`~mw.lib.sessions.Cache.process`
  16     method.
  17
  18     :Parameters:
  19         user_events : iter( (user, timestamp, event) )
  20             an iterable over tuples of user, timestamp and event data.
  21
  22             * user : `hashable`
  23             * timestamp : :class:`mw.Timestamp`
  24             * event : `mixed`
  25
  26         cutoff : int
  27             the maximum time between events within a user session
  28
  29     :Returns:
  30         a iterator over :class:`~mw.lib.sessions.Session`
  31
  32     :Example:
  33         >>> from mw.lib import sessions
  34         >>>
  35         >>> user_events = [
  36         ...     ("Willy on wheels", 100000, {'rev_id': 1}),
  37         ...     ("Walter", 100001, {'rev_id': 2}),
  38         ...     ("Willy on wheels", 100001, {'rev_id': 3}),
  39         ...     ("Walter", 100035, {'rev_id': 4}),
  40         ...     ("Willy on wheels", 103602, {'rev_id': 5})
  41         ... ]
  42         >>>
  43         >>> for user, events in sessions.cluster(user_events):
  44         ...     (user, events)
  45         ...
  46         ('Willy on wheels', [{'rev_id': 1}, {'rev_id': 3}])
  47         ('Walter', [{'rev_id': 2}, {'rev_id': 4}])
  48         ('Willy on wheels', [{'rev_id': 5}])
  49
  50
  51     """
  52
  53     # Construct the session manager
  54     cache = Cache(cutoff)
  55
  56     # Apply the events
  57     for user, timestamp, event in user_events:
  58
  59         for session in cache.process(user, timestamp, event):
  60             yield session
  61
  62     # Yield the left-overs
  63     for session in cache.get_active_sessions():
  64         yield session
  65
  66
  67 # For backwards compatibility
  68 sessions = cluster