Bundles

The bundle.yaml reference

Every key the runtime reads, what it falls back to, and the exact rules of the very small parser that reads the file.

A bundle is a folder. bundle.yaml is the optional file inside it that names the button, describes it, picks its engine and binds its keys. Nothing in it is required: a bundle with no bundle.yaml at all still produces a working button, because every value has a fallback.

Count.pushbutton\
  script.py       # required: no script.py, no button
  bundle.yaml     # optional: metadata only
  icon.png        # optional

The file is read once, at discovery time. Change it and click Reload on the pyNavis panel; there is no need to restart Navisworks.

It is not YAML#

This is the single most useful thing to know about the file. pyNavis does not use a YAML library. It uses a forty-line reader that walks the file one line at a time and produces a flat dictionary of strings. The name and the .yaml extension are a convention inherited from pyRevit, not a promise of YAML semantics.

The whole algorithm, in order:

1. Split the text on \n. Trim a trailing \r, then trim whitespace from both ends of the line.
2. Skip the line if it is now empty, or if it starts with #.
3. Find the first :. If there is none, or it is the first character, skip the line.
4. The key is everything before that colon, trimmed and lowercased.
5. The value is everything after that colon, trimmed.
6. If the value is two characters or longer and starts and ends with the same quote character, " or ', remove exactly one character from each end.
7. Store it. A key seen twice keeps the last value.

That is all of it. There is no escape processing, no type coercion, no schema, and no error reporting. A file that cannot be read, or that does not exist, yields an empty dictionary and the bundle falls back on its defaults.

Inputs that surprise people#

Most of these are consequences of the rules above rather than special cases, but they are worth reading once so you recognise them when a value comes out wrong.

What the file cannot express#

Because the parser only ever produces flat string pairs, none of the following work. They do not raise an error either; they parse into keys you will never read again.

• Nesting. An indented block is just more top-level keys, and the parent line becomes a key with an empty value.
• Lists. A line of - item has no colon and is dropped.
• Multi-line values. There is no | or > handling. A tooltip is one line.
• Anchors, aliases, tags, documents. None of the YAML machinery exists.
• Types. Every value is a string. There are no booleans, numbers or nulls.

# Export the current selection
title: Export points
tooltip: Writes every selected item to a CSV file.
engine: ironpython
shortcut: Ctrl+Shift+E
keytip: EP

title: Export points  # to CSV
tooltip: >
  Writes every selected
  item to a CSV file.
options:
  - csv
  - json

In the second file the title keeps the comment, tooltip is literally >, the two prose lines vanish for having no colon, options is an empty string, and the two list lines vanish as well. Nothing warns you.

The keys a pushbutton reads#

Exactly eight, and nothing else in the file is looked at. The same eight apply to the three kinds that are parsed as pushbuttons: *.nobutton, *.toggle and *.smartbutton, wherever they sit, including inside a *.slideout. context: is the one key a nobutton reads to no effect, because greying needs a rendered control.

context: enabling and disabling a button#

Without a context: key a button is always enabled, exactly as before. With one, the runtime reads a small boolean expression and re-evaluates it against the live document on every hub event, flipping the button's enabled state to match. It never blocks a click by itself; it only decides whether the button can be clicked at all.

Seven condition names, answered from one snapshot of the active document:

Combine names with & (and), | (or) and ! (not). ! binds tightest, then &, then |, and both binary operators are left-associative. There is no way to write parentheses: ( is not part of the vocabulary and produces Unexpected character '(' in context rule. Split the rule across two buttons, or simplify the condition, when a different grouping is genuinely needed. The word forms and, or and not, and the doubled && and ||, are not accepted either.

context: doc
context: selection & clash-tests
context: viewpoints | selection-sets
context: selection & !multi-model

A condition name that does not match one of the seven above is legal syntax and evaluates to false forever, but discovery says so rather than staying silent:

Bundle 'D:\NavisTools\...\Export.pushbutton': unknown context condition 'selction'.

A rule that fails to parse outright, for instance a stray leading operator, is also logged, and the button falls back to always enabled rather than never enabled:

Bundle 'D:\NavisTools\...\Export.pushbutton': bad context rule - Unexpected '&' in context
rule '& selection'. Button stays always enabled.

min_host_version and max_host_version: gating on the Navisworks release#

Two keys, each a bare year. Either can be used alone, and neither is required.

title: New clash API demo
min_host_version: 2024

A ceiling on its own, for a tool that drives something the host later removed:

title: Legacy clash report
max_host_version: 2025

Or both, for a tool that only works inside one window of releases:

title: Bridge export
min_host_version: 2024
max_host_version: 2026

An out-of-range button still renders exactly like any other: it is not greyed out and it is not hidden. The check happens on click, before the script runs, and shows a warning toast in place of running it:

Requires Navisworks 2024 or newer (this is 2023).
Requires Navisworks 2026 or older (this is 2027).

A value that is not a whole number is logged and ignored, leaving that side of the range open rather than failing the bundle. The test is a plain integer parse, so 2024 works and 2024.1, v2024 and 20.0 do not:

Bundle 'D:\NavisTools\...\Export.pushbutton': min_host_version 'v2024' is not a year - ignored.

The host's own year is derived from the Navisworks API assembly version. On the rare install where that cannot be read, the gate is disabled entirely and every button runs, because refusing to run on a host you cannot identify is the worse failure. The gate also covers only the two runs that go through the script executor, a click or a chord: a *.smartbutton's build-time run and a *.dockpane's script.py are not version checked.

The keys a pulldown reads#

A *.pulldown folder may carry its own bundle.yaml describing the menu button itself. It reads three keys: title, tooltip and keytip. shortcut and engine are ignored there, because a pulldown does not run anything; only the pushbuttons inside it do.

*.splitbutton and *.splitpushbutton are parsed exactly the same way and read the identical three keys. Buttons, stacks and pulldowns covers what makes their header click different from a plain pulldown's.

The keys a urlbutton reads#

A *.urlbutton has no script.py, so engine and shortcut are not read: there is no code for either of them to apply to. It reads four keys, one of them required.

Urlbutton 'D:\NavisTools\...\Documentation.urlbutton' has no url: in bundle.yaml - skipped.

The keys a linkbutton reads#

A *.linkbutton also has no script.py. Its required key is plugin, the target add-in's id in Id.DeveloperId form, the same identity Navisworks itself uses to find a registered plugin.

Linkbutton 'D:\NavisTools\...\Legacy_Tool.linkbutton' has no plugin: in bundle.yaml - skipped.

The keys a dockpane reads#

A *.dockpane renders as a ribbon toggle rather than a button that runs and returns, but its bundle.yaml is parsed by the same reader and reads five keys. There is no width or height key: a pane's size belongs to the slot it lands in, identical for all five compile-time slots, not to the bundle that borrows one.

pane.xaml in the bundle folder is required; a folder without one is skipped (Dockpane '<dir>' has no pane.xaml - skipped.). script.py is optional, unlike a pushbutton where its absence is what makes the folder invisible. Buttons, stacks and pulldowns covers what the toggle does and what __pane__ exposes.

The keys an extension reads#

An *.extension folder may carry extension.yaml, a different filename read by the same parser. It has two keys.

Folders that read nothing#

Four folder kinds have no configuration file at all, and putting one there is a common way to lose an afternoon.

How title and tooltip actually resolve#

Metadata resolves most specific first: bundle.yaml, then the script, then the folder name. The two chains are not the same length, which matters.

Breaking a long caption onto two lines#

A large button is as wide as its caption, so four long names can eat half the ribbon. A literal \n in the title breaks it:

title: Export\nViewpoints

The break applies to the large vertical caption only: on the ribbon the button reads Export over Viewpoints, while everywhere the name appears as text, it stays one line with the break as a single space. That includes the log, toasts, the output window title, the generated keytip letters, the Shortcuts editor and __title__ inside the script. Spaces around the break are optional, so Export \n Viewpoints gives the same two lines.

A stacked or menu row draws its caption beside the icon rather than under it, so those never wrap: the same bundle used in a .stack shows the one-line form. Use one break, not several; the ribbon gives a large button room for two lines.

How the script is scanned#

When bundle.yaml does not supply a title or tooltip, the runtime reads script.py as text and looks for two things with a regular expression and a small hand-written scan. It is not a Python parser, and the difference shows.

__title__#

The pattern is an assignment to __title__ that starts at column zero, using a single or double quoted string. That is the entire grammar.

__title__ = 'Export points'
__title__="Export points"
__title__  =  'Export points'     # the trailing comment is fine here

    __title__ = 'Export points'   # indented: the pattern is anchored to column zero
__title__ = """Export points"""   # triple quotes are not matched
__title__ = 'Export ' + 'points'  # only the first literal is taken: "Export "
__title__ = f'Export {kind}'      # the f is not a quote, so no match at all
__title__ = TITLES['export']      # no quote after the equals sign

Nothing reports these. The button falls back to the folder name and looks like it ignored your script.

The docstring#

The scan skips blank lines and lines starting with #, then requires the next content to open with """ or '''. It takes everything up to the next occurrence of the same delimiter and trims it. If the first real statement is anything else, there is no docstring, and the search stops there: a triple-quoted string further down the file is never found.

# Licence header comments are skipped.

"""Exports the current selection to CSV."""
from pynavis import selection

from pynavis import selection

"""Exports the current selection to CSV."""

Keys that do nothing#

Every key in the file is parsed, but only the ones listed above are ever read. Anything else sits in a dictionary that nobody queries. This matters most if you are arriving from pyRevit, because several familiar keys have no equivalent here.

None of these produce a warning, in the log or anywhere else. If a key is not in the tables on this page, assume it does nothing.

A complete example#

# Points exporter. Comments have to live on their own line.
title: Export points
tooltip: Writes every selected item to a CSV file, one row per item.
engine: ironpython
shortcut: Ctrl+Shift+E
keytip: EP