diff --git a/.coveragerc b/.coveragerc
new file mode 100644
index 00000000..f55fa189
--- /dev/null
+++ b/.coveragerc
@@ -0,0 +1,25 @@
+# .coveragerc to control coverage.py
+[run]
+branch = True
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+# Have to re-enable the standard pragma
+ pragma: no cover
+
+# Don't complain about missing debug-only code:
+ def __repr__
+
+# Don't complain if tests don't hit defensive assertion code:
+ raise AssertionError
+ raise NotImplementedError
+
+# Don't complain if non-runnable code isn't run:
+ if 0:
+ if __name__ == .__main__.:
+
+# Don't complain about TYPE_CHECKING specific imports:
+ if TYPE_CHECKING:
+
+ignore_errors = True
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 7422f7c8..4fb1a267 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -1,6 +1,15 @@
version: 2
updates:
+ # Maintain dependencies for pip
+ - package-ecosystem: "pip"
+ directory: "/"
+ schedule:
+ interval: "daily"
+ assignees:
+ - "LeMyst"
+ open-pull-requests-limit: 10
+
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
@@ -8,11 +17,13 @@ updates:
interval: "daily"
assignees:
- "LeMyst"
+ open-pull-requests-limit: 10
- # Maintain dependencies for pip
+ # Maintain dependencies for documentation
- package-ecosystem: "pip"
- directory: "/"
+ directory: "/docs/"
schedule:
interval: "daily"
assignees:
- "LeMyst"
+ open-pull-requests-limit: 10
diff --git a/.github/workflows/publish-to-pypi.yml b/.github/workflows/publish-to-pypi.yml
index 58e22ce9..73102b63 100644
--- a/.github/workflows/publish-to-pypi.yml
+++ b/.github/workflows/publish-to-pypi.yml
@@ -11,10 +11,10 @@ jobs:
steps:
- uses: actions/checkout@v3
- - name: Set up Python 3.9
+ - name: Set up Python 3.10
uses: actions/setup-python@v4
with:
- python-version: 3.9
+ python-version: '3.10'
- name: Install pypa/build
run: >-
diff --git a/.github/workflows/python-lint.yml b/.github/workflows/python-lint.yml
new file mode 100644
index 00000000..f415cee4
--- /dev/null
+++ b/.github/workflows/python-lint.yml
@@ -0,0 +1,62 @@
+name: Python Code Quality and Lint
+
+on:
+ push:
+ branches: [ master ]
+ paths:
+ - 'wikibaseintegrator/**.py'
+ - 'test/**.py'
+ pull_request:
+ branches: [ '**' ]
+ paths:
+ - 'wikibaseintegrator/**.py'
+ - 'test/**.py'
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v2.4.0
+
+ - name: Set up Python 3.10
+ uses: actions/setup-python@v2.3.1
+ with:
+ python-version: '3.10'
+
+ - name: Cache pip
+ uses: actions/cache@v3
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+ restore-keys: |
+ ${{ runner.os }}-pip-
+ ${{ runner.os }}-
+
+ - name: Upgrade setup tools
+ run: |
+ python -m pip install --upgrade pip setuptools
+
+ - name: Install dependencies
+ run: |
+ python -m pip install .[dev]
+
+ - name: isort imports check
+ run: |
+ python -m isort --check --diff wikibaseintegrator test
+
+ - name: mypy typing check
+ run: |
+ python -m mypy --install-types --non-interactive
+
+ - name: pylint code linting
+ run: |
+ python -m pylint wikibaseintegrator test || pylint-exit $?
+
+ - name: codespell spell checking
+ run: |
+ codespell wikibaseintegrator test
+
+ - name: flynt string formatter converting
+ run: |
+ python -m flynt -f wikibaseintegrator test
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-pytest.yml
similarity index 69%
rename from .github/workflows/python-package.yml
rename to .github/workflows/python-pytest.yml
index a1f0cb94..92a3b704 100644
--- a/.github/workflows/python-package.yml
+++ b/.github/workflows/python-pytest.yml
@@ -1,45 +1,59 @@
-name: Python package
-
-on:
- push:
- branches: [ master ]
- pull_request:
- branches: [ '**' ]
-
-jobs:
- build:
- name: pytest ${{ matrix.python-version }}
- runs-on: ubuntu-latest
-
- strategy:
- matrix:
- python-version: [ '3.7', '3.8', '3.9', '3.10', '3.11-dev' ]
-
- steps:
- - uses: actions/checkout@v3
-
- - name: Set up Python ${{ matrix.python-version }}
- uses: actions/setup-python@v4
- with:
- python-version: ${{ matrix.python-version }}
-
- - name: Cache pip
- uses: actions/cache@v3
- with:
- path: ~/.cache/pip
- key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
- restore-keys: |
- ${{ runner.os }}-pip-
- ${{ runner.os }}-
-
- - name: Upgrade setup tools
- run: |
- python -m pip install --upgrade pip setuptools
-
- - name: Install dependencies
- run: |
- python -m pip install .[dev]
-
- - name: Test with pytest
- run: |
- python -m pytest
+name: Python pytest
+
+on:
+ push:
+ branches: [ master ]
+ paths:
+ - 'wikibaseintegrator/**.py'
+ - 'test/**.py'
+ - 'setup.cfg'
+ - 'setup.py'
+ - 'requirements.txt'
+ - 'pyproject.toml'
+ pull_request:
+ branches: [ '**' ]
+ paths:
+ - 'wikibaseintegrator/**.py'
+ - 'test/**.py'
+ - 'setup.cfg'
+ - 'setup.py'
+ - 'requirements.txt'
+ - 'pyproject.toml'
+
+jobs:
+ build:
+ name: pytest ${{ matrix.python-version }}
+ runs-on: ubuntu-latest
+
+ strategy:
+ matrix:
+ python-version: [ '3.7', '3.8', '3.9', '3.10' ] # '3.11-dev'
+
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Set up Python ${{ matrix.python-version }}
+ uses: actions/setup-python@v4
+ with:
+ python-version: ${{ matrix.python-version }}
+
+ - name: Cache pip
+ uses: actions/cache@v3
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+ restore-keys: |
+ ${{ runner.os }}-pip-
+ ${{ runner.os }}-
+
+ - name: Upgrade setup tools
+ run: |
+ python -m pip install --upgrade pip setuptools
+
+ - name: Install dependencies
+ run: |
+ python -m pip install .[dev]
+
+ - name: Test with pytest
+ run: |
+ python -m pytest
diff --git a/.gitignore b/.gitignore
index c22045f1..db4a00d4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -157,5 +157,8 @@ fabric.properties
# Idea pylint plugin configuration file
.idea/pylint.xml
+# Completely remove .idea folder
+.idea
+
# Other stuff
/drafts/
diff --git a/.idea/WikibaseIntegrator.iml b/.idea/WikibaseIntegrator.iml
deleted file mode 100644
index 0f6053e6..00000000
--- a/.idea/WikibaseIntegrator.iml
+++ /dev/null
@@ -1,24 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/codeStyles/codeStyleConfig.xml b/.idea/codeStyles/codeStyleConfig.xml
deleted file mode 100644
index df5f35dc..00000000
--- a/.idea/codeStyles/codeStyleConfig.xml
+++ /dev/null
@@ -1,5 +0,0 @@
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/inspectionProfiles/WikibaseIntegrator.xml b/.idea/inspectionProfiles/WikibaseIntegrator.xml
deleted file mode 100644
index c122a9d0..00000000
--- a/.idea/inspectionProfiles/WikibaseIntegrator.xml
+++ /dev/null
@@ -1,50 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml
deleted file mode 100644
index 25c0d868..00000000
--- a/.idea/inspectionProfiles/profiles_settings.xml
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/misc.xml b/.idea/misc.xml
deleted file mode 100644
index 80b44c9f..00000000
--- a/.idea/misc.xml
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/modules.xml b/.idea/modules.xml
deleted file mode 100644
index 7044df13..00000000
--- a/.idea/modules.xml
+++ /dev/null
@@ -1,8 +0,0 @@
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/vagrant.xml b/.idea/vagrant.xml
deleted file mode 100644
index 9b406386..00000000
--- a/.idea/vagrant.xml
+++ /dev/null
@@ -1,7 +0,0 @@
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.idea/vcs.xml b/.idea/vcs.xml
deleted file mode 100644
index b156bfce..00000000
--- a/.idea/vcs.xml
+++ /dev/null
@@ -1,13 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..9da2e983
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+ configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+ - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+ version: "3.8"
+ install:
+ - method: pip
+ path: .
+ extra_requirements:
+ - docs
diff --git a/LICENSE.txt b/LICENSE
similarity index 94%
rename from LICENSE.txt
rename to LICENSE
index 3c42ddc4..09efaf17 100644
--- a/LICENSE.txt
+++ b/LICENSE
@@ -1,6 +1,6 @@
MIT License
-Copyright (c) 2017 The Su Lab, The Scripps Research Institute
+Copyright (c) 2017 Wikibase Integrator contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index 20fdb8fd..65b275bf 100644
--- a/README.md
+++ b/README.md
@@ -1,102 +1,110 @@
# Wikibase Integrator #
+[![PyPi](https://img.shields.io/pypi/v/wikibaseintegrator.svg)](https://pypi.python.org/pypi/wikibaseintegrator)
[![Python package](https://github.com/LeMyst/WikibaseIntegrator/actions/workflows/python-package.yml/badge.svg)](https://github.com/LeMyst/WikibaseIntegrator/actions/workflows/python-package.yml)
[![CodeQL](https://github.com/LeMyst/WikibaseIntegrator/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/LeMyst/WikibaseIntegrator/actions/workflows/codeql-analysis.yml)
-[![Pyversions](https://img.shields.io/pypi/pyversions/wikibaseintegrator.svg)](https://pypi.python.org/pypi/wikibaseintegrator)
-[![PyPi](https://img.shields.io/pypi/v/wikibaseintegrator.svg)](https://pypi.python.org/pypi/wikibaseintegrator)
-
-# Breaking changes in future major version #
+[![Pyversions](https://img.shields.io/pypi/implementation/wikibaseintegrator.svg)](https://pypi.python.org/pypi/wikibaseintegrator)
+[![Read the Docs](https://readthedocs.org/projects/pip/badge/?version=latest&style=flat)](https://wikibaseintegrator.readthedocs.io)
-A complete rewrite of the core of WikibaseIntegrator is in progress. You can track the evolution and ask questions in
-the related Pull Request [#152](https://github.com/LeMyst/WikibaseIntegrator/pull/152). The changes will break
-compatibility with existing scripts.
+Wikibase Integrator is a python package whose purpose is to manipulate data present on a Wikibase instance (like
+Wikidata).
-It offers a new object-oriented approach, a better readability and a support of Property, Lexeme and MediaInfo entities.
+# Breaking changes in v0.12 #
-The new version is currently in "beta" state, but I invite people to start using it. If you want to install it, you can
-use this command in your project to get the latest pre-release:
+A complete rewrite of the WikibaseIntegrator core has been done in v0.12 which has led to some important changes.
-```bash
-python -m pip install --pre wikibaseintegrator
-```
+It offers a new object-oriented approach, better code readability and support for Property, Lexeme and MediaInfo
+entities (in addition to Item).
-If you want to avoid an unwanted upgrade to the v0.12, you can put this line in your requirements.txt:
+If you want to stay on v0.11.x, you can put this line in your requirements.txt:
```
wikibaseintegrator~=0.11.3
```
-I will continue to bug-fixes the current version (v0.11) even after the release of v0.12+.
-
-
+---
- [WikibaseIntegrator / WikidataIntegrator](#wikibaseintegrator--wikidataintegrator)
+- [Documentation](#documentation)
- [Installation](#installation)
- [Using a Wikibase instance](#using-a-wikibase-instance)
+ - [Wikimedia Foundation User-Agent policy](#wikimedia-foundation-user-agent-policy)
- [The Core Parts](#the-core-parts)
- - [wbi_core.ItemEngine](#wbi_coreitemengine)
- - [wbi_functions](#wbi_functions)
- - [Use MediaWiki API](#use-mediawiki-api)
- - [wbi_login.Login](#wbi_loginlogin)
+ - [Entity manipulation](#entity-manipulation)
+ - [wbi_login](#wbi_login)
- [Login using OAuth1 or OAuth2](#login-using-oauth1-or-oauth2)
+ - [As a bot](#as-a-bot)
+ - [To impersonate a user (OAuth 1.0a)](#to-impersonate-a-user-oauth-10a)
+ - [Login with a bot password](#login-with-a-bot-password)
- [Login with a username and a password](#login-with-a-username-and-a-password)
- [Wikibase Data Types](#wikibase-data-types)
+ - [Structured Data on Commons](#structured-data-on-commons)
+ - [Retrieve data](#retrieve-data)
+ - [Write data](#write-data)
- [Helper Methods](#helper-methods)
+ - [Use MediaWiki API](#use-mediawiki-api)
- [Execute SPARQL queries](#execute-sparql-queries)
- - [Use Mediawiki API](#use-mediawiki-api)
- [Wikibase search entities](#wikibase-search-entities)
- [Merge Wikibase items](#merge-wikibase-items)
- [Examples (in "normal" mode)](#examples-in-normal-mode)
- - [A Minimal Bot](#a-minimal-bot)
- - [A Minimal Bot for Mass Import](#a-minimal-bot-for-mass-import)
+ - [Create a new Item](#create-a-new-item)
+ - [Modify an existing item](#modify-an-existing-item)
+ - [A bot for Mass Import](#a-bot-for-mass-import)
- [Examples (in "fast run" mode)](#examples-in-fast-run-mode)
+- [Debugging](#debugging)
# WikibaseIntegrator / WikidataIntegrator #
-WikibaseIntegrator (wbi) is a fork from [WikidataIntegrator](https://github.com/SuLab/WikidataIntegrator) (wdi) whose
-purpose is to be focused on Wikibase compatibility. There have been many improvements that have led to breaking changes
-in the code. Refer to the [release notes](https://github.com/LeMyst/WikibaseIntegrator/releases) to find out what has
+WikibaseIntegrator (wbi) is a fork of [WikidataIntegrator](https://github.com/SuLab/WikidataIntegrator) (wdi) whose
+purpose is to focus on compatibility with Wikibase. There have been many improvements which have led to radical changes
+in the code. See the [release notes](https://github.com/LeMyst/WikibaseIntegrator/releases) to find out what has
changed.
+# Documentation #
+
+A (basic) documentation generated from the python source code is available on
+the [Read the Docs website](https://wikibaseintegrator.readthedocs.io/).
+
# Installation #
-The easiest way to install WikibaseIntegrator is using `pip`. WikibaseIntegrator supports Python 3.7 and higher. If
-Python 2 is installed `pip` will lead to an error indicating missing dependencies.
+The easiest way to install WikibaseIntegrator is to use the `pip` package manager. WikibaseIntegrator supports Python
+3.7 and above. If Python 2 is installed, `pip` will lead to an error indicating missing dependencies.
```bash
python -m pip install wikibaseintegrator
```
-You can also clone the repo and execute with administrator rights or install into a virtualenv.
+You can also clone the repo and run it with administrator rights or install it in a virtualenv.
```bash
git clone https://github.com/LeMyst/WikibaseIntegrator.git
cd WikibaseIntegrator
-python -m pip install pip setuptools
+python -m pip install --upgrade pip setuptools
python -m pip install .
```
-To test for correct installation, start a Python console and execute the following (Will retrieve the Wikidata item
-for ['Human'](https://www.wikidata.org/entity/Q5)):
+To check that the installation is correct, launch a Python console and run the following code (which will retrieve the
+Wikidata element for [Human](https://www.wikidata.org/entity/Q5)):
```python
-from wikibaseintegrator import wbi_core
+from wikibaseintegrator import WikibaseIntegrator
-my_first_wikidata_item = wbi_core.ItemEngine(item_id='Q5')
+wbi = WikibaseIntegrator()
+my_first_wikidata_item = wbi.item.get(entity_id='Q5')
# to check successful installation and retrieval of the data, you can print the json representation of the item
-print(my_first_wikidata_item.get_json_representation())
+print(my_first_wikidata_item.get_json())
```
# Using a Wikibase instance #
-WikibaseIntegrator use Wikidata as default endpoint. To use a Wikibase instance instead, you can overload the
-wbi_config.
+WikibaseIntegrator uses Wikidata as default endpoint. To use another instance of Wikibase instead, you can override the
+wbi_config module.
An example for a Wikibase instance installed
with [wikibase-docker](https://github.com/wmde/wikibase-release-pipeline/tree/main/example), add this to the top of your
@@ -110,79 +118,65 @@ wbi_config['SPARQL_ENDPOINT_URL'] = 'http://localhost:8834/proxy/wdqs/bigdata/na
wbi_config['WIKIBASE_URL'] = 'http://wikibase.svc'
```
-You can find more default parameters in the file wbi_config.py
+You can find more default settings in the file wbi_config.py
-# The Core Parts #
+## Wikimedia Foundation User-Agent policy ##
-wbi_core supports two modes it can be operated in, a normal mode, updating each item at a time and, a fast run mode,
-which is pre-loading data locally and then just updating items if the new data provided is differing from what is in
-Wikidata. The latter mode allows for great speedups (measured up to 9x) when tens of thousand of Wikidata items need to
-be checked if they require updates but only a small number will finally be updated, a situation usually encountered when
-keeping Wikidata in sync with an external resource.
+If you interact with a Wikibase instance hosted by the Wikimedia Foundation (like Wikidata, Wikimedia Commons, etc.),
+it's highly advised to follow the User-Agent policy that you can find on the
+page [User-Agent policy](https://meta.wikimedia.org/wiki/User-Agent_policy)
+of the Wikimedia Meta-Wiki.
-wbi_core consists of a central class called ItemEngine and Login for authenticating with a MediaWiki instance (like
-Wikidata).
+You can set a complementary User-Agent by modifying the variable `wbi_config['USER_AGENT']` in wbi_config.
-## wbi_core.ItemEngine ##
+For example, with your library name and contact information:
-This is the central class which does all the heavy lifting.
+```python
+from wikibaseintegrator.wbi_config import config as wbi_config
-Features:
+wbi_config['USER_AGENT'] = 'MyWikibaseBot/1.0 (https://www.wikidata.org/wiki/User:MyUsername)'
+```
-* Load a Wikibase item based on data to be written (e.g. a unique central identifier)
-* Load a Wikibase item based on its Wikibase item id (aka QID)
-* Checks for conflicts automatically (e.g. multiple items carrying a unique central identifier will trigger an
- exception)
-* Checks automatically if the correct item has been loaded by comparing it to the data provided
-* All Wikibase data types implemented
-* A dedicated wbi_core.ItemEngine.write() method allows loading and consistency checks of data before any write to
- Wikibase is performed
-* Full access to the whole Wikibase item as a JSON document
+# The Core Parts #
-There are two ways of working with Wikibase items:
+WikibaseIntegrator supports two modes in which it can be used, a normal mode, updating each item at a time, and a fast
+run mode, which preloads some data locally and then just updates items if the new data provided differs from Wikidata.
+The latter mode allows for great speedups when tens of thousands of Wikidata elements need to be checked for updates,
+but only a small number will eventually be updated, a situation typically encountered when synchronising Wikidata with
+an external resource.
-* A user can provide data, and ItemEngine will search for and load/modify an existing item or create a new one, solely
- based on the data provided (preferred). This also performs consistency checks based on a set of SPARQL queries.
-* A user can work with a selected QID to specifically modify the data on the item. This requires that the user knows
- what he/she is doing and should only be used with great care, as this does not perform consistency checks.
+## Entity manipulation ##
-## wbi_functions ##
+WikibaseIntegrator supports the manipulation of Item, Property, Lexeme and MediaInfo entities through these classes:
-wbi_functions provides a set of static functions to request or manipulate data from MediaWiki API or SPARQL Service.
+* wikibaseintegrator.entities.item.Item
+* wikibaseintegrator.entities.property.Property
+* wikibaseintegrator.entities.lexeme.Lexeme
+* wikibaseintegrator.entities.mediainfo.MediaInfo
Features:
-* Minimize the number of HTTP requests for reads and writes to improve performance
-* Method to easily execute [SPARQL](https://query.wikidata.org) queries on the Wikibase SPARQL endpoint.
-
-### Use MediaWiki API ###
-
-WikibaseIntegrator don't have functions to make API call to non-wikibase actions. You can
-use `wbi_functions.mediawiki_api_call_helper()` to make a custom call.
+* Loading a Wikibase entity based on its Wikibase entity ID.
+* All Wikibase data types are implemented (and some data types implemented by extensions).
+* Full access to the entire Wikibase entity in the form of a JSON dict representation.
-Example to get the last two revisions of entity Q42 :
+## wbi_login ##
-```python
-from wikibaseintegrator import wbi_functions
+`wbi_login` provides the login functionality and also stores the cookies and edit tokens required (For security reasons,
+every MediaWiki edit requires an edit token). There is multiple methods to login:
-data = {
- 'action': 'query',
- 'prop': 'revisions',
- 'titles': 'Q42',
- 'rvlimit': 2,
- 'rvprop': 'ids|timestamp|comment|user',
- 'rvslots': 'main'
-}
+* `wbi_login.OAuth2(consumer_token, consumer_secret)` (recommended)
+* `wbi_login.OAuth1(consumer_token, consumer_secret, access_token, access_secret)`
+* `wbi_login.Clientlogin(user, password)`
+* `wbi_login.Login(user, password)`
-print(wbi_functions.mediawiki_api_call_helper(data, allow_anonymous=True))
-```
-
-## wbi_login.Login ##
+There is more parameters available. If you want to authenticate on another instance than Wikidata, you can set the
+mediawiki_api_url, mediawiki_rest_url or mediawiki_index_url. Read the documentation for more information.
### Login using OAuth1 or OAuth2 ###
-OAuth is the authentication method recommended by the Mediawiki developers. It can be used for authenticating a bot or
-to use WBI as a backend for an application.
+OAuth is the authentication method recommended by the MediaWiki developers. It can be used to authenticate a bot or to
+use WBI as a backend for an application.
#### As a bot ####
@@ -190,185 +184,285 @@ If you want to use WBI with a bot account, you should use OAuth as
an [Owner-only consumer](https://www.mediawiki.org/wiki/OAuth/Owner-only_consumers). This allows to use the
authentication without the "continue oauth" step.
-The first step is to request a new OAuth consumer on your Mediawiki instance on the page "Special:
-OAuthConsumerRegistration", the "Owner-only" (or "This consumer is for use only by ...") has to be checked. You will get
-a consumer key, consumer secret, access token and access secret.
+The first step is to request a new OAuth consumer on your MediaWiki instance on the page
+"Special:OAuthConsumerRegistration", the "Owner-only" (or "This consumer is for use only by ...") has to be checked and
+the correct version of the OAuth protocol must be set (OAuth 2.0). You will get a consumer token and consumer secret
+(and an access token and access secret if you chose OAuth 1.0a). For a Wikimedia instance (like Wikidata), you need to
+use the [Meta-Wiki website](https://meta.wikimedia.org/wiki/Special:OAuthConsumerRegistration).
-Example if you use OAuth 1.0a:
+Example if you use OAuth 2.0:
```python
from wikibaseintegrator import wbi_login
-login_instance = wbi_login.Login(consumer_key='', consumer_secret='',
- access_token='', access_secret='')
+login_instance = wbi_login.OAuth2(consumer_token='', consumer_secret='')
```
-Example if you use OAuth 2.0:
+Example if you use OAuth 1.0a:
```python
from wikibaseintegrator import wbi_login
-login_instance = wbi_login.Login(client_id='', client_secret='')
+login_instance = wbi_login.OAuth1(consumer_token='', consumer_secret='',
+ access_token='', access_secret='')
```
#### To impersonate a user (OAuth 1.0a) ####
-If WBI should be used as a backend for a webapp, the script should use OAuth for authentication, WBI supports this, you
-just need to specify consumer key and consumer secret when instantiating `wbi_login.Login`. In contrast to username and
-password login, OAuth is a 2 steps process as manual user confirmation for OAuth login is required. This means that the
-method `wbi_login.Login.continue_oauth()` needs to be called after creating the `wbi_login.Login` instance.
+If WBI is to be used as a backend for a web application, the script must use OAuth for authentication, WBI supports
+this, you just need to specify consumer key and consumer secret when instantiating `wbi_login.Login`. Unlike login by
+username and password, OAuth is a 2-step process, as manual confirmation of the user for the OAuth login is required.
+This means that the `wbi_login.OAuth1.continue_oauth()` method must be called after creating the `wbi_login.Login`
+instance.
Example:
```python
from wikibaseintegrator import wbi_login
-login_instance = wbi_login.Login(consumer_key='', consumer_secret='')
-login_instance.continue_oauth()
+login_instance = wbi_login.OAuth1(consumer_token='', consumer_secret='')
+login_instance.continue_oauth(oauth_callback_data='')
```
-The method `wbi_login.Login.continue_oauth()` will either prompt the user for a callback URL (normal bot runs), or it
-will take a parameter so in the case of WBI being used as a backend for e.g. a web app, where the callback will provide
-the authentication information directly to the backend and so no copy and paste of the callback URL is required.
+The `wbi_login.OAuth1.continue_oauth()` method will either ask the user for a callback URL (normal bot execution) or
+take a parameter. Thus, in the case where WBI is used as a backend for a web application for example, the callback will
+provide the authentication information directly to the backend and thus no copy and paste of the callback URL is needed.
+
+### Login with a bot password ###
+
+It's a good practice to use [Bot password](https://www.mediawiki.org/wiki/Manual:Bot_passwords) instead of simple
+username and password, this allows limiting the permissions given to the bot.
+
+```python
+from wikibaseintegrator import wbi_login
+
+login_instance = wbi_login.Login(user='', password='')
+```
### Login with a username and a password ###
-`wbi_login.Login` provides the login functionality and also stores the cookies and edit tokens required (For security
-reasons, every Mediawiki edit requires an edit token). The constructor takes two essential parameters, username and
-password. Additionally, the server (default wikidata.org), and the token renewal periods can be specified. It's a good
-practice to use [Bot password](https://www.mediawiki.org/wiki/Manual:Bot_passwords) instead of simple username and
-password, this allows limiting the permissions given to the bot.
+If you want to log in with your user account, you can use the "clientlogin" authentication method. This method is not
+recommended.
```python
from wikibaseintegrator import wbi_login
-login_instance = wbi_login.Login(user='', pwd='')
+login_instance = wbi_login.Clientlogin(user='', password='')
```
## Wikibase Data Types ##
Currently, Wikibase supports 17 different data types. The data types are represented as their own classes in
-wbi_datatype. Each data types has its specialties, which means that some of them require special parameters (e.g. Globe
-Coordinates).
+wikibaseintegrator.datatypes. Each datatype has its own peculiarities, which means that some of them require special
+parameters (e.g. Globe Coordinates). They are available under the namespace `wikibase.datatypes`.
The data types currently implemented:
-* wbi_datatype.CommonsMedia
-* wbi_datatype.EDTF
-* wbi_datatype.ExternalID
-* wbi_datatype.Form
-* wbi_datatype.GeoShape
-* wbi_datatype.GlobeCoordinate
-* wbi_datatype.ItemID
-* wbi_datatype.Lexeme
-* wbi_datatype.LocalMedia
-* wbi_datatype.Math
-* wbi_datatype.MonolingualText
-* wbi_datatype.MusicalNotation
-* wbi_datatype.Property
-* wbi_datatype.Quantity
-* wbi_datatype.Sense
-* wbi_datatype.String
-* wbi_datatype.TabularData
-* wbi_datatype.Time
-* wbi_datatype.Url
+* CommonsMedia
+* ExternalID
+* Form
+* GeoShape
+* GlobeCoordinate
+* Item
+* Lexeme
+* Math
+* MonolingualText
+* MusicalNotation
+* Property
+* Quantity
+* Sense
+* String
+* TabularData
+* Time
+* URL
+
+Two additional data types are also implemented but require the installation of the MediaWiki extension to work properly:
+
+* extra.EDTF ([Wikibase EDTF](https://www.mediawiki.org/wiki/Extension:Wikibase_EDTF))
+* extra.LocalMedia ([Wikibase Local Media](https://www.mediawiki.org/wiki/Extension:Wikibase_Local_Media))
For details of how to create values (=instances) with these data types, please (for now) consult the docstrings in the
-source code. Of note, these data type instances hold the values and, if specified, data type instances for references
-and qualifiers. Furthermore, calling the get_value() method of an instance returns either an integer, a string or a
-tuple, depending on the complexity of the data type.
+source code or the documentation website. Of note, these data type instances hold the values and, if specified, data
+type instances for references and qualifiers.
-# Helper Methods #
+## Structured Data on Commons ##
-## Execute SPARQL queries ##
+WikibaseIntegrator supports SDC (Structured Data on Commons) to update a media file hosted on Wikimedia Commons.
+
+### Retrieve data ###
-The method `wbi_core.ItemEngine.execute_sparql_query()` allows you to execute SPARQL queries without a hassle. It takes
-the actual query string (query), optional prefixes (prefix) if you do not want to use the standard prefixes of Wikidata,
-the actual entpoint URL (endpoint), and you can also specify a user agent for the http header sent to the SPARQL
-server (user_agent). The latter is very useful to let the operators of the endpoint know who you are, especially if you
-execute many queries on the endpoint. This allows the operators of the endpoint to contact you (e.g. specify an email
-address, or the URL to your bot code repository.)
+```python
+from wikibaseintegrator import WikibaseIntegrator
+
+wbi = WikibaseIntegrator()
+media = wbi.mediainfo.get('M16431477')
-## Use Mediawiki API ##
+# Retrieve the first "depicts" (P180) claim
+print(media.claims.get('P180')[0].mainsnak.datavalue['value']['id'])
+```
-The method `wbi_functions.mediawiki_api_call_helper()` allows you to execute MediaWiki API POST call. It takes a
-mandatory data array (data) and multiple optionals parameters like a login object of type wbi_login.Login, a
-mediawiki_api_url string if the Mediawiki is not Wikidata, a user_agent string to set a custom HTTP User Agent header,
-and an allow_anonymous boolean to force authentication.
+### Write data ###
+
+```python
+from wikibaseintegrator import WikibaseIntegrator
+from wikibaseintegrator.datatypes import Item
+
+wbi = WikibaseIntegrator()
+media = wbi.mediainfo.get('M16431477')
+
+# Add the "depicts" (P180) claim
+media.claims.add(Item(prop_nr='P180', value='Q3146211'))
+
+media.write()
+```
+
+# Helper Methods #
+
+## Use MediaWiki API ##
+
+The method `wbi_helpers.mediawiki_api_call_helper()` allows you to execute MediaWiki API POST call. It takes a mandatory
+data array (data) and multiple optionals parameters like a login object of type wbi_login.Login, a mediawiki_api_url
+string if the MediaWiki is not Wikidata, a user_agent string to set a custom HTTP User Agent header, and an
+allow_anonymous boolean to force authentication.
Example:
Retrieve last 10 revisions from Wikidata element Q2 (Earth):
```python
-from wikibaseintegrator import wbi_functions
+from wikibaseintegrator import wbi_helpers
-query = {
+data = {
'action': 'query',
'prop': 'revisions',
'titles': 'Q2',
'rvlimit': 10
}
-print(wbi_functions.mediawiki_api_call_helper(query, allow_anonymous=True))
+print(wbi_helpers.mediawiki_api_call_helper(data=data, allow_anonymous=True))
```
+## Execute SPARQL queries ##
+
+The method `wbi_helpers.execute_sparql_query()` allows you to execute SPARQL queries without a hassle. It takes the
+actual query string (query), optional prefixes (prefix) if you do not want to use the standard prefixes of Wikidata, the
+actual endpoint URL (endpoint), and you can also specify a user agent for the http header sent to the SPARQL server (
+user_agent). The latter is very useful to let the operators of the endpoint know who you are, especially if you execute
+many queries on the endpoint. This allows the operators of the endpoint to contact you (e.g. specify an email address,
+or the URL to your bot code repository.)
+
## Wikibase search entities ##
-The method `wbi_core.ItemEngine.search_entities()` allows for string search in a Wikibase instance. This means that
-labels, descriptions and aliases can be searched for a string of interest. The method takes five arguments: The actual
-search string (search_string), an optional server (mediawiki_api_url, in case the Wikibase instance used is not
-Wikidata), an optional user_agent, an optional max_results (default 500), an optional language (default 'en'), and an
-option dict_id_label to return a dict of item id and label as a result.
+The method `wbi_helpers.search_entities()` allows for string search in a Wikibase instance. This means that labels,
+descriptions and aliases can be searched for a string of interest. The method takes five arguments: The actual search
+string (search_string), an optional server (mediawiki_api_url, in case the Wikibase instance used is not Wikidata), an
+optional user_agent, an optional max_results (default 500), an optional language (default 'en'), and an option
+dict_id_label to return a dict of item id and label as a result.
## Merge Wikibase items ##
Sometimes, Wikibase items need to be merged. An API call exists for that, and wbi_core implements a method accordingly.
-`wbi_functions.merge_items()` takes five arguments:
-the QID of the item which should be merged into another item (from_id), the QID of the item the first item should be
-merged into (to_id), a login object of type wbi_login.Login to provide the API call with the required authentication
-information, a server (mediawiki_api_url) if the Wikibase instance is not Wikidata and a flag for ignoring merge
-conflicts (ignore_conflicts). The last parameter will do a partial merge for all statements which do not conflict. This
-should generally be avoided because it leaves a crippled item in Wikibase. Before a merge, any potential conflicts
-should be resolved first.
+`wbi_helpers.merge_items()` takes five arguments:
+
+* the QID of the item which should be merged into another item (from_id)
+* the QID of the item the first item should be merged into (to_id)
+* a login object of type wbi_login.Login to provide the API call with the required authentication information
+* a boolean if the changes need to be marked as made by a bot (is_bot)
+* a flag for ignoring merge conflicts (ignore_conflicts), will do a partial merge for all statements which do not
+ conflict. This should generally be avoided because it leaves a crippled item in Wikibase. Before a merge, any
+ potential conflicts should be resolved first.
# Examples (in "normal" mode) #
-## A Minimal Bot ##
+In order to create a minimal bot based on wbi_core, two things are required:
+
+* A datatype object containing a value.
+* An entity object (Item/Property/Lexeme/...) which takes the data, does the checks and performs write.
+
+An optional Login object can be used to be authenticated on the Wikibase instance.
+
+## Create a new Item ##
+
+```python
+from wikibaseintegrator import wbi_login, WikibaseIntegrator
+from wikibaseintegrator.datatypes import ExternalID
+from wikibaseintegrator.wbi_config import config as wbi_config
+
+wbi_config['USER_AGENT'] = 'MyWikibaseBot/1.0 (https://www.wikidata.org/wiki/User:MyUsername)'
+
+# login object
+login_instance = wbi_login.OAuth2(consumer_token='', consumer_secret='')
+
+wbi = WikibaseIntegrator(login=login_instance)
+
+# data type object, e.g. for a NCBI gene entrez ID
+entrez_gene_id = ExternalID(value='', prop_nr='P351')
+
+# data goes into a list, because many data objects can be provided to
+data = [entrez_gene_id]
+
+# Create a new item
+item = wbi.item.new()
-In order to create a minimal bot based on wbi_core, three things are required:
+# Set an english label
+item.labels.set(language='en', value='Newly created item')
+
+# Set a French description
+item.descriptions.set(language='fr', value='Une description un peu longue')
+
+item.claims.add(data)
+item.write()
+```
-* A login object, as described above.
-* A data type object containing a value.
-* A ItemEngine object which takes the data, does the checks and performs write.
+## Modify an existing item ##
```python
-from wikibaseintegrator import wbi_core, wbi_login, wbi_datatype
+from wikibaseintegrator import wbi_login, WikibaseIntegrator
+from wikibaseintegrator.datatypes import ExternalID
+from wikibaseintegrator.wbi_enums import ActionIfExists
+from wikibaseintegrator.wbi_config import config as wbi_config
+
+wbi_config['USER_AGENT'] = 'MyWikibaseBot/1.0 (https://www.wikidata.org/wiki/User:MyUsername)'
# login object
-login_instance = wbi_login.Login(user='', pwd='')
+login_instance = wbi_login.OAuth2(consumer_token='', consumer_secret='')
+
+wbi = WikibaseIntegrator(login=login_instance)
# data type object, e.g. for a NCBI gene entrez ID
-entrez_gene_id = wbi_datatype.String(value='', prop_nr='P351')
+entrez_gene_id = ExternalID(value='', prop_nr='P351')
# data goes into a list, because many data objects can be provided to
data = [entrez_gene_id]
-# Search for and then edit/create new item
-wd_item = wbi_core.ItemEngine(data=data)
-wd_item.write(login_instance)
+# Search and then edit an Item
+item = wbi.item.get(entity_id='Q141806')
+
+# Set an english label but don't modify it if there is already an entry
+item.labels.set(language='en', value='An updated item', action_if_exists=ActionIfExists.KEEP)
+
+# Set a French description and replace the existing one
+item.descriptions.set(language='fr', value='Une description un peu longue', action_if_exists=ActionIfExists.REPLACE_ALL)
+
+item.claims.add(data)
+item.write()
```
-## A Minimal Bot for Mass Import ##
+## A bot for Mass Import ##
An enhanced example of the previous bot just puts two of the three things into a 'for loop' and so allows mass creation,
or modification of items.
```python
-from wikibaseintegrator import wbi_core, wbi_login, wbi_datatype
+from wikibaseintegrator import WikibaseIntegrator, wbi_login
+from wikibaseintegrator.datatypes import ExternalID, Item, String, Time
+from wikibaseintegrator.wbi_config import config as wbi_config
+from wikibaseintegrator.wbi_enums import WikibaseDatePrecision
+
+wbi_config['USER_AGENT'] = 'MyWikibaseBot/1.0 (https://www.wikidata.org/wiki/User:MyUsername)'
# login object
-login_instance = wbi_login.Login(user='', pwd='')
+login_instance = wbi_login.OAuth2(consumer_token='', consumer_secret='')
# We have raw data, which should be written to Wikidata, namely two human NCBI entrez gene IDs mapped to two Ensembl Gene IDs
raw_data = {
@@ -376,39 +470,42 @@ raw_data = {
'1029': 'ENST00000498124'
}
+wbi = WikibaseIntegrator(login=login_instance)
+
for entrez_id, ensembl in raw_data.items():
# add some references
references = [
[
- wbi_datatype.ItemID(value='Q20641742', prop_nr='P248', is_reference=True),
- wbi_datatype.Time(time='+2020-02-08T00:00:00Z', prop_nr='P813', is_reference=True),
- wbi_datatype.ExternalID(value='1017', prop_nr='P351', is_reference=True)
+ Item(value='Q20641742', prop_nr='P248'),
+ Time(time='+2020-02-08T00:00:00Z', prop_nr='P813', precision=WikibaseDatePrecision.DAY),
+ ExternalID(value='1017', prop_nr='P351')
]
]
# data type object
- entrez_gene_id = wbi_datatype.String(value=entrez_id, prop_nr='P351', references=references)
- ensembl_transcript_id = wbi_datatype.String(value=ensembl, prop_nr='P704', references=references)
+ entrez_gene_id = String(value=entrez_id, prop_nr='P351', references=references)
+ ensembl_transcript_id = String(value=ensembl, prop_nr='P704', references=references)
# data goes into a list, because many data objects can be provided to
data = [entrez_gene_id, ensembl_transcript_id]
# Search for and then edit/create new item
- wd_item = wbi_core.ItemEngine(data=data)
- wd_item.write(login_instance)
+ item = wbi.item.new()
+ item.claims.add(data)
+ item.write()
```
# Examples (in "fast run" mode) #
In order to use the fast run mode, you need to know the property/value combination which determines the data corpus you
would like to operate on. E.g. for operating on human genes, you need to know
-that [P351](https://www.wikidata.org/entity/P351) is the NCBI entrez gene ID and you also need to know that you are
+that [P351](https://www.wikidata.org/entity/P351) is the NCBI Entrez Gene ID and you also need to know that you are
dealing with humans, best represented by the [found in taxon property (P703)](https://www.wikidata.org/entity/P703) with
the value [Q15978631](https://www.wikidata.org/entity/Q15978631) for Homo sapiens.
IMPORTANT: In order for the fast run mode to work, the data you provide in the constructor must contain at least one
-unique value/id only present on one Wikidata item, e.g. an NCBI entrez gene ID, Uniprot ID, etc. Usually, these would be
-the same unique core properties used for defining domains in wbi_core, e.g. for genes, proteins, drugs or your custom
+unique value/id only present on one Wikidata element, e.g. an NCBI entrez gene ID, Uniprot ID, etc. Usually, these would
+be the same unique core properties used for defining domains in wbi_core, e.g. for genes, proteins, drugs or your custom
domains.
Below, the normal mode run example from above, slightly modified, to meet the requirements for the fast run mode. To
@@ -417,18 +514,22 @@ holding the properties to filter for as keys, and the item QIDs as dict values.
just provide an empty string. For the above example, the dictionary looks like this:
```python
-fast_run_base_filter = {'P351': '', 'P703': 'Q15978631'}
+from wikibaseintegrator.datatypes import ExternalID, Item
+
+fast_run_base_filter = [ExternalID(prop_nr='P351'), Item(prop_nr='P703', value='Q15978631')]
```
The full example:
```python
-from wikibaseintegrator import wbi_core, wbi_login, wbi_datatype
+from wikibaseintegrator import WikibaseIntegrator, wbi_login
+from wikibaseintegrator.datatypes import ExternalID, Item, String, Time
+from wikibaseintegrator.wbi_enums import WikibaseDatePrecision
# login object
-login_instance = wbi_login.Login(user='', pwd='')
+login = wbi_login.OAuth2(consumer_token='', consumer_secret='')
-fast_run_base_filter = {'P351': '', 'P703': 'Q15978631'}
+fast_run_base_filter = [ExternalID(prop_nr='P351'), Item(prop_nr='P703', value='Q15978631')]
fast_run = True
# We have raw data, which should be written to Wikidata, namely two human NCBI entrez gene IDs mapped to two Ensembl Gene IDs
@@ -442,24 +543,38 @@ for entrez_id, ensembl in raw_data.items():
# add some references
references = [
[
- wbi_datatype.ItemID(value='Q20641742', prop_nr='P248', is_reference=True),
- wbi_datatype.Time(time='+2020-02-08T00:00:00Z', prop_nr='P813', is_reference=True),
- wbi_datatype.ExternalID(value='1017', prop_nr='P351', is_reference=True)
+ Item(value='Q20641742', prop_nr='P248')
+ ],
+ [
+ Time(time='+2020-02-08T00:00:00Z', prop_nr='P813', precision=WikibaseDatePrecision.DAY),
+ ExternalID(value='1017', prop_nr='P351')
]
]
# data type object
- entrez_gene_id = wbi_datatype.String(value=entrez_id, prop_nr='P351', references=references)
- ensembl_transcript_id = wbi_datatype.String(value=ensembl, prop_nr='P704', references=references)
+ entrez_gene_id = String(value=entrez_id, prop_nr='P351', references=references)
+ ensembl_transcript_id = String(value=ensembl, prop_nr='P704', references=references)
# data goes into a list, because many data objects can be provided to
data = [entrez_gene_id, ensembl_transcript_id]
# Search for and then edit/create new item
- wd_item = wbi_core.ItemEngine(data=data, fast_run=fast_run, fast_run_base_filter=fast_run_base_filter)
- wd_item.write(login_instance)
+ wb_item = WikibaseIntegrator(login=login).item.new()
+ wb_item.add_claims(claims=data)
+ wb_item.init_fastrun(base_filter=fast_run_base_filter)
+ wb_item.write()
```
-Note: Fastrun mode checks for equality of property/value pairs, qualifers (not including qualifier attributes), labels,
+Note: Fastrun mode checks for equality of property/value pairs, qualifiers (not including qualifier attributes), labels,
aliases and description, but it ignores references by default!
-References can be checked in fast run mode by setting `fast_run_use_refs` to `True`.
+References can be checked in fast run mode by setting `use_refs` to `True`.
+
+# Debugging #
+
+You can enable debugging by adding this piece of code to the top of your project:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+```
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..ba501f6f
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+SOURCEDIR = source
+BUILDDIR = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..216bff58
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,5 @@
+# Sphinx-apidoc
+
+```shell
+sphinx-apidoc.exe -e -f -o docs\source .\wikibaseintegrator\ -t docs\source\_templates
+```
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 00000000..6247f7e2
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 00000000..43dea041
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,6 @@
+Sphinx~=4.5.0
+readthedocs-sphinx-ext~=2.1.5
+sphinx-rtd-theme~=1.0.0
+sphinx_github_changelog~=1.2.0
+m2r2~=0.3.2
+sphinx-autodoc-typehints==1.18.1
diff --git a/docs/source/_templates/module.rst_t b/docs/source/_templates/module.rst_t
new file mode 100644
index 00000000..d886dcfb
--- /dev/null
+++ b/docs/source/_templates/module.rst_t
@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- [basename] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+ :{{ option }}:
+{%- endfor %}
+
diff --git a/docs/source/_templates/package.rst_t b/docs/source/_templates/package.rst_t
new file mode 100644
index 00000000..2eb85377
--- /dev/null
+++ b/docs/source/_templates/package.rst_t
@@ -0,0 +1,48 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+ :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+ :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+ {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{%- if subpackages %}
+Submodules
+----------
+{%- endif %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
diff --git a/docs/source/_templates/toc.rst_t b/docs/source/_templates/toc.rst_t
new file mode 100644
index 00000000..846c6b16
--- /dev/null
+++ b/docs/source/_templates/toc.rst_t
@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+ :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+ {{ docname }}
+{%- endfor %}
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
new file mode 100644
index 00000000..85fb4e01
--- /dev/null
+++ b/docs/source/changelog.rst
@@ -0,0 +1,9 @@
+.. _changelog:
+
+Changelog
+*********
+
+.. changelog::
+ :changelog-url: https://wikibaseintegrator.readthedocs.io/en/stable/#changelog
+ :github: https://github.com/LeMyst/WikibaseIntegrator/releases/
+ :pypi: https://pypi.org/project/wikibaseintegrator/
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 00000000..a1ddd9dd
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+#
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+from datetime import datetime
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc',
+ 'sphinx.ext.mathjax',
+ 'sphinx.ext.viewcode',
+ 'sphinx_rtd_theme',
+ 'sphinx_github_changelog',
+ 'm2r2',
+ 'sphinx_autodoc_typehints']
+
+# Provide a GitHub API token:
+# Pass the SPHINX_GITHUB_CHANGELOG_TOKEN environment variable to your build
+# OR
+# sphinx_github_changelog_token = ""
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = {'.rst': 'restructuredtext'}
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'WikibaseIntegrator'
+copyright = u'%d, LeMyst' % datetime.now().year
+author = u'LeMyst and WikibaseIntegrator contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'0.12.0'
+# The full version, including alpha/beta/rc tags.
+release = u'0.12.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+autodoc_typehints = 'both'
+autodoc_default_options = {
+ 'special-members': '__init__',
+ 'members': True,
+ 'undoc-members': True,
+ 'inherited-members': True,
+ 'show-inheritance': True,
+ 'exclude-members': 'subclasses'
+}
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+html_theme_options = {
+ 'style_external_links': False,
+ # Toc options
+ 'collapse_navigation': False
+}
+
+html_context = {
+ 'display_github': True,
+ 'github_user': 'LeMyst',
+ 'github_repo': 'WikibaseIntegrator',
+ 'github_version': 'master',
+ "conf_py_path": "/docs/"
+}
+
+
+def skip(app, what, name, obj, would_skip, options):
+ if name == "__init__":
+ return False
+ if name == "sparql_query":
+ return True
+ return would_skip
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", skip)
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 00000000..5774be85
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,33 @@
+.. _index:
+
+WikibaseIntegrator
+==================
+
+.. toctree::
+ :maxdepth: 5
+
+ wikibaseintegrator
+
+..
+ README
+ ======
+
+ .. mdinclude:: ../../README.md
+
+
+Changelog
+=========
+
+.. toctree::
+ :maxdepth: 5
+ :caption: Miscellaneous
+
+ changelog
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
new file mode 100644
index 00000000..c8c8f23d
--- /dev/null
+++ b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator
+==================
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator
\ No newline at end of file
diff --git a/docs/source/wikibaseintegrator.datatypes.basedatatype.rst b/docs/source/wikibaseintegrator.datatypes.basedatatype.rst
new file mode 100644
index 00000000..db7f462f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.basedatatype.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.basedatatype
+=========================================
+
+.. automodule:: wikibaseintegrator.datatypes.basedatatype
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.commonsmedia.rst b/docs/source/wikibaseintegrator.datatypes.commonsmedia.rst
new file mode 100644
index 00000000..b210ec2a
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.commonsmedia.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.commonsmedia
+=========================================
+
+.. automodule:: wikibaseintegrator.datatypes.commonsmedia
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.externalid.rst b/docs/source/wikibaseintegrator.datatypes.externalid.rst
new file mode 100644
index 00000000..0c5ffb0d
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.externalid.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.externalid
+=======================================
+
+.. automodule:: wikibaseintegrator.datatypes.externalid
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.extra.edtf.rst b/docs/source/wikibaseintegrator.datatypes.extra.edtf.rst
new file mode 100644
index 00000000..82db2eb9
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.extra.edtf.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.extra.edtf
+=======================================
+
+.. automodule:: wikibaseintegrator.datatypes.extra.edtf
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.extra.localmedia.rst b/docs/source/wikibaseintegrator.datatypes.extra.localmedia.rst
new file mode 100644
index 00000000..b8a40e8c
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.extra.localmedia.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.extra.localmedia
+=============================================
+
+.. automodule:: wikibaseintegrator.datatypes.extra.localmedia
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.extra.rst b/docs/source/wikibaseintegrator.datatypes.extra.rst
new file mode 100644
index 00000000..13426ded
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.extra.rst
@@ -0,0 +1,9 @@
+wikibaseintegrator.datatypes.extra
+==================================
+
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes.extra.edtf
+ wikibaseintegrator.datatypes.extra.localmedia
diff --git a/docs/source/wikibaseintegrator.datatypes.form.rst b/docs/source/wikibaseintegrator.datatypes.form.rst
new file mode 100644
index 00000000..56ee30d2
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.form.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.form
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.form
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.geoshape.rst b/docs/source/wikibaseintegrator.datatypes.geoshape.rst
new file mode 100644
index 00000000..dbf46e2b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.geoshape.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.geoshape
+=====================================
+
+.. automodule:: wikibaseintegrator.datatypes.geoshape
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.globecoordinate.rst b/docs/source/wikibaseintegrator.datatypes.globecoordinate.rst
new file mode 100644
index 00000000..4b5f8df8
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.globecoordinate.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.globecoordinate
+============================================
+
+.. automodule:: wikibaseintegrator.datatypes.globecoordinate
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.item.rst b/docs/source/wikibaseintegrator.datatypes.item.rst
new file mode 100644
index 00000000..8113deb9
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.item.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.item
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.item
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.lexeme.rst b/docs/source/wikibaseintegrator.datatypes.lexeme.rst
new file mode 100644
index 00000000..8f9141ee
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.lexeme.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.lexeme
+===================================
+
+.. automodule:: wikibaseintegrator.datatypes.lexeme
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.math.rst b/docs/source/wikibaseintegrator.datatypes.math.rst
new file mode 100644
index 00000000..10ff4221
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.math.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.math
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.math
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.monolingualtext.rst b/docs/source/wikibaseintegrator.datatypes.monolingualtext.rst
new file mode 100644
index 00000000..95257695
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.monolingualtext.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.monolingualtext
+============================================
+
+.. automodule:: wikibaseintegrator.datatypes.monolingualtext
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.musicalnotation.rst b/docs/source/wikibaseintegrator.datatypes.musicalnotation.rst
new file mode 100644
index 00000000..c941619f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.musicalnotation.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.musicalnotation
+============================================
+
+.. automodule:: wikibaseintegrator.datatypes.musicalnotation
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.property.rst b/docs/source/wikibaseintegrator.datatypes.property.rst
new file mode 100644
index 00000000..f6845640
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.property.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.property
+=====================================
+
+.. automodule:: wikibaseintegrator.datatypes.property
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.quantity.rst b/docs/source/wikibaseintegrator.datatypes.quantity.rst
new file mode 100644
index 00000000..5d9ecc3f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.quantity.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.quantity
+=====================================
+
+.. automodule:: wikibaseintegrator.datatypes.quantity
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.rst b/docs/source/wikibaseintegrator.datatypes.rst
new file mode 100644
index 00000000..fb450673
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.rst
@@ -0,0 +1,35 @@
+wikibaseintegrator.datatypes
+============================
+
+Subpackages
+-----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes.extra
+
+Submodules
+----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes.basedatatype
+ wikibaseintegrator.datatypes.commonsmedia
+ wikibaseintegrator.datatypes.externalid
+ wikibaseintegrator.datatypes.form
+ wikibaseintegrator.datatypes.geoshape
+ wikibaseintegrator.datatypes.globecoordinate
+ wikibaseintegrator.datatypes.item
+ wikibaseintegrator.datatypes.lexeme
+ wikibaseintegrator.datatypes.math
+ wikibaseintegrator.datatypes.monolingualtext
+ wikibaseintegrator.datatypes.musicalnotation
+ wikibaseintegrator.datatypes.property
+ wikibaseintegrator.datatypes.quantity
+ wikibaseintegrator.datatypes.sense
+ wikibaseintegrator.datatypes.string
+ wikibaseintegrator.datatypes.tabulardata
+ wikibaseintegrator.datatypes.time
+ wikibaseintegrator.datatypes.url
diff --git a/docs/source/wikibaseintegrator.datatypes.sense.rst b/docs/source/wikibaseintegrator.datatypes.sense.rst
new file mode 100644
index 00000000..601d91a7
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.sense.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.sense
+==================================
+
+.. automodule:: wikibaseintegrator.datatypes.sense
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.string.rst b/docs/source/wikibaseintegrator.datatypes.string.rst
new file mode 100644
index 00000000..d5feba7b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.string.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.string
+===================================
+
+.. automodule:: wikibaseintegrator.datatypes.string
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.tabulardata.rst b/docs/source/wikibaseintegrator.datatypes.tabulardata.rst
new file mode 100644
index 00000000..e363421d
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.tabulardata.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.tabulardata
+========================================
+
+.. automodule:: wikibaseintegrator.datatypes.tabulardata
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.time.rst b/docs/source/wikibaseintegrator.datatypes.time.rst
new file mode 100644
index 00000000..5a26f7fc
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.time.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.time
+=================================
+
+.. automodule:: wikibaseintegrator.datatypes.time
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.datatypes.url.rst b/docs/source/wikibaseintegrator.datatypes.url.rst
new file mode 100644
index 00000000..feda6427
--- /dev/null
+++ b/docs/source/wikibaseintegrator.datatypes.url.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.datatypes.url
+================================
+
+.. automodule:: wikibaseintegrator.datatypes.url
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.baseentity.rst b/docs/source/wikibaseintegrator.entities.baseentity.rst
new file mode 100644
index 00000000..03f52769
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.baseentity.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.baseentity
+======================================
+
+.. automodule:: wikibaseintegrator.entities.baseentity
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.item.rst b/docs/source/wikibaseintegrator.entities.item.rst
new file mode 100644
index 00000000..c8943e29
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.item.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.item
+================================
+
+.. automodule:: wikibaseintegrator.entities.item
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.lexeme.rst b/docs/source/wikibaseintegrator.entities.lexeme.rst
new file mode 100644
index 00000000..c4d1e683
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.lexeme.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.lexeme
+==================================
+
+.. automodule:: wikibaseintegrator.entities.lexeme
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.mediainfo.rst b/docs/source/wikibaseintegrator.entities.mediainfo.rst
new file mode 100644
index 00000000..a3283d0f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.mediainfo.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.mediainfo
+=====================================
+
+.. automodule:: wikibaseintegrator.entities.mediainfo
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.property.rst b/docs/source/wikibaseintegrator.entities.property.rst
new file mode 100644
index 00000000..183603b4
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.property.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.entities.property
+====================================
+
+.. automodule:: wikibaseintegrator.entities.property
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.entities.rst b/docs/source/wikibaseintegrator.entities.rst
new file mode 100644
index 00000000..905ae27b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.entities.rst
@@ -0,0 +1,12 @@
+wikibaseintegrator.entities
+===========================
+
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.entities.baseentity
+ wikibaseintegrator.entities.item
+ wikibaseintegrator.entities.lexeme
+ wikibaseintegrator.entities.mediainfo
+ wikibaseintegrator.entities.property
diff --git a/docs/source/wikibaseintegrator.models.aliases.rst b/docs/source/wikibaseintegrator.models.aliases.rst
new file mode 100644
index 00000000..57bb0c0f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.aliases.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.aliases
+=================================
+
+.. automodule:: wikibaseintegrator.models.aliases
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.basemodel.rst b/docs/source/wikibaseintegrator.models.basemodel.rst
new file mode 100644
index 00000000..697e03cd
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.basemodel.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.basemodel
+===================================
+
+.. automodule:: wikibaseintegrator.models.basemodel
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.claims.rst b/docs/source/wikibaseintegrator.models.claims.rst
new file mode 100644
index 00000000..16385a5b
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.claims.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.claims
+================================
+
+.. automodule:: wikibaseintegrator.models.claims
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.descriptions.rst b/docs/source/wikibaseintegrator.models.descriptions.rst
new file mode 100644
index 00000000..40822474
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.descriptions.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.descriptions
+======================================
+
+.. automodule:: wikibaseintegrator.models.descriptions
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.forms.rst b/docs/source/wikibaseintegrator.models.forms.rst
new file mode 100644
index 00000000..c21b0da0
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.forms.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.forms
+===============================
+
+.. automodule:: wikibaseintegrator.models.forms
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.labels.rst b/docs/source/wikibaseintegrator.models.labels.rst
new file mode 100644
index 00000000..e5532e78
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.labels.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.labels
+================================
+
+.. automodule:: wikibaseintegrator.models.labels
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.language_values.rst b/docs/source/wikibaseintegrator.models.language_values.rst
new file mode 100644
index 00000000..ae17c258
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.language_values.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.language\_values
+==========================================
+
+.. automodule:: wikibaseintegrator.models.language_values
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.lemmas.rst b/docs/source/wikibaseintegrator.models.lemmas.rst
new file mode 100644
index 00000000..c39994e0
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.lemmas.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.lemmas
+================================
+
+.. automodule:: wikibaseintegrator.models.lemmas
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.qualifiers.rst b/docs/source/wikibaseintegrator.models.qualifiers.rst
new file mode 100644
index 00000000..eea12fb5
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.qualifiers.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.qualifiers
+====================================
+
+.. automodule:: wikibaseintegrator.models.qualifiers
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.references.rst b/docs/source/wikibaseintegrator.models.references.rst
new file mode 100644
index 00000000..138e7212
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.references.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.references
+====================================
+
+.. automodule:: wikibaseintegrator.models.references
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.rst b/docs/source/wikibaseintegrator.models.rst
new file mode 100644
index 00000000..833ef137
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.rst
@@ -0,0 +1,20 @@
+wikibaseintegrator.models
+=========================
+
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.models.aliases
+ wikibaseintegrator.models.basemodel
+ wikibaseintegrator.models.claims
+ wikibaseintegrator.models.descriptions
+ wikibaseintegrator.models.forms
+ wikibaseintegrator.models.labels
+ wikibaseintegrator.models.language_values
+ wikibaseintegrator.models.lemmas
+ wikibaseintegrator.models.qualifiers
+ wikibaseintegrator.models.references
+ wikibaseintegrator.models.senses
+ wikibaseintegrator.models.sitelinks
+ wikibaseintegrator.models.snaks
diff --git a/docs/source/wikibaseintegrator.models.senses.rst b/docs/source/wikibaseintegrator.models.senses.rst
new file mode 100644
index 00000000..6e0c99ca
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.senses.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.senses
+================================
+
+.. automodule:: wikibaseintegrator.models.senses
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.sitelinks.rst b/docs/source/wikibaseintegrator.models.sitelinks.rst
new file mode 100644
index 00000000..b7ac4ab0
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.sitelinks.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.sitelinks
+===================================
+
+.. automodule:: wikibaseintegrator.models.sitelinks
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.models.snaks.rst b/docs/source/wikibaseintegrator.models.snaks.rst
new file mode 100644
index 00000000..eece442f
--- /dev/null
+++ b/docs/source/wikibaseintegrator.models.snaks.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.models.snaks
+===============================
+
+.. automodule:: wikibaseintegrator.models.snaks
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.rst b/docs/source/wikibaseintegrator.rst
new file mode 100644
index 00000000..802df089
--- /dev/null
+++ b/docs/source/wikibaseintegrator.rst
@@ -0,0 +1,27 @@
+wikibaseintegrator
+==================
+
+Subpackages
+-----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.datatypes
+ wikibaseintegrator.entities
+ wikibaseintegrator.models
+
+Submodules
+----------
+
+.. toctree::
+ :maxdepth: 4
+
+ wikibaseintegrator.wbi_backoff
+ wikibaseintegrator.wbi_config
+ wikibaseintegrator.wbi_enums
+ wikibaseintegrator.wbi_exceptions
+ wikibaseintegrator.wbi_fastrun
+ wikibaseintegrator.wbi_helpers
+ wikibaseintegrator.wbi_login
+ wikibaseintegrator.wikibaseintegrator
diff --git a/docs/source/wikibaseintegrator.wbi_backoff.rst b/docs/source/wikibaseintegrator.wbi_backoff.rst
new file mode 100644
index 00000000..fe4665a4
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_backoff.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_backoff
+===============================
+
+.. automodule:: wikibaseintegrator.wbi_backoff
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_config.rst b/docs/source/wikibaseintegrator.wbi_config.rst
new file mode 100644
index 00000000..95c816c3
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_config.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_config
+==============================
+
+.. automodule:: wikibaseintegrator.wbi_config
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_enums.rst b/docs/source/wikibaseintegrator.wbi_enums.rst
new file mode 100644
index 00000000..a2161406
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_enums.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_enums
+=============================
+
+.. automodule:: wikibaseintegrator.wbi_enums
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_exceptions.rst b/docs/source/wikibaseintegrator.wbi_exceptions.rst
new file mode 100644
index 00000000..a9175027
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_exceptions.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_exceptions
+==================================
+
+.. automodule:: wikibaseintegrator.wbi_exceptions
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_fastrun.rst b/docs/source/wikibaseintegrator.wbi_fastrun.rst
new file mode 100644
index 00000000..15e436ed
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_fastrun.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_fastrun
+===============================
+
+.. automodule:: wikibaseintegrator.wbi_fastrun
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_helpers.rst b/docs/source/wikibaseintegrator.wbi_helpers.rst
new file mode 100644
index 00000000..4a36b544
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_helpers.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_helpers
+===============================
+
+.. automodule:: wikibaseintegrator.wbi_helpers
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wbi_login.rst b/docs/source/wikibaseintegrator.wbi_login.rst
new file mode 100644
index 00000000..f287a9f5
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wbi_login.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wbi\_login
+=============================
+
+.. automodule:: wikibaseintegrator.wbi_login
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/source/wikibaseintegrator.wikibaseintegrator.rst b/docs/source/wikibaseintegrator.wikibaseintegrator.rst
new file mode 100644
index 00000000..cee861b9
--- /dev/null
+++ b/docs/source/wikibaseintegrator.wikibaseintegrator.rst
@@ -0,0 +1,7 @@
+wikibaseintegrator.wikibaseintegrator
+=====================================
+
+.. automodule:: wikibaseintegrator.wikibaseintegrator
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/notebooks/item_create_new.ipynb b/notebooks/item_create_new.ipynb
new file mode 100644
index 00000000..d498f68e
--- /dev/null
+++ b/notebooks/item_create_new.ipynb
@@ -0,0 +1,356 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "3bc67e37",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "# Create a new Item"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3646845d",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Load wikibaseintegrator"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "498b50c2",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "from wikibaseintegrator.models import Qualifiers, References, Reference\n",
+ "\n",
+ "from wikibaseintegrator import WikibaseIntegrator\n",
+ "from wikibaseintegrator import wbi_login\n",
+ "from wikibaseintegrator import datatypes\n",
+ "from wikibaseintegrator.wbi_config import config"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "90b179a6",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "WDUSER = ''\n",
+ "WDPASS = ''"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "bb9948a9",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Set default variables"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "2ffe3908",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "config['MEDIAWIKI_API_URL'] = 'https://test.wikidata.org/w/api.php'\n",
+ "config['USER_AGENT'] = 'Lexeme Write Notebook'"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "27e3932f",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Create login and WikibaseIntegrator object"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "4963fc82",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "login = wbi_login.Login(user=WDUSER, password=WDPASS, mediawiki_api_url='https://test.wikidata.org/w/api.php')\n",
+ "wbi = WikibaseIntegrator(login=login)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c8b2ce02",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Create a new Item object"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "5ce0df1e",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "new_item = wbi.item.new()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "00f46d7d",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Set labels"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "71cd2848",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": ""
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "new_item.labels.set('en', 'New item')\n",
+ "new_item.labels.set('fr', 'Nouvel élément')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "cef7ce93",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Set aliases"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "id": "7ada4b6a",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": "], 'fr': []}>"
+ },
+ "execution_count": 7,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "new_item.aliases.set('en', 'Item')\n",
+ "new_item.aliases.set('fr', 'Élément')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7185bec3",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Set descriptions"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "id": "a2a3b081",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": ""
+ },
+ "execution_count": 8,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "new_item.descriptions.set('en', 'A freshly created element')\n",
+ "new_item.descriptions.set('fr', 'Un élément fraichement créé')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "078c3b4b",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Create a claim, with qualifiers and references, and add it to the new item entity"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "id": "ac4b06df",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": " _Snak__property_number='P31533' _Snak__hash=None _Snak__datavalue={'value': 'A String property', 'type': 'string'} _Snak__datatype='string'> _Claim__type='statement' _Claim__qualifiers= _Snak__property_number='P828' _Snak__hash=None _Snak__datavalue={'value': 'Item qualifier', 'type': 'string'} _Snak__datatype='string'>]}> _Claim__qualifiers_order=[] _Claim__id=None _Claim__rank= _Claim__removed=False _Claim__references= _Snak__property_number='P828' _Snak__hash=None _Snak__datavalue={'value': 'Item string reference', 'type': 'string'} _Snak__datatype='string'>]}> _Reference__snaks_order=[]>, _Snak__property_number='P828' _Snak__hash=None _Snak__datavalue={'value': 'Another item string reference', 'type': 'string'} _Snak__datatype='string'>]}> _Reference__snaks_order=[]>]>>]}>"
+ },
+ "execution_count": 9,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "new_qualifiers = Qualifiers()\n",
+ "new_qualifiers.add(datatypes.String(prop_nr='P828', value='Item qualifier'))\n",
+ "\n",
+ "new_references = References()\n",
+ "new_reference1 = Reference()\n",
+ "new_reference1.add(datatypes.String(prop_nr='P828', value='Item string reference'))\n",
+ "\n",
+ "new_reference2 = Reference()\n",
+ "new_reference2.add(datatypes.String(prop_nr='P828', value='Another item string reference'))\n",
+ "\n",
+ "new_references.add(new_reference1)\n",
+ "new_references.add(new_reference2)\n",
+ "\n",
+ "new_claim = datatypes.String(prop_nr='P31533', value='A String property', qualifiers=new_qualifiers, references=new_references)\n",
+ "\n",
+ "new_item.claims.add(new_claim)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b2e30176",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "Write the new item to the Wikibase instance"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 10,
+ "id": "29c22ef2",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": "\n\t _BaseEntity__title=None\n\t _BaseEntity__pageid=None\n\t _BaseEntity__lastrevid=579081\n\t _BaseEntity__type='item'\n\t _BaseEntity__id='Q225256'\n\t _BaseEntity__claims= _Snak__property_number='P31533' _Snak__hash='112d32b098a091cc1398c779e76c763a523d4ffc' _Snak__datavalue={'value': 'A String property', 'type': 'string'} _Snak__datatype='string'> _Claim__type='statement' _Claim__qualifiers= _Snak__property_number='P828' _Snak__hash='8d721edd0365e35ed006822601a4837b35e68fd6' _Snak__datavalue={'value': 'Item qualifier', 'type': 'string'} _Snak__datatype='string'>]}> _Claim__qualifiers_order=['P828'] _Claim__id='Q225256$A1CB5069-5FF4-4EE4-BE99-D1607BFFB705' _Claim__rank= _Claim__removed=False _Claim__references= _Snak__property_number='P828' _Snak__hash='811577f0f42a7059f39bd6b169366bb1fb2f9af3' _Snak__datavalue={'value': 'Item string reference', 'type': 'string'} _Snak__datatype='string'>]}> _Reference__snaks_order=['P828']>, _Snak__property_number='P828' _Snak__hash='774c2b3d70f072fb26d05a95d24445fbc8b2534e' _Snak__datavalue={'value': 'Another item string reference', 'type': 'string'} _Snak__datatype='string'>]}> _Reference__snaks_order=['P828']>]>>]}>\n\t _ItemEntity__labels=, 'fr': }>\n\t _ItemEntity__descriptions=, 'fr': }>\n\t _ItemEntity__aliases=], 'fr': []}>\n\t _ItemEntity__sitelinks=>"
+ },
+ "execution_count": 10,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "new_item.write()\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.5"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
\ No newline at end of file
diff --git a/notebooks/item_get.ipynb b/notebooks/item_get.ipynb
new file mode 100644
index 00000000..02ee483e
--- /dev/null
+++ b/notebooks/item_get.ipynb
@@ -0,0 +1,165 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "3bc67e37",
+ "metadata": {},
+ "source": [
+ "# Get english label and height for entity Q42 (Douglas Adams)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3646845d",
+ "metadata": {},
+ "source": [
+ "Load wikibaseintegrator"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "498b50c2",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "from wikibaseintegrator import WikibaseIntegrator\n",
+ "from wikibaseintegrator.wbi_config import config"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "Set default variables"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "outputs": [],
+ "source": [
+ "config['USER_AGENT'] = 'Item Get Notebook'"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ee386bbb",
+ "metadata": {},
+ "source": [
+ "Create WikibaseIntegrator object"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "f5131e52",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "wbi = WikibaseIntegrator()"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "5ce0df1e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "q42 = wbi.item.get('Q42')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b642a951",
+ "metadata": {},
+ "source": [
+ "Get english label"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "29c22ef2",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": "'Douglas Adams'"
+ },
+ "execution_count": 5,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "q42.labels.get('en').value"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b3f25818",
+ "metadata": {},
+ "source": [
+ "Get height"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "e3639082",
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": "'+1.96'"
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "q42.claims.get('P2048')[0].mainsnak.datavalue['value']['amount']\n"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3 (ipykernel)",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.10.1"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
\ No newline at end of file
diff --git a/notebooks/lexeme_update.ipynb b/notebooks/lexeme_update.ipynb
new file mode 100644
index 00000000..85f76ff4
--- /dev/null
+++ b/notebooks/lexeme_update.ipynb
@@ -0,0 +1,292 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "source": [
+ "# Update an existing Lexeme"
+ ],
+ "metadata": {
+ "collapsed": false
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "from wikibaseintegrator import WikibaseIntegrator, wbi_login, datatypes\n",
+ "from wikibaseintegrator.models import Reference, References\n",
+ "from wikibaseintegrator.models.qualifiers import Qualifiers\n",
+ "from wikibaseintegrator.wbi_config import config"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "outputs": [],
+ "source": [
+ "WDUSER = ''\n",
+ "WDPASS = ''"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Set default variables"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "outputs": [],
+ "source": [
+ "config['MEDIAWIKI_API_URL'] = 'https://test.wikidata.org/w/api.php'\n",
+ "config['USER_AGENT'] = 'Lexeme Write Notebook'"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Create login and WikibaseIntegrator object"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "outputs": [],
+ "source": [
+ "login = wbi_login.Login(user=WDUSER, password=WDPASS, mediawiki_api_url='https://test.wikidata.org/w/api.php')\n",
+ "wbi = WikibaseIntegrator(login=login)"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Get existing lexeme entity"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "outputs": [],
+ "source": [
+ "lexeme = wbi.lexeme.get(entity_id='L42')"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Set french lemmas"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ }
+ },
+ {
+ "cell_type": "code",
+ "source": [
+ "# Lemmas\n",
+ "lexeme.lemmas.set(language='fr', value='réponse')"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "execution_count": 6,
+ "outputs": [
+ {
+ "data": {
+ "text/plain": ""
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Create a new claim"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "outputs": [],
+ "source": [
+ "# Claims\n",
+ "claim_references = References() # Create a group of references\n",
+ "\n",
+ "claim_reference1 = Reference()\n",
+ "claim_reference1.add(datatypes.String(prop_nr='P828', value='Claim string reference'))\n",
+ "\n",
+ "claim_reference2 = Reference()\n",
+ "claim_reference2.add(datatypes.String(prop_nr='P828', value='Another claim string reference'))\n",
+ "\n",
+ "# Add each reference to the group of references\n",
+ "claim_references.add(claim_reference1)\n",
+ "claim_references.add(claim_reference2)\n",
+ "\n",
+ "claim_qualifiers = Qualifiers()\n",
+ "claim_qualifiers.add(datatypes.String(prop_nr='P828', value='Claim qualifier'))\n",
+ "\n",
+ "claim = datatypes.String(prop_nr='P828', value=\"Create a string claim for claim\", references=claim_references,\n",
+ " qualifiers=claim_qualifiers)\n"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ }
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "## Add claim to lexeme"
+ ],
+ "metadata": {
+ "collapsed": false,
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ }
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "outputs": [
+ {
+ "data": {
+ "text/plain": " _Snak__property_number='P77771' _Snak__hash='5362eb3a0f7cba043a1b2afbc0352fc16463b0de' _Snak__datavalue={'value': {'entity-type': 'form', 'id': 'L41-F1'}, 'type': 'wikibase-entityid'} _Snak__datatype='wikibase-form'> _Claim__type='statement' _Claim__qualifiers= _Claim__qualifiers_order=[] _Claim__id='L42$7bd50233-4080-3f02-5fc3-c01b905a58ed' _Claim__rank= _Claim__removed=False _Claim__references=>,