model Package

model Package

Models for TiddlyWeb Entities.

Classes representing the important entities in the TiddlyWeb system.

These are intentionally limited, making no effort to handle their own persistence or presentation. That is the job of the store and serializer.

bag Module

A module containing the Bag class.

class tiddlyweb.model.bag.Bag(name, desc=u'')

Bases: object

A Bag is a virtual container for tiddlers. The bag provides a domain for the tiddlers within identifying those tiddlers uniquely and optionally acting a topical, functional or authorization container for the tiddlers.

A bag can contain many tiddlers but every tiddler must have a different title. The canonical identifier of a tiddler is the combination of the containing bag’s name and the tiddler’s title.

Containership is achieved via association: There are no methods on a bag to access the contained tiddlers. These are found via store.list_bag_tiddlers.

A Bag has a Policy which may be used to control access to both the Bag and the tiddlers within. These controls are optional and are primarily designed for use within the web handlers.

collections Module

Classes representing collections of bags, recipes and tiddlers.

Because the main reason for having a collection is to send it out over the web, the collections keep track of their last-modified time and generate a hash suitable for use as an ETag.

class tiddlyweb.model.collections.Collection(title='')

Bases: object

Base class for all collections.

Can be used directly for general collections if required.

A collection acts as generator, yielding one of its contents when iterated.

add(thing)

Add an item to the container, updating the digest and modified information.

hexdigest()

Return the current hex representation of the hash digest of this collection.

class tiddlyweb.model.collections.Container(title='')

Bases: tiddlyweb.model.collections.Collection

A collection of things which have a name attribute.

In TiddlyWeb this is for lists of bags and recipes.

class tiddlyweb.model.collections.Tiddlers(title='', store=None, bag=None, recipe=None)

Bases: tiddlyweb.model.collections.Collection

A Collection specifically for tiddlers.

This differs from the base class in two ways:

The calculation of the digest is more detailed in order to create stong ETags for the collection.

When iterated, if store is set on the Collection, then a yielded tiddler will be loaded from the store to fill in all its attributes. When a tiddler is added to the collection, if it is already filled, a non-full copy is made and put into the collection. This is done to save memory and because often the data is not needed.

If collections.use_memory is True in config then the full tiddler is kept in the collection. On servers with adequate memory this can be more efficient.

add(tiddler)

Add a reference to the tiddler to the container, updating the digest and modified information. If the tiddler has recently been deleted, resulting in a StoreError, don’t add it.

policy Module

A module containing the Policy class and associated exceptions.

exception tiddlyweb.model.policy.ForbiddenError

Bases: tiddlyweb.model.policy.PermissionsError

The provided user cannot do this action.

exception tiddlyweb.model.policy.PermissionsError

Bases: exceptions.Exception

Base class for Policy violations.

class tiddlyweb.model.policy.Policy(owner=None, read=None, write=None, create=None, delete=None, manage=None, accept=None)

Bases: object

A container for information about the contraints on a bag or recipe. Both are containers of tiddlers. We need to be able to control who can do what to do those tiddlers. We also need to be able to control who can manage those constraints.

The :pu:func:__init__ parameters represent a default policy.

There are six constraints plus one identifying attribute (owner). The constraints are listed below with descriptions of what is allowed if the constraint passes.

read

View this entity in lists. View the contained entities.

write

Edit the contained entities that already exist.

create

Create new entities in the container.

delete

Remove a contained entity.

manage

Change the policy itself.

accept

Accept the entity into the container without requiring validation.

allows(usersign, constraint)

Is the user encapsulated by the usersign dict allowed to perform the action described by constraint. If so, return True. If not raise a UserRequiredError (if the user is GUEST) or ForbiddenError exception.

The dict has a name key with a string value which is a username and a roles key with a list of roles as its value. Either may match in the constraint. Usersign is usually populated during the CredentialsExtractor phase of a request.

attributes = [u'read', u'write', u'create', u'delete', u'manage', u'accept', u'owner']

user_perms(usersign)

For this policy return a list of constraints for which this usersign passes.

exception tiddlyweb.model.policy.UserRequiredError

Bases: tiddlyweb.model.policy.PermissionsError

To do this action a user is required.

tiddlyweb.model.policy.create_policy_check(environ, entity, usersign)

Determine if the user in usersign can create entity type.

recipe Module

The Recipe class.

class tiddlyweb.model.recipe.Recipe(name, desc=u'')

Bases: object

A Recipe is an ordered list that represents a program for creating a collection of tiddlers.

Each line in the recipe is the combination of a bag name and a filter string. This implementation uses list of tuples.

In common usage a recipe contains only strings representing bags and filters, but for the sake of easy testing, the bag argument can be a Bag object.

A Recipe has a Policy which can be used to control access to the Recipe. These controls are optional and are primarily designed for use within the web handlers.

get_recipe(template=None)

Return the recipe list, as a list of tuple pairs.

set_recipe(recipe_list)

Set the contents of the recipe list.

tiddler Module

A module containing the Tiddler class and related functions.

class tiddlyweb.model.tiddler.Tiddler(title=None, bag=None)

Bases: object

The primary content object in the TiddlyWiki and TiddlyWeb universe, representing a distinct piece of content, often vaguely corresponding to a Page in wiki systems. A Tiddler has text and some associated metadata. The text can be anything, often wikitext in some form, or Javascript code. It is possible for a Tiddler to container binary content, such as image data.

A Tiddler is intentionally solely a container of data. That is, it has no methods which change the state of attributes in the Tiddler or manipulate the tiddler. Changing the attributes is done by directly changing the attributes. This is done to make the Tiddler easier to store and serialize in many ways.

A Tiddler has several attributes:

title

The name of the tiddler. Required.

created

A string representing when this tiddler was created.

modified

A string representing when this tiddler was last changed. Defaults to now.

modifier

A string representing a personage that changed this tiddler in some way. This doesn’t necessarily have any assocation with the tiddlyweb.usersign, though it may.

tags

A list of strings that describe the tiddler.

fields

An arbitrary dictionary of extended (custom) fields on the tiddler.

text

The contents of the tiddler. A string.

revision

The revision of this tiddler. The type of a revision is unspecified and is store dependent.

bag

The name of the bag in which this tiddler exists, if any.

recipe

The name of the recipe in which this tiddler exists, if any.

store

A reference to the Store object which retrieved this tiddler from persistent storage.

creator

Get the creator of this tiddler. If it has not been set then use modifier.

Use the creator property instead.

data_members = ['title', 'creator', 'created', 'modifier', 'modified', 'tags', 'fields', 'type', 'text']

slots = ['title', 'creator', 'created', 'modifier', 'modified', 'tags', 'fields', 'type', 'text', 'revision', 'bag', 'recipe', 'store']

tiddlyweb.model.tiddler.current_timestring()

Translate the current UTC time into a TiddlyWiki conformat timestring.

tiddlyweb.model.tiddler.string_to_tags_list(string)

Given a string representing tags (space-delimited, tags containing spaces are enclosed in in double brackets), parse them into a list of tag strings.

Duplicates are removed.

tiddlyweb.model.tiddler.tags_list_to_string(tags)

Given a list of tags, turn it into the canonical string representation (space-delimited, enclosing tags containing spaces in double brackets).

tiddlyweb.model.tiddler.timestring_to_datetime(timestring)

Turn a TiddlyWiki timestring into a datetime object.

Will raise ValueError if the input is not a 12 or 14 digit timestring.

user Module

A class representing a simple user entity.

A User object is not required during TiddlyWeb requests, credentials extractors and policies may work with arbitrary data for authentication and authorization. However if a locally stored user is required the User may be used.

class tiddlyweb.model.user.User(usersign, note=None)

Bases: object

A simple representation of a user. A user is a username, an optional password, an optional list of roles, and an optional note.

add_role(role)

Add the named role (a string) to this user.

check_password(candidate_password)

Check the password for this user. Return True if correct.

del_role(role)

Remove the named role (a string) from this user. If it is not there, do nothing.

list_roles()

List (as a list of strings) the roles that this user has.

set_password(password)

Set the password for this user.