API

This is the situation Application Programming Interface (API). This document provides a reference for using situation to write your own code.

situation

situation.id_generator(size=8, chars=None)

Create a random sequence of letters and numbers.

Parameters:

• size (int) – the desired length of the sequence
• chars (str) – the eligible character set to draw from when picking random characters

Returns:

a string with the random sequence

Resource

class situation.Resource(name, url, publisher, author[, description])

A Resource is an authoritative information source from which evidence is drawn.

Usually, a Resource is an artifact like a newspaper article, a report, or another document. These documents usually have an associated URL.

There may be many Resource from a single publisher or organization. Currently, the publisher is not a special component of the situation ontology. If it is necessary to include a publisher in a model, represent it as a Group.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• name (str) – what the resource is called (usually the title or headline)
• url (str) – the canonical URL for the resource
• publisher (str) – the name of the institution whose reputation backs this resource
• author (str) – the name of the author(s)
• description (str) – a short summary of this resource

Excerpt

class situation.Excerpt(content, resource[, xpath])

An Excerpt is a direct quote that comes from any Resource.

Any time an Excerpt is used, that Excerpt must be directly quotable from a Resource.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• content (str) – the actual quoted material of the excerpt
• resource (Resource) – the Resource from which this excerpt comes
• xpath (str) – the xpath leading to this excerpt within the Resource

Person

class situation.Person(name, alias[, excerpts, events, places, possessions, properties, groups, acquaintances])

A Person is an actor in a Situation.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• name (str) – what the person is called
• alias (str) – that other thing the person is called
• slug (str) – a URL-friendly identifier
• excerpts ([Excerpt]) – excerpts related to this Person
• events ([Event]) – events related to this Person
• places ([Place]) – places related to this Person
• possessions ([Item]) – items related to this Person
• properties ([Place]) – places owned by this Person
• groups ([Group]) – groups this Person is a member of
• acquaintances ([Acquaintance]) – people this Person knows

isa(isa_type, of)

A Person is a type of Acquaintance with the Acquainted.

alice = Person.find(name=”Alice”) bob = Person.find(name=”Bob”) bob.isa(“friend”, of=alice)

Acquaintance

class situation.Acquaintance(isa, person, acquainted[, excerpts])

An Acquaintance is a relationship between Persons.

This represents a directed edge, so a separate Acquaintance must be created to establish reciprocity.

Parameters:

• isa (str) – a description of the type of relationship
• person (Person) – the “source” of the acquaintance
• acquainted (Person) – the “target” of the acquaintance
• excerpts ([Excerpt]) – excerpts related to this Acquaintance

Place

class situation.Place(name, description, address, lat, lon[, owners, excerpts])

A Place is a location.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• name (str) – what the place is called
• description (str) – a short summary of this place
• address (str) – a human-readable postal address
• lat (float) – latitude
• lon (float) – longitudel
• owners ([Person]) – the property owner(s)
• excerpts ([Excerpt]) – excerpts related to this Place

Item

class situation.Item(name[, excerpts, owners, description])

An item is any “thing” that is work describing.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• name (str) – what the item is called
• description (str) – a short summary of this item
• owners ([Person]) – the property owner(s)
• excerpts ([Excerpt]) – excerpts related to this Item

Group

class situation.Group(name[, members, excerpts])

A Group is a collection of Persons who are associated with one another.

Membership in a group implies a many-to-many relationship between the members. A group is different from an Acquaintance; it is bi-directional, not uni-directional.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• name (str) – what the group is called
• members ([Person]) – people who are members of this Group
• excerpts ([Excerpt]) – excerpts related to this Group

Event

class situation.Event(name[, description, place, phone, timestamp, actors, excerpts, items])

An Event is an occurrence that somehow alters the Situation.

Parameters:

• id (int) – the database object identifier
• unique (str) – alpha-numeric code for shorthand identifier
• name (str) – what the event is called
• description (str) – a short summary of this item
• place (Place) – null
• phone (bool) – true if this event is a phone call
• timestamp (DateTime) – null
• actors ([Person]) – null
• excerpts ([Excerpt]) – excerpts related to this Event
• items ([Item]) – null

situation.io

situation.io.dump()

Build a dictionary containing the entire Situation.

Returns:a Dict with the situation as nested Dictionaries.

situation.io.save(filename)

Write the Situation to a JSON file.

Parameters:filename (str) – the name of the file to output to.

situation.io.build_events_dot()

Create a DOT graph from the Situation Events.

Returns:str with a valid DOT representation of actors, events, and locations

situation.io.save_events_dot(filename)

Write the Events as a Dot file.

Parameters:filename (str) – the name of the file to output to.