Stalker Documentation

Travis-CI Build Status License Supported Python versions PyPI Version Wheel Support


Stalker is an Open Source Production Asset Management (ProdAM) Library designed specifically for Animation and VFX Studios but can be used for any kind of projects. Stalker is licensed under LGPL v3.


Stalker has the following features:

  • Designed for Animation and VFX Studios.
  • Platform independent.
  • Default installation handles nearly all the asset and project management needs of an animation and vfx studio.
  • Customizable with configuration scripts.
  • Customizable object model (Stalker Object Model - SOM).
  • Uses TaskJuggler as the project planing and tracking backend.
  • Mainly developed for PostgreSQL in mind but SQLite3 is also supported.
  • Can be connected to all the major 3D animation packages like Maya, Houdini, Nuke, Fusion, Softimage, Blender etc. and any application that has a Python API. And with applications like Adobe Photoshop which does not have a direct Python API but supports win32com or comtypes.
  • Mainly developed for Python 3.0+ and Python 2.7 is fully supported.
  • Developed with TDD practices.

Stalker is build over these other OpenSource projects:

  • Python
  • SQLAlchemy and Alembic
  • Jinja2
  • TaskJuggler

Stalker as a library has no graphical UI, it is a python library that gives you the ability to build your pipeline on top of it. There are other python packages like the Open Source Pyramid Web Application Stalker Pyramid and the Open Source pipeline library Anima which has PyQt/PySide/PySide2 UIs for applications like Maya, Nuke, Houdini, Fusion, Photoshop etc.



pip install stalker


Let’s play with Stalker.

Initialize the database and fill with some default data:

from stalker import db

Create a User:

from stalker.db.session import DBSession
from stalker import User
me = User(
    name='Erkan Ozgur Yilmaz',

# Save the user to database

Create a Repository for project files to be saved under:

from stalker import Repository
repo = Repository(
    name='Commercial Projects Repository',

Create a FilenameTemplate (to be used as file naming convention):

from stalker import FilenameTemplate

task_template = FilenameTemplate(
    name='Standard Task Filename Template',
    target_entity_type='Task',  # This is for files saved for Tasks
         '{%- for parent_task in parent_tasks -%}'
         '{%- endfor -%}',  # This is Jinja2 template code

Create a Structure that uses this template:

from stalker import Structure
standard_folder_structure = Structure(
    name='Standard Project Folder Structure',
    custom_template='{{project.code}}/References'  # If you need extra folders

Now create a Project that uses this structure and will be placed under the repository:

from stalker import Project
new_project = Project(
    name='Test Project',
    repositories=[repo],  # if you have more than one repository you can do it

Define the project resolution:

from stalker import ImageFormat
hd1080 = ImageFormat(

Set the project resolution:

new_project.image_format = hd1080

# Save the project and all the other data it is connected to it

Create Assets, Shots and other Tasks:

from stalker import Task, Asset, Shot, Type

# define Character asset type
char_type = Type(name='Character', code='CHAR', target_entity_type='Asset')

character1 = Asset(
    name='Character 1',

# Save the Asset

model = Task(

rigging = Task(
    depends=[model],  # For project management, define that Rig can not start
                      # before Model ends.

# Save the new tasks[model, rigging])

# A shot and some tasks for it
shot = Shot(

# Save the Shot

animation = Task(

lighting = Task(
    depends=[animation], # Lighting can not start before Animation ends,
    schedule_unit='d',  # The task expected to take 1 day to complete
)[animation, lighting])

Let’s create versions for the Animation task.

from stalker import Version

new_version = Version(task=animation)
new_version.update_paths()  # to render the naming convention template
new_version.extension = '.ma'  # let's say that we have created under Maya

Let’s check how the version path is rendered:

assert new_version.absolute_full_path == \
assert new_version.version_number == 1

Create a new version and check that the version number increased automatically:

new_version2 = Version(task=animation)
new_version2.update_paths()  # to render the naming convention template
new_version2.extension = '.ma'  # let's say that we have created under Maya

assert new_version2.version_number == 2

See more detailed example in API Tutorial.

Table of Contents


stalker.db Database module of Stalker.
stalker.db.setup Utility function that helps to connect the system to the given database.
stalker.exceptions Errors for the system.
stalker.exceptions.CircularDependencyError Raised when there is circular dependencies within Tasks
stalker.exceptions.LoginError Raised when the login information is not correct or not correlate with the data in the database.
stalker.exceptions.OverBookedError Raised when a resource is booked more than once for the same time period
stalker.exceptions.StatusError Raised when the status of an entity is not suitable for the desired action
stalker.models.asset.Asset The Asset class is the whole idea behind Stalker.
stalker.models.auth.AuthenticationLog Keeps track of login/logout dates and the action (login or logout).
stalker.models.auth.Group Creates groups for users to be used in authorization system.
stalker.models.auth.LocalSession A simple temporary session object which simple stores session data.
stalker.models.auth.Role Defines a User role.
stalker.models.auth.Permission A class to hold permissions.
stalker.models.auth.User The user class is designed to hold data about a User in the system.
stalker.models.budget.Budget Manages project budgets
stalker.models.budget.BudgetEntry Manages entries in a Budget.
stalker.models.budget.Good Manages commercial items that is served by the Studio.
stalker.models.budget.Invoice Holds information about invoices
stalker.models.budget.Payment Holds information about the payments.
stalker.models.budget.PriceList Contains CommercialItems to create a list of items that is sold by the Studio.
stalker.models.department.Department The departments that forms the studio itself.
stalker.models.department.DepartmentUser The association object used in Department-to-User relation
stalker.models.client.Client The Client (e.g.
stalker.models.client.ClientUser The association object used in Client-to-User relation
stalker.models.entity.Entity Another base data class that adds tags and notes to the attributes list.
stalker.models.entity.EntityGroup Groups a wide variety of objects together to let one easily reach them.
stalker.models.entity.SimpleEntity The base class of all the others
stalker.models.format.ImageFormat Common image formats for the Projects. Holds data about external links.
stalker.models.message.Message The base of the messaging system in Stalker
stalker.models.mixins.ACLMixin A Mixin for adding ACLs to mixed in class.
stalker.models.mixins.CodeMixin Adds code info to the mixed in class.
stalker.models.mixins.DateRangeMixin Adds date range info to the mixed in class.
stalker.models.mixins.ProjectMixin Allows connecting a Project to the mixed in object.
stalker.models.mixins.ReferenceMixin Adds reference capabilities to the mixed in class.
stalker.models.mixins.ScheduleMixin Adds schedule info to the mixed in class.
stalker.models.mixins.StatusMixin Makes the mixed in object statusable.
stalker.models.mixins.TargetEntityTypeMixin Adds target_entity_type attribute to mixed in class.
stalker.models.mixins.WorkingHoursMixin Sets working hours for the mixed in class.
stalker.models.note.Note Notes for any of the SOM objects.
stalker.models.project.Project All the information about a Project in Stalker is hold in this class.
stalker.models.project.ProjectClient The association object used in Client-to-Project relation
stalker.models.project.ProjectRepository The association object for Project to Repository instances
stalker.models.project.ProjectUser The association object used in User-to-Project relation
stalker.models.repository.Repository Manages fileserver/repository related data. Manages the Task Review Workflow. Manages data related to Dailies. The association object used in Daily-to-Link relation
stalker.models.scene.Scene Stores data about Scenes.
stalker.models.schedulers.SchedulerBase This is the base class for schedulers.
stalker.models.schedulers.TaskJugglerScheduler This is the main scheduler for Stalker right now.
stalker.models.sequence.Sequence Stores data about Sequences.
stalker.models.shot.Shot Manages Shot related data.
stalker.models.status.Status Defines object statutes.
stalker.models.status.StatusList Type specific list of Status instances.
stalker.models.structure.Structure Defines folder structures for Projects. Manage all the studio information at once. A helper class to manage Studio working hours.
stalker.models.tag.Tag Use it to create tags for any object available in SOM.
stalker.models.task.Task Manages Task related data.
stalker.models.task.TaskDependency The association object used in Task-to-Task dependency relation
stalker.models.task.TimeLog Holds information about the uninterrupted time spent on a specific Task by a specific User.
stalker.models.template.FilenameTemplate Holds templates for filename and path conventions.
stalker.models.ticket.Ticket Tickets are the way of reporting errors or asking for changes.
stalker.models.ticket.TicketLog Holds Ticket.Ticket.status change operations.
stalker.models.type.EntityType A simple class just to hold the registered class names in Stalker
stalker.models.type.Type Everything can have a type.
stalker.models.version.Version Holds information about the created versions (files) for a class:.Task A simple Wiki page implementation.

Indices and tables