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/.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/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..a7805ab3 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +Sphinx~=4.2.0 +readthedocs-sphinx-ext~=2.1.4 +sphinx-rtd-theme~=1.0.0 +git+https://github.com/LeMyst/sphinx-github-changelog.git@1.0.8-Sphinx-4.2.0#egg=sphinx_github_changelog +m2r2~=0.3.1 +sphinx-autodoc-typehints~=1.12.0 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..050b7ed8 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,120 @@ +# -*- 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/pyproject.toml b/pyproject.toml index 8b387b68..80143fed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,6 @@ extension-pkg-allow-list = [ max-line-length = 180 disable = [ "fixme", - "missing-docstring", "redefined-builtin", "invalid-name", # To remove later "too-few-public-methods", diff --git a/setup.cfg b/setup.cfg index 9a8c5cdd..81e586cc 100644 --- a/setup.cfg +++ b/setup.cfg @@ -45,5 +45,12 @@ dev = pylint pylint-exit mypy +docs = + Sphinx~=4.2.0 + readthedocs-sphinx-ext~=2.1.4 + sphinx-rtd-theme~=1.0.0 + sphinx_github_changelog @ git+https://github.com/LeMyst/sphinx-github-changelog.git@1.0.8-Sphinx-4.2.0#egg=sphinx_github_changelog + m2r2~=0.3.1 + sphinx-autodoc-typehints~=1.12.0 coverage = pytest-cov diff --git a/setup.py b/setup.py index abedd3fd..fe65a962 100644 --- a/setup.py +++ b/setup.py @@ -18,6 +18,14 @@ "pylint-exit", "mypy" ], + "docs": [ + "Sphinx ~= 4.2.0", + "readthedocs-sphinx-ext ~= 2.1.4", + "sphinx-rtd-theme ~= 1.0.0", + "sphinx_github_changelog @ git+https://github.com/LeMyst/sphinx-github-changelog.git@1.0.8-Sphinx-4.2.0#egg=sphinx_github_changelog", + "m2r2 ~= 0.3.1", + "sphinx-autodoc-typehints ~= 1.12.0" + ], "coverage": ["pytest-cov"], }, ) diff --git a/wikibaseintegrator/__init__.py b/wikibaseintegrator/__init__.py index d3f39e8d..7e2e06e9 100644 --- a/wikibaseintegrator/__init__.py +++ b/wikibaseintegrator/__init__.py @@ -1,3 +1,20 @@ +""" +WikibaseIntegrator Library +~~~~~~~~~~~~~~~~~~~~~ + +WikibaseIntegrator is a Wikibase library, written in Python, for human beings. +Basic read usage: + + >>> from wikibaseintegrator import WikibaseIntegrator + >>> from wikibaseintegrator.wbi_config import config + >>> config['USER_AGENT'] = 'Item Get Notebook' + >>> wbi = WikibaseIntegrator() + >>> q42 = wbi.item.get('Q42') + >>> q42.labels.get('en').value + 'Douglas Adams' + +Full documentation is available at . +""" import pkg_resources from .wikibaseintegrator import WikibaseIntegrator diff --git a/wikibaseintegrator/datatypes/geoshape.py b/wikibaseintegrator/datatypes/geoshape.py index 3e013387..7a7210bc 100644 --- a/wikibaseintegrator/datatypes/geoshape.py +++ b/wikibaseintegrator/datatypes/geoshape.py @@ -21,23 +21,19 @@ def __init__(self, value: str = None, **kwargs: Any): Constructor, calls the superclass BaseDataType :param value: The GeoShape map file name in Wikimedia Commons to be linked - :type value: str or None - :param prop_nr: The item ID for this claim - :type prop_nr: str with a 'P' prefix followed by digits - :param snaktype: The snak type, either 'value', 'somevalue' or 'novalue' - :type snaktype: str - :param references: List with reference objects - :type references: A data type with subclass of BaseDataType - :param qualifiers: List with qualifier objects - :type qualifiers: A data type with subclass of BaseDataType - :param rank: rank of a snak with value 'preferred', 'normal' or 'deprecated' - :type rank: str + :param kwargs: :Keyword Arguments: - * *extra* (``list``) -- - Extra stuff - * *supplement* (``dict``) -- - Additional content + * *prop_nr* (``str``) -- + The item ID for this claim + * *snaktype* (``str``) -- + The snak type, either 'value', 'somevalue' or 'novalue' + * *references* (``References`` or list of ``Claim``) -- + List with reference objects + * *qualifiers* (``Qualifiers``) -- + List with qualifier objects + * *rank* (``WikibaseRank``) -- + The snak type, either 'value', 'somevalue' or 'novalue' """ super().__init__(**kwargs) diff --git a/wikibaseintegrator/entities/baseentity.py b/wikibaseintegrator/entities/baseentity.py index c8f77f2e..9bfa1375 100644 --- a/wikibaseintegrator/entities/baseentity.py +++ b/wikibaseintegrator/entities/baseentity.py @@ -49,6 +49,11 @@ def add_claims(self, claims: Union[Claim, list], action_if_exists: ActionIfExist return self def get_json(self) -> Dict[str, Union[str, Dict[str, list]]]: + """ + To get the dict equivalent of the JSON representation of the entity. + + :return: + """ json_data: Dict = { 'type': self.type, 'claims': self.claims.get_json() @@ -77,7 +82,7 @@ def from_json(self, json_data: Dict[str, Any]) -> BaseEntity: # noinspection PyMethodMayBeStatic def _get(self, entity_id: str, **kwargs: Any) -> Dict: # pylint: disable=no-self-use """ - retrieve an item in json representation from the Wikibase instance + Retrieve an entity in json representation from the Wikibase instance :return: python complex dictionary representation of a json """ diff --git a/wikibaseintegrator/entities/item.py b/wikibaseintegrator/entities/item.py index 09317b5a..121eaaf9 100644 --- a/wikibaseintegrator/entities/item.py +++ b/wikibaseintegrator/entities/item.py @@ -38,6 +38,13 @@ def new(self, **kwargs: Any) -> Item: return Item(api=self.api, **kwargs) def get(self, entity_id: Union[str, int], **kwargs: Any) -> Item: + """ + Request the Mediawiki API to get data for the entity specified in argument. + + :param entity_id: The entity_id of the Item entity you want. Must start with a 'Q'. + :param kwargs: + :return: an Item instance + """ if isinstance(entity_id, str): pattern = re.compile(r'^Q?([0-9]+)$') matches = pattern.match(entity_id) @@ -55,6 +62,11 @@ def get(self, entity_id: Union[str, int], **kwargs: Any) -> Item: return Item(api=self.api).from_json(json_data=json_data['entities'][entity_id]) def get_json(self) -> Dict[str, Union[str, Dict]]: + """ + To get the dict equivalent of the JSON representation of the Item. + + :return: A dict representation of the Item. + """ return { 'labels': self.labels.get_json(), 'descriptions': self.descriptions.get_json(), diff --git a/wikibaseintegrator/models/claims.py b/wikibaseintegrator/models/claims.py index 12366851..54f7bf7b 100644 --- a/wikibaseintegrator/models/claims.py +++ b/wikibaseintegrator/models/claims.py @@ -123,6 +123,12 @@ class Claim(BaseModel): DTYPE = 'claim' def __init__(self, qualifiers: Qualifiers = None, rank: WikibaseRank = None, references: Union[References, List[Union[Claim, List[Claim]]]] = None) -> None: + """ + + :param qualifiers: + :param rank: + :param references: A References object, a list of Claim object or a list of list of Claim object + """ self.mainsnak = Snak(datatype=self.DTYPE) self.type = 'statement' self.qualifiers = qualifiers or Qualifiers() @@ -225,6 +231,10 @@ def remove(self, remove=True) -> None: self.removed = remove def from_json(self, json_data: Dict[str, Any]) -> Claim: + """ + + :param json_data: a JSON representation of a Claim + """ self.mainsnak = Snak().from_json(json_data['mainsnak']) self.type = str(json_data['type']) if 'qualifiers' in json_data: diff --git a/wikibaseintegrator/models/language_values.py b/wikibaseintegrator/models/language_values.py index aa2ba814..182fea92 100644 --- a/wikibaseintegrator/models/language_values.py +++ b/wikibaseintegrator/models/language_values.py @@ -12,7 +12,10 @@ def __init__(self): self.values = {} @property - def values(self): + def values(self) -> Dict[str, LanguageValue]: + """ + A dict of LanguageValue with the language as key. + """ return self.__values @values.setter @@ -20,6 +23,12 @@ def values(self, value): self.__values = value def add(self, language_value: LanguageValue) -> LanguageValues: + """ + Add a LanguageValue object to the list + + :param language_value: A LanguageValue object + :return: The current LanguageValues object + """ assert isinstance(language_value, LanguageValue) if language_value.value: @@ -28,6 +37,12 @@ def add(self, language_value: LanguageValue) -> LanguageValues: return self def get(self, language: str = None) -> Optional[LanguageValue]: + """ + Get a LanguageValue object with the specified language. Use the default language in wbi_config if none specified. + + :param language: The requested language. + :return: The related LanguageValue object or None if none found. + """ language = str(language or config['DEFAULT_LANGUAGE']) if language in self.values: return self.values[language] @@ -35,12 +50,21 @@ def get(self, language: str = None) -> Optional[LanguageValue]: return None def set(self, language: str = None, value: str = None, action_if_exists: ActionIfExists = ActionIfExists.REPLACE) -> Optional[LanguageValue]: + """ + Create or update the specified language with the valued passed in arguments. + + :param language: The desired language. + :param value: The desired value of the LanguageValue object. Use None to delete an existing LanguageValue object from the list. + :param action_if_exists: The action if the LanguageValue object is already defined. Can be ActionIfExists.REPLACE (default) or ActionIfExists.KEEP. + :return: The created or updated LanguageValue. None if there's no LanguageValue object with this language. + """ language = str(language or config['DEFAULT_LANGUAGE']) assert action_if_exists in [ActionIfExists.REPLACE, ActionIfExists.KEEP] # Remove value if None - if value is None and language in self.values: - self.values[language].remove() + if value is None: + if language in self.values: + self.values[language].remove() return None if action_if_exists == ActionIfExists.REPLACE or self.get(language=language) is None: @@ -51,12 +75,23 @@ def set(self, language: str = None, value: str = None, action_if_exists: ActionI return self.get(language=language) def from_json(self, json_data: Dict[str, Dict]) -> LanguageValues: + """ + Create a new LanguageValues object from a JSON/dict object. + + :param json_data: A dict object who use the same format as Wikibase. + :return: The newly created or updated object. + """ for language_value in json_data: self.add(language_value=LanguageValue(language=json_data[language_value]['language']).from_json(json_data=json_data[language_value])) return self def get_json(self) -> Dict[str, Dict]: + """ + Get a formated dict who respect the Wikibase format. + + :return: A dict using Wikibase format. + """ json_data: Dict[str, Dict] = {} for language, language_value in self.values.items(): json_data[language] = language_value.get_json() @@ -74,11 +109,11 @@ def __init__(self, language: str, value: str = None): self.removed = False @property - def language(self): + def language(self) -> str: return self.__language @language.setter - def language(self, value): + def language(self, value: Optional[str]): if value is None: raise ValueError("language can't be None") @@ -91,19 +126,23 @@ def language(self, value): self.__language = value @property - def value(self): + def value(self) -> Optional[str]: + """ + The value of the LanguageValue instance. + :return: A string with the value of the LanguageValue instance. + """ return self.__value @value.setter - def value(self, value): + def value(self, value: Optional[str]): self.__value = value @property - def removed(self): + def removed(self) -> bool: return self.__removed @removed.setter - def removed(self, value): + def removed(self, value: bool): self.__removed = value def remove(self) -> LanguageValue: @@ -117,7 +156,7 @@ def from_json(self, json_data: Dict[str, str]) -> LanguageValue: return self - def get_json(self) -> Dict[str, str]: + def get_json(self) -> Dict[str, Optional[str]]: json_data = { 'language': self.language, 'value': self.value diff --git a/wikibaseintegrator/wbi_backoff.py b/wikibaseintegrator/wbi_backoff.py index 93b15b9f..edbbf0f1 100644 --- a/wikibaseintegrator/wbi_backoff.py +++ b/wikibaseintegrator/wbi_backoff.py @@ -1,3 +1,6 @@ +""" +WikibaseIntegrator implementation of backoff python library. +""" import sys from functools import partial from json import JSONDecodeError @@ -15,12 +18,10 @@ def wbi_backoff_backoff_hdlr(details): print("Backing off {wait:0.1f} seconds afters {tries} tries calling function with args {args} and kwargs {kwargs}".format(**details)) # pylint: disable=consider-using-f-string -def wbi_backoff_check_json_decode_error(e): +def wbi_backoff_check_json_decode_error(e) -> bool: """ Check if the error message is "Expecting value: line 1 column 1 (char 0)" if not, its a real error and we shouldn't retry - :param e: - :return: """ return isinstance(e, JSONDecodeError) and str(e) != "Expecting value: line 1 column 1 (char 0)" diff --git a/wikibaseintegrator/wbi_fastrun.py b/wikibaseintegrator/wbi_fastrun.py index 5cd3cf77..de62004f 100644 --- a/wikibaseintegrator/wbi_fastrun.py +++ b/wikibaseintegrator/wbi_fastrun.py @@ -110,6 +110,14 @@ def reconstruct_statements(self, qid: str) -> List[BaseDataType]: return reconstructed_statements def get_item(self, claims: Union[list, Claims], cqid: str = None) -> Optional[str]: + """ + Load an item from the SPARQL endpoint. + + :param claims: + :param cqid: + :return: the claim id + :exception: if there is more than one claim + """ match_sets = [] for claim in claims: # skip to next if statement has no value or no data type defined, e.g. for deletion objects @@ -165,6 +173,14 @@ def get_item(self, claims: Union[list, Claims], cqid: str = None) -> Optional[st return matching_qids.pop() def write_required(self, data: List[BaseDataType], action_if_exists: ActionIfExists = ActionIfExists.REPLACE, cqid: str = None) -> bool: + """ + Check if a write is required + + :param data: + :param action_if_exists: + :param cqid: + :return: Return True if the write is required + """ del_props = set() data_props = set() append_props = [] @@ -260,6 +276,7 @@ def write_required(self, data: List[BaseDataType], action_if_exists: ActionIfExi def init_language_data(self, lang: str, lang_data_type: str) -> None: """ Initialize language data store + :param lang: language code :param lang_data_type: 'label', 'description' or 'aliases' :return: None diff --git a/wikibaseintegrator/wbi_helpers.py b/wikibaseintegrator/wbi_helpers.py index c6882cf6..62386602 100644 --- a/wikibaseintegrator/wbi_helpers.py +++ b/wikibaseintegrator/wbi_helpers.py @@ -32,21 +32,21 @@ class BColors: UNDERLINE = '\033[4m' -# Session used for anonymous requests +# Session used for all anonymous requests default_session = requests.Session() def mediawiki_api_call(method: str, mediawiki_api_url: str = None, session: Session = None, max_retries: int = 100, retry_after: int = 60, **kwargs: Any) -> Dict: """ + A function to call the Mediawiki API. + :param method: 'GET' or 'POST' :param mediawiki_api_url: :param session: If a session is passed, it will be used. Otherwise a new requests session is created :param max_retries: If api request fails due to rate limiting, maxlag, or readonly mode, retry up to `max_retries` times - :type max_retries: int :param retry_after: Number of seconds to wait before retrying request (see max_retries) - :type retry_after: int - :param kwargs: Passed to requests.request - :return: + :param kwargs: Any additional keyword arguments to pass to requests.request + :return: The data returned by the API as a dictionary """ mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL']) @@ -124,6 +124,21 @@ def mediawiki_api_call(method: str, mediawiki_api_url: str = None, session: Sess def mediawiki_api_call_helper(data: Dict[str, Any] = None, login: Login = None, mediawiki_api_url: str = None, user_agent: str = None, allow_anonymous: bool = False, max_retries: int = 1000, retry_after: int = 60, maxlag: int = 5, is_bot: bool = False, **kwargs: Any) -> Dict: + """ + A simplified function to call the Mediawiki API + + :param data: A dictionary containing the JSON data to send to the API + :param login: A wbi_login instance + :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata) + :param user_agent: The user agent (Recommended for Wikimedia Foundation instances) + :param allow_anonymous: Allow an unidentified edit to the Mediawiki API (default False) + :param max_retries: The maximum number of retries + :param retry_after: The tiemout between each retry + :param maxlag: If appliable, the maximum lag allowed for the replication (An lower number reduce the load on the replicated database) + :param is_bot: Flag the edit as a bot + :param kwargs: Any additional keyword arguments to pass to requests.request + :return: The data returned by the API as a dictionary + """ mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL']) user_agent = user_agent or (str(config['USER_AGENT']) if config['USER_AGENT'] is not None else None) @@ -177,6 +192,7 @@ def mediawiki_api_call_helper(data: Dict[str, Any] = None, login: Login = None, def execute_sparql_query(query: str, prefix: str = None, endpoint: str = None, user_agent: str = None, max_retries: int = 1000, retry_after: int = 60) -> Optional[Dict[str, dict]]: """ Static method which can be used to execute any SPARQL query + :param prefix: The URI prefixes required for an endpoint, default is the Wikidata specific prefixes :param query: The actual SPARQL query string :param endpoint: The URL string for the SPARQL endpoint. Default is the URL for the Wikidata SPARQL endpoint @@ -235,12 +251,13 @@ def execute_sparql_query(query: str, prefix: str = None, endpoint: str = None, u return None -def merge_items(from_id: str, to_id: str, ignore_conflicts: List[str] = None, is_bot: bool = False, **kwargs: Any) -> Dict: +def merge_items(from_id: str, to_id: str, login: Login = None, ignore_conflicts: List[str] = None, is_bot: bool = False, **kwargs: Any) -> Dict: """ A static method to merge two items :param from_id: The ID to merge from. This parameter is required. :param to_id: The ID to merge to. This parameter is required. + :param login: A wbi_login.Login instance :param ignore_conflicts: List of elements of the item to ignore conflicts for. Can only contain values of "description", "sitelink" and "statement" :param is_bot: Mark this edit as bot. """ @@ -258,12 +275,12 @@ def merge_items(from_id: str, to_id: str, ignore_conflicts: List[str] = None, is if is_bot: params.update({'bot': ''}) - return mediawiki_api_call_helper(data=params, **kwargs) + return mediawiki_api_call_helper(data=params, login=login, **kwargs) def merge_lexemes(source: str, target: str, summary: str = None, is_bot: bool = False, **kwargs: Any) -> Dict: """ - A static method to merge two items + A static method to merge two lexemes :param source: The ID to merge from. This parameter is required. :param target: The ID to merge to. This parameter is required. @@ -289,7 +306,7 @@ def merge_lexemes(source: str, target: str, summary: str = None, is_bot: bool = def remove_claims(claim_id: str, summary: str = None, baserevid: int = None, is_bot: bool = False, **kwargs: Any) -> Dict: """ - Delete an item + Delete a claim from an entity :param claim_id: One GUID or several (pipe-separated) GUIDs identifying the claims to be removed. All claims must belong to the same entity. :param summary: Summary for the edit. Will be prepended by an automatically generated comment. diff --git a/wikibaseintegrator/wbi_login.py b/wikibaseintegrator/wbi_login.py index 4ce113af..51da7c66 100644 --- a/wikibaseintegrator/wbi_login.py +++ b/wikibaseintegrator/wbi_login.py @@ -1,5 +1,5 @@ """ -Login class for Wikidata. Takes username and password and stores the session cookies and edit tokens. +Login class for Wikidata. Takes authentication parameters and stores the session cookies and edit tokens. """ import logging import time @@ -105,6 +105,16 @@ class OAuth2(_Login): @wbi_backoff() def __init__(self, consumer_token: str = None, consumer_secret: str = None, mediawiki_api_url: str = None, mediawiki_rest_url: str = None, token_renew_period: int = 1800, user_agent: str = None): + """ + This class is used to interact with the OAuth2 API. + + :param consumer_token: The consumer token + :param consumer_secret: The consumer secret + :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata) + :param mediawiki_rest_url: The URL to the Mediawiki REST API (default Wikidata) + :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server + :param user_agent: UA string to use for API requests. + """ mediawiki_rest_url = str(mediawiki_rest_url or config['MEDIAWIKI_REST_URL']) @@ -124,6 +134,19 @@ class OAuth1(_Login): @wbi_backoff() def __init__(self, consumer_token: str = None, consumer_secret: str = None, access_token: str = None, access_secret: str = None, callback_url: str = 'oob', mediawiki_api_url: str = None, mediawiki_index_url: str = None, token_renew_period: int = 1800, user_agent: str = None): + """ + This class is used to interact with the OAuth1 API. + + :param consumer_token: The consumer token + :param consumer_secret: The consumer secret + :param access_token: The access token + :param access_secret: The access secret + :param callback_url: The callback URL used to finalize the handshake + :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata) + :param mediawiki_index_url: The URL to the Mediawiki index (default Wikidata) + :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server + :param user_agent: UA string to use for API requests. + """ mediawiki_index_url = str(mediawiki_index_url or config['MEDIAWIKI_INDEX_URL']) @@ -155,6 +178,7 @@ def continue_oauth(self, oauth_callback_data: str = None) -> None: """ Continuation of OAuth procedure. Method must be explicitly called in order to complete OAuth. This allows external entities, e.g. websites, to provide tokens through callback URLs directly. + :param oauth_callback_data: The callback URL received to a Web app :type oauth_callback_data: bytes :return: @@ -184,6 +208,15 @@ def continue_oauth(self, oauth_callback_data: str = None) -> None: class Login(_Login): @wbi_backoff() def __init__(self, user: str = None, password: str = None, mediawiki_api_url: str = None, token_renew_period: int = 1800, user_agent: str = None): + """ + This class is used to log in with a bot password + + :param user: The user of the bot password (format @) + :param password: The password generated byt the Mediawiki + :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata) + :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server + :param user_agent: UA string to use for API requests. + """ mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL']) session = Session() @@ -224,6 +257,15 @@ def __init__(self, user: str = None, password: str = None, mediawiki_api_url: st class Clientlogin(_Login): @wbi_backoff() def __init__(self, user: str = None, password: str = None, mediawiki_api_url: str = None, token_renew_period: int = 1800, user_agent: str = None): + """ + This class is used to log in with a user account + + :param user: The username + :param password: The password + :param mediawiki_api_url: The URL to the Mediawiki API (default Wikidata) + :param token_renew_period: Seconds after which a new token should be requested from the Wikidata server + :param user_agent: UA string to use for API requests. + """ mediawiki_api_url = str(mediawiki_api_url or config['MEDIAWIKI_API_URL']) session = Session() diff --git a/wikibaseintegrator/wikibaseintegrator.py b/wikibaseintegrator/wikibaseintegrator.py index 05deca34..859babc1 100644 --- a/wikibaseintegrator/wikibaseintegrator.py +++ b/wikibaseintegrator/wikibaseintegrator.py @@ -1,3 +1,6 @@ +""" +Main class of the Library. +""" from __future__ import annotations from typing import TYPE_CHECKING @@ -14,6 +17,12 @@ class WikibaseIntegrator: def __init__(self, is_bot: bool = False, login: Login = None): + """ + This function initializes a WikibaseIntegrator instance to quickly access different entity type instances. + + :param is_bot: declare if the bot flag must be set when you interact with the Mediawiki API. + :param login: a wbi_login instance needed when you try to access a restricted Mediawiki instance. + """ # Runtime variables self.is_bot = is_bot or False self.login = login