# Introduction ![Pyblish by Example](https://cloud.githubusercontent.com/assets/2152766/12489260/51843d38-c067-11e5-93c8-7b96c30ed37a.png) Welcome to the Pyblish by Example tutorial. ## You will learn * The basics of publishing in the production of film and games * The fundamentals of [Pyblish](http://pyblish.com) and it's [API](http://api.pyblish.com) * How to validate content * How to guarantee valid content on export * How to properly position and name content according to convention * How to visualise the results of one or more publishes * Developer and Artist communication through the UI ## Introduction Pyblish is an open source, cross-platform framework for test-driven content creation. *Pyblish by Example* is a hands-on introduction to Pyblish using short example programs written like a book - to be read from top to bottom. * [What is Publishing?](https://github.com/pyblish/pyblish/wiki/What-is-publishing) ## Installation If you haven't already, go ahead and install Pyblish. ```bash $ pip install pyblish-base ``` Any problems, have a look at the [extended installation guide](http://forums.pyblish.com/t/pyblish-1-4-released/239/2). ## How to use this guide Start by confirming to yourself that you are indeed using version 1.4+ of Pyblish. ```python >>> import pyblish >>> pyblish.__version__ '1.4.3' ``` If not, see the top-left corner of this page for a dropdown of your version. As you read through this guide it is recommended that you use the scripting API, accessible via `pyblish.util`. ```python from pyblish import util util.publish() ``` ## Reporting issues Should you happen to find errors or would like to contribute material to this guide, you can: 1. Click on the `+` button to the right of each paragraph to add a comment 2. Register on [GitBook](https://www.gitbook.com/book/pyblish/pyblish-by-example) to edit this book directly. 3. Fork the [GitHub repository](https://github.com/pyblish/pyblish-by-example) and submit a pull-request with your changes. ## Content Have a look to the left for a table of contents, and below for related topics in the forums. > **Note:** The below content was written at various versions of Pyblish and may not include current best practices, but all remain forwards compatible with version 1.4. > > For example, `.set_data("key", "value")` has been superseded by `.data["key"] = "value"` but will still work with newer plug-ins. **Intermediate** * [Responsibility of Extractors](http://forums.pyblish.com/t/responsibilities-of-extractors/266/9) * [Multiple families workflow](http://forums.pyblish.com/t/multiple-families-workflow/205) * [Per task plug-ins](http://forums.pyblish.com/t/task-specific-plugins/127) * [Publishing with comments](http://forums.pyblish.com/t/publishing-with-comments/120) * [Instances and Plain-Old-Data](http://forums.pyblish.com/t/instances-and-plain-old-data/136) * [Cooperative Collection](http://forums.pyblish.com/t/cooperative-collection/137) * [Search and Customisation](http://forums.pyblish.com/t/pyblish-search-and-customisation) * [Good to know about Pyblish](http://forums.pyblish.com/t/good-to-know-about-pyblish) * [`hosts` Attribute In-Depth](http://forums.pyblish.com/t/the-use-of-hosts-attribute/78/3) * [Registration versus families](http://forums.pyblish.com/t/filtering-collected-instances-based-on-category-family/245/5) * [Backwards compatibility](http://forums.pyblish.com/t/backwards-compatibility-and-breaking-changes/246) **Advanced** * [Magenta development thread](http://forums.pyblish.com/t/pyblish-magenta/79) * [Developer Guide](http://forums.pyblish.com/t/developer-guide) * [Pyblish in 100 lines](https://pyblish.gitbooks.io/developer-guide/content/pyblish_in_100_lines.html) **Changelog** * `2015-08-06 16:27` - Added [Quickstart](http://forums.pyblish.com/t/learning-pyblish-by-example/108/3) * `2015-08-07 10:12` - Added [Architecture](http://forums.pyblish.com/t/learning-pyblish-by-example/108/6) * `2015-08-07 10:14` - Updated [Quickstart](http://forums.pyblish.com/t/learning-pyblish-by-example/108/3) * `2015-08-07 19:17` - Added [Good to know about Pyblish](http://forums.pyblish.com/t/good-to-know-about-pyblish) * `2015-08-07 20:41` - Updated [Architecture](http://forums.pyblish.com/t/learning-pyblish-by-example/108/6) * `2015-08-07 20:48` - Updated This * `2015-08-09 10:51` - Updated [Validating II](http://forums.pyblish.com/t/learning-pyblish-by-example/108/16) with flow chart * `2015-08-09 17:24` - Updated This, with installation instructions * `2015-08-10 09:00` - Updated This * `2015-08-11 07:28` - Updated [Quickstart](http://forums.pyblish.com/t/learning-pyblish-by-example/108/3) * `2015-08-11 07:30` - Updated [Files](http://forums.pyblish.com/t/learning-pyblish-by-example/108/4) with comma-separated paths * `2015-08-11 07:40` - Fixed typo in [Report IV](http://forums.pyblish.com/t/learning-pyblish-by-example/108/26) * `2015-08-13 21:08` - Updated [Report I-IV](http://forums.pyblish.com/t/learning-pyblish-by-example/108/26) * `2015-08-14 09:26` - Updated [Report I-II](http://forums.pyblish.com/t/learning-pyblish-by-example/108/26) * `2015-08-18 07:02` - Added [host attribute in-depth](http://forums.pyblish.com/t/the-use-of-hosts-attribute/78/3) * `2015-08-18 07:22` - Added "You will learn" to This * `2015-10-19 14:38` - Updated use of "Asset" to "Instance" * `2015-11-19 09:07` - Updated to pure-dict * `2015-12-20 21:56` - Updated image of [Context + Instance](http://forums.pyblish.com/t/learning-pyblish-by-example/108/6). * `2016-01-21 17:46` - Transitioned to GitBooks, removed section about custom test and services. * `2016-06-07 09:48` - Defer use of GUI from guide. * `2016-07-01 14:54` - Link to installation guide on Forum * `2016-08-03 10:40` - Add intermediate and advanced links * `2017-08-12 10:30` - Removed deprecated dependency injection link --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://learn.pyblish.com/readme.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.