Quickstart 2

This guide will take you through a hypothetical scenario in which the role of publishing is explained.

Introduction

To get started, type or paste this into an empty file.

# getting_started.py
import pyblish.api as pyblish

john = pyblish.Instance(name="John")
john.set_data("content", "Hello, I'm John)

We've now created John. John is an instance. An instance is the in-memory representation of a file - almost like the opposite of one.

Let's make sure John introduces himself.

# getting_started.py
import pyblish.api as pyblish

john = pyblish.Instance(name="John")
john.set_data("content", "Hello, I'm John)

class ValidateContent(pyblish.Validator):
    def process_instance(self, instance):
        if not "John" in instance.data("content"):
            raise pyblish.ValidatorError(
                "John didn't introduce himself")
        else:
            print instance.data("content")

ValidateContent().process_instance(john)

Now run this file from your terminal.

$ python getting_started.py
Hello, I'm John

Unless an error was thrown, John did introduce himself.

Make it more dynamic

Let's see how we could make this a little more dynamic.

# getting_started.py
import pyblish.api as pyblish

john = pyblish.Instance(name="John")
john.set_data("content", "Hello, I'm %s" % john.data("name"))

class ValidateContent(pyblish.Validator):
    def process_instance(self, instance):
        name = instance.data("name")
        if not name in instance.data("content"):
            raise pyblish.ValidatorError(
                "%s didn't introduce himself" % name)
        else:
            print instance.data("content")

ValidateContent().process_instance(john)

$ python getting_started.py
Hello, I'm John

Rather than type John a bunch of times, we now get the name by asking John himself.

Get John from host

Pyblish is ultimately about getting data, good data, out of a particular application. This particular application is called "host". In this case, our host will be the Python interpreter and we'll use it to get John from a directory on disk.

$ mkdir MyProject
$ cd MyProject
$ touch John

In this empty directory there is only John. An empty file. This file will represent John, as opposed to creating him ourselves in Python.

To select John, we need a "Context". A context contains one or more instances.

# getting_started.py
import os
import pyblish.api as pyblish

context = pyblish.Context()

class SelectFiles(pyblish.Selector):
    def process_context(self, context):
        current_dir = os.getcwd()
        for item in os.listdir(current_dir):
            instance = pyblish.Instance(name=item, parent=context)
            instance.set_data("content", "Hello, I'm %s" % item)

SelectFiles().process_context(context)
print context

Note the use of process_context()

$ python ../getting_started.py
# [Instance("John")]

Let's add a friend.

$ touch Steve
$ python ../getting_started.py
# [Instance("John"), Instance("Steve")]

Let's make sure they both introduce themselves.

# getting_started.py
import os
import pyblish.api as pyblish

context = pyblish.Context()

class SelectFiles(pyblish.Selector):
    def process_context(self, context):
        current_dir = os.getcwd()
        for item in os.listdir(current_dir):
            instance = pyblish.Instance(name=item, parent=context)
            instance.set_data("content", "Hello, I'm %s" % instance.data("name"))

class ValidateContent(pyblish.Validator):
    def process_instance(self, instance):
        name = instance.data("name")
        if not name in instance.data("content"):
            raise pyblish.ValidatorError(
                "%s didn't introduce himself" % name)
        else:
            print instance.data("content")

SelectFiles().process_context(context)

for instance in context:
    ValidateContent().process_instance(instance)

Now let's run it.

$ python ../getting_started.py
Hello, I'm John
Hello, I'm Steve

Speak for Yourself

At this point, we are guaranteed to never fail (is that such a bad thing?). However, to make things a little more interesting, let's allow John and Steve to speak for themselves. Then we'll double-check to make sure they're talking in a fashion that suits us.

Edit the file John and paste this.

Hello, I'm John

Now edit the file Steve to say this.

hello, I'm Steve

From now on, I'll only be showing modified code.

Let's use this for content, instead of speaking for them.

class SelectFiles(pyblish.Selector):
    def process_context(self, context):
        current_dir = os.getcwd()
        for item in os.listdir(current_dir):
            instance = pyblish.Instance(name=item, parent=context)

            with open(item) as f:
                instance.set_data('content', f.read())

In ValidateContent, besides making sure they both introduce themselves, also ensure they use the proper grammar.

# ...
class ValidateContent(pyblish.Validator):
    def process_instance(self, instance):
        name = instance.data("name")
        words = instance.data('content').split()
        
        if not name in instance.data("content"):
            raise pyblish.ValidatorError(
                "%s didn't introduce himself" % name)

        elif not words[0] == words[0].title():
            raise pyblish.ValidationError(
                "%s misspelt his introduction" % name)

        else:
            print instance.data("content")

Let's run this.

$ python ../getting_started.py
# ...
# pyblish.error.ValidationError: Steve misspelt his introduction

Quality Control

Let's take a breather and think about what we've accomplished so far. At this point, you've stumbled upon one of two important aspects of Pyblish; quality control.

Running your script at this point reveals important information about Steve; he didn't live up to your requirements.

In visual effects production, its equivalent may be that normals were inverted on geometry or that a critical part of a character setup is missing.

By ensuring that data lives up to requirements, you not only heighten the quality of your content, you also facilitate automation. When you can guarantee the format of every file and content within each file, you can do some amazing things; such as automatically publish all shots using an updated portion of content, without human intervention.