prisoner package


prisoner.SocialObjects module

class prisoner.SocialObjects.Address

Bases: prisoner.SocialObjects.SocialObject

Generally used as an attribute of Place, encodes a textual description of a physical address on Earth


The country name


A full textual representation of the address, formatted as for printing a mailing label


The city, town, village, etc.


The zip or postal code


The state or region


The street address including house number, street name, PO Box

class prisoner.SocialObjects.Collection

Bases: prisoner.SocialObjects.SocialObject

Represents a generic collection of SocialObjects. It may contain any number and any combination of SocialObjects.


The collection of objects. Should be a list or SocialObjects instances.

class prisoner.SocialObjects.Comment

Bases: prisoner.SocialObjects.SocialObject

A textual response to another SocialObject. The base type should not be used for replying with rich content - video or images, etc.


The SocialObject (or set of objects) this comment is in response to.

class prisoner.SocialObjects.DateTimeJSONHandler(context)

Bases: jsonpickle.handlers.BaseHandler

flatten(obj, data)
class prisoner.SocialObjects.Event

Bases: prisoner.SocialObjects.SocialObject

An event occuring in a place during a time interval.


A collection of People who have RSVP’d to an event


A time object representing when the event ends


A collection of People who have responded to say they may attend the event


A collection of People who have responded to say they are not attending the event


A time object representing when the event starts

class prisoner.SocialObjects.Image

Bases: prisoner.SocialObjects.SocialObject

A graphical image, such as a photo.


A URI for a full-size version of this image.

exception prisoner.SocialObjects.InvalidTransformationLevelError(value)

Bases: exceptions.Exception

class prisoner.SocialObjects.Note

Bases: prisoner.SocialObjects.SocialObject

A short text message, often used in a microblogging context, or to share short status updates. Shorter than blog posts, Notes are expected to have a shorter life and might not even expose a permalink

class prisoner.SocialObjects.Person

Bases: prisoner.SocialObjects.SocialObject

A human actor involved in the exchange of SocialObjects.


An instance of Image used to visually represent this Person.

class prisoner.SocialObjects.Place

Bases: prisoner.SocialObjects.SocialObject

A location on Earth. For maximum flexibility, use geographic coordinates. Alternatively, a physical address or free-form location name may be provided, so long as the applications which consume Place objects can understand its semantics. A combination of location identifiers may be used.


An instance of Address, for encoding a textual addresss


Latitude, longitude and altitude of point on Earth. This must be an ISO 6709 string (eg. “+27.5916+086.5640+8850/”)


Converts the internal ISO 6709 representation to a dictionary with ‘lat’ and ‘lng’ components, non-destructively

class prisoner.SocialObjects.SocialObject

Bases: object

SocialObjects are representations of social data, consumed and generated by a range of services and applications. Every SocialObject provides a small number of general attributes, with each implementation providing additional relevant attributes. SocialObjects must also provide transformation logic for each attribute, allowing each attribute to be sanitised to an appropriate level.


The person responsible for the creation of the object. For example, the person who wrote a post, uploaded a photo, etc. Should be an instance of Person.

base_transform_name(string, transformation, level)

The Base Social Objects package provides a number of standard transformations which are intended for use by any objects providing attributes of common types. This base transformation is designed to anonymise names of people, objects etc. but can be used for any string attribute

  • string (str) – the string to transform
  • transformation (str) – “reduce” supported. Coarsens author object depending on value for level
  • level (str) – first - reduce author’s displayName to first name last - reduce author’s displayName to last name initial - reduce author’s displayName to initials of current names



The main content of this object. Where possible, this should be plain text, or a URI to an external resource. Avoid packing binary data into this property as it may be difficult to sanitise and serialize.


A natural language plain-text description of this object, without any additional markup. For example, the name of a location, or a person’s full name.


All Social Objects should include a dictionary of friendly names - mapping their attributes to human-readable terms. Friendly names may consist of several words, and must make sense in the following sentence construction:

“This experiment may retrieve this social object’s <friendly name>”

Subclassed objects should provide their own self._friendly_names dictionary with mappings for each additional attribute it provides, or where it has semantically altered a base attribute. PRISONER will attempt to return a friendly name from the most specialised dictionary where possible

Parameters:attribute (str) – Attribute to get friendly name of

A unique identifier for this object. Where possible, this should allow the service gateway to relate an instance of a SocialObject to its counterpart on the service


An instance of Place to indicate the location of an object, or the location in which it was used.


The name of the ServiceGateway which generated this object, or where it is intended to be published to. This must map to an available ServiceGateway, or not be set.


A time object indicating when the object was created.


A collection of SocialObjects associated with this object. This object must not be dependent on the tags to be semantically correct (eg. do not embed a collection of authors as tags)

transform_hash(content, level='sha224')

Hashes content using given algorithm. Currently only supports SHA224

  • content – the content to be hashed
  • level – the hashing algorithm to use (only supports sha224)

hashed object

transform_reduce(content, level)

New-style transform for reduce. This is just a wrapper around the old base_transform_name

  • content – the content to be transformed, which will be cast to a string
  • level – the level to reduce to.

reduced content


A time object indicating when the object was last updated.


A permament link to this object’s online representation. This should be unique to this object and ideally permanent. It is acceptable for this link to be inaccessible without authentication.

Module contents