Extension:Piwo

From mediawiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced.svg
Piwo
Release status: experimental
Implementation Parser function
Description Allows executing of Python scripts on pages
Author(s) Kenny2wikitalk
Latest version 0.1.0
MediaWiki 1.31+
License MIT License
Download
NS_GRAM
(NS_GRAM_TALK)
gram-edit

Check usage and version matrix.

The Piwo extension allows executing of Python scripts on MediaWiki (Python In, Wikitext Out). Since it uses the shell framework, it can and should be sandboxed.

Installation[edit]

  • Install Python
  • Download and place the file(s) in a directory called Piwo in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'Piwo' );
    $wgGroupPermissions['bureaucrat']['gram-edit'] = true;
    
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Usage[edit]

This extension defines a custom namespace, "Gram", that stores Python scripts. Editing the Gram namespace requires the gram-edit right. To invoke a script, use the following parser function:

{{#piwo:name of script, without "Gram:"|parameter1|parameter2|...}}

In the Python script, the parameters can be accessed through mw.argv (no import is needed); an extra function, mw.hsc is provided as an equivalent to PHP's htmlspecialchars; mw.MW_ROOT is equivalent to $IP; mw.GRAM_NAME is the name of the script, without "Gram:".

mw.py[edit]

You might need the source code of mw.py for debugging and it's also copied here for reference.

from sys import argv
from os import environ as env
from html import escape as hsc

MW_ROOT = env.get('MW_ROOT', None)
GRAM_NAME = env.get('MW_GRAM_NAME', None)
argv[0] = '#piwo:' + GRAM_NAME

Any and all of the Python standard library can be imported, as of January 2018. The accessibility depends on the user you run your MediaWiki with.

Examples[edit]

Obviously we need to be careful what to disclose via the Python code. In principle even the jailboxed environment might have access to security relevant data.

Take the use cases:

  1. We want to display some text as ASCII-Art and are to lazy to look for a PHP / extension based solution. There is https://pypi.org/project/art/ which looks nice for the job. There seems to be no security risk involved.
  2. We want to display the disk usage in our wiki. This info might not be too security sensible and e.g. useful in an intranet to show when we run out of disk space.

ASCII-ART[edit]

Prepare the usage of the pypi art library by

pip install art

in the user space of your MediaWiki environment.

Gram:Art[edit]

from art import *
print("<pre>")
tprint(mw.argv[1])
print("</pre>")

Template:Art[edit]

<noinclude>
{{Art|Kenny}}
see: [[Gram:Art]]
</noinclude><includeonly>
{{#Piwo:Art|{{{1|Hello world!}}}}}
</includeonly>

Result[edit]

 _  __                           
| |/ /  ___  _ __   _ __   _   _ 
| ' /  / _ \| '_ \ | '_ \ | | | |
| . \ |  __/| | | || | | || |_| |
|_|\_\ \___||_| |_||_| |_| \__, |
                           |___/ 

And you can use the {{Art|...}} template anywhere in your wiki hiding the fact that the implementation is python based.

Diskusage[edit]

Gram:Diskusage[edit]

Just get some python code which does the relevant task e.g. see https://stackoverflow.com/a/48929832/1497139 and put into the Gram namespace.

import shutil

total, used, free = shutil.disk_usage("/")

print("Total: %d GiB" % (total // (2**30)))
print("Used: %d GiB" % (used // (2**30)))
print("Free: %d GiB" % (free // (2**30)))

Diskusage[edit]

A page in the main namespace may now call the python function

{{#piwo:Diskusage}}
[[Category:piwo]]

Result[edit]

Total: 187 GiB Used: 140 GiB Free: 37 GiB 

Debugging[edit]

If you'd like to remote debug your code you might want to add:

import pydevd
pydevd.settrace("<your ip or hostname here>", port=5678)

to your python code. You'll then be able to debug the python code execution with your favorite Debug environment/IDE. This feature has e.g. been tested with Eclipse/Liclipse. see

See also[edit]