# mw.lib.reverts – detecting reverts¶

This module provides a set of utilities for detecting identity reverts in revisioned content.

To detect reverts in a stream of revisions to a single page, you can use detect(). If you’ll be detecting reverts in a collection of pages or would, for some other reason, prefer to process revisions one at a time, Detector and it’s process() will allow you to do so.

To detect reverts one-at-time and arbitrarily, you can user the check() functions:

Note that these functions are less performant than detecting reverts in a stream of page revisions. This can be practical when trying to identify reverted revisions in a user’s contribution history.

Detects reverts that occur in a sequence of revisions. Note that, revision data meta will simply be returned in the case of a revert.

This function serves as a convenience wrapper around calls to Detector‘s process() method.

Parameters: checksum_revisions : iter( ( checksum : str, revision : mixed ) ) an iterable over tuples of checksum and revision meta data radius : int a positive integer indicating the maximum revision distance that a revert can span. a iterator over Revert >>> from mw.lib import reverts >>> >>> checksum_revisions = [ ... ("aaa", {'rev_id': 1}), ... ("bbb", {'rev_id': 2}), ... ("aaa", {'rev_id': 3}), ... ("ccc", {'rev_id': 4}) ... ] >>> >>> list(reverts.detect(checksum_revisions)) [Revert(reverting={'rev_id': 3}, reverteds=[{'rev_id': 2}], reverted_to={'rev_id': 1})] 
class mw.lib.reverts.Revert

Represents a revert event. This class behaves like collections.namedtuple. Note that the datatypes of reverting, reverteds and reverted_to is not specified since those types will depend on the revision data provided during revert detection.

Members: reverting The reverting revision data : mixed reverteds The reverted revision data (ordered chronologically) : list( mixed ) reverted_to The reverted-to revision data : mixed

Detects revert events in a stream of revisions (to the same page) based on matching checksums. To detect reverts, construct an instance of this class and call process() in chronological order (direction == "newer").

Parameters: radius : int a positive integer indicating the maximum revision distance that a revert can span. >>> from mw.lib import reverts >>> detector = reverts.Detector() >>> >>> detector.process("aaa", {'rev_id': 1}) >>> detector.process("bbb", {'rev_id': 2}) >>> detector.process("aaa", {'rev_id': 3}) Revert(reverting={'rev_id': 3}, reverteds=[{'rev_id': 2}], reverted_to={'rev_id': 1}) >>> detector.process("ccc", {'rev_id': 4}) 
process(checksum, revision=None)

Process a new revision and detect a revert if it occurred. Note that you can pass whatever you like as revision and it will be returned in the case that a revert occurs.

Parameters: checksum : str Any identity-machable string-based hash of revision content revision : mixed Revision meta data. Note that any data will just be returned in the case of a revert. a Revert if one occured or None

## Convenience functions¶

mw.lib.reverts.api.check_rev(session, rev, **kwargs)[source]

Checks whether a revision (database row) was reverted (identity) and returns a named tuple of Revert(reverting, reverteds, reverted_to).

Parameters: session : mw.api.Session An API session to make use of rev : dict a revision dict containing ‘revid’ and ‘page.id’ radius : int a positive integer indicating the maximum number of revisions that can be reverted before : mw.Timestamp if set, limits the search for reverting revisions to those which were saved before this timestamp properties : set( str ) a set of properties to include in revisions (see mw.api.Revisions)
mw.lib.reverts.api.check(session, rev_id, page_id=None, radius=15, before=None, window=None, properties=None)[source]

Checks whether a revision was reverted (identity) and returns a named tuple of Revert(reverting, reverteds, reverted_to).

Parameters: session : mw.api.Session An API session to make use of rev_id : int the ID of the revision to check page_id : int the ID of the page the revision occupies (slower if not provided) radius : int a positive integer indicating the maximum number of revisions that can be reverted before : mw.Timestamp if set, limits the search for reverting revisions to those which were saved before this timestamp window : int if set, limits the search for reverting revisions to those which were saved within window seconds after the reverted edit properties : set( str ) a set of properties to include in revisions (see mw.api.Revisions)
mw.lib.reverts.database.check_row(db, rev_row, **kwargs)[source]

Checks whether a revision (database row) was reverted (identity) and returns a named tuple of Revert(reverting, reverteds, reverted_to).

Parameters: db : mw.database.DB A database connection to make use of. rev_row : dict a revision row containing ‘rev_id’ and ‘rev_page’ or ‘page_id’ radius : int a positive integer indicating the the maximum number of revisions that can be reverted check_archive : bool should the archive table be checked for reverting revisions? before : Timestamp if set, limits the search for reverting revisions to those which were saved before this timestamp
mw.lib.reverts.database.check(db, rev_id, page_id=None, radius=15, check_archive=False, before=None, window=None)[source]

Checks whether a revision was reverted (identity) and returns a named tuple of Revert(reverting, reverteds, reverted_to).

Parameters: db : mw.database.DB A database connection to make use of. rev_id : int the ID of the revision to check page_id : int the ID of the page the revision occupies (slower if not provided) radius : int a positive integer indicating the maximum number of revisions that can be reverted check_archive : bool should the archive table be checked for reverting revisions? before : Timestamp if set, limits the search for reverting revisions to those which were saved before this timestamp window : int if set, limits the search for reverting revisions to those which were saved within window seconds after the reverted edit

## Constants¶

TODO: Better documentation here. For the time being, see:

Priedhorsky, R., Chen, J., Lam, S. T. K., Panciera, K., Terveen, L., & Riedl, J. (2007, November). Creating, destroying, and restoring value in Wikipedia. In Proceedings of the 2007 international ACM conference on Supporting group work (pp. 259-268). ACM.