Merge branch 'master' of https://git.xpub.nl/kamo/kamo-soupbato

projects/kiwibot/documentation.md

@@ -0,0 +1,91 @@
+---
+categories:
+    - Web
+    - Python
+    - Wiki
+cover: kiwi.jpg
+cover_alt: Kiwi not the fruit
+date: 01/06/2022
+description: Working with the Media Wiki API
+git: https://git.xpub.nl/kamo/kiwiboat
+slug: kiwiboat
+title: Kiwiboat
+---
+
+[mwclient](https://mwclient.readthedocs.io/) is a library for interacting with the MediaWiki API with Python. It provides an easy way to fetch and edit contents, create pages and upload materials.
+
+It opens interesting possibilities for _Soupboat ⇄ Wiki_ pubblishing practices: using the wiki as a CMS and the Soupboat to display contents, using the Soupboat as a way to collect materials, an improvements of the Padliography, etc.
+
+The setup to work with the XPUB & LB wiki is straightforward: first install `mwclient` with `pip`
+
+`pip install mwclient`
+
+Then connect to the wiki
+
+```python
+import mwclient
+
+# 1. Connect to the Mediawiki client logging in as a user
+site = mwclient.Site('pzwiki.wdka.nl', path='/mw-mediadesign/')
+site.login(
+    username='username',
+    password='password'
+)
+
+# 2. Get a page to edit. If it doesn't exist it will be created
+page = site.pages['A test page']
+
+# 3. Get the text from the page
+text = page.text()
+
+# 4. Edit the contents
+text += 'Editing the test page from the wiki'
+
+# 5. Write the modification
+page.edit(text, 'Summary of the edit')
+
+```
+
+And that's all!
+
+There are a couple of things to notice here:
+
+1. Some actions such as editing a page require an authentication i.e. to log in as a user. You can use your own credentials or the ones of the account Diffbot. Find them in Zzzulip.
+
+2. In every case watch out and avoid publishing code with your credentials written in it! Otherwise people could easily access your profile and use it maliciously like uploading animal pictures on the wiki etc. You never know. There are different ways to avoid that such as to use `.env` files that are stored in a safe -not public- place which your code can access but malevolent users not.
+
+### Example
+
+This is the approach we tried for SI18.6: it relies on [python-dotenv](https://pypi.org/project/python-dotenv/), that is a library that let you read .env files from your python code. This is an usefull approach when your code is stored in a public folder like the `public_html` one, or when you want to show the code to your friends without revealing your credentials (read: git).
+
+A `.env` file is a text file that follow the same syntax:
+
+```
+YOUR_VARIABLE = its value
+MW_BOT = Diffbot
+MW_KEY = your supa secret password
+```
+
+We put this file in the shared folder of the Soupboat that is not pubblicly accessible from the outside world. Watch out: never publish your .env files on git! Otherwise all this workaround is meaningless aha.
+
+```python
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+
+# load the .env variables, they will be accessible from os.environ
+# /var/www is the path for the shared folder of the Soupboat
+# (not accessible from the outside web)
+dotenv_path = Path("/var/www/.mw-credentials")
+load_dotenv(dotenv_path=dotenv_path)
+
+# use the variable without revealing them
+site = mwclient.Site('pzwiki.wdka.nl', path='/mw-mediadesign/')
+site.login(
+    username=os.environ.get('MW_BOT'),
+    password=os.environ.get('MW_KEY')
+    )
+
+# ... etc etc etc do your things
+
+```