Welcome to xtools
’ documentation!¶
xtools
is a Python wrapper around XTools’ API.
Note this project is not affiliated with nor endorsed by XTools.
Install¶
pip install xtools
Usage¶
Functions are divided in four modules, exactly like the XTools API. They are also available under the top-level
xtools
module: xtools.top_edits
is the same as xtools.user.top_edits
, etc.
xtools.project
¶
Endpoints related to projects.
https://xtools.readthedocs.io/en/stable/api/project.html
-
xtools.project.
admin_statistics
(project: str, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, actions: Optional[Sequence[str]] = None) → dict¶ Return admin users of the project with counts of the actions they took.
XTools limits the time period to one month.
https://xtools.readthedocs.io/en/stable/api/project.html#admin-statistics
- Parameters
project –
start –
end –
actions – available actions include:
delete
,revision-delete
,log-delete
,restore
,re-block
,unblock
,re-protect
,unprotect
,rights
,merge
,import
.
- Returns
-
xtools.project.
admins_and_user_groups
(project: str) → dict¶ https://xtools.readthedocs.io/en/stable/api/project.html#admins-and-user-groups
- Parameters
project –
- Returns
-
xtools.project.
automated_tools
(project: str) → dict¶ Return a list of known (semi-)automated tools used on the project.
Example:
>>> automated_tools("en.wikipedia.org") { "project": "en.wikipedia.org", "Admin actions": { "regex": "^...", "link": "Project:Administrators", "label": "Admin actions", "namespaces": [], "tags": [], }, "Advisor.js": { "regex": "...Advisor.js", ... }, ... }
Note the exact same endpoint exists under
api/user
.https://xtools.readthedocs.io/en/stable/api/project.html#automated-tools https://xtools.readthedocs.io/en/stable/api/user.html#automated-tools
- Parameters
project –
- Returns
-
xtools.project.
namespaces
(project: str) → dict¶ https://xtools.readthedocs.io/en/stable/api/project.html#namespaces
- Parameters
project –
- Returns
-
xtools.project.
normalize_project
(project: str) → dict¶ https://xtools.readthedocs.io/en/stable/api/project.html#normalize-project
Example:
>>> normalize_project("enwiki") { "project": "en.wikipedia.org", "domain": "en.wikipedia.org", "url": "https://en.wikipedia.org/", "api": "https://en.wikipedia.org/w/api.php", "database": "enwiki", "elapsed_time": 0.051 }
- Parameters
project –
- Returns
-
xtools.project.
page_assessments
(project: str) → dict¶ https://xtools.readthedocs.io/en/stable/api/project.html#page-assessments
- Parameters
project –
- Returns
-
xtools.project.
page_assessments_configuration
() → dict¶ Return the list of wikis that support page assessments and the configuration for each.
https://xtools.readthedocs.io/en/stable/api/project.html#page-assessments-configuration
Example:
>>> page_assessments_configuration() { "projects": [ "ar.wikipedia.org", "en.wikipedia.org", "en.wikivoyage.org", ... ], "config": { "ar.wikipedia.org": { ... }, ... }, }
- Returns
-
xtools.project.
patroller_statistics
(project: str, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, actions: Optional[Sequence[str]] = None) → dict¶ Same as
admin_statistics
with different actions.https://xtools.readthedocs.io/en/stable/api/project.html#patroller-statistics
- Parameters
project –
start –
end –
actions – available actions include:
patrol
,page-curation
,pc-accept
,pc-reject
.
- Returns
-
xtools.project.
steward_statistics
(project: str, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, actions: Optional[Sequence[str]] = None) → dict¶ Same as
admin_statistics
with different actions.https://xtools.readthedocs.io/en/stable/api/project.html#stewards-statistics
- Parameters
project –
start –
end –
actions – available actions include:
global-account-un-lock
(global locks and unlocks),global-block
,global-unblock
,global-rename
,global-rights
,wiki-set-change
.
- Returns
xtools.page
¶
Endpoints related to pages.
https://xtools.readthedocs.io/en/stable/api/page.html
-
xtools.page.
article_info
(project: str, article: str) → dict¶ Return basic information about an article, such as page views, watchers, edits counts; author; assessment.
https://xtools.readthedocs.io/en/stable/api/page.html#article-info
- Parameters
project –
article –
- Returns
-
xtools.page.
assessments
(project: str, articles: Sequence[str], class_only: bool = False) → dict¶ Get assessment data for the given articles.
Example:
>>> assessments("en.wikipedia.org", ["Albert_Einstein", "Bob_Dylan"], class_only=True) { "project": "en.wikipedia.org", "Albert Einstein": { "value": "GA", "color": "#66FF66", "category": "Category:GA-Class articles", "badge": "https://upload.wikimedia.org/wikipedia/commons/9/94/Symbol_support_vote.svg" }, "Bob Dylan": { "value": "FA", "color": "#9CBDFF", "category": "Category:FA-Class articles", "badge": "https://upload.wikimedia.org/wikipedia/commons/b/bc/Featured_article_star.svg" }, "elapsed_time": 0.361 }
https://xtools.readthedocs.io/en/stable/api/page.html#assessments
- Parameters
project –
articles –
class_only –
- Returns
-
xtools.page.
links
(project: str, article: str) → dict¶ Return in and outgoing links counts of an article.
Example:
>>> links("enwiki", "Albert_Einstein") { "project": "en.wikipedia.org", "page": "Albert_Einstein", "links_ext_count": 372, "links_out_count": 1178, "links_in_count": 9744, "redirects_count": 19, "elapsed_time": 17.902 }
https://xtools.readthedocs.io/en/stable/api/page.html#links
- Parameters
project –
article –
- Returns
-
xtools.page.
prose
(project: str, article: str) → dict¶ Return prose information about an article, such as references and words counts.
https://xtools.readthedocs.io/en/stable/api/page.html#prose
Example:
>>> prose("en.wikipedia.org", "Albert_Einstein") { "project": "en.wikipedia.org", "page": "Albert_Einstein", "characters": 66690, "words": 10536, "references": 308, "unique_references": 251, "sections": 63, "elapsed_time": 0.645, }
- Parameters
project –
article –
- Returns
-
xtools.page.
top_editors
(project: str, article: str, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, limit: Optional[int] = None, exclude_bots: bool = False) → dict¶ Get top editors on an article.
Note: as of 2020/05/10, passing a limit without start and end gives an error.
Example:
>>> top_editors("en.wikipedia", "Albert_Einstein") { "project": "en.wikipedia.org", "page": "Albert_Einstein", "limit": 20, "top_editors": [ { "rank": 1, "username": "Otterpops", "count": 509, "minor": 46, "first_edit": {"id": 111357663, "timestamp": 20070227165531}, "latest_edit": {"id": 115188249, "timestamp": 20070314232325}, }, ... ], "elapsed_time": 0.133, }
https://xtools.readthedocs.io/en/stable/api/page.html#top-editors
- Parameters
project –
article –
start – optional start date.
end – optional end date.
limit – optional limit (XTools’ default is 20)
exclude_bots – if True, exclude bots.
- Returns
xtools.user
¶
Endpoints related to users.
https://xtools.readthedocs.io/en/stable/api/user.html
-
xtools.user.
automated_edit_counter
(project: str, username: str, namespace: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, offset: Optional[int] = None, tools: bool = False) → dict¶ https://xtools.readthedocs.io/en/stable/api/user.html#automated-edit-counter
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.start –
end –
offset –
tools –
- Returns
-
xtools.user.
automated_edits
(project: str, username: str, namespace: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, offset: Optional[int] = None) → dict¶ https://xtools.readthedocs.io/en/stable/api/user.html#automated-edits
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.start –
end –
offset –
- Returns
-
xtools.user.
category_edit_counter
(project: str, username: str, categories: Sequence[str], start: Optional[datetime.date] = None, end: Optional[datetime.date] = None) → dict¶ https://xtools.readthedocs.io/en/stable/api/user.html#category-edit-counter
- Parameters
project –
username –
categories – Categories. The namespace prefix can be omitted.
start –
end –
- Returns
-
xtools.user.
edit_summaries
(project: str, username: str, namespace: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None) → dict¶ https://xtools.readthedocs.io/en/stable/api/user.html#edit-summaries
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.start –
end –
- Returns
-
xtools.user.
log_counts
(project: str, username: str) → dict¶ Return counts of logged actions made by a user.
https://xtools.readthedocs.io/en/stable/api/user.html#log-counts
Example:
>>> log_counts("en.wikipedia.org", "Jimbo_Wales") { "project": "en.wikipedia.org", "username": "Jimbo_Wales", "log_counts": { "block-block": 83, "block-unblock": 42, "create-create": 2, "delete-delete": 325, "delete-delete_redir": 1, "delete-event": 1, "delete-restore": 20, ... }, }
- Parameters
project –
username –
- Returns
-
xtools.user.
month_counts
(project: str, username: str) → dict¶ Return the edit count of a user, grouped by namespace then year and month.
https://xtools.readthedocs.io/en/stable/api/user.html#month-counts
- Parameters
project –
username –
- Returns
-
xtools.user.
namespace_totals
(project: str, username: str) → dict¶ Return the edit count for each namespace with at least 1 edit.
https://xtools.readthedocs.io/en/stable/api/user.html#namespace-totals
- Parameters
project –
username –
- Returns
-
xtools.user.
non_automated_edits
(project: str, username: str, namespace: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, offset: Optional[int] = None) → dict¶ https://xtools.readthedocs.io/en/stable/api/user.html#non-automated-edits
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.start –
end –
offset –
- Returns
-
xtools.user.
number_of_pages_created
(project: str, username: str, namespace: Optional[str] = None, redirects: Optional[str] = None, deleted: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None) → dict¶ Return the number of pages created by a user along with some other info.
Example:
>>> number_of_pages_created("en.wikipedia", "Jimbo_Wales") { "project": "en.wikipedia.org", "username": "Jimbo_Wales", ... "counts": { "count": 42, "total_length": 30691, "avg_length": 730.7380952380952, "deleted": 1 }, "elapsed_time": 0.059, }
https://xtools.readthedocs.io/en/stable/api/user.html#number-of-pages-created
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.redirects – either
"noredirects"
(default),"onlyredirects"
, or"all"
for both.deleted – either
"live"
,"deleted"
, or"all"
(default).start –
end –
- Returns
-
xtools.user.
pages_created
(project: str, username: str, namespace: str = None, redirects: Optional[str] = None, deleted: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, offset: Optional[int] = None, all_times: bool = False) → dict¶ Return pages created by a user. This does not handle pagination; see
pages_created_iter
for that.Note that XTools doesn’t support users with >400,000 edits, and this function raises a
xtools.exceptions.TooManyEdits
exception if you try.Example:
>>> pages_created("enwiki", "Jimbo_Wales") { "pages": [ { "namespace": 0, "type": "rev", "page_title": "Helen Crlenkovich", "page_is_redirect": 0, "length": 10691, "page_len": 11597, "rev_timestamp": 20200509210713, "rev_len": 10691, "rev_id": 170658958, "recreated": null, "pa_class": null, "pa_importance": null, "pa_page_revision": null, "raw_time": 20200509210713, "human_time": "2020-05-09 21:07", "badge": "https://upload.wikimedia.org/....svg", }, ... ], "continue": 1, }
https://xtools.readthedocs.io/en/stable/api/user.html#pages-created
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.redirects – either
"noredirects"
(default),"onlyredirects"
, or"all"
for both.deleted – either
"live"
,"deleted"
, or"all"
(default).start –
end –
offset –
all_times – if
True
, fetch all pages instead of the more recent ones. This overridesstart
andend
.
- Returns
-
xtools.user.
pages_created_iter
(project: str, username: str, namespace: str = None, redirects: Optional[str] = None, deleted: Optional[str] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None, all_times: bool = False) → Generator[dict, None, None]¶ Equivalent of
pages_created
that yields page dicts and does the pagination for you.See
pages_created
for sample return values.Example:
>>> for page in pages_created_iter("enwiki", "Jimbo_Wales"): ... print(page["page_title"])
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.redirects – either
"noredirects"
(default),"onlyredirects"
, or"all"
for both.deleted – either
"live"
,"deleted"
, or"all"
(default).start –
end –
all_times – if
True
, fetch all pages instead of the more recent ones. This overridesstart
andend
.
- Returns
-
xtools.user.
simple_edit_count
(project: str, username: str, namespace: Optional[int] = None, start: Optional[datetime.date] = None, end: Optional[datetime.date] = None) → dict¶ https://xtools.readthedocs.io/en/stable/api/user.html#simple-edit-count
Example:
>>> simple_edit_count("en.wikipedia.org", "Jimbo_Wales") { "project": "en.wikipedia.org", "username": "Jimbo_Wales", "namespace": "all", "user_id": 24, "deleted_edit_count": 424, "live_edit_count": 13751, ..., "elapsed_time": 80.916 }
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.start –
end –
- Returns
-
xtools.user.
time_card
(project: str, username: str) → dict¶ Return the relative distribution of edits made by a user based on hour of the day and day of the week.
Example:
>>> time_card("en.wikipedia.org", "Jimbo_Wales") { "project": "en.wikipedia.org", "username": "Jimbo_Wales", "timecard": [ { "day_of_week": 1, "hour": 0, "value": 83, "scale": 9 }, ... ], }
https://xtools.readthedocs.io/en/stable/api/user.html#time-card
- Parameters
project –
username –
- Returns
-
xtools.user.
top_edits
(project: str, username: str, namespace: Optional[str] = None, page_title: Optional[str] = None) → dict¶ Return the top-edited pages by a user, or all edits made by a user to a specific page.
https://xtools.readthedocs.io/en/stable/api/user.html#top-edits
- Parameters
project –
username –
namespace – one namespace (default is
"0"
, the main one) or"all"
for all of them.page_title – page title. For non-main pages you must either fill the
namespace
parameter or set it to a blank string and use the namespace-prefixed article title.
- Returns
xtools.quote
¶
Endpoints related to quotes. They all return either one Quote object or a sequence of it.
A Quote is a named tuple with id
and text
fields.
https://xtools.readthedocs.io/en/stable/api/quote.html
-
class
xtools.quote.
Quote
(id, text)¶ -
property
id
¶ Alias for field number 0
-
property
text
¶ Alias for field number 1
-
property
-
xtools.quote.
all_quotes
() → Sequence[xtools.quote.Quote]¶ Get all quotes.
https://xtools.readthedocs.io/en/stable/api/quote.html#all-quotes
- Returns
sequence of Quote objects.
-
xtools.quote.
random_quote
() → xtools.quote.Quote¶ Return a random quote.
https://xtools.readthedocs.io/en/stable/api/quote.html#random-quote
- Returns
Quote.
-
xtools.quote.
single_quote
(quote_id: int) → xtools.quote.Quote¶ Get a quote by ID.
https://xtools.readthedocs.io/en/stable/api/quote.html#single-quote
- Parameters
quote_id –
- Returns
Quote.