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 overrides start and end.

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 overrides start and end.

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

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.

Welcome to `xtools`’ documentation!¶

Install¶

Usage¶

`xtools.project`¶

`xtools.page`¶

`xtools.user`¶

`xtools.quote`¶

xtools

Navigation

Related Topics

Welcome to xtools’ documentation!¶

Install¶

Usage¶

xtools.project¶

xtools.page¶

xtools.user¶

xtools.quote¶

Welcome to `xtools`’ documentation!¶

`xtools.project`¶

`xtools.page`¶

`xtools.user`¶

`xtools.quote`¶