Scripts

The script environment

What the runtime does between the click and the first line of your code, and every rule that follows from it.

A pyNavis script is not run the way a file is run from a terminal. There is no argument vector, no interpreter start-up, and no process boundary. Your file is compiled and executed inside a scope that the runtime prepares for it, on the same thread that is drawing the Navisworks window, in an interpreter that has already been alive for as long as the session.

Almost every surprise in authoring comes from one of those facts. This page covers all of them.

What happens when you click#

The path from a ribbon click to your first statement is short and entirely deterministic.

The five injected globals#

The runtime sets exactly five names in your scope before executing your file. This is the complete list for a *.pushbutton and every kind built on one. Everything else you see is either something you defined or something Python itself provides.

You can see all five at once. This is one of the few scripts where print is the right call, because opening the output window is the entire point of it:

"""Prints the environment the runtime handed this script."""
print('__file__        %s' % __file__)
print('__commandpath__ %s' % __commandpath__)
print('__title__       %s' % __title__)
print('__selfinit__    %s' % __selfinit__)
print('__pynavis__     %s' % __pynavis__)
print('version         %s' % __pynavis__.Version)
print('dark theme      %s' % __pynavis__.IsDarkTheme)
print('__name__        %r' % __name__)

__pynavis__ is the same object pynavis.script.get_host() returns, so you rarely touch the global directly. Its members:

.SetCommandContext(...) and .SetCurrentOutput(...) also exist and belong to the runtime. Calling either from a script points the whole host at the wrong tool; there is no reason to.

Prefer the Python wrappers. pynavis.script exposes the read-only members as functions, and pynavis.output wraps the HTML and progress members in something you would want to call twice.

from pynavis import script

script.get_host()          # the __pynavis__ object, even outside a script scope
script.get_script_path()   # str, the executing command's script.py
script.get_command_path()  # str, the bundle folder
script.get_title()         # str, the resolved title
script.get_host_version()  # str, runtime assembly version
script.is_dark_theme()     # bool
script.reload_pynavis()    # rescan and rebuild the ribbon, no restart

__name__ is '__main__'#

A hosted scope has no __name__ of its own, so if __name__ == '__main__': would be false and the body of such a script would silently never run. Both engines therefore set the name explicitly before your first statement, and both have a test that proves it. The familiar guard works:

"""Counts the selection."""
from pynavis import selection, toast


def main():
    items = selection.get_items()
    toast.success('%d selected' % len(items))


if __name__ == '__main__':      # true on IronPython and on CPython
    main()

That is the only name Python itself would have given you. Everything else in the scope is either one of the five injected globals or something you defined.

Module-level code is still the shorter and more common style, and every shipped bundle uses it. Defining helper functions is fine and encouraged; just make sure something calls them.

"""Counts the selection."""
from pynavis import selection, toast

items = selection.get_items()
toast.success('%d selected' % len(items))

"""Counts the selection."""
from pynavis import selection, toast

def main():
    items = selection.get_items()
    toast.success('%d selected' % len(items))

# nothing calls main(), so the script does nothing

Choosing an engine#

The engine is a per-bundle choice, resolved once when the bundle is parsed:

1. The engine: key in the bundle's bundle.yaml.
2. The engine: key in the extension's extension.yaml, which sets a default for every bundle in it.
3. ironpython.

title: Analyse quantities
engine: cpython

The CPython DLL is looked for in three places, in order: the "cpython" key in %APPDATA%\pyNavis\config.json, then the PYNAVIS_CPYTHON environment variable, then the registry under SOFTWARE\Python\PythonCore, current user before local machine. Either of the first two may name a python3XX.dll directly or the folder that holds one. The registry scan accepts versions 3.7 to 3.13 and prefers the newest. If nothing is found, the first click on a CPython bundle raises a message naming both the config key and python.org.

Because the interpreter is initialised once and never shut down, changing the key takes effect on the next Navisworks start, not on Reload. The Settings window says so when you edit it.

Only pushbuttons honour engine:. Setting it on a pulldown does nothing; the key belongs on each pushbutton inside it, or on the extension.

Module search paths#

Two sets of paths combine on every run. The per-bundle set is the bundle's own folder plus its extension's lib\ folder when that folder exists. The engine-global set is the bundled stdlib, which only IronPython ever sees, the directory holding the pynavis package, and every *.lib folder found under the extension roots. The diagram below leaves the *.lib folders out for room; they sit immediately after pynavislib on both engines, in the order they were discovered, so they are always ahead of a bundle's own folder and of an extension's lib\. Anatomy of an extension covers what they are.

CPython restores sys.path, sys.stdout and sys.stderr in a finally, so a run cannot leak its paths or its output redirection into the next one. If pynavislib cannot be found on disk at all, the runtime logs an error at boot and import pynavis fails for every bundle.

The module cache and the edit loop#

Before every run that has bundle search paths, the engine walks sys.modules and deletes every module whose __file__ sits under your bundle folder or your extension's lib\ folder. Paths are compared lowercased with a trailing backslash appended, so C:\a does not match C:\ab.

script.py itself is never in that cache: it is read and executed from source on every run, never imported. Together those two facts give you an edit loop with no ceremony in the common case.

Splitting a large tool across files therefore costs you nothing in turnaround:

MyTools.extension\
  lib\
    acme_geometry.py        # edits picked up on the next run
  MyTools.tab\
    Model.panel\
      Analyse.pushbutton\
        script.py           # re-read from source on every run
        rules.py            # edits picked up on the next run

Importing#

import pynavis gives you exactly one public name, pynavis.__version__. There are no re-exports, no __all__ and no automatic submodule import, so the package itself is nearly free to import and you always name what you want.

Every shipped bundle uses the same style: from pynavis import with the modules in alphabetical order, at module level, immediately after the docstring.

"""Groups the active clash test."""
from pynavis import clash, forms, toast

"""Groups the active clash test."""
import pynavis
pynavis.clash.walk_tests()  # AttributeError

What an import costs depends entirely on which module it is. Three tiers:

That last tier is why a tool whose dialog you want to open outside Navisworks uses a guarded import. This is the pattern the shipped clash grouper uses so its options dialog still works when there is no model:

from pynavis import forms, settings, toast

try:
    from pynavis import clash
except ImportError:
    clash = None

if clash is None:
    toast.error('No Navisworks session', 'Open a model and run this again.')
else:
    ...

One script at a time#

A long script pumps the Windows message loop so the window can repaint, and pumping dispatches queued input, including another click on a ribbon button. Rather than run two scripts over one document, the runtime holds a process-wide gate. A second click while one script is running is refused with a toast reading “<title> is still running” and “Wait for it to finish, then try again.”

This is not something you can opt out of, and it is worth designing around: a job that takes thirty seconds should say so. Use the output window's progress bar and check for cancellation in your loop.

For a modal progress dialog with its own cancel button, use pynavis.forms.progress, a context manager over the runtime's progress window: update(fraction, label) reports and returns False once the user has cancelled, and check() raises forms.Cancelled instead. The shipped Sets From Excel importer does exactly this:

from pynavis import forms

with forms.progress('Importing sets', 'Starting') as p:
    for i, item in enumerate(items):
        p.check()                        # raises forms.Cancelled on cancel
        p.update(float(i) / len(items), 'Set %d' % (i + 1))

Output and errors#

The output window is created lazily, on the first write, and is titled pyNavis - <button title>. A script that writes nothing shows no window at all, which is exactly the behaviour you want from a tool that just did its job.

from pynavis import toast

toast.success('Exported 412 items', path)

print('Exported 412 items')
# opens a window to say one line

An uncaught exception is formatted by the engine that raised it, IronPython through ExceptionOperations.FormatException and CPython through PythonException.Format(), then written to the output window in the error colour and copied to %APPDATA%\pyNavis\logs\pyNavis.log. You do not need a top-level try to see a traceback; add one only when you can turn the failure into a better message.

Whatever happens, ProgressScope.CloseAll() runs in the runtime's finally. A crashed script cannot leave a modal progress dialog on screen and lock the user out of Navisworks. Your own try/finally is still the first line of defence; this is the backstop.

Threading#

If a job is slow, the answer is progress reporting and a cancel check, not concurrency. Work that genuinely belongs off the main thread belongs in a separate process instead: write the input to disk, run something external, read the result back.