serializations Package

serializations Package

Turn entities to and fro various representations.

This is the base class and interface class used to transform strings of various forms to model objects and model objects to strings of various forms.

class tiddlyweb.serializations.SerializationInterface(environ=None)

Bases: object

A Serialization is a collection of methods that either turn an input string into the object named by the method, or turn the object into a string form. A Serialization is not called directly, instead a Serializer facade is used.

The interface is fairly simple: For the core entities that exist in the TiddlyWeb system (bags, recipes and tiddlers there (optionally) exists <entity>_as and as_<entity> methods in each Serialization.

*_as returns a string form of the entity, perhaps as HTML, Text, YAML, Atom, whatever the Serialization does.

as_* takes a provided entity and string and updates the skeletal entity to use the information contained in the string (in the Serialization format).

There are also three supporting methods, list_tiddlers(), list_recipes() and list_bags() that provide convenience methods for presenting a collection of entities in the Serialization form. A string is returned.

Strings are usually unicode.

If a method doesn’t exist a NoSerializationError is raised and the calling code is expected to do something intelligent when trapping it.

as_bag(bag, input_string)

Take input_string which is a serialized bag and use it to populate the Bag in bag (if possible).

as_recipe(recipe, input_string)

Take input_string which is a serialized recipe and use it to populate the Recipe in recipe (if possible).

as_tags(string)

Not called directly, but made public for future use. Turn a string into a list of tags.

as_tiddler(tiddler, input_string)

Take input_string which is a serialized tiddler and use it to populate the Tiddler in tiddler (if possible).

bag_as(bag)

Serialize a Bag into this serializer’s form.

list_bags(bags)

Provided a list of bags, make a serialized list of those bags (e.g. a a list of HTML links).

list_recipes(recipes)

Provided a list of recipes, make a serialized list of those recipes (e.g. a a list of HTML links).

list_tiddlers(bag)

Provided a bag, output the associated tiddlers.

recipe_as(recipe)

Serialize a :py:Recipe into this serializer’s form.

tags_as(tags)

Not called directly, but made public for future use. Turn a list of tags into a serialized list.

tiddler_as(tiddler)

Serialize a Tiddler into this serializer’s form.

html Module

Serialization for HTML.

HEADER and FOOTER can be overridden to change the basic framing of the system.

class tiddlyweb.serializations.html.Serialization(environ=None)

Bases: tiddlyweb.serializations.SerializationInterface

Serialize entities and collections to HTML representations. This is primarily used to create browser based presentations. No support is provided for turning HTML into entities.

Set css_uri in config to control CSS.

Set tiddlyweb.links in environ to a list of <link> elements to include those links in the output.

bag_as(bag)

Bag as HTML, including a link to the tiddlers within.

list_bags(bags)

Yield the provided bags as HTML.

list_recipes(recipes)

Yield the provided recipes as HTML.

list_tiddlers(tiddlers)

Yield the provided tiddlers as HTML.

This is somewhat more complex than the other list methods as we need to list the tiddler whether it is a revision or not, if it is in a bag or recipe or if it is a search result.

recipe_as(recipe)

Recipe as HTML, including a link to the tiddlers within.

tiddler_as(tiddler)

Transform the provided tiddler into an HTML representation. Render the text of the tiddler if its type is configured.

json Module

Serialization for JSON.

class tiddlyweb.serializations.json.Serialization(environ=None)

Bases: tiddlyweb.serializations.SerializationInterface

Turn entities and collections thereof to and from JSON.

as_bag(bag, input_string)

Turn a JSON dictionary into a bag if it is in the proper form. Include the policy.

as_recipe(recipe, input_string)

Turn a JSON dictionary into a recipe if it is in the proper form. Include the policy.

as_tiddler(tiddler, input_string)

Turn a JSON dictionary into a tiddler. Any keys in the JSON which are not recognized will be ignored.

bag_as(bag)

A bag as a JSON dictionary. Includes the bag’s policy.

list_bags(bags)

Create a JSON list of bag names from the provided bags.

list_recipes(recipes)

Create a JSON list of recipe names from the provided recipes.

list_tiddlers(tiddlers)

List the provided tiddlers as JSON. The format is a list of dicts in the form described by _tiddler_dict().

If fat=1 is set in tiddlyweb.query include the text of each tiddler in the output.

If render=1 is set in tiddlyweb.query include the rendering of the text of each tiddler in the output, if the tiddler is renderable.

recipe_as(recipe)

A recipe as a JSON dictionary. Includes the recipe’s policy.

tiddler_as(tiddler)

Create a JSON dictionary representing a tiddler, as described by _tiddler_dict() plus the text of the tiddler.

If fat=0 is set in tiddlyweb.query do not include the text of the tiddler in the output.

If render=1 is set in tiddlyweb.query include the rendering of the text of the tiddler in the output, if the tiddler is renderable.

text Module

Serialization for plain text.

class tiddlyweb.serializations.text.Serialization(environ=None)

Bases: tiddlyweb.serializations.SerializationInterface

Serialize entities and collections to and from textual representations. This is primarily used by the text Store.

as_recipe(recipe, input_string)

Turn a string into a recipe if possible.

as_tiddler(tiddler, input_string)

Transform a text representation of a tiddler into a tiddler object.

field = 'text'

fields_as(tiddler)

Turn extended tiddler fields into RFC 822-style header strings.

list_bags(bags)

Return a linefeed separated list of bag names in the bags list.

list_recipes(recipes)

Return a linefeed separated list of recipe names in the recipes list.

list_tiddlers(tiddlers)

Return a linefeed separated list of tiddler titles in the tiddlers list.

If the tiddlers are a collection of revisions, include the revision identifier.

recipe_as(recipe)

Dump a recipe as text.

tiddler_as(tiddler, omit_empty=False, omit_members=None)

Represent a tiddler as a text string: headers, blank line, text.

omit_* arguments are non-standard options, usable only when this method is called directly (outside the regular Serializer interface)

If omit_empty is True, don’t emit empty Tiddler members.

omit_members can be used to provide a list of members to not include in the output.

tiddler_members = ['creator', 'created', 'modifier', 'modified', 'tags', 'type']