API

Models

There are two types of models used in Fiction Outlines, Standard and Tree.

Standard

Standard models are rather typical Django models and so the API is much as you would expect.

class fiction_outlines.models.Series(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

Container object to hold multiple outline objects if necessary.

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• title (CharField) – Name of the series. You can always change this later.
• description (TextField) – Jot down a description about your series.
• user_id (ForeignKey) – The user that created this Series.

This model represents a story series that can hold one or more outlines within it. it is not necessary to define a Series, but it is a useful organizational tool. Standard Django ORM applies.

class fiction_outlines.models.Character(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

Reusable character defintion model.

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• name (CharField) – Name of the character.
• description (TextField) – Notes about the character to help you remember.
• user_id (ForeignKey) – The user that created this character.

This model represents a character that may be reused in multiple series, outlines, and story elements.

class fiction_outlines.models.CharacterInstance(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

An instance of the character object that can be associated with outlines.

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• main_character (BooleanField) – Is this character the main character for the outline?
• pov_character (BooleanField) – Is this character a POV character?
• protagonist (BooleanField) – Does this character serve as the protagonist for this outline?
• antagonist (BooleanField) – Does this character serve as an antagonist for this outline?
• obstacle (BooleanField) – Is this character an obstacle in the outline? (not antagonist)
• villain (BooleanField) – Is the character a straight-out villain?
• character_id (ForeignKey) – Reference to originating character object.
• outline_id (ForeignKey) – Outline this instance is associated with.

This model represents a single instance of a character that is associated with an Outline. Contains additional metadata on the character’s role in the story.

class fiction_outlines.models.Location(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

Reusable location definition model

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• name (CharField) – Name of the location.
• description (TextField) – Notes about the location to help you remember.
• user_id (ForeignKey) – The user that created this location.

This model represents a location that may be reused in multiple series, outlines, and story elements.

class fiction_outlines.models.LocationInstance(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

An instance of the given location that can be associated with a given outline.

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• location_id (ForeignKey) – Originating location object.
• outline_id (ForeignKey) – Outline this object is associated with.

This model represents an instance of a location that is associated with an outline.

class fiction_outlines.models.Outline(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

The typical top of the hierarchy when not enclosed in a series.

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• title (CharField) – Outline title. You can always change this later.
• description (TextField) – Optionally, describe the story. Or use for notes.
• series_id (ForeignKey) – Belongs to series.
• user_id (ForeignKey) – The user that created this outline.

The outline is the manuscript level element that represents and encapsulates all the information about a specific work. It provides a number of convenient convenience features.

Outline.length_estimate()

Calculates and estimated word count based on number of characters, locations, and arcs. For reference see: http://www.writingexcuses.com/2017/07/02/12-27-choosing-a-length/

This is a cached property that calculates the projected total length of the manuscript.

Example:

o1.length_estimate
# Returns estimated total words.

Outline.story_tree_root()

Fetches the root node for the outline’s StoryElementNode tree.

Cached property that returns the root of the outline tree.

Example:

root_node = o1.story_tree_root

Outline.refresh_from_db(*args, **kwargs)

Just like Django’s refresh_from_db() except that this clears the property cache of the object as well.

Outline.create_arc(mace_type, name)

Creates the story arc and initial tree for that arc for the current outline. Returns the resulting Arc instance.

Creates an Arc object within the outline, and builds the initial tree of ArcElementNode objects. Returns the Arc object.

Example:

arc1 = o1.create_arc(mace_type='event', name='Dragon Invasion')

Outline.validate_nesting()

Reviews the story tree and validates associated arc elements are nested appropriately. Returns a dict of errors.

Evaluates the tree of StoryElementNode objects and returns a dict of errors if any are found. For each error entry, a list of offending nodes will also be included.

Example:

error_dict = o1.validate_nesting()
if error_dict:
   # There are errors
   for key, value in error_dict.items():
       print("%s: %s" % (key, value)

class fiction_outlines.models.Arc(*args, **kwargs)

Bases: model_utils.models.TimeStampedModel

A MACE arc for a outline.

Parameters:

• created (AutoCreatedField) – Created
• modified (AutoLastModifiedField) – Modified
• id (UUIDField) – Id
• mace_type (CharField) – The MACE type of the Arc.
• outline_id (ForeignKey) – Arc belongs to this outline.
• name (CharField) – Name of this Arc (makes it easier for you to keep track of it.)

The arc represents a story throughline that will be integrated with the outline.

Arc.current_errors()

Returns list of errors from arc_validation.

A cached property of current structural errors within the Arc.

Arc.arc_root_node()

Returns the root node from this object’s ArcElementNode tree.

A cached property pointing to the root node of the ArcElementNode object tree.

Arc.refresh_from_db(*args, **kwargs)

Like the standard Django method, but this also clears cached properties.

Arc.generate_template_arc_tree()

Generate a seven point template in this arc. Arc must be empty.

Creates the template arc tree using Seven Point Story Structure.

Arc.fetch_arc_errors()

Evaluates the current tree of the arc and provides a list of errors that the user should correct.

Evaluates the arc tree for errors the user is recommended to correct.

Arc.validate_first_element()

Ensures that the first node for the direct decendents of root is the hook.

Checks that the first child of the root is the Hook.

Arc.validate_last_element()

Ensures that the last element of the arc is the resolution.

Checks that the last child of the root is the Resolution.

Arc.validate_generations()

Make sure that the descendent depth is valid.

Reviews the structure of the Arc to ensure that node types follow the allowed_parents and allowed_children properties.

Arc.validate_milestones()

Reviews the arc element tree to ensure that milestones appear in the right order.

Verifies that milestones appear in the tree in the Arc tree in the correct sequence.

Tree Models

Tree models are Materialized Path trees descended from the django-treebeard provided MP_Node.

Note

A discussion of the details of working with MP trees is out of scope for this document. You are recommended to peruse django-treebeard’s excellent documentation. Make sure to also review fiction_outlines Caveats documentation.

class fiction_outlines.models.ArcElementNode(*args, **kwargs)

Bases: treebeard.mp_tree.MP_Node

Tree nodes for the arc elements.

Parameters:

• path (CharField) – Path
• depth (PositiveIntegerField) – Depth
• numchild (PositiveIntegerField) – Numchild
• id (UUIDField) – Id
• arc_element_type (CharField) – What part of the arc does this represent?
• arc_id (ForeignKey) – Parent arc.
• headline (CharField) – Autogenerated from description
• description (TextField) – Describe what happens at this moment in the story…
• story_element_node_id (ForeignKey) – Which story node is this element associated with?

This model represents the nodes of the tree that is used as the structure of the Arc.

ArcElementNode.milestone_seq()

Returns the milestone sequence based off of the arc element definitions.

Cached property retrieving the derived milestone sequence number as it relates to 7PSS_.

ArcElementNode.is_milestone()

Does this node represent an arc milestone?

Cached property returning if this node represents an arc milestone.

ArcElementNode.parent_outline()

Private method to fetch parent outline.

Cached property for convenient access to the outline to which this arc tree belongs.

ArcElementNode.move(target, pos=None)

Moves the current node and all it’s descendants to a new position relative to another node.

Raises:PathOverflow – when the library can’t make room for the node’s new position

Subclass of the treebeard method. Fires a tree_manipulation signal for your use.

ArcElementNode.add_child(arc_element_type, description=None, story_element_node=None, **kwargs)

Overrides the default treebeard function, adding additional integrity checks.

Subclasses the treebeard method to add required logic for instantiating an Arc Element object.

Example:

# Add a try/fail cycle
new_element = ae1.add_child('tf', description="Attempting to get into the secret enclave to get information")

ArcElementNode.add_sibling(pos=None, arc_element_type=None, description=None, story_element_node=None, **kwargs)

Overrides the default treebeard function, adding additional integrity checks.

Subclasses the treebeard method to add specific model instantiation requirements.

Example:

# Add another beat that followed after another one
beat2 = beat1.add_sibling('beat', description="John discovers an odd item in his bag.")

class fiction_outlines.models.StoryElementNode(*args, **kwargs)

Bases: treebeard.mp_tree.MP_Node

Tree nodes for the overall outline of the story.

Parameters:

• path (CharField) – Path
• depth (PositiveIntegerField) – Depth
• numchild (PositiveIntegerField) – Numchild
• id (UUIDField) – Id
• name (CharField) – Optional name/title for this element of the story.
• description (TextField) – Optional description for this element of the story.
• outline_id (ForeignKey) – Parent outline.
• story_element_type (CharField) – What part of the story does this represent? A scene? A chapter?

This class represent the actual structure of the overall outline. Individual arc elements can be associated with a story node, which is how the outline validation tool can verify that Nesting is valid.

StoryElementNode.all_characters()

Returns a queryset of all characters associated with this node and its descendants, excluding any duplicates.

A property that returns queryset of all the unique character instances associated with this node, and any of its descendant nodes.

StoryElementNode.all_locations()

Returns a queryset of all locations associated with this node and its descendants, excluding any duplicates.

A property that returns a queryset of all the unique location instances associated with this node, and any of its descendant nodes.

StoryElementNode.impact_rating()

Returns the impact rating for this node. Impact rating is a measure of how powerful this moment in the story is by evaluting how many simultaneous arc elements are associated with it. There is also a generational bleed element, where the impact score creates shockwaves throughout their direct ancestor and descendant nodes. This echo fades fast, but the bigger the impact, the farther it goes.

Currently, the impact bleed does not extend to sibling nodes.

WARNING: Here be dragons.

A property representing the impact/tension rating of this node (expressed as a float) in the outline. This rating is derived from associations with arc elements, with extra impact when mulitple arcs overlap in the same node. Impact also affects ancestor and descendant nodes with weakening influence the more generations away from the source node. However, impact bleed does not extend to sibling nodes.

StoryElementNode.move(target, pos=None)

An override of the treebeard api in order to send a signal in advance.

Subclass of the treebeard move method, but also sends signal tree_manipulation which you can use with your signal receivers.

StoryElementNode.add_child(story_element_type=None, outline=None, name=None, description=None, **kwargs)

An override of the treebeard add_child() method so we can send a signal.

Subclass of the treebeard method, but adds instantiation logic for this model.

Example:

new_node = node.add_child(story_element_type='chapter', outline=o1, name='Chapter 1', description='Our story begins.')

StoryElementNode.add_sibling(story_element_type=None, outline=None, name=None, description=None, pos=None, **kwargs)

Override of treebeard api to allow us to send a signal.

Subclass of the treebeard method, but adds model instantiation logic.

Example:

chap2 = new_node.add_sibling(story_element_type='chapter', outline=o1, name='Chapter 2', description='Meanwhile, on the other side of the world')