For more complete information also see:
TiddlyWeb is a web service and library for managing and manipulating resources useful in the creation of dynamic wiki-like collections of content and functionality. The model of the data was originally designed for creating custom TiddlyWiki implementations, where the content of the TiddlyWiki can be saved to the server, and shared among multiple users.
TiddlyWeb presents an HTTP API for resource management. The API follows, as possible, RESTful principles to keep the API flexible and scalable. The URLs for this interface are kept in a file called urls.map found in the tiddlyweb package. urls.map dispatches web requests at specific URLs to specific functions in modules in the tiddlyweb.web.handler package. urls.map may be located in another place by changing the urls_map key in tiddlywebconfig.py. There are also mechanisms for overriding storage (see tiddlyweb.store), serialization (see tiddlyweb.serializer) and authentication (see tiddlyweb.web.challenger and tiddlyweb.web.extractor) systems. There are also system_plugins and twanager_plugins for further extensibility.
TiddlyWeb includes twanager, a command line tool for doing a variety of TiddlyWeb activities. Run twanager without arguments for a list of commands.
See the documentation for other modules and packages within tiddlyweb for additional details.
The configuration of a particular instance of TiddlyWeb, carried around as a dict in the WSGI environ as tiddlyweb.config.
If there is a tiddlywebconfig.py file in the working directory where twanager or the web server is started, its values will override the defaults established in this module.
The server administrator may add additional keys to the config via extensions.
control provides routines which integrate the basic model classes with the rest of the system. The model classes are intentionally simple. The methods here act as controllers on those classes.
These are primarily related to handling recipes.
This is done reversing the recipe list and seeing if the tiddler passes the constraint of the bag and its associated filter. If bag+filter is true, return that bag.
Given a recipe and a tiddler determine the bag in which this tiddler can be found. This is different from determine_bag_for_tiddler(). That one finds the bag the tiddler could be in. This is the bag the tiddler is in.
This is done by reversing the recipe’s list, and filtering each bag according to any filters present. The resulting tiddlers are checked.
If an indexer is configured use the index to determine if a tiddler exists in a bag.
Return a generator of tiddlers resulting from filtering the provided iterator of tiddlers by the provided filters.
If filters is a string, it will be parsed for filters.
The tiddlers return are empty objects that have not been loaded from the store.
Rarely used, see tiddlyweb.store.Store.list_bag_tiddlers().
Return the list of tiddlers that result from processing the recipe.
This list of tiddlers is unique by title with tiddlers later in the recipe taking precedence over those earlier in the recipe.
The tiddlers returned are empty objects (i.e. not loaded from the store).
manage provides the workings for the twanager command line tool. twanager calls handle(), making available all commands that have been put into the COMMANDS dictionary by the make_command() decorator. See tiddlyweb.commands for examples.
Plugins which add commands must be added to the twanager_plugins config setting so they are imported at the proper time.
Dispatch to the proper function for the command given in args.
A decorator that marks the decorated method as a member of the commands dictionary, with associated help.
The pydoc of the method is used in automatically generated :py:func:usage information.
List this help
Serialize TiddlyWeb entities for the sake of taking input and sending output.
This module provides the facade for accessing the possibly many modules which act as serializations. It is asked by calling code to provide a serialization for a given MIME type. Plugins may override what MIME types are handled and by what modules. See tiddlyweb.config for related configuration settings.
The provided input is insufficient to form a valid Bag.
There is a NoSerialization of this type for the entity.
The provided input is insufficient to form a valid Recipe.
A Serializer can also list collections of entities in a particular representation.
A single Serializer is a reusable tool which can serialize more than one object. You must set serializer.object after initialization and then again for each subsequent object being serialized.
The following example turns the tiddler into JSON and vice-versa:
tiddler = Tiddler('cow', 'bag') tiddler.text = 'moo' serializer = Serializer('json', environ) serializer.object = tiddler json_string = serializer.to_string() assert '"text": "moo"' in json_string new_string = json_string.replace('moo', 'meow') serializer.from_string(new_string) assert tiddler.text == 'meow'
Turn the provided input_string into a TiddlyWeb entity object of the type of self.object. That is: populate self.object based on input_string.
Provide a (usually unicode) string representation of the provided bags in the current serialization.
Provide a (usually unicode) string representation of the provided recipes in the current serialization.
The provided input is insufficient to form a valid Tiddler.
If config['special_bag_detectors'] is set, it is a list of functions that take two arguments: a WSGI environ and a string and return either:
The first function yields tiddlers, like tiddlyweb.store.list_bag_tiddlers(). It’s arguments are a WSGI environ and a string.
The second function returns a single tiddler. It’s arguments are a WSGI environ and a tiddler object (with at least title and bag set).
A generic exception to be raised by special bag implementations.
When loading bag or tiddlers within it from the store, this method is used to inspect config['special_bag_detectors'] to determine if there is a special handler. If there is, the handler is returned and used for retrieval, otherwise None is returned and the store is used as normal.
Store TiddlyWeb entities to a configured persistence layer.
This module provides the facade for accessing one of many possible modules which provide storage for entities. It provides a general interface to get, put, delete or list entities.
Each of the single entity methods can be augmented with hooks provided by plugins. This allows actions to be performed based on data in the store being retrieved or updated, such as updating an index.
No tiddlyweb.model.bag.Bag was found.
No tiddlyweb.model.recipe.Recipe was found.
No tiddlyweb.model.tiddler.Tiddler was found.
No tiddlyweb.model.user.User was found.
Because of the facade system it is relatively straightforward to create diverse storage systems for all sorts of or multiple media. In addition stores can be layered to provide robust caching and reliability.
The Store distinguishes between single entities and collections. With single entities, an entity is passed to the store and the store is asked to get(), put() or delete() it. When get() is used the provided object is updated in place in operation that could be described as population. Dispatch is based on the class of the provided entity.
After any of those operations optional HOOKS are called.
With collections there are specific list methods:
Finally a store may optionally provide a search(). How search works and what it even means is up to the implementation.
Delete a thing: recipe, bag, tiddler or user.
Get a thing: recipe, bag, tiddler or user.
List all the tiddlers in the bag.
List all the available bags in the system.
List all the available recipes in the system.
List the revision ids of the revisions of the indicated tiddler in reverse chronological older (newest first).
List all the available users in the system.
Put a thing, recipe, bag, tiddler or user.
Something about an entity made it impossible to be encoded to the form required by the store.
Base Exception for Store Exceptions.
This process was unable to get a lock on the store.
A tiddlyweb.stores.StorageInterface does not implement this method.
Load the provided entity from the store if it has not already been loaded. If it can’t be found, still return the same entity, just keep it empty.
This works for tiddlers, bags and recipes. Not users!
This module provides a centralized collection of miscellaneous utility functions used throughout TiddlyWeb and plugins.
Web specific utilities are in tiddlyweb.web.util.
This process was unable to get a lock.
Test if a tiddler represents binary content (e.g. an image).
Return True if this Tiddler has a type which suggests the content of the tiddler is non-textual.
Initialize the system’s logging.
If this code is reached from twanager when there is no sub_command logging is not started. This avoids spurious tiddlyweb.log files popping up all over the place.
Update the global_config with the additional data provided in the dict additional_config. If reconfig is True, then reread and merge tiddlywebconfig.py so its overrides continue to operate.
Note that if the value of a existing key is a dict, then it is updated (merged) with the value from additional_config. Otherwise the value is replaced.
Warning: Please ensure (via tests) when using this that it will give the desired results.
Test if a tiddler represents textual content that should be treated as a pseudo-binary.
TiddlyWeb requires that such content be uploaded encoded as UTF-8.
Read in a local configuration override, named tiddlywebconfig.py, from the current working directory. If the file exists but can’t be imported as valid Python an exception will be thrown, preventing unexpected results.
What is expected in the override file is a dict with the name config.
global_config is a reference to the currently operational main TiddlyWeb config. The read configuration data is merged into it.
Read the UTF-8 encoded file at filename and return unicode.
Allow any exceptions to raise.
Create a sha1 digest of the data.
Display message on the stderr console.
Some finagling is done to ensure that unicode content makes its way to the console even if there are encoding problems.
Given an instance return the lowerclass name of the penultimate class in the hierarchy (the last is object). This is used to do dynamic method lookups in adaptor classes via serializer.py and store.py while still allowing model entities to be subclassed. Those subclasses must insure that their __mro__ results in Bag, User, Recipe or Tiddler in the penultimate slot.
Create an advisory lock file based on filename.
This is primarily used by the text store.
Unlock the write lock associated with filename.
Write the unicode string in content to a UTF-8 encoded file named filename.
Allow any exceptions to raise.