Manual:Pywikibot/Cookbook/Basic concepts

Pywikibot Cookbook
Introduction Basic concepts Testing the framework Getting a single page Saving a single page Page generators – working with plenty of pages Working with page histories Working with namespaces Working with users Working with categories Creating and reading lists Working with your watchlist Working with dumps Creating pages based on a pattern

Pywikibot
Quick overview Installation Running on PAWS Running on Windows Running on Toolforge Configuration and scripts user-config.py Global options Generator and filter options i18n Scripts Uses Cookbook Wikidata Non-Wikimedia wikis Development Further help More... »

Throughout the manual and the documentation we speak about MediaWiki rather than Wikipedia and Wikibase rather than Wikidata because these are the underlying software. You may use Pywikibot on other projects of WikiMedia Foundation, any non-WMF wiki and repository on Internet, even on a MediaWiki or Wikibase instance on your home computer or your company wiki. See the right-hand menu for help.

Site

A site is a wiki that you will contact. Usually you work with one site at a time. If you have set your family and language in user-config.py, getting your site (e.g. one language version of Wikipedia) is as simple as site = pywikibot.Site().

You will find more options at https://doc.wikimedia.org/pywikibot/master/api_ref/pywikibot.html#pywikibot.Site

Site is a bit tricky because you don't find its methods directly in the documentation. This is because Site is not a class, rather a factory method that returns class instances. Digging into it you will find that its methods are under BaseSite as well as APISite.

Even more strange is that some of these methods manipulate pages. This is a technical decision of the developers, but you don't have to deal with them, as they are not for direct use. It is interesting to browse the site methods as you may get ideas from them how to use the framework.

>>> import pywikibot
>>> site = pywikibot.Site()
>>> site
APISite("hu", "wikipedia")

This shows that your site is an APISite, but it also inherits methods from BaseSite.

Repository

A data repository is a Wikibase instance; when you work with WMF wikis, it is Wikidata itself. While you can directly work with Wikidata, in which case it will be a site, often you want to connect Wikipedia and Wikidata. So your Wikipedia will be the site and Wikidata the connected data repository. The site knows about its repository, therefore you don't have to write it in your user-config, rather get it as site.data_repository(). (See https://doc.wikimedia.org/pywikibot/master/api_ref/pywikibot.site.html#pywikibot.site._apisite.APISite.data_repository.) However, articles have some direct methods to their Wikidata page, so in most cases you may not have to use the repository at all.

Image repository basically means Commons, at least for WMF wikis.

Continuing the previous code will show that the repository is also a special subclass of BaseSite:

>>> site.data_repository()
DataSite("wikidata", "wikidata")
>>> site.image_repository()
DataSite("commons", "commons")

Commons and Wikidata don't have language versions like Wikipedia, so their language and family is the same.

DataSite object is descibed here.

Page

Page is the most sophisticated entity in Pywikibot as we usually work with pages, and they have several kinds, properties, operations. See:

https://doc.wikimedia.org/pywikibot/master/api_ref/pywikibot.html#pywikibot.Page

Page is a subclass of BasePage, a general concept to represent all kinds of wikipages such as Page, WikibasePage and FlowPage. See:

https://doc.wikimedia.org/pywikibot/master/api_ref/pywikibot.page.html#page.BasePage

In most of your time you are likely to work with Page instances (unless your primary target is Wikidata itself). You won't instantiate BasePage directly, but if you wonder what you can do with a page (such as an article, a talk page or a community noticeboard), you should browse both documentations above.

We have two main approaches to pages: ready-to-use page objects may be obtained from page generators or single pages may be created one by one from the titles. Below we look into both.

Category

Category is a subclass of Page. That means it represents a category with its special methods as well as the category page itself.

User

User is a subclass of Page. That means it represents a user with its special methods as well as the user page itself.

All the above concepts are classes or classlike factories; in the scripts we instantiate them. E.g. site = pywikibot.Site() will create a site instance.

Directory mode and library mode of Pywikibot

See in section Beginning and ending.