<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.
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 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.
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.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.
# 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
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.
# context directives are listed under `context` key, the order does not matter context: - Walls - Text Notes
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.