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.
The primary resources presented by the server are Recipes, Bags and Tiddlers. See the tiddlyweb.model package.
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.
Return the bag which this tiddler would be in if we were to save it to the named recipe rather than to a bag.
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.
Yield the individual tiddlers that are in a bag.
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[1].
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.
Bases: exceptions.Exception
The provided input is insufficient to form a valid Bag.
Bases: exceptions.Exception
There is a NoSerialization of this type for the entity.
Bases: exceptions.Exception
The provided input is insufficient to form a valid Recipe.
Bases: object
A Serializer is a facade to a Serialization which implements the tiddlyweb.serializations.SerializationInterface to turn a TiddlyWeb entity into a particular representation or vice versa.
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'
Note that to_string() and from_string() operate on the Serializer which dispatches to a method in the SerializationInterface implementation based on the class of the object being serialized.
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.
Provide a (usually unicode) string representation of the tiddlers in the provided Tiddlers collection.
Bases: exceptions.Exception
The provided input is insufficient to form a valid Tiddler.
Special bags are a feature implemented in plugins that allow non-standard collections of data to be represented as a bag of tiddlers. An example is remotebag.
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).
Bases: exceptions.Exception
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.
Bases: tiddlyweb.store.StoreError
No tiddlyweb.model.bag.Bag was found.
Bases: tiddlyweb.store.StoreError
No tiddlyweb.model.recipe.Recipe was found.
Bases: tiddlyweb.store.StoreError
No tiddlyweb.model.tiddler.Tiddler was found.
Bases: tiddlyweb.store.StoreError
No tiddlyweb.model.user.User was found.
Bases: object
A Store is a facade to an implementation of tiddlyweb.stores.StorageInterface to handle the storage and retrieval of all entities in the TiddlyWeb system.
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.
Search in the store, using a search algorithm specific to the tiddlyweb.stores.StorageInterface implementation.
Bases: tiddlyweb.store.StoreError
Something about an entity made it impossible to be encoded to the form required by the store.
Bases: exceptions.IOError
Base Exception for Store Exceptions.
Bases: tiddlyweb.store.StoreError
This process was unable to get a lock on the store.
Bases: tiddlyweb.store.StoreError
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.
Bases: exceptions.IOError
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.
A pseudo binary is defined as textual content for which (this) TiddlyWeb (instance) has no serialization or is not treated as wikitext. It is identified by a MIME type that looks like text, json, xml or javascript.
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.
Return True if the provided tiddler's type is one that can be rendered to HTML by the wikitext rendering subsystem.
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.