<aside> <img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/ef7e1c71-55d2-42b6-b63b-f0e8787d53cc/ic_01_idea.png" alt="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/ef7e1c71-55d2-42b6-b63b-f0e8787d53cc/ic_01_idea.png" width="40px" /> pyRevit History: Initially, pyRevit bundles were all written in IronPython, and the metadata about the bundle were included inside the python code as global variables. For example, the __title__ global variable would define a title for the tool in Revit UI. With the release of pyRevit 4.7, many more bundle types and languages were supported and a unified way was needed to provide this metadata. This page describes the unified Bundle Metadata File. The in-script global variables is still supported for IronPython for backward compatibility and convenience.

See Anatomy of IronPython Scripts for more information on in-script global variables.

</aside>

The most important data about a bundle is the Bundle Type, and the Bundle Content (script, or other types of content). The naming conventions is the mechanism to provide this information to pyRevit runtime. For example for an IronPython command bundle, the folder extension (*.pushbutton) defines the bundle type, and the *script.py file defines the bundle content to be executed.

Bundle File

Bundle Metadata File (Bundle File for short) is a YAML *.yaml file that provides the extended, and optional metadata about the bundle. This metadata is used to improve the user experience, and provide more information about the bundle requirements and dependencies to the pyRevit runtime.

Improving Bundle User Experience

Bundle file can improve the user interface of a bundle, by providing a title, tooltip message, help url, and information about the authors. It is important to mention that the default UI title for a bundle is extracted from the bundle folder (MyTool in MyTool.pushbutton), but the bundle file can override that to define a better formatted name. One of the most popular cases for setting the title in a bundle file is when a line break (\\n) is needed to better format the button name e.g. My\\nTool.

# bundle title
title: "Make\\nPattern"

# title can also be in various locales
# pyRevit pulls the correct name based on Revit langauge
title:
  en_us: Test Bundle (Custom Title)
  chinese_s: 测试包

# bundle tooltip
tooltip: Create new patterns in Revit
# tooltip can also be in various locales
# pyRevit pulls the correct tooltip based on Revit langauge
tooltip:
  en_us: Create new patterns in Revit
  chinese_s: 创建新模式

# bundle help url
help_url: "<https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf>"
# help url can also be in various locales
# pyRevit pulls the correct help url based on Revit langauge
help_url:
  en_us: "<https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf>"
  chinese_s: "<https://www.youtube.com/watch?v=H7b8hjHbauE&t=8s&list=PLc_1PNcpnV57FWI6G8Cd09umHpSOzvamf>"

# bundle author
author: Ehsan Iran-Nejad

# bundle author can also be a list of authors
authors:
  - John Doe
  - Ehsan Iran-Nejad

Use the locale codes here as shown above for various langauges

Supported Locale Codes

Context Directives

The bundle file can also set the execution context of the bundle. This helps activating the bundle, where the appropriate conditions are available. For example a bundle can request to be activated only when selection is available.

<aside> <img src="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/db316e4a-d249-451a-ab8a-2fc1343d1866/ic_01_idea.png" alt="https://s3-us-west-2.amazonaws.com/secure.notion-static.com/db316e4a-d249-451a-ab8a-2fc1343d1866/ic_01_idea.png" width="40px" /> See Bundle Context for more information on available context directives.

</aside>

Example

# context directives are listed under `context` key, the order does not matter
context:
  - Walls
  - Text Notes

Bundle Environment Configs

Supported Revit Versions

Bundle file can define the range of Revit versions that support the bundle. pyRevit will not load the bundle if it is not supported under the running Revit. In the example below, the bundle will be loaded with Revit 2015 up to 2018 and is expected to work with the APIs for these versions.

# minimium supported Revit version
min_revit_version: 2015

# maximum supported Revit version
max_revit_version: 2018

Bundle file can also set the state of the bundle. pyRevit user can decide whether to load the Beta bundles when starting Revit or not.