Refactor tools, refine ls() schema

pyblish · Sep 22, 2016 · 5168d64 · 5168d64
1 parent 6589f28
commit 5168d64
Show file tree

Hide file tree

Showing 13 changed files with 209 additions and 122 deletions.
diff --git a/README.md b/README.md
@@ -1,18 +1,57 @@
 ### Pyblish Starter
 
-A basic publishing pipeline, with batteries included.
+A basic asset creation pipeline, with batteries included.
 
 > WARNING: Not ready for use.
 
+**Table of contents**
+
+- [Install](#install)
+- [Usage](#usage)
+- [Description](#description)
+- [Terminology](#terminology)
+- [Information Hierarchy](#information-hierarchy)
+- [Contract](#contract)
+    - [`starter.model`](#startermodel)
+    - [`starter.rig`](#starterrig)
+    - [`starter.animation`](#starteranimation)
+
+<br>
+<br>
+
+### Install
+
+Starter takes the form of a Python package with embedded plug-ins.
+
+```bash
+$ pip install pyblish-starter
+```
+
+<br>
+<br>
+
+### Usage
+
+Starter is initialised by calling `install()` with an interface for your host.
+
+```python
+>>> from pyblish_starter import install, maya
+>>> install(maya)
+```
+
+From here, you model, rig and animate as per the contract below.
+
 <br>
 <br>
 
 ### Description
 
-Build your own publishing pipeline, starting with the basics.
+Build your own asset creation pipeline, starting with the basics.
 
 **Overview**
 
+Asset creation covers all aspects related to building the assets used in the production of film. A film is typically partitioned into sequences and shots, where each shot consists of one or more assets.
+
 This project includes interface and implementation for 3 common types of assets a typical production pipeline.
 
 - Modeling
@@ -30,33 +69,49 @@ It includes a series of graphical user interfaces to aid the user in conforming
 <br>
 <br>
 
-### Install
+### Terminology
 
-Starter takes the form of a Python package with embedded plug-ins.
+Starter reserves the following words for private and public use. Public members are exposed to the user, private ones are internal to the implementation.
 
-```bash
-$ pip install pyblish-starter
-```
+|          | Term                | Public | Description         | Example
+|:---------|:--------------------|:-------|:--------------------|:------------------------
+| ![][pro] | `project`           | `X`    | Root of information | Gravity, Dr. Strange
+| ![][ast] | `asset`             | `X`    | Unit of data        | Hulk, Bicycle, Flower pot
+| ![][ver] | `version`           | `X`    | An iteration        | v1, v034
+| ![][rep] | `representation`    |        | A data format       | Maya file, pointcache, thumbnail
+| ![][for] | `format`            |        | A file extension    | `.ma`, `.abc`, `.ico`, `.png`
+
+[ver]: https://cloud.githubusercontent.com/assets/2152766/18576835/f6b80574-7bdc-11e6-8237-1227f779815a.png
+[ast]: https://cloud.githubusercontent.com/assets/2152766/18576836/f6ca19e4-7bdc-11e6-9ef8-3614474c58bb.png
+[rep]: https://cloud.githubusercontent.com/assets/2152766/18759916/b2e3161c-80f6-11e6-9e0a-c959d63047a8.png
+[for]: https://cloud.githubusercontent.com/assets/2152766/18759918/b479168e-80f6-11e6-8d1c-aee4e654d335.png
+[pro]: https://cloud.githubusercontent.com/assets/2152766/18760901/d6bf24b4-80fa-11e6-8880-7a0e927c8c27.png
 
 <br>
 <br>
 
-### Usage
+### Information Hierarchy
 
-Starter is initialised by calling `install()`.
+The mental and physical model for files and folders look like this.
 
-```python
->>> import pyblish_starter
->>> pyblish_starter.install()
-```
+```bash
+ ________________________________ ________________________________ 
+|          |          |          |          |          |          |
+| version1 | version2 | version3 | version1 | version2 | version3 |
+|__________|__________|__________|__________|__________|__________|
+|                                |                                |
+|             asset1             |             asset2             |
+|________________________________|________________________________|
 
-From here, you model, rig and animate as per the contract below.
+```
 
 <br>
 <br>
 
 ### Contract
 
+![](http://placehold.it/880x300)
+
 Starter defines these families.
 
 | Family              | Definition                                                  | Link
@@ -69,6 +124,8 @@ Starter defines these families.
 
 ### `starter.model`
 
+![](http://placehold.it/880x100)
+
 <img align="right" src="https://cloud.githubusercontent.com/assets/2152766/18526694/7453567a-7ab9-11e6-817c-84a874092399.png"></img>
 
 A generic representation of geometry.
@@ -101,25 +158,13 @@ A generic representation of geometry.
 - `geometry_SEL (geometry)`: Meshes suitable for rigging
 - `aux_SEL (any, optional)`: Auxilliary meshes for e.g. fast preview, collision geometry
 
-**Metadata**
-
-```json
-{
-    "name": "Elisabeth",
-    "representations": [
-        {
-            "hosts": ["maya", "mayapy"],
-            "files": ["Elisabeth_model.ma"]
-        }
-    ]
-}
-```
-
 <br>
 <br>
 
 ### `starter.rig`
 
+![](http://placehold.it/880x100)
+
 <img align="right" src="https://cloud.githubusercontent.com/assets/2152766/18526730/9c7f040a-7ab9-11e6-9007-4795ddbadde8.png"></img>
 
 The `starter.rig` contains the necessary implementation and interface for animators to produce 
@@ -150,6 +195,8 @@ The `starter.rig` contains the necessary implementation and interface for animat
 
 ### `starter.animation`
 
+![](http://placehold.it/880x100)
+
 <img align="right" src="https://cloud.githubusercontent.com/assets/2152766/18526738/a0fba5ba-7ab9-11e6-934f-48ca2a2ce3d2.png"></img>
 
 Point positions and normals represented as one Alembic file.

diff --git a/pyblish_starter/__init__.py b/pyblish_starter/__init__.py
@@ -8,8 +8,11 @@
     ls,
     install,
     uninstall,
+
     register_host,
     register_plugins,
+
+    registered_host,
 )
 
 from .lib import (
@@ -21,8 +24,12 @@
     "ls",
     "install",
     "uninstall",
+
     "register_host",
     "register_plugins",
+
+    "registered_host",
+
     "format_private_dir",
     "format_version",
 ]
diff --git a/pyblish_starter/__main__.py b/pyblish_starter/__main__.py
@@ -1,6 +1,3 @@
-import os
-import json
-import types
 import argparse
 
 from . import pipeline
@@ -17,43 +14,14 @@
 
 args = parser.parse_args()
 
-
-# Produce standalone host
-def root():
-    return os.getcwd()
-
-
-def loader(asset, version=-1, representation=None):
-    print(json.dumps({
-        "asset": asset,
-        "version": version,
-        "representation": representation
-    }, indent=4))
-
-    return "my_asset"
-
-
-def creator(name, family):
-    print(json.dumps({
-        "name": name,
-        "family": family,
-    }, indent=4))
-
-
-host = types.ModuleType("standalone")
-host.__dict__.update({
-    "root": root,
-    "loader": loader,
-    "creator": creator
-})
-
+host = pipeline.debug_host()
 pipeline.register_host(host)
 
 
 if args.creator:
-    from .tools import instance_creator
-    instance_creator.show(debug=args.debug)
+    from .tools import creator
+    creator.show(debug=args.debug)
 
 if args.loader:
-    from .tools import asset_loader
-    asset_loader.show(debug=args.debug)
+    from .tools import loader
+    loader.show(debug=args.debug)
diff --git a/pyblish_starter/lib.py b/pyblish_starter/lib.py
@@ -3,6 +3,13 @@
 import datetime
 
 
+def listdir(dirname):
+    try:
+        return os.listdir(dirname)
+    except OSError:
+        return list()
+
+
 def time():
     return datetime.datetime.now().strftime("%Y-%m-%dT%H-%M-%SZ")
 

diff --git a/pyblish_starter/maya/__init__.py b/pyblish_starter/maya/__init__.py
@@ -9,8 +9,8 @@
     uninstall,
 
     root,
-    loader,
-    creator,
+    load,
+    create,
 
     hierarchy_from_string,
     export_alembic,
@@ -23,8 +23,8 @@
     "uninstall",
 
     "root",
-    "loader",
-    "creator",
+    "load",
+    "create",
 
     "export_alembic",
     "hierarchy_from_string",

diff --git a/pyblish_starter/maya/lib.py b/pyblish_starter/maya/lib.py
@@ -30,16 +30,16 @@ def uninstall():
 
 
 def install_menu():
-    from pyblish_starter.tools import instance_creator, asset_loader
+    from pyblish_starter.tools import creator, loader
 
     uninstall_menu()
 
     cmds.menu(self.menu,
               label="Pyblish Starter",
               tearOff=True,
               parent="MayaWindow")
-    cmds.menuItem("Create Instance", command=instance_creator.show)
-    cmds.menuItem("Load Asset", command=asset_loader.show)
+    cmds.menuItem("Show Creator", command=creator.show)
+    cmds.menuItem("Show Loader", command=loader.show)
 
 
 def uninstall_menu():
@@ -112,7 +112,7 @@ def outmesh(shape, name=None):
     return outmesh
 
 
-def loader(asset, version=-1):
+def load(asset, version=-1):
     """Load asset
 
     Arguments:
@@ -141,12 +141,10 @@ def loader(asset, version=-1):
     formats = pipeline.registered_formats()
 
     # Pick any representation
-    representation = next(
-        (rep for rep in version["representations"]
-         if rep["format"] in formats), None
-    )
-
-    if representation is None:
+    try:
+        representation = next(rep for rep in version["representations"]
+                              if rep["format"] in formats)
+    except StopIteration:
         raise ValueError(
             "No supported representations for %s\n"
             "Supported representations: %s" % (
@@ -166,7 +164,7 @@ def loader(asset, version=-1):
     return cmds.referenceQuery(nodes, referenceNode=True)
 
 
-def creator(name, family):
+def create(name, family):
     """Create new instance
 
     Arguments: