TiddlyParse allows Python to interact with TiddlyWiki files.
At the moment it handles standalone HTML files, with the two tiddler formats. The first one was used in version up to and including 5.1.23, the second one uses JSON snippets and is in use since 5.2.0.
Points that are currently open but can be added upon interest:
- Seamlessly interact with a server-side TiddlyWiki and use the REST API in that context
- Handle encrypted files
Use the parse method to get a wiki instance returned:
from tiddlyparse import parse
from pathlib import Path
wiki_file = Path('wiki.html')
wiki = parse(file=wiki_file)
This will automatically detect the format and transparently handle this also for saving back.
The number of tiddlers are returned with the len
function:
>>> len(wiki)
7
Note that only the root tiddlers are returned. The individual tiddlers contained therein are not currently handled, though that may change.
You can access individual tiddlers using dictionary notation or get
:
>>> wiki['$:/isEncrypted']
<tiddlyparse.parser.JsonTiddler object at 0x105a85130>
>>> wiki.get('no such tiddler')
It is also possible to execute simple searches. Any keyword argument to the search
function is converted into a query component. If the argument value is True
, then all tiddlers that have this attribute defined are returned:
>>> tiddlers = wiki.search(author=True)
>>> tiddlers
[<tiddlyparse.parser.JsonTiddler object at 0x101827e80>, <tiddlyparse.parser.JsonTiddler object at 0x101832130>, <tiddlyparse.parser.JsonTiddler object at 0x101832190>]
>>> [t.title for t in tiddlers]
['$:/core', '$:/themes/tiddlywiki/snowwhite', '$:/themes/tiddlywiki/vanilla']
If it's any string value, then all tiddlers that have this attribute set to exactly this value are returned:
>>> tiddlers = wiki.search(name='Snow White')
>>> [t.title for t in tiddlers]
['$:/themes/tiddlywiki/snowwhite']
The tiddlers are all represented using the Tiddler
class (JsonTiddler
or DivTiddler
more specifically). The tiddler attributes are available as properties are available on those objects:
>>> tiddler = wiki['$:/isEncrypted']
>>> tiddler.text
'no'
>>> tiddler = wiki.get('$:/core')
>>> tiddler.author
'JeremyRuston'
To create or modify a tiddler, use the get_or_create
method to first get the tiddler. Then add it to the wiki with add
:
>>> tiddler = wiki.get_or_create('Testing TiddlyParse')
>>> tiddler.text = "This is the first ''test'' with TiddlyParse."
>>> tiddler.tags = 'Test TiddlyParse'
>>> wiki.add(tiddler)
To persist the changes, use save
:
>>> wiki.save()