abstractfactory/pyblish — pull request #100 by mottosso (2014-09-20 13:38:24+00:00)
Title: API

Hey folks,

Today I'd like to introduce to you our first API. The API simplifies building plugins with Pyblish and also represents the point at which we attempt to maintain forwards- and backwards-compatibility.

Let me illustrate.

```python
import pyblish.backend.plugin

class ValidateNamespaces(pyblish.backend.plugin):
pass
```

Previously, this is what the boiler-plate for a plugin might look like. Which not only looks awkward, but more importantly means that if we at some point in time decide to refactor either `backend` or `plugin`, all of our users plugins will break.

```python
import pyblish

class ValidateNamespaces(pyblish.Validator):
pass
```

This is how it looks with an API.

The object itself still resides within `pyblish.backend.plugin`, but it's name is accessed directly via the `pyblish` library.

### Examples

```python
import pyblish

plugins = pyblish.discover()
context = pyblish.Context()

@pyblish.log
class MyExtractor(pyblish.Extractor):
...

pyblish.register_plugin_path(r'c:\my_plugins')
```

### Technically

The API is just that; references to inner objects and functions of the main `pyblish` package. If you look within `api.py`, you'll see what is really going on, and it isn't magic.

At this point, it's plain. This is due to us not having any changes made to the inner classes since the API was made (today!). But as we modify (and most prominently, re-factor) our code, `api.py` will compensate these changes so as to not break plugins.

In the rigging world, the API represents the controller on a character rig, whereas using `pyblish.backend.plugin` directly is the equivalent to animating the joints themselves.

### Documentation

With an API, we also open up the doors to dedicated API documentation.

The difference between such a documentation and a Source Code documentation is that the API is for our end-users, and Source Code documentation is for contributors. Contributors need to understand the internals, whereas end-users must only understand the API and its behaviour.

In the rigging world, the API documentation represents explaining *what* a control and its attributes does and source code documentation is explaining *how* the control is doing what it is doing.