"""Object representing a Wiki user."""
#
# (C) Pywikibot team, 2009-2022
#
# Distributed under the terms of the MIT license.
#
from typing import Optional
import pywikibot
from pywikibot.backports import Iterable, Tuple
from pywikibot.exceptions import (
APIError,
AutoblockUserError,
NotEmailableError,
UserRightsError,
)
from pywikibot.page._links import Link
from pywikibot.page._pages import Page
from pywikibot.page._revision import Revision
from pywikibot.tools import deprecated, is_ip_address
__all__ = ('User', )
[docs]class User(Page):
"""
A class that represents a Wiki user.
This class also represents the Wiki page User:<username>
"""
def __init__(self, source, title: str = '') -> None:
"""
Initializer for a User object.
All parameters are the same as for Page() Initializer.
"""
self._isAutoblock = True
if title.startswith('#'):
title = title[1:]
elif ':#' in title:
title = title.replace(':#', ':')
else:
self._isAutoblock = False
super().__init__(source, title, ns=2)
if self.namespace() != 2:
raise ValueError("'{}' is not in the user namespace!"
.format(self.title()))
if self._isAutoblock:
# This user is probably being queried for purpose of lifting
# an autoblock.
pywikibot.output(
'This is an autoblock ID, you can only use to unblock it.')
@property
def username(self) -> str:
"""
The username.
Convenience method that returns the title of the page with
namespace prefix omitted, which is the username.
"""
if self._isAutoblock:
return '#' + self.title(with_ns=False)
return self.title(with_ns=False)
[docs] def isRegistered(self, force: bool = False) -> bool: # noqa: N802
"""
Determine if the user is registered on the site.
It is possible to have a page named User:xyz and not have
a corresponding user with username xyz.
The page does not need to exist for this method to return
True.
:param force: if True, forces reloading the data from API
"""
# T135828: the registration timestamp may be None but the key exists
return (not self.isAnonymous()
and 'registration' in self.getprops(force))
[docs] def isAnonymous(self) -> bool: # noqa: N802
"""Determine if the user is editing as an IP address."""
return is_ip_address(self.username)
[docs] def getprops(self, force: bool = False) -> dict:
"""
Return a properties about the user.
:param force: if True, forces reloading the data from API
"""
if force and hasattr(self, '_userprops'):
del self._userprops
if not hasattr(self, '_userprops'):
self._userprops = list(self.site.users([self.username, ]))[0]
if self.isAnonymous():
r = list(self.site.blocks(iprange=self.username, total=1))
if r:
self._userprops['blockedby'] = r[0]['by']
self._userprops['blockreason'] = r[0]['reason']
return self._userprops
[docs] def registration(self,
force: bool = False) -> Optional[pywikibot.Timestamp]:
"""
Fetch registration date for this user.
:param force: if True, forces reloading the data from API
"""
if not self.isAnonymous():
reg = self.getprops(force).get('registration')
if reg:
return pywikibot.Timestamp.fromISOformat(reg)
return None
[docs] def editCount(self, force: bool = False) -> int: # noqa: N802
"""
Return edit count for a registered user.
Always returns 0 for 'anonymous' users.
:param force: if True, forces reloading the data from API
"""
return self.getprops(force).get('editcount', 0)
[docs] def is_blocked(self, force: bool = False) -> bool:
"""Determine whether the user is currently blocked.
.. versionchanged:: 7.0
renamed from :meth:`isBlocked` method,
can also detect range blocks.
:param force: if True, forces reloading the data from API
"""
return 'blockedby' in self.getprops(force)
[docs] @deprecated('is_blocked', since='7.0.0')
def isBlocked(self, force: bool = False) -> bool: # noqa: N802
"""Determine whether the user is currently blocked.
.. deprecated:: 7.0
use :meth:`is_blocked` instead
:param force: if True, forces reloading the data from API
"""
return self.is_blocked(force)
[docs] def is_locked(self, force: bool = False) -> bool:
"""Determine whether the user is currently locked globally.
.. versionadded:: 7.0
:param force: if True, forces reloading the data from API
"""
return self.site.is_locked(self.username, force)
[docs] def isEmailable(self, force: bool = False) -> bool: # noqa: N802
"""
Determine whether emails may be send to this user through MediaWiki.
:param force: if True, forces reloading the data from API
"""
return not self.isAnonymous() and 'emailable' in self.getprops(force)
[docs] def groups(self, force: bool = False) -> list:
"""
Return a list of groups to which this user belongs.
The list of groups may be empty.
:param force: if True, forces reloading the data from API
:return: groups property
"""
return self.getprops(force).get('groups', [])
[docs] def gender(self, force: bool = False) -> str:
"""Return the gender of the user.
:param force: if True, forces reloading the data from API
:return: return 'male', 'female', or 'unknown'
"""
if self.isAnonymous():
return 'unknown'
return self.getprops(force).get('gender', 'unknown')
[docs] def rights(self, force: bool = False) -> list:
"""Return user rights.
:param force: if True, forces reloading the data from API
:return: return user rights
"""
return self.getprops(force).get('rights', [])
[docs] def getUserPage(self, subpage: str = '') -> Page: # noqa: N802
"""
Return a Page object relative to this user's main page.
:param subpage: subpage part to be appended to the main
page title (optional)
:return: Page object of user page or user subpage
"""
if self._isAutoblock:
# This user is probably being queried for purpose of lifting
# an autoblock, so has no user pages per se.
raise AutoblockUserError(
'This is an autoblock ID, you can only use to unblock it.')
if subpage:
subpage = '/' + subpage
return Page(Link(self.title() + subpage, self.site))
[docs] def getUserTalkPage(self, subpage: str = '') -> Page: # noqa: N802
"""
Return a Page object relative to this user's main talk page.
:param subpage: subpage part to be appended to the main
talk page title (optional)
:return: Page object of user talk page or user talk subpage
"""
if self._isAutoblock:
# This user is probably being queried for purpose of lifting
# an autoblock, so has no user talk pages per se.
raise AutoblockUserError(
'This is an autoblock ID, you can only use to unblock it.')
if subpage:
subpage = '/' + subpage
return Page(Link(self.username + subpage,
self.site, default_namespace=3))
[docs] def send_email(self, subject: str, text: str, ccme: bool = False) -> bool:
"""
Send an email to this user via MediaWiki's email interface.
:param subject: the subject header of the mail
:param text: mail body
:param ccme: if True, sends a copy of this email to the bot
:raises NotEmailableError: the user of this User is not emailable
:raises UserRightsError: logged in user does not have 'sendemail' right
:return: operation successful indicator
"""
if not self.isEmailable():
raise NotEmailableError(self)
if not self.site.has_right('sendemail'):
raise UserRightsError("You don't have permission to send mail")
params = {
'action': 'emailuser',
'target': self.username,
'token': self.site.tokens['email'],
'subject': subject,
'text': text,
}
if ccme:
params['ccme'] = 1
mailrequest = self.site.simple_request(**params)
maildata = mailrequest.submit()
if 'emailuser' in maildata \
and maildata['emailuser']['result'] == 'Success':
return True
return False
[docs] def block(self, *args, **kwargs):
"""
Block user.
Refer :py:obj:`APISite.blockuser` method for parameters.
:return: None
"""
try:
self.site.blockuser(self, *args, **kwargs)
except APIError as err:
if err.code == 'invalidrange':
raise ValueError('{} is not a valid IP range.'
.format(self.username))
raise err
[docs] def unblock(self, reason: Optional[str] = None) -> None:
"""
Remove the block for the user.
:param reason: Reason for the unblock.
"""
self.site.unblockuser(self, reason)
[docs] def logevents(self, **kwargs):
"""Yield user activities.
:keyword logtype: only iterate entries of this type
(see mediawiki api documentation for available types)
:type logtype: str
:keyword page: only iterate entries affecting this page
:type page: Page or str
:keyword namespace: namespace to retrieve logevents from
:type namespace: int or Namespace
:keyword start: only iterate entries from and after this Timestamp
:type start: Timestamp or ISO date string
:keyword end: only iterate entries up to and through this Timestamp
:type end: Timestamp or ISO date string
:keyword reverse: if True, iterate oldest entries first
(default: newest)
:type reverse: bool
:keyword tag: only iterate entries tagged with this tag
:type tag: str
:keyword total: maximum number of events to iterate
:type total: int
:rtype: iterable
"""
return self.site.logevents(user=self.username, **kwargs)
@property
def last_event(self):
"""Return last user activity.
:return: last user log entry
:rtype: LogEntry or None
"""
return next(self.logevents(total=1), None)
[docs] def contributions(self, total: int = 500, **kwargs) -> tuple:
"""
Yield tuples describing this user edits.
Each tuple is composed of a pywikibot.Page object,
the revision id (int), the edit timestamp (as a pywikibot.Timestamp
object), and the comment (str).
Pages returned are not guaranteed to be unique.
:param total: limit result to this number of pages
:keyword start: Iterate contributions starting at this Timestamp
:keyword end: Iterate contributions ending at this Timestamp
:keyword reverse: Iterate oldest contributions first (default: newest)
:keyword namespaces: only iterate pages in these namespaces
:type namespaces: iterable of str or Namespace key,
or a single instance of those types. May be a '|' separated
list of namespace identifiers.
:keyword showMinor: if True, iterate only minor edits; if False and
not None, iterate only non-minor edits (default: iterate both)
:keyword top_only: if True, iterate only edits which are the latest
revision (default: False)
:return: tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment
"""
for contrib in self.site.usercontribs(
user=self.username, total=total, **kwargs):
ts = pywikibot.Timestamp.fromISOformat(contrib['timestamp'])
yield (Page(self.site, contrib['title'], contrib['ns']),
contrib['revid'],
ts,
contrib.get('comment'))
@property
def first_edit(
self
) -> Optional[Tuple[Page, int, pywikibot.Timestamp, str]]:
"""Return first user contribution.
:return: first user contribution entry
:return: tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment
"""
return next(self.contributions(reverse=True, total=1), None)
@property
def last_edit(
self
) -> Optional[Tuple[Page, int, pywikibot.Timestamp, str]]:
"""Return last user contribution.
:return: last user contribution entry
:return: tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment
"""
return next(self.contributions(total=1), None)
[docs] def deleted_contributions(
self, *, total: int = 500, **kwargs
) -> Iterable[Tuple[Page, Revision]]:
"""Yield tuples describing this user's deleted edits.
.. versionadded:: 5.5
:param total: Limit results to this number of pages
:keyword start: Iterate contributions starting at this Timestamp
:keyword end: Iterate contributions ending at this Timestamp
:keyword reverse: Iterate oldest contributions first (default: newest)
:keyword namespaces: Only iterate pages in these namespaces
"""
for data in self.site.alldeletedrevisions(user=self.username,
total=total, **kwargs):
page = Page(self.site, data['title'], data['ns'])
for contrib in data['revisions']:
yield page, Revision(**contrib)
[docs] def uploadedImages(self, total: int = 10): # noqa: N802
"""
Yield tuples describing files uploaded by this user.
Each tuple is composed of a pywikibot.Page, the timestamp (str in
ISO8601 format), comment (str) and a bool for pageid > 0.
Pages returned are not guaranteed to be unique.
:param total: limit result to this number of pages
"""
if not self.isRegistered():
return
for item in self.logevents(logtype='upload', total=total):
yield (item.page(),
str(item.timestamp()),
item.comment(),
item.pageid() > 0)
@property
def is_thankable(self) -> bool:
"""
Determine if the user has thanks notifications enabled.
.. note::
This doesn't accurately determine if thanks is enabled for user.
Privacy of thanks preferences is under discussion, please see
:phab:`T57401#2216861` and :phab:`T120753#1863894`.
"""
return self.isRegistered() and 'bot' not in self.groups()
