AYON Core Addon

https://github.com/ynput/ayon-core
Admin
AYON Core Addon provides the foundational building blocks, command-line handling, publishing...
Tokens:363,905
Snippets:2,525
Trust Score:9.7
License:Apache-2.0
Update:2 days ago
Show doc for...
Tokens:
Raw
### Quick Start: Create AYON-styled application

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui.md

Sets up a QApplication with the AYON style, creates a container with a button and label, and displays the window. Requires qtpy and the ayon_core.ui modules.

```python
from qtpy.QtWidgets import QApplication

from ayon_core.ui.style_types import get_ayon_style
from ayon_core.ui.components.buttons import AYButton
from ayon_core.ui.components.container import AYContainer
from ayon_core.ui.components.label import AYLabel

app = QApplication([])
app.setStyle(get_ayon_style())

container = AYContainer(
      layout=AYContainer.Layout.VBox,
      variant=AYContainer.Variants.Low,
      layout_margin=10,
      layout_spacing=8,
)

container.add_widget(
      AYButton("Run", variant=AYButton.Variants.Filled, icon="play_arrow")
)
container.add_widget(
      AYLabel("Ready", icon="check_circle", icon_color="#60c689")
)

style_widget_and_siblings(container)
container.show()
app.exec()
```

--------------------------------

### Install test dependencies

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Installs the test dependencies defined in pyproject.toml under [project.optional-dependencies].

```bash
pip install -e ".[test]"
```

--------------------------------

### Component test example: MyWidgetTest

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Example test file for a component. Subclass WidgetTest, implement build() to return the widget under test, and optionally implement steps() to mutate widget state. The size and tolerance attributes are optional with defaults (800, 600) and 0.0 respectively.

```python
# tests/client/ayon_core/ui/components/test_my_widget.py
from qtpy.QtWidgets import QWidget
from widget_test import WidgetTest
from ayon_core.ui.components.my_widget import AYMyWidget


class MyWidgetTest(WidgetTest):
    size = (600, 400)       # optional: widget dimensions in pixels
    tolerance = 0.0         # optional: per-pixel diff tolerance (0.0–1.0)

    def build(self) -> QWidget:
        self._widget = AYMyWidget()
        return self._widget

    def enabled(self) -> None:
        """Step: enable the widget."""
        self._widget.setEnabled(True)

    def disabled(self) -> None:
        """Step: disable the widget."""
        self._widget.setEnabled(False)

    def steps(self):
        return [self.enabled, self.disabled]
```

--------------------------------

### Extend a publish plugin with AYONPyblishPluginMixin

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/publish/README.md

Use this mixin to add custom logic to publish plugins. The example shows a context plugin inheriting from both pyblish.api.ContextPlugin and AYONPyblishPluginMixin. The mixin enables defining instance attributes via get_attribute_defs and converting legacy values with convert_attribute_values.

```python
import pyblish.api
from ayon_core.pipeline import AYONPyblishPluginMixin


# Example context plugin
class MyExtendedPlugin(
    pyblish.api.ContextPlugin, AYONPyblishPluginMixin
):
    pass

```

--------------------------------

### Use traits in a Maya loader

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Example of a Maya loader that uses traits to check compatibility with a representation. It uses Representation.from_dict() and contains_traits() to verify required traits.

```python
"""Alembic loader using traits."""
from __future__ import annotations
import json
from typing import Any, TypeVar, Type
from ayon_maya.api.plugin import MayaLoader
from ayon_core.pipeline.traits import (
    FileLocation,
    Spatial,

    Representation,
    TraitBase,
)

T = TypeVar("T", bound=TraitBase)


class AlembicTraitLoader(MayaLoader):
    """Alembic loader using traits."""
    label = "Alembic Trait Loader"
    ...

    required_traits: list[T] = [
        FileLocation,
        Spatial,
    ]

    @staticmethod
    def is_compatible_loader(context: dict[str, Any]) -> bool:
        traits_raw = context["representation"].get("traits")
        if not traits_raw:
            return False

        # construct Representation object from the context
        representation = Representation.from_dict(
            name=context["representation"]["name"],
            representation_id=context["representation"]["id"],
            trait_data=json.loads(traits_raw),
        )

        # check if the representation is compatible with this loader
        if representation.contains_traits(AlembicTraitLoader.required_traits):
            # you can also check for specific values in traits here
            return True
        return False

    ...
```

--------------------------------

### View all reference images with --show-refs

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Run visual_utils.py with --show-refs to view all reference images without running tests. Useful for verifying reference images are correct.

```bash
python tests/client/ayon_core/ui/visual_utils.py --show-refs
```

--------------------------------

### Project structure tree

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui.md

Shows the directory layout of the client/ayon_core/ui/ module, including components, resources, and vendor subdirectories.

```text
client/ayon_core/ui/
├── __init__.py
├── style.py
├── variants.py
├── image_cache.py
├── data_models.py
├── components/
│   ├── buttons.py
│   ├── check_box.py
│   ├── combo_box.py
│   ├── ...
├── resources/
│   └── ayon_style.json
└── vendor/
    └── qtmaterialsymbols/
```

--------------------------------

### Open visual comparison viewer

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Opens the visual comparison viewer to inspect pixel differences and optionally accept them as new baselines.

```bash
pytest tests/client/ayon_core/ui/ --show-images
```

--------------------------------

### Run full UI test suite

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Runs all UI tests in the specified directory.

```bash
pytest tests/client/ayon_core/ui/
```

--------------------------------

### Developer Commands via ./tools/manage.sh

Source: https://github.com/ynput/ayon-core/blob/develop/AGENTS.md

Common tasks for creating the environment, running tests, linting, and executing commands. Requires Python 3.9.x only; the script rejects 3.10+.

```bash
./tools/manage.sh create-env   # Create/update venv via uv, install pre-commit hooks
./tools/manage.sh run-tests    # Run pytest (excludes 'server' marker)
./tools/manage.sh ruff-check   # Run ruff linter
./tools/manage.sh ruff-fix     # Run ruff linter with --fix
./tools/manage.sh codespell    # Run codespell
./tools/manage.sh run <cmd>    # Run any command via uv run
```

--------------------------------

### Creating and manipulating a Representation with traits

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Shows how to create a Representation, add traits, and access them using both methods and dictionary-style indexing.

```python
# import Image trait
from ayon_core.pipeline.traits import Image, Tagged, Representation


# create new representation with name "foo" and add Image trait to it
rep = Representation(name="foo", traits=[Image()])

# you can add another trait like so
rep.add_trait(Tagged(tags=["tag"]))

# or you can
rep[Tagged.id] = Tagged(tags=["tag"])

# and getting them in analogous
image = rep.get_trait(Image)

# or
image = rep[Image.id]
```

--------------------------------

### Import migration from ayon-ui-qt addon

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui.md

Shows the import statements before and after migrating from the standalone ayon-ui-qt addon to the integrated core module. The imports remain the same, but the module is now part of ayon_core.

```python
# Before (standalone addon)
from ayon_core.ui.components.buttons import AYButton
from ayon_core.ui.style_types import get_ayon_style

# After (integrated into core)
from ayon_core.ui.components.buttons import AYButton
from ayon_core.ui.style_types import get_ayon_style
```

--------------------------------

### Snapshot filename pattern

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Pattern for reference image filenames: {ClassName}_{index:02d}_{step_name}.png

```text
{ClassName}_{index:02d}_{step_name}.png
```

--------------------------------

### Test structure directory tree

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Shows the directory layout of the UI test suite, including conftest.py, test_visual.py, visual_utils.py, widget_test.py, components, utils, and reference PNG snapshots.

```text
tests/client/ayon_core/ui/
├── conftest.py          # Sets QT_QPA_PLATFORM=offscreen before any Qt import
├── test_visual.py       # Auto-discovering runner — generates parametrized tests
├── visual_utils.py      # capture_widget() helper
├── widget_test.py       # WidgetTest base class
├── components/          # One test_*.py file per component
│   ├── test_buttons.py
│   └── test_check_box.py
├── utils/               # Shared test utilities
│   └── composite_widget.py
└── test_visual/         # Reference PNG snapshots (committed to version control)
    ├── ButtonTest_00_initial.png
    ├── ButtonTest_01_check_all.png
    └── ...
```

--------------------------------

### Create and validate a representation with traits

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Creates a Representation with FileLocation, Image, PixelBased, Persistent, and Static traits, then validates it and catches TraitValidationError.

```python
from pathlib import Path
from ayon_core.pipeline.traits import (
    FileLocation,
    Image,
    PixelBased,
    Persistent,
    Representation,
    Static,

    TraitValidationError,
)
    
rep = Representation(name="reference image", traits=[
    FileLocation(
        file_path=Path("/foo/bar/baz.exr"),
        file_size=1234,
        file_hash="sha256:...",
    ),
    Image(),
    PixelBased(
        display_window_width=1920,
        display_window_height=1080,
        pixel_aspect_ratio=1.0,
    ),
    Persistent(),
    Static()
])

# validate the representation

try:
    rep.validate()
except TraitValidationError as e:
    print(f"Representation {rep.name} is invalid: {e}")

```

--------------------------------

### AYONPyblishPluginMixin

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/publish/README.md

Mixin class to extend publish plugins with additional logic, such as defining attributes for instances during creation.

```APIDOC
## AYONPyblishPluginMixin

### Description
Mixin class to extend publish plugins with additional logic. Inherit from this class along with a pyblish plugin base class.

### Usage Example
```python
import pyblish.api
from ayon_core.pipeline import AYONPyblishPluginMixin


# Example context plugin
class MyExtendedPlugin(
    pyblish.api.ContextPlugin, AYONPyblishPluginMixin
):
    pass
```

### Methods

#### get_attribute_defs
Returns attribute definitions for families defined in the plugin's `families` attribute if it's an instance plugin, or for the whole context if it's a context plugin.

#### convert_attribute_values
Converts existing attribute values (or removes legacy values). Implement this method to remove legacy data or convert it to a new data structure. Values of publish attributes from created instances are never removed automatically.

### Notes
Possible attribute definitions can be found in `ayon_core/lib/attribute_definitions.py`.

```

--------------------------------

### Generate reference images with pytest --force-regen

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Command to generate reference images for a new component test. Run from the project root. The -k flag selects the test class, and --force-regen forces regeneration of reference images.

```bash
pytest tests/client/ayon_core/ui/test_visual.py -k MyWidgetTest --force-regen
```

--------------------------------

### Create a representation from a dictionary

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Builds a representation data dictionary and uses Representation.from_dict() to create a Representation instance.

```python
rep_dict = {
        "ayon.content.FileLocation.v1": {
            "file_path": Path("/path/to/file"),
            "file_size": 1024,
            "file_hash": None,
        },
        "ayon.two_dimensional.Image": {},
        "ayon.two_dimensional.PixelBased": {
            "display_window_width": 1920,
            "display_window_height": 1080,
            "pixel_aspect_ratio": 1.0,
        },
        "ayon.two_dimensional.Planar": {
            "planar_configuration": "RGB",
        }
}

rep = Representation.from_dict(name="image", rep_dict)

```

--------------------------------

### Generate or regenerate reference images

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Regenerates reference images when adding new tests or intentionally changing component appearance.

```bash
pytest tests/client/ayon_core/ui/ --force-regen
```

--------------------------------

### Update baseline with pytest --force-regen

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui_testing.md

Run pytest with --force-regen to save the captured image as the new baseline. Use -k <TestClassName> to target specific tests.

```bash
pytest --force-regen -k <TestClassName>
```

--------------------------------

### Minimal representation dict

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Shows the minimal form of a representation as a dict-like structure with name, ext, files, and stagingDir.

```python
{
    "name": "foo",
    "ext": "exr",
    "files": ["foo_001.exr", "foo_002.exr"],
    "stagingDir": "/bar/dir"
}
```

--------------------------------

### fetch_page_batch callback

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui.md

Optional callback for coalescing child-node fetches in tree mode. It receives a list of BatchFetchRequest objects and returns a dictionary mapping parent IDs to lists of item dictionaries.

```APIDOC
## fetch_page_batch

### Description
Optional callback for coalescing child-node fetches in tree mode. It receives a list of BatchFetchRequest objects and returns a dictionary mapping parent IDs to lists of item dictionaries.

### Parameters
- **requests** (list[BatchFetchRequest]) - Required - A list of BatchFetchRequest objects representing the child fetches to perform.

### Returns
- **dict[str | None, list[dict]]** - A dictionary mapping parent IDs (or None for root) to lists of item dictionaries.
```

--------------------------------

### Define custom traits in an addon

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Shows how to implement the ITraits interface in an addon to define custom traits. The get_addon_traits() method returns a list of trait classes.

```python
from ayon_core.pipeline.traits import TraitBase
from ayon_core.addon import (
    AYONAddon,
    ITraits,
)

class MyTraitFoo(TraitBase):
    id = "myaddon.mytrait.foo.v1"
    name = "My Trait Foo"
    description = "This is my trait foo"
    persistent = True


class MyTraitBar(TraitBase):
    id = "myaddon.mytrait.bar.v1"
    name = "My Trait Bar"
    description = "This is my trait bar"
    persistent = True

    
class MyAddon(AYONAddon, ITraits):
    def __init__(self):
        super().__init__()

    def get_addon_traits(self):
        return [
            MyTraitFoo,
            MyTraitBar,
        ]
```

--------------------------------

### PublishError

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/publish/README.md

Exception to raise on known errors during publishing. The message is shown to the artist.

```APIDOC
## PublishError

### Description
Raise this exception on known errors during publishing. The message is shown to the artist.

### Constructor Arguments
- **message** (string) - Required - Error message.
- **title** (string) - Optional - Short description of error (2-5 words). Used for grouping exceptions per plugin. Defaults to "This is not your fault" if not provided.
- **description** (string) - Optional - Override of 'message' for UI. Can contain markdown and HTML. Defaults to 'message'.
- **detail** (string) - Optional - Additional detail message hidden under a collapsed component.

```

--------------------------------

### Create representation with traits in extractor

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Use this snippet in an extractor's extract method to create a representation with traits. It collects traits like Geometry, MimeType, Persistent, Spatial, and optionally FrameRanged, then constructs a Representation with a FileLocation trait and adds it to the instance.

```python
class SomeExtractor(Extractor):
    """Some extractor."""
    ...

    def extract(self, instance: Instance) -> None:
        """Extract the data."""
        # get the path to the file
        path = self.get_path(instance)

        # create the representation
        traits: list[TraitBase] = [
            Geometry(),
            MimeType(mime_type="application/abc"),
            Persistent(),
            Spatial(
                up_axis=cmds.upAxis(q=True, axis=True),
                meters_per_unit=maya_units_to_meters_per_unit(
                    instance.context.data["linearUnits"]),
                handedness="right",
            ),
        ]

        if instance.data.get("frameStart"):
            traits.append(
                FrameRanged(
                    frame_start=instance.data["frameStart"],
                    frame_end=instance.data["frameEnd"],
                    frames_per_second=instance.context.data["fps"],
                )
            )

        representation = Representation(
            name="alembic",
            traits=[
                FileLocation(
                    file_path=Path(path),
                    file_size=os.path.getsize(path),
                    file_hash=get_file_hash(Path(path))
                ),
                *traits],
        )

        add_trait_representations(
            instance,
            [representation],
        )
        ...
```

--------------------------------

### fetch_page callback

Source: https://github.com/ynput/ayon-core/blob/develop/docs/ui.md

The required callback signature for PaginatedTableModel to fetch a page of data. It receives the page number, page size, sort key, descending flag, and optional parent ID, and returns a list of dictionaries.

```APIDOC
## fetch_page

### Description
Callback signature required by PaginatedTableModel to fetch a page of data.

### Parameters
- **page** (int) - Required - The page number to fetch.
- **page_size** (int) - Required - The number of items per page.
- **sort_key** (str | None) - Required - The key to sort by, or None.
- **descending** (bool) - Required - Whether to sort in descending order.
- **parent_id** (str | None) - Required - The parent node ID for tree mode, or None for root-level fetch.

### Returns
- **list[dict]** - A list of dictionaries representing the fetched items.
```

--------------------------------

### Translated representation structure in database

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Shows the structure of a representation as stored in the database, including files with metadata and attrib/data sections.

```python
{
    "name": "foo",
    "version_id": "...",
    "files": [
        {
            "id": ...,
            "hash": ...,
            "name": "foo_001.exr",
            "path": "{root[work]}/bar/dir/foo_001.exr",
            "size": 1234,
            "hash_type": "...",
        },
        ...
    ],
    "attrib": {
        "path": "root/bar/dir/foo_001.exr",
        "template": "{root[work]}/{project[name]}...",
    },
    "data": {
        "context": {
            "ext": "exr",
            "root": {...},
            ...
    },
    "active": True
    ...

}
```

--------------------------------

### PublishValidationError

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/publish/README.md

Exception for validation plugins to indicate an artist-fixable error and provide actions to fix it.

```APIDOC
## PublishValidationError

### Description
Raise this exception in validation plugins to show the artist what's wrong and give actions to fix it. The error can be fixed by the artist (with or without action on the plugin). Any other errors will stop publishing immediately. If raised after the validation order, it has the same effect as any other exception.

### Constructor Arguments
- **message** (string) - Required - Error message.
- **title** (string) - Optional - Short description of error. Defaults to the plugin label if not provided.
- **description** (string) - Optional - Override of 'message' for UI. Can contain markdown and HTML. Defaults to 'message'.
- **detail** (string) - Optional - Additional detail message hidden under a collapsed component.

```

--------------------------------

### Access trait values from a representation

Source: https://github.com/ynput/ayon-core/blob/develop/client/ayon_core/pipeline/traits/README.md

Shows two ways to access trait values: using get_trait() and using the trait ID as an index. Catches MissingTraitError if the trait is not present.

```python

try:
    width = rep.get_trait(PixelBased).display_window_width
    # or like this:
    height = rep[PixelBased.id].display_window_height
except MissingTraitError:
    print(f"resolution isn't set on {rep.name}")

```
Tokens:
Raw