From c8e3515d4a85657afb81d288cb4eb54cec79cc9d Mon Sep 17 00:00:00 2001 From: fastily Date: Mon, 22 Apr 2024 00:09:55 -0700 Subject: [PATCH] expand docs, tweak structure --- docs/{ => API}/dwrap-reference.md | 0 docs/{ => API}/gquery-reference.md | 0 docs/{ => API}/mquery-reference.md | 0 docs/{ => API}/ns-reference.md | 0 docs/{ => API}/oquery-reference.md | 0 docs/{ => API}/wiki-reference.md | 0 .../wparser-reference.md} | 0 docs/examples.md | 38 +++++++++++++++---- docs/index.md | 20 +++++++--- mkdocs.yml | 2 +- 10 files changed, 46 insertions(+), 14 deletions(-) rename docs/{ => API}/dwrap-reference.md (100%) rename docs/{ => API}/gquery-reference.md (100%) rename docs/{ => API}/mquery-reference.md (100%) rename docs/{ => API}/ns-reference.md (100%) rename docs/{ => API}/oquery-reference.md (100%) rename docs/{ => API}/wiki-reference.md (100%) rename docs/{wparser-reference copy.md => API/wparser-reference.md} (100%) diff --git a/docs/dwrap-reference.md b/docs/API/dwrap-reference.md similarity index 100% rename from docs/dwrap-reference.md rename to docs/API/dwrap-reference.md diff --git a/docs/gquery-reference.md b/docs/API/gquery-reference.md similarity index 100% rename from docs/gquery-reference.md rename to docs/API/gquery-reference.md diff --git a/docs/mquery-reference.md b/docs/API/mquery-reference.md similarity index 100% rename from docs/mquery-reference.md rename to docs/API/mquery-reference.md diff --git a/docs/ns-reference.md b/docs/API/ns-reference.md similarity index 100% rename from docs/ns-reference.md rename to docs/API/ns-reference.md diff --git a/docs/oquery-reference.md b/docs/API/oquery-reference.md similarity index 100% rename from docs/oquery-reference.md rename to docs/API/oquery-reference.md diff --git a/docs/wiki-reference.md b/docs/API/wiki-reference.md similarity index 100% rename from docs/wiki-reference.md rename to docs/API/wiki-reference.md diff --git a/docs/wparser-reference copy.md b/docs/API/wparser-reference.md similarity index 100% rename from docs/wparser-reference copy.md rename to docs/API/wparser-reference.md diff --git a/docs/examples.md b/docs/examples.md index b14becb..fe2b68a 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,5 +1,5 @@ # Examples -⚠️ This section is under construction +This is a non-exhaustive collection of snippets exhibiting some of the functionality `pwiki` is capable of. ## Basics ```python @@ -10,6 +10,12 @@ wiki = Wiki() # new Wiki instance, pointed at commons.wikimedia.org, logging in with user/pass wiki = Wiki("commons.wikimedia.org", "MyCoolUsername", "MySuperSecretPassword") + +# login on en.wikipedia.org as MyCoolUsername. Password will be read from environment variable "MyCoolUsername_PW" +wiki = Wiki(username="MyCoolUsername") + +# save cookies so they can automatically be reused for next time +wiki.save_cookies() ``` ## Read Page Content @@ -18,16 +24,14 @@ from pwiki.wiki import Wiki wiki = Wiki() -# print all the titles in "Category:American 3D films" -for title in wiki.category_members("Category:American 3D films"): - print(title) +# get all the titles in "Category:American 3D films" +print(wiki.category_members("Category:American 3D films")) -# print all external links on the page "GitHub" -for url in wiki.external_links("GitHub"): - print(url) +# get all external links on the page "GitHub" +print(wiki.external_links("GitHub")): ``` -## Edit/Create Page Content +## Edit/Create Content ```python from pwiki.wiki import Wiki @@ -39,4 +43,22 @@ wiki.edit("Wikipedia:Sandbox", append="this is a test") # Replace "Wikipedia:Sandbox" with "I changed the page!" and edit summary "Hello, world!" wiki.edit("Wikipedia:Sandbox", "I changed the page!", "Hello, world!") + +# Upload a file +from pathlib import Path +wiki.upload(Path("/path/to/file.jpg"), "My awesome new file on Wikipedia.jpg", "my file description", "test edit summary") +``` + +## Categories +```python +from pwiki.ns import NS +from pwiki.wiki import Wiki + +wiki = Wiki() + +# get all category members of "Category:Some Cool Category" +print(wiki.category_members("Category:Some Cool Category")) + +# get all category members of "Category:Some Cool Category" in the File namespace +print(wiki.category_members("Category:Some Cool Category", NS.FILE)) ``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 9a21c9a..8d90cc4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,21 @@ -# Welcome to pwiki's docs +# Introduction +[![Python 3.9+](https://upload.wikimedia.org/wikipedia/commons/4/4f/Blue_Python_3.9%2B_Shield_Badge.svg)](https://www.python.org) +[![MediaWiki 1.35+](https://upload.wikimedia.org/wikipedia/commons/b/b3/Blue_MediaWiki_1.35%2B_Shield_Badge.svg)](https://www.mediawiki.org/wiki/MediaWiki) +[![License: GPL v3](https://upload.wikimedia.org/wikipedia/commons/8/86/GPL_v3_Blue_Badge.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html) **pwiki** is a Python library which makes interacting with the MediaWiki API simple and easy. It can be used with sites such as Wikipedia, or virtually any other website that runs on MediaWiki. ## Installation - -Install with `pip` - ```bash pip install pwiki -``` \ No newline at end of file +``` + +## Overview +I created `pwiki` with the goal of being simple and powerful, all while being mindful of DX (developer experience). This means that every interaction with the API is simple, easy, and usually just one line of code. + +`pwiki` is split into four main modules: + +1. [wiki](API/wiki-reference.md) - The main API and entry point. This module ecompasses most of the functionality for reading from/writing to MediaWiki. +2. [mquery](API/mquery-reference.md) - The batch query API. This module makes it easy to efficiently query against many titles/articles on the MediaWiki instance in fewer round-trips. +3. [gquery](API/gquery-reference.md) - A batch query API that uses python generators to efficiently query for results. This is useful for sampling large quantities of data from MediaWiki in a piecemeal fashion. +4. [wparser](API/wparser-reference.md) - Contains methods for parsing wikitext into higher level object-based models that are easy to work with. diff --git a/mkdocs.yml b/mkdocs.yml index 805f70b..3b26541 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: pwiki docs +site_name: pwiki documentation site_url: https://fastily.github.io/pwiki/ theme: