Add the experimentation API

Closes #2.

README.md

@@ -39,6 +39,8 @@ Added the `python-dateutil` and `pypandoc` dependencies
 
 Added a fancy progress bar with `tqdm` for long running `etherpump pull --all` calls
 
+Started with the experimental library API.
+
 **September 2019**
 
 Forking *etherpump* into *etherpump*.
@@ -97,8 +99,8 @@ Install etherpump
 
 Etherpump only supports Python 3.
 
-Example
--------
+Command-line example
+--------------------
 
 ```
 $ mkdir mydump
@@ -118,6 +120,22 @@ The APIKEY is the contents of the file APIKEY.txt in the etherpad folder.
 
 The settings are placed in a file called `.etherpump/settings.json` and are used (by default) by future commands.
 
+Library API Example
+-------------------
+
+Etherpump can be used as a library. See [etherpump/examples](https://git.vvvvvvaria.org/varia/etherpump/src/branch/master/etherpump/examples)
+or read the short one below:
+
+```python
+from etherpump.api import magicword
+
+@magicword('__VARIA_PUB_CLUB__')
+def maakt_niet_uit_wat_je_hier_schrijft(pads):
+    print(pads['my-pad-name']['html'])
+```
+
+This is still a work in progress.
+
 Subcommands
 ----------
 

etherpump/__init__.py

@@ -2,4 +2,4 @@ import os
 
 DATAPATH = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data")
 
-__VERSION__ = '0.0.4'
+__VERSION__ = '0.0.5'

etherpump/api/__init__.py

@@ -0,0 +1 @@
+from etherpump.api.magicword import magicword  # noqa

etherpump/api/_utils.py

@@ -0,0 +1,23 @@
+"""Utilities for API functions."""
+
+from pathlib import Path
+from urllib.parse import urlencode
+
+from etherpump.commands.common import getjson, loadpadinfo
+from etherpump.commands.init import main
+
+
+def ensure_init():
+    """Ensure etherpump has already been init'd."""
+    try:
+        main([])
+    except SystemExit:
+        pass
+
+
+def get_pad_ids():
+    """Retrieve all available pad ids."""
+    info = loadpadinfo(Path('.etherpump/settings.json'))
+    data = {'apikey': info['apikey']}
+    url = info['localapiurl'] + 'listAllPads?' + urlencode(data)
+    return getjson(url)['data']['padIDs']

etherpump/api/magicword.py

@@ -0,0 +1,37 @@
+"""API for programming against pads marked with __MAGIC_WORDS__."""
+
+__all__ = ['magicword']
+
+import json
+from pathlib import Path
+
+from etherpump.api._utils import ensure_init, get_pad_ids
+from etherpump.commands.pull import main as pull
+
+
+def magicword(word):
+    """Decorator for handling magic words."""
+
+    ensure_init()
+    pull(['--all', '--publish-opt-in', '--publish', word])
+
+    pads = {}
+    for pad_id in get_pad_ids():
+        pads[pad_id] = {}
+        try:
+            pads[pad_id]['html'] = open(Path(f'./p/{pad_id}.raw.html')).read()
+            pads[pad_id]['txt'] = open(Path(f'./p/{pad_id}.raw.txt')).read()
+            pads[pad_id]['meta'] = json.loads(
+                open(Path(f'./p/{pad_id}.meta.json')).read()
+            )
+            pads[pad_id]['dhtml'] = open(Path(f'./p/{pad_id}.raw.dhtml')).read()
+        except FileNotFoundError:
+            pass
+
+    def wrap(userfunc):
+        def wrappedf(*args):
+            userfunc(pads)
+
+        return wrappedf
+
+    return wrap

etherpump/commands/init.py

@@ -92,9 +92,7 @@ def main(args):
         with open(padinfopath) as f:
             padinfo = json.load(f)
         if not args.reinit:
-            print(
-                "Folder is already initialized. Use --reinit to reset settings."
-            )
+            print("Folder already initialized. Use --reinit to reset settings")
             sys.exit(0)
     except IOError:
         pass

etherpump/commands/publication.py

@@ -194,8 +194,8 @@ def main(args):
     )
     pg.add_argument(
         "--generator",
-        default="https://gitlab.com/activearchives/etherpump",
-        help="generator, default: https://gitlab.com/activearchives/etherdump",
+        default="https://git.vvvvvvaria.org/varia/etherpump",
+        help="generator, default: https://git.vvvvvvaria.org/varia/etherdump",
     )
     pg.add_argument(
         "--timestamp",
@@ -223,6 +223,7 @@ def main(args):
 
     inputs = args.input
     inputs.sort()
+
     # Use "base" to strip (longest) extensions
     # inputs = group(inputs, base)
 
@@ -253,7 +254,7 @@ def main(args):
         if p.endswith(".meta.json"):
             with open(p) as f:
                 return json.load(f)
-        # # IF there is a .meta.json, load it & MERGE with other files
+        # if there is a .meta.json, load it & MERGE with other files
         # if ret:
         #     # TODO: merge with other files
         #     for p in paths:

etherpump/examples/magicword.py

@@ -0,0 +1,25 @@
+"""How to use the 'magicword' API.
+
+In this example, we have a pad called "my-pad-name" on our etherpad-lite
+instance. Inside the content of that pad is the so-called "magic word"
+__WORSE_IS_BETTER__. The "@magicword" takes care of retrieving all the formats
+of those pads and returns a dictionary called "pads" ready to go.
+
+Run this example like so:
+
+$ python etherdump/examples/magicword.py
+
+"""
+
+from etherpump.api import magicword
+
+
+@magicword('__WORSE_IS_BETTER__')
+def can_be_called_anything_you_like(pads):
+    print(pads['foobar']['html'])
+    print(pads['foobar']['txt'])
+    print(pads['foobar']['meta'])
+
+
+if __name__ == "__main__":
+    can_be_called_anything_you_like()