Code Documentation

This documentation file is automatically generated and kind of ugly. It will be more organized later.

Item Types (cms.models)

This module creates the item type framework, and defines the core item types.

class cms.models.AIMContactMethod(*args, **kwargs)

An AIMContactMethod is a ContactMethod that specifies an AIM screen name.

Version

alias of AIMContactMethodVersion

class cms.models.AddressContactMethod(*args, **kwargs)

An AddressContactMethod is a ContactMethod that specifies a physical address (or mailing address).

Version

alias of AddressContactMethodVersion

class cms.models.Agent(*args, **kwargs)

This item type represents an agent that can “do” things. Often this will be a person (see the Person subclass), but actions can also be performed by other agents, such as bots and anonymous agents.

Agents are unique in the following ways:

  • Agents can be assigned permissions
  • Agents show up in the creator fields of other items
  • Agents can authenticate with Deme using AuthenticationMethods
  • Agents can be contacted via their ContactMethods
  • Agents can subscribe to other items with Subscriptions
Version

alias of AgentVersion

class cms.models.AnonymousAgent(*args, **kwargs)

This item type is the agent that users of Deme authenticate as by default.

Because every action must be associated with a responsible Agent (e.g., updating an item), we require that users are authenticated as some Agent at all times. So if a user never bothers logging in at the website, they will automatically be logged in as an AnonymousAgent, even if the website says “not logged in”.

There should be exactly one AnonymousAgent at all times.

Version

alias of AnonymousAgentVersion

class cms.models.AuthenticationMethod(*args, **kwargs)

This item type represents an Agent’s credentials to login.

For example, there might be a AuthenticationMethod representing my Facebook account, a AuthenticationMethod representing my WebAuth account, and a AuthenticationMethod representing my OpenID account. Rather than storing the login credentials directly in a particular Agent, we allow agents to have multiple authentication methods, so that they can login different ways. In theory, AuthenticationMethods can also be used to sync profile information through APIs. There are subclasses of AuthenticationMethod for each different way of authenticating.

Version

alias of AuthenticationMethodVersion

class cms.models.Collection(*args, **kwargs)

A Collection is an Item that represents an unordered set of other items.

Collections just use pointers from Memberships to represent their contents, so multiple Collections can point to the same contained items.

Collections “directly” contain items via Memberships, but they also “indirectly” contain items via chained Memberships (see the RecursiveMembership model). If Collection 1 directly contains Collection 2 which directly contains Item 3, then Collection 1 indirectly contains Item 3.

It is possible for there to be circular memberships. Collection 1 might contain Collection 2 and Collection 2 might contain Collection 1. This will not cause any errors: it simply means that Collection 1 indirectly contains itself.

Version

alias of CollectionVersion

all_contained_collection_members(recursive_filter=None)

Return a QuerySet for all items that are either directly or indirectly contained by self (using RecursiveMembership).

If a recursive_filter is specified, use it to filter which RecursiveMemberships can be used to infer an item’s membership in this collection. Often, one will use a permission filter so that only those RecursiveMemberships that the Agent is allowed to view will be used.

class cms.models.Comment(*args, **kwargs)

A Comment is a unit of discussion about an Item.

Each comment specifies the commented item and version number. Like Document, Comment is meant to be abstract, so developers should always create subclasses rather than creating raw Comments.

Currently, users can only create TextComments.

Version

alias of CommentVersion

original_comment_in_thread()

Return the original comment at the top of this thread. If this already the topmost comment (i.e. it is a comment on a non-comment item), just return self.

For example, imagine self is comment A, and A is a reply to comment B, and B is a reply to non-comment item C. This method would return B. This method uses the RecursiveComment table.

class cms.models.ContactMethod(*args, **kwargs)

A ContactMethod belongs to an Agent and contains details on how to contact them. ContactMethod is meant to be abstract, so developers should always create subclasses rather than creating raw ContactMethods.

Version

alias of ContactMethodVersion

class cms.models.CustomUrl(*args, **kwargs)

A CustomUrl is a ViewerRequest that represents a specific path.

Each CustomUrl has a parent ViewerRequest (it will be the Site if this CustomUrl is the first path component) and a string for the path component. So when a user visits http://example.com/abc/def/ghi, Deme looks for a CustomUrl with name “ghi” with a parent with name “def” with a parent with name “abc” with a parent Site with hostname “example.com”.

Version

alias of CustomUrlVersion

class cms.models.DemeSetting(*args, **kwargs)

This item type stores global settings for the Deme installation.

Each DemeSetting has a unique key and an arbitrary value. Since values are strings of limited size, settings that involve a lot of text (e.g., a default layout) should have a value pointing to an item that contains the data (e.g., the id of a document).

Version

alias of DemeSettingVersion

static get(key)

Return the value of the DemeSetting with the specified key, or None if it is inactive or no such DemeSetting exists.

static set(key, value, action_agent)

Set the DemeSetting with the specified key to the specified value, such that the agent is the creator. This may result in creating a new DemeSetting, updating an existing DemeSetting, or reactivating an inactive DemeSetting.

class cms.models.DjangoTemplateDocument(*args, **kwargs)

This item type is a TextDocument that stores Django template code. It can display a fully customized page on Deme. This is primarily useful for customizing the layout of some or all pages, but it can also be used to make pages that can display content not possible in other Documents.

Version

alias of DjangoTemplateDocumentVersion

class cms.models.Document(*args, **kwargs)

A Document is an Item that is meant can be a unit of collaborative work.

Document is meant to be abstract, so developers should always create subclasses rather than creating raw Documents.

Version

alias of DocumentVersion

class cms.models.EditLock(*args, **kwargs)

This table contains information on all items currently being edited. This allows us to lock items to prevent simultaneous editing.

class cms.models.EmailContactMethod(*args, **kwargs)

An EmailContactMethod is a ContactMethod that specifies an email address.

Version

alias of EmailContactMethodVersion

class cms.models.Excerpt(*args, **kwargs)

An Excerpt is an Item that refers to a portion of another Item (or an external resource, such as a webpage).

Excerpt is meant to be abstract, so developers should always create subclasses rather than creating raw Excerpts.

Version

alias of ExcerptVersion

class cms.models.FaxContactMethod(*args, **kwargs)

A FaxContactMethod is a ContactMethod that specifies a fax number.

Version

alias of FaxContactMethodVersion

class cms.models.FileDocument(*args, **kwargs)

A FileDocument is a Document that stores a file on the filesystem (could be an MP3 or a Microsoft Word Document). It is intended for all binary data, which does not belong in a TextDocument (even though it is technically possible).

Subclasses of FileDocument may be able to understand various file formats and add metadata and extra functionality.

Version

alias of FileDocumentVersion

class cms.models.Folio(*args, **kwargs)

A folio is a special collection that belongs to a group.

Version

alias of FolioVersion

class cms.models.Group(*args, **kwargs)

A group is a collection of Agents.

A group has a folio that is used for collaboration among members.

Version

alias of GroupVersion

class cms.models.GroupAgent(*args, **kwargs)

This item type is an Agent that acts on behalf of an entire group. It can’t do anything that other agents can’t do. Its significance is just symbolic: by being associated with a group, the actions taken by the group agent are seen as collective action of the group members. In general, permission to login_as the group agent will be limited to powerful members of the group.

There should be exactly one GroupAgent for every group.

Version

alias of GroupAgentVersion

class cms.models.HtmlDocument(*args, **kwargs)

An HtmlDocument is a TextDocument that renders its body as HTML.

Version

alias of HtmlDocumentVersion

class cms.models.ImageDocument(*args, **kwargs)

An ImageDocument is a FileDocument that stores an image.

Right now, the only difference is that viewers know the file can be displayed as an image. In the future, this may add metadata like EXIF data and thumbnails.

Version

alias of ImageDocumentVersion

class cms.models.Item(*args, **kwargs)

Superclass of all item types.

Since everything is an item, this item type provides a unique id across all items. This item type also defines some important common structure to all items, such as name, description, and details about its creation and last update.

Every subclass should define the following attributes:

  • introduced_immutable_fields: a frozenset of strings representing the names of fields which may not be modified after creation (this differs from editable=False in that introduced_immutable_fields may be customized by a user upon creation, but uneditable fields are not to be edited in the front end)
  • introduced_abilities: a frozenset of abilities that are relevant to this item type
  • introduced_global_abilities: a frozenset of global abilities that are introduced by this item type
  • dyadic_relations: a dict from field_name1 to (field_name2, relation_name) for showing that this item type is really just a dyadic relation between the two fields
Version

alias of ItemVersion

actual_item_type()

Return the actual item type for this item as a class (not a string).

For example, Item.objects.get(pk=1).actual_item_type() == Agent

all_comments()

Return all active Comments made directly or indirectly on self.

classmethod all_immutable_fields()

Return a frozenset of the names of all the fields that are immutable for this item type (recursively traverses through item type hierarchy).

all_parents_in_thread(include_parent_collections=False, recursive_filter=None)

Return a QuerySet including self and all direct and indirect parents in this thread. If self is a Comment, this will return self, the parent, the grandparent, so on up to (and including) the original item. If self is not a Comment, this should only self (unless include_parent_collections is True as explained below).

If include_parent_collections=True, also include all Collections containing self or parents in this thread, either through direct or indirect membership. If a recursive_filter is specified, use it to filter which RecursiveMemberships can be used to infer an item’s membership in this collection. Often, one will use a permission filter so that only those RecursiveMemberships that the Agent is allowed to view will be used.

ancestor_collections(recursive_filter=None)

Return all active Collections containing self directly or indirectly.

A Collection does not indirectly contain itself by default.

If a recursive_filter is specified, use it to filter which RecursiveMemberships can be used to infer self’s membership in a collection. Often, one will use a permission filter so that only those RecursiveMemberships that the Agent is allowed to view will be used.

classmethod auto_populate_fields(item_type, field_dict, viewer)

Given a field_dict from field names to initial values, populate any other fields (in the dict) with values. For example, in a Subscription, given that the subscribed item is X, we might want to set the name of the subscription to “Subscription to X”. This is used when presenting a user with a form.

Item types that want to automatically populate field names based on other fields should override this method, making sure to put a call superclasses at the top, like: >> super(Subscription, cls).auto_populate_fields(item_type, field_dict, viewer)

can_be_deleted()

This method returns False for special items that should never be deleted, such as the AnonymousAgent; and it returns True for ordinary items.

Item types that want to define special items should override this method.

copy_fields_from_version(version_number)

Set the fields of self to what they were at the given version number. This method does not make any database writes.

copy_fields_to_itemversion(itemversion)

Sets the fields of the itemversion from self’s fields. This method does not make any database writes.

This method may use self.version_number to calculate a delta (although it does not currently).

deactivate(*args, **kwargs)

Deactivate the current Item (the specified agent was responsible with the given summary at the given time). This will call _after_deactivate if the item was previously active.

destroy(*args, **kwargs)

Nullify the fields of this item (the specified agent was responsible with the given summary at the given time) and delete all versions. The item must already be inactive and cannot have already been destroyed. This will call _after_destroy.

display_name(can_view_name_field=True)

Return a friendly display name for the item.

If the item has a blank name field, return a string of the form “ItemType id” (like Agent 1). Otherwise, just return the value of the name field.

If can_view_name_field is False, only return the “ItemType id” form.

classmethod do_specialized_form_configuration(item_type, is_new, attrs)

Perform any specialized configuration for a Django form. The is_new parameter is True if the form is creating a new item, and is False if the form is updating an existing item. The attrs parameter is the list of class attrs that are about to be passed into the forms.models.ModelFormMetaclass constructor.

This function should modify the attrs dictionary in order to configure the form.

Item types that want to configure the default Django form in a special way should override this method, making sure to put a call superclasses at the top, like: >> super(Membership, cls).do_specialized_form_configuration(item_type, is_new, attrs)

downcast()

Return this item as an instance of the actual item type.

For example, if the current item is an Agent, this will return an Agent, even though self is an Item.

When the type of self is the actual item type, this returns self (not a copy); otherwise, this makes a single database query and returns an instance of the actual item type.

get_default_viewer()

Return the name of the default viewer. If the default_viewer field is invalid, returns the item type’s default viewer.

is_downcast()

Return true if this item is instantiated at the actual item type.

For example, if item 123 is an agent, then: Agent.get(pk=123).is_downcast() == true Item.get(pk=123).is_downcast() == false

original_item_in_thread()

Return the original item that was commented on in this thread. If this is not a Comment, just return self.

For example, if this is a reply to a reply to a comment on X, this method will return X. This method uses the RecursiveComment table.

reactivate(*args, **kwargs)

Reactivate the current Item (the specified agent was responsible with the given summary at the given time). This will call _after_reactivate if the item was previously inactive.

relation_action_notice_natural_language_representation(permission_cache, field_name, relation_added, action_item)

Return a natural language representation of a RelationActionNotice with the given parameters, such that the from_item is self. The result will be in the form of a list of strings and items. The string representation can later be formed by concatenating the elements of the list, using the strings and relevant fields of the items. Remember to include spaces in the strings so that there is space around the item name. If field_name does not match any of the foreign keys for the item type, return None.

save_versioned(*args, **kwargs)

Save the current item (the specified agent was responsible with the given summary at the given time), making sure to keep track of versions.

Use this method instead of save() because it will keep things consistent with versions and special fields. This will set created_at to the current time (or action_time parameter) if this is a creation.

If first_agent=True, then this method assumes you are creating the first item (which should be an Agent). It is necessary to save the first item as an Agent in this way so that every Item has a valid creator pointer.

If the initial_permissions parameter is given, it should be a list of unsaved Permissions. After successfully saving self, this method will save these permissions (setting permission.target = self) before calling any callbacks.

This will call _after_create or _after_edit, depending on whether the item already existed.

unique_error_message(model_class, unique_check)

Set the error message function for uniqueness constraint violations, so that when it is displayed, it links to the item it clashes with (and provides a quick link to overwrite it).

class cms.models.Membership(*args, **kwargs)

A Membership is a relationship between a collection and one of its items.

Version

alias of MembershipVersion

class cms.models.Person(*args, **kwargs)

A Person is an Agent that represents a person in real life.

Version

alias of PersonVersion

class cms.models.PhoneContactMethod(*args, **kwargs)

A PhoneContactMethod is a ContactMethod that specifies a phone number.

Version

alias of PhoneContactMethodVersion

class cms.models.RecursiveComment(*args, **kwargs)

This table contains all pairs (item, comment) such that comment is directly or indirectly a comment on item.

For example if A is an Item, B is a Comment on A, and C is a comment on B, then this table will contain (A,B) (B,C) and (A,C).

static recursive_add_comment(comment)

Update the table to reflect that the given comment was created.

static recursive_remove_comment(comment)

Update the table to reflect that the given comment was destroyed.

class cms.models.RecursiveMembership(*args, **kwargs)

This table contains all pairs (collection, item) such that item is directly or indirectly a member of collection.

Each RecursiveMembership row also contains a many-to-many set of Memberships (child_memberships) such that there exists an path of memberships from the child to the parent where the first membership in the path is in child_memberships.

When Collections or Memberships are deactivated, this table is updated as if the Collection or Membership did not exist.

For example if A is a Collection, and B is a Collection (which is a member of A), and C is an Item (which is a member of B), and D is an Item (which is a member of A and B), then the table will contain:

(A,B) child_memberships={(A,B)} (B,C) child_memberships={(B,C)} (A,C) child_memberships={(B,C)} (A,D) child_memberships={(A,D),(B,D))} (B,D) child_memberships={(B,D)}

The permission_enabled field is set to True if there exists at least one path of Memberships from parent to child, such that each membership in the path has permission_enabled=True.

static recursive_add_collection(collection)

Update the table to reflect that the given collection was created or reactivated.

static recursive_add_membership(membership)

Update the table to reflect that the given membership was created (or reactivated).

static recursive_remove_collection(collection)

Update the table to reflect that the given collection was deactivated.

static recursive_remove_edge(parent, child)

Update the table to reflect that child is no longer directly a member of parent.

class cms.models.Site(*args, **kwargs)

A Site is a ViewerRequest that represents a logical website with URLs.

Multiple Sites on the same Deme installation share the same Items with the same unique ids, but they resolve URLs differently so each Site can have a different page for /mike. If you go to the base URL of a site (like http://example.com/), you see the ViewerRequest that this Site inherits from.

Version

alias of SiteVersion

class cms.models.Subscription(*args, **kwargs)

A Subscription is a relationship between an Item and a ContactMethod, indicating that all action notices on the item should be sent to the contact method as notifications.

If deep=True and the item is a Collection, then action notices on all items in the collection (direct or indirect) will be sent in addition to comments on the collection itself.

The subscribe_edit, subscribe_delete, subscribe_comments, and subscribe_relations fields determine what action notices will trigger this subscription.

Version

alias of SubscriptionVersion

class cms.models.TextComment(*args, **kwargs)

A TextComment is a Comment and a TextDocument combined. It is currently the only form of user-generated comments.

Version

alias of TextCommentVersion

class cms.models.TextDocument(*args, **kwargs)

A TextDocument is a Document that has a body that stores arbitrary text.

Version

alias of TextDocumentVersion

class cms.models.TextDocumentExcerpt(*args, **kwargs)

A TextDocumentExcerpt refers to a contiguous region of text in a version of another TextDocument in Deme.

The body field contains the excerpted region, and the start_index and length identify the character position of this region within the specified TextDocument.

Version

alias of TextDocumentExcerptVersion

class cms.models.Transclusion(*args, **kwargs)

A Transclusion is an embedded reference from a location in a specific version of a TextDocument to another Item.

Version

alias of TransclusionVersion

class cms.models.ViewerRequest(*args, **kwargs)

A ViewerRequest represents a particular action at a particular viewer (basically a URL, although its stored more explicitly). It specifies a viewer (just a string, since viewers are not Items), an action (like “view” or “edit”), an item that is referred to (or null for collection-wide actions), a query_string if you want to pass parameters to the viewer, and a format.

A ViewerRequest is supposed to be abstract, so users can only create Sites and CustomUrls.

Version

alias of ViewerRequestVersion

calculate_full_path()

Return a tuple (site, custom_urls) where custom_urls is a list.

class cms.models.WebsiteContactMethod(*args, **kwargs)

A WebsiteContactMethod is a ContactMethod that specifies a website URL.

Version

alias of WebsiteContactMethodVersion

cms.models.all_item_types()

Return a list of every item type (as a class).

cms.models.get_item_type_with_name(name, case_sensitive=True)

Return the item type class with the given name (case-sensitive or not, as specified), or return None if there is no item type with the name.

class cms.models.ActionNotice(*args, **kwargs)

An ActionNotice is a model (not a subclass of Item) that records an action happening in Deme. ActionNotice is meant to be abstract, so only subclasses should ever be created.

notification_email(subscription, email_contact_method)

Return an EmailMessage with the notification that should be sent to the specified EmailContactMethod. If there is no Subscription, or the Agent with the subscription is not allowed to receive the notification, return None.

notification_reply_item()

Return the item that comments created about this notice (via replying to a notification email for this notice) are replies to.

class cms.models.RelationActionNotice(*args, **kwargs)

A RelationActionNotice is created on an item whenever another item (the “from item”) is created or modified so that one of its foreign-key fields now points to the item (when it didn’t before) or no longer points to the item (when it did before).

If relation_added is true, it means that the from item did not point before but now does; and if relation_added is false, it means that from item did point before but no longer does.

static create_notices(action_agent, action_summary, action_time, action_item, existed_before, existed_after)

This method should be called whenever an item is created, edited, deactivated, or reactivated. It generates all relevant RelationActionNotices relevant to the action.

The flags existed_before and existed_after are used to indicate what the action did to the item. If the item was reactivated or created, existed_before would be false, otherwise it would be true. If the item was deactivated, existed_after would be false, otherwise it would be true.

notification_reply_item()

In RelationActionNotices, when someone replies to a notification, it should be turned into a comment on from_item, not item.

For example, if we have a RelationActionNotice with from_item=membership and item=agent, the reply comment should go to membership, not agent.

class cms.models.DeactivateActionNotice(*args, **kwargs)

A DeactivateActionNotice is generated whenever someone deactivates an item.

class cms.models.ReactivateActionNotice(*args, **kwargs)

A ReactivateActionNotice is generated whenever someone reactivates an item.

class cms.models.DestroyActionNotice(*args, **kwargs)

A DestroyActionNotice is generated whenever someone destroys an item.

class cms.models.CreateActionNotice(*args, **kwargs)

A CreateActionNotice is generated whenever someone creates an item.

class cms.models.EditActionNotice(*args, **kwargs)

An EditActionNotice is generated whenever someone edits an item.

class cms.models.FixedBooleanField(*args, **kwargs)

This is a modified NullBooleanField that uses a checkbox-style FormField. This is used to replace BooleanFields that are normally not supposed to have a null options, but are allowed to have null options for the purpose of deleting items. Because Django SVN revision r10456 made it so BooleanFields cannot be null, we have to use this instead.

south_field_triple()

Returns a suitable description of this field for South.

class cms.models.FixedForeignKey(*args, **kwargs)

This is a modified ForeignKey that specifies the abilities required to modify the field. The abilities must be had by the action agent on the pointee.

south_field_triple()

Returns a suitable description of this field for South.

class cms.models.Permission(*args, **kwargs)

Abstract superclass of all permissions.

class cms.models.OneToOnePermission(*args, **kwargs)

Permissions from individual agents to individual items.

class cms.models.OneToSomePermission(*args, **kwargs)

Permissions from individual agents to collections of items.

class cms.models.OneToAllPermission(*args, **kwargs)

Permissions from individual agents to all items.

class cms.models.SomeToOnePermission(*args, **kwargs)

Permissions from collections of agents to individual items.

class cms.models.SomeToSomePermission(*args, **kwargs)

Permissions from collections of agents to collections of items.

class cms.models.SomeToAllPermission(*args, **kwargs)

Permissions from collections of agents to all items.

class cms.models.AllToOnePermission(*args, **kwargs)

Permissions from all agents to individual items.

class cms.models.AllToSomePermission(*args, **kwargs)

Permissions from all agents to collections of items.

class cms.models.AllToAllPermission(*args, **kwargs)

Permissions from all agents to all items.

cms.models.friendly_name_for_ability(ability)

Return a friendly name string for the given ability, or None if not found.

class cms.models.Webpage(*args, **kwargs)

This item type represents a webpage. The only new field that isn’t inherited from Item is the webpage’s url

Version

alias of WebpageVersion

Item Viewers (cms.views)

Table Of Contents

Previous topic

Deme Architecture

This Page