--- a/Allura/allura/model/artifact.py
+++ b/Allura/allura/model/artifact.py
@@ -216,6 +216,10 @@
return None
class Feed(MappedClass):
+ """
+ Used to generate rss/atom feeds. This does not need to be extended;
+ all feed items go into the same collection
+ """
class __mongometa__:
session = project_orm_session
name = 'artifact_feed'
@@ -235,6 +239,7 @@
@classmethod
def post(cls, artifact, title=None, description=None):
+ "Create a Feed item"
idx = artifact.index()
if title is None:
title='%s modified by %s' % (idx['title_s'], c.user.get_pref('display_name'))
@@ -248,6 +253,7 @@
@classmethod
def feed(cls, q, feed_type, title, link, description,
since=None, until=None, offset=None, limit=None):
+ "Produces webhelper.feedgenerator Feed"
d = dict(title=title, link=h.absurl(link), description=description, language=u'en')
if feed_type == 'atom':
feed = FG.Atom1Feed(**d)
@@ -275,6 +281,19 @@
return feed
class Artifact(MappedClass):
+ """
+ The base class for anything you want to keep track of.
+
+ It will automatically be added to solr (see index() method). It also
+ gains a discussion thread and can have files attached to it.
+
+ :var tool_version: default's to the app's version
+ :var acl: dict of permission name => [roles]
+ :var labels: list of plain old strings
+ :var references: list of outgoing references to other tickets
+ :var backreferences: dict of incoming references to this artifact, mapped by solr id
+ """
+
class __mongometa__:
session = artifact_orm_session
name='artifact'
@@ -301,7 +320,7 @@
tags = FieldProperty([dict(tag=str, count=int)])
labels = FieldProperty([str])
references = FieldProperty([ArtifactReferenceType])
- backreferences = FieldProperty({str:ArtifactReferenceType})
+ backreferences = FieldProperty({str:ArtifactReferenceType}) # keyed by solr id to emulate a set
app_config = RelationProperty('AppConfig')
@classmethod
@@ -431,6 +450,7 @@
l.remove(project_role_id)
def index_id(self):
+ "Used for solr search indexing"
id = '%s.%s#%s' % (
self.__class__.__module__,
self.__class__.__name__,
@@ -438,6 +458,15 @@
return id.replace('.', '/')
def index(self):
+ """
+ Subclasses should override this, providing a dictionary of solr_field => value.
+ These fields & values will be stored by solr. Subclasses should call the
+ super() index() and then extend it with more fields. All these fields will be
+ included in the 'text' field (done by search.solarize())
+
+ The _s and _t suffixes, for example, follow solr dynamic field naming pattern.
+ """
+
project = self.project
return dict(
id=self.index_id(),
@@ -456,6 +485,9 @@
snippet_s='')
def url(self):
+ """
+ Subclasses should implement this, providing the URL to the artifact
+ """
raise NotImplementedError, 'url' # pragma no cover
def shorthand_id(self):
@@ -484,6 +516,7 @@
return att
class Snapshot(Artifact):
+ """A snapshot of an :class:`Artifact <allura.model.Artifact>`, used in :class:`VersionedArtifact <allura.model.VersionedArtifact>`"""
class __mongometa__:
session = artifact_orm_session
name='artifact_snapshot'
@@ -524,6 +557,10 @@
return getattr(self.data, name)
class VersionedArtifact(Artifact):
+ """
+ An :class:`Artifact <allura.model.Artifact>` that has versions.
+ Associated data like attachments and discussion thread are not versioned.
+ """
class __mongometa__:
session = artifact_orm_session
name='versioned_artifact'
@@ -594,6 +631,14 @@
return self.mod_date
class Message(Artifact):
+ """
+ A message
+
+ :var _id: an email friendly (e.g. message-id) string id
+ :var slug: slash-delimeted random identifier. Slashes useful for threaded searching and ordering
+ :var full_slug: string of slash-delimited "timestamp:slug" components. Useful for sorting by timstamp
+ """
+
class __mongometa__:
session = artifact_orm_session
name='message'
@@ -711,6 +756,7 @@
return self.short
class AwardGrant(Artifact):
+ "An :class:`Award <allura.model.Award>` can be bestowed upon a project by a neighborhood"
class __mongometa__:
session = main_orm_session
name='grant'