Note

This documentation is a work-in-progress. Thanks for your patience.

Index¶

Getting Started

I suggest reading this section completely as it provides 99% of what you will need to know for developing scripts in pyRevit environment. Other sections dive deeper into pyRevit inner workings.

Anatomy of a pyRevit Script¶

pyRevit provides a few basic services to python scripts that use its engine. These fuctionalities are accessible through a few high level modules. This is a quick look at these services and their associated python modules.

Basic script parameters¶

Command Tooltips

Tooltips are shown similarly to the other buttons in Revit interface. You can define the tooltip for a script using the doscstring at the top of the script or by explicitly defining __doc__ parameter.
"""You can place the docstring (tooltip) at the top of the script file.
This serves both as python docstring and also button tooltip in pyRevit.
You should use triple quotes for standard python docstrings."""
__doc__ = 'This is the text for the button tooltip associated with this script.'

Custom Command Title
When using the bundle name is not desired or you want to add a newline character to the command name for better display inside Revit UI Panel, you can define the __title__ variable in your script and set it to the desired button title.
__title__ = 'Sample\\nCommand'
Command Author
You can define the script author as shown below. This will show up on the button tooltip.
__author__ = 'Ehsan Iran-Nejad'

Command Availability¶

Revit commands use standard IExternalCommandAvailability class to let Revit know if they are available in different contexts. For example, if a command needs to work on a set of elements, it can tell Revit to deactivate the button unless the user has selected one or more elements.

In pyRevit, command availability is set through the __context__ variable. Currently, pyRevit support three types of command availability types.

# Tool activates when at least one element is selected
__context__ = 'Selection'

# Tools are active even when there are no documents available/open in Revit
__context__ = 'zerodoc'

# Tool activates when all selected elements are of the given category or categories
__context__ = '<Element Category>'
__context__ = ['<Element Category>', '<Element Category>']

Element Categories
<Element Category> can be any of the standard Revit element categories. See Appendix B: System Category Names for a full list of system categories. You can use the List tool under pyRevit > Spy and list the standard categories.

Here are a few examples:
# Tool activates when all selected elements are of the given category __context__ = 'Doors' __context__ = 'Walls' __context__ = 'Floors' __context__ = ['Space Tags', 'Spaces']

pyrevit.script Module¶

All pyRevit scripts should use the pyrevit.script module to access pyRevit functionality unless listed otherwise. pyRevit internals are subject to changes and accessing them directly is not suggested.

Here is a list of supported modules for pyRevit scripts. Examples of using the functionality in these modules are provided on this page.

pyrevit.script

This module provides access to output window (pyrevit.output), logging (pyrevit.coreutils.logger), temporary files (pyrevit.coreutils.appdata), and other misc features. See the module page for usage examples and full documentation of all available functions.

Logging¶

You can get the default logger for the script using pyrevit.script.get_logger().

from pyrevt import script

logger = script.get_logger()

logger.info('Test Log Level :ok_hand_sign:')

logger.warning('Test Log Level')

logger.critical('Test Log Level')

Critical and warning messages are printed in color for clarity. Normally debug messages are not printed. you can hold CTRL and click on a command button to put that command in DEBUG mode and see all its debug messages

logger.debug('Yesss! Here is the debug message')

Controlling Output Window¶

Each script can control its own output window:

from pyrevit import script

output = script.get_output()

output.set_height(600)
output.get_title()
output.set_title('More control please!')

See Effective Output/Input for more info.

Script Config¶

Each script can save and load configuration pyRevit’s user configuration file:

See pyrevit.output for more examples.

See pyrevit.script.get_config() and pyrevit.script.save_config() for the individual functions used here.

from pyrevit import script

config = script.get_config()

# set a new config parameter: firstparam
config.firstparam = True

# saving configurations
script.save_config()

# read the config parameter value
if config.firstparam:
    do_task_A()

Logging Results¶

pyRevit has a usage logging system that can record all tool usages to either a json file or to a web server. Scripts can return custom data to this logging system.

In example below, the script reports the amount of time it saved to the logging system:

from pyrevit import script

results = script.get_results()
results.timesaved = 10

Using Temporary Files¶

Scripts can create 3 different types of data files:

Universal files
These files are not marked by host Revit version and could be shared between all Revit versions and instances. These data files are saved in pyRevit’s appdata directory and are NOT cleaned up at Revit restarts.

See pyrevit.script.get_universal_data_file()

Note

Script should take care of cleaning up these data files.
# provide a unique file id and file extension # Method will return full path of the data file from pyrevit import script script.get_universal_data_file(file_id, file_ext)
Data files
These files are marked by host Revit version and could be shared between instances of host Revit version Data files are saved in pyRevit’s appdata directory and are NOT cleaned up when Revit restarts.

See pyrevit.script.get_data_file()

Note

Script should take care of cleaning up these data files.
# provide a unique file id and file extension # Method will return full path of the data file from pyrevit import script script.get_data_file(file_id, file_ext)
Instance Data files
These files are marked by host Revit version and process Id and are only available to current Revit instance. This avoids any conflicts between similar scripts running under two or more Revit instances. Data files are saved in pyRevit’s appdata directory (with extension .tmp) and ARE cleaned up when Revit restarts.

See pyrevit.script.get_instance_data_file()
# provide a unique file id and file extension # Method will return full path of the data file from pyrevit import script script.get_instance_data_file(file_id)
Document Data files
(Shared only between instances of host Revit version): These files are marked by host Revit version and name of Active Project and could be shared between instances of host Revit version. Data files are saved in pyRevit’s appdata directory and are NOT cleaned up when Revit restarts.

See pyrevit.script.get_document_data_file()

Note

Script should take care of cleaning up these data files.
# provide a unique file id and file extension # Method will return full path of the data file from pyrevit import script script.get_document_data_file(file_id, file_ext) # You can also pass a document object to get a data file for that # document (use document name in file naming) script.get_document_data_file(file_id, file_ext, doc)

Appendix A: Builtin Parameters Provided by pyRevit Engine¶

Variables listed below are provided for every script in pyRevit.

Note

It’s strongly advised not to read or write values from these variables unless necessary. The pyrevit module provides wrappers around these variables that are safe to use.

# Revit UIApplication is accessible through:
__revit__

# Command data provided to this command by Revit is accessible through:
__commandData__

# selection of elements provided to this command by Revit
__elements__

# pyRevit engine manager that is managing this engine
__ipyenginemanager__

# This variable is True if command is being run in a cached engine
__cachedengine__

# pyRevit external command object wrapping the command being run
__externalcommand__

# information about the pyrevit command being run
__commandpath__             # main script path
__alternatecommandpath__    # alternate script path
__commandname__             # command name
__commandbundle__           # command bundle name
__commandextension__        # command extension name
__commanduniqueid__         # command unique id

# This variable is True if user CTRL-Clicks the button
__forceddebugmode__

# This variable is True if user SHIFT-Clicks the button
__shiftclick__

# results dictionary
__result__

Appendix B: System Category Names¶

Adaptive Points
Air Terminal Tags
Air Terminals
Analysis Display Style
Analysis Results
Analytical Beam Tags
Analytical Beams
Analytical Brace Tags
Analytical Braces
Analytical Column Tags
Analytical Columns
Analytical Floor Tags
Analytical Floors
Analytical Foundation Slabs
Analytical Isolated Foundation Tags
Analytical Isolated Foundations
Analytical Link Tags
Analytical Links
Analytical Node Tags
Analytical Nodes
Analytical Slab Foundation Tags
Analytical Spaces
Analytical Surfaces
Analytical Wall Foundation Tags
Analytical Wall Foundations
Analytical Wall Tags
Analytical Walls
Annotation Crop Boundary
Area Load Tags
Area Tags
Areas
Assemblies
Assembly Tags
Boundary Conditions
Brace in Plan View Symbols
Cable Tray Fitting Tags
Cable Tray Fittings
Cable Tray Runs
Cable Tray Tags
Cable Trays
Callout Boundary
Callout Heads
Callouts
Cameras
Casework
Casework Tags
Ceiling Tags
Ceilings
Color Fill Legends
Columns
Communication Device Tags
Communication Devices
Conduit Fitting Tags
Conduit Fittings
Conduit Runs
Conduit Tags
Conduits
Connection Symbols
Contour Labels
Crop Boundaries
Curtain Grids
Curtain Panel Tags
Curtain Panels
Curtain System Tags
Curtain Systems
Curtain Wall Mullions
Data Device Tags
Data Devices
Detail Item Tags
Detail Items
Dimensions
Displacement Path
Door Tags
Doors
Duct Accessories
Duct Accessory Tags
Duct Color Fill
Duct Color Fill Legends
Duct Fitting Tags
Duct Fittings
Duct Insulation Tags
Duct Insulations
Duct Lining Tags
Duct Linings
Duct Placeholders
Duct Systems
Duct Tags
Ducts
Electrical Circuits
Electrical Equipment
Electrical Equipment Tags
Electrical Fixture Tags
Electrical Fixtures
Electrical Spare/Space Circuits
Elevation Marks
Elevations
Entourage
Filled region
Fire Alarm Device Tags
Fire Alarm Devices
Flex Duct Tags
Flex Ducts
Flex Pipe Tags
Flex Pipes
Floor Tags
Floors
Foundation Span Direction Symbol
Furniture
Furniture System Tags
Furniture Systems
Furniture Tags
Generic Annotations
Generic Model Tags
Generic Models
Grid Heads
Grids
Guide Grid
HVAC Zones
Imports in Families
Internal Area Load Tags
Internal Line Load Tags
Internal Point Load Tags
Keynote Tags
Level Heads
Levels
Lighting Device Tags
Lighting Devices
Lighting Fixture Tags
Lighting Fixtures
Line Load Tags
Lines
Masking Region
Mass
Mass Floor Tags
Mass Tags
Matchline
Material Tags
Materials
Mechanical Equipment
Mechanical Equipment Tags
MEP Fabrication Containment
MEP Fabrication Containment Tags
MEP Fabrication Ductwork
MEP Fabrication Ductwork Tags
MEP Fabrication Hanger Tags
MEP Fabrication Hangers
MEP Fabrication Pipework
MEP Fabrication Pipework Tags
Multi-Category Tags
Multi-Rebar Annotations
Nurse Call Device Tags
Nurse Call Devices
Panel Schedule Graphics
Parking
Parking Tags
Part Tags
Parts
Pipe Accessories
Pipe Accessory Tags
Pipe Color Fill
Pipe Color Fill Legends
Pipe Fitting Tags
Pipe Fittings
Pipe Insulation Tags
Pipe Insulations
Pipe Placeholders
Pipe Segments
Pipe Tags
Pipes
Piping Systems
Plan Region
Planting
Planting Tags
Plumbing Fixture Tags
Plumbing Fixtures
Point Clouds
Point Load Tags
Project Information
Property Line Segment Tags
Property Tags
Railing Tags
Railings
Ramps
Raster Images
Rebar Cover References
Rebar Set Toggle
Rebar Shape
Reference Lines
Reference Planes
Reference Points
Render Regions
Revision Cloud Tags
Revision Clouds
Roads
Roof Tags
Roofs
Room Tags
Rooms
Routing Preferences
Schedule Graphics
Scope Boxes
Section Boxes
Section Line
Section Marks
Sections
Security Device Tags
Security Devices
Shaft Openings
Sheets
Site
Site Tags
Space Tags
Spaces
Span Direction Symbol
Specialty Equipment
Specialty Equipment Tags
Spot Coordinates
Spot Elevation Symbols
Spot Elevations
Spot Slopes
Sprinkler Tags
Sprinklers
Stair Landing Tags
Stair Paths
Stair Run Tags
Stair Support Tags
Stair Tags
Stair Tread/Riser Numbers
Stairs
Structural Annotations
Structural Area Reinforcement
Structural Area Reinforcement Symbols
Structural Area Reinforcement Tags
Structural Beam System Tags
Structural Beam Systems
Structural Column Tags
Structural Columns
Structural Connection Tags
Structural Connections
Structural Fabric Areas
Structural Fabric Reinforcement
Structural Fabric Reinforcement Symbols
Structural Fabric Reinforcement Tags
Structural Foundation Tags
Structural Foundations
Structural Framing
Structural Framing Tags
Structural Internal Loads
Structural Load Cases
Structural Loads
Structural Path Reinforcement
Structural Path Reinforcement Symbols
Structural Path Reinforcement Tags
Structural Rebar
Structural Rebar Coupler Tags
Structural Rebar Couplers
Structural Rebar Tags
Structural Stiffener Tags
Structural Stiffeners
Structural Truss Tags
Structural Trusses
Switch System
Telephone Device Tags
Telephone Devices
Text Notes
Title Blocks
Topography
View Reference
View Titles
Viewports
Views
Wall Tags
Walls
Window Tags
Windows
Wire Tags
Wires
Zone Tags

Effective Output/Input¶

Clickable Element Links¶

work in progress

Tables¶

work in progress

Code Output¶

work in progress

Progress bars¶

work in progress

Standard Prompts¶

Alerts¶

pyrevit.forms.alert(msg, title='pyRevit', ok=True, cancel=False, yes=False, no=False, retry=False, exit=False)

pyrevit.forms.check_workshared(doc)

class pyrevit.forms.WarningBar(height=32, **kwargs)

Show warning bar at the top of Revit window.

Parameters:	title (string) – warning bar text

Example

>>> with WarningBar(title='my warning'):
...    # do stuff

Command Options¶

_static/images/forms-CommandSwitchWindow.png

class pyrevit.forms.CommandSwitchWindow(context, title, width, height, **kwargs)

Standard form to select from a list of command options.

Parameters:	context (list[str]) – list of command options to choose from switches (list[str]) – list of on/off switches message (str) – window title message config (dict) – dictionary of config dicts for options or switches
Returns:	name of selected option
Return type:	str
Returns:	if `switches` option is used, returns a tuple of selection option name and dict of switches
Return type:	tuple(str, dict)

Example

This is an example with series of command options:

>>> from pyrevit import forms
>>> ops = ['option1', 'option2', 'option3', 'option4']
>>> forms.CommandSwitchWindow.show(ops, message='Select Option')
'option2'

A more advanced example of combining command options, on/off switches, and option or switch configuration options:

>>> from pyrevit import forms
>>> ops = ['option1', 'option2', 'option3', 'option4']
>>> switches = ['switch1', 'switch2']
>>> cfgs = {'option1': { 'background': '0xFF55FF'}}
>>> rops, rswitches = forms.CommandSwitchWindow.show(
...     ops,
...     switches=switches
...     message='Select Option',
...     config=cfgs
...     )
>>> rops
'option2'
>>> rswitches
{'switch1': False, 'switch2': True}

Showing Progress¶

class pyrevit.forms.ProgressBar(height=32, **kwargs)

Show progress bar at the top of Revit window.

Parameters:	title (string) – progress bar text, defaults to 0/100 progress format indeterminate (bool) – create indeterminate progress bar cancellable (bool) – add cancel button to progress bar step (int) – update progress intervals

Example

>>> from pyrevit import forms
>>> count = 1
>>> with forms.ProgressBar(title='my command progress message') as pb:
...    # do stuff
...    pb.update_progress(count, 100)
...    count += 1

Progress bar title could also be customized to show the current and total progress values. In example below, the progress bar message will be in format “0 of 100”

>>> with forms.ProgressBar(title='{value} of {max_value}') as pb:

By default progress bar updates the progress every time the .update_progress method is called. For operations with a large number of max steps, the gui update process time will have a significate effect on the overall execution time of the command. In these cases, set the value of step argument to something larger than 1. In example below, the progress bar updates once per every 10 units of progress.

>>> with forms.ProgressBar(title='message', steps=10):

Progress bar could also be set to indeterminate for operations of unknown length. In this case, the progress bar will show an infinitely running ribbon:

>>> with forms.ProgressBar(title='message', indeterminate=True):

if cancellable is set on the object, a cancel button will show on the progress bar and .cancelled attribute will be set on the ProgressBar instance if users clicks on cancel button:

>>> with forms.ProgressBar(title='message',
...                        cancellable=True) as pb:
...    # do stuff
...    if pb.cancelled:
...        # wrap up and cancel operation

Standard Dialogs¶

Pick File¶

pyrevit.forms.pick_file(file_ext='', files_filter='', init_dir='', restore_dir=True, multi_file=False, unc_paths=False)

pyrevit.forms.save_file(file_ext='', files_filter='', init_dir='', default_name='', restore_dir=True, unc_paths=False)

Pick Folder¶

pyrevit.forms.pick_folder()

Select Views¶

pyrevit.forms.select_views(title='Select Views', button_name='Select', width=500, multiple=True, filterfunc=None, doc=None)

Select Sheets¶

pyrevit.forms.select_sheets(title='Select Sheets', button_name='Select', width=500, multiple=True, filterfunc=None, doc=None)

Select Revisions¶

pyrevit.forms.select_revisions(title='Select Revision', button_name='Select', width=500, multiselect=True, filterfunc=None, doc=None)

Select From Open Documents¶

pyrevit.forms.select_dest_docs()

Select From List¶

class pyrevit.forms.SelectFromList(context, title, width, height, **kwargs)

Standard form to select from a list of items.

Parameters:	context (list[str]) – list of items to be selected from title (str) – window title width (int) – window width height (int) – window height button_name (str) – name of select button multiselect (bool) – allow multi-selection

Example

>>> from pyrevit import forms
>>> items = ['item1', 'item2', 'item3']
>>> forms.SelectFromList.show(items, button_name='Select Item')
>>> ['item1']

Select From Checkbox List¶

class pyrevit.forms.SelectFromCheckBoxes(context, title, width, height, **kwargs)

Standard form to select from a list of check boxes.

Check box items passed in context to this standard form, must implement name and state parameter and __nonzero__ method for truth value testing.

Parameters:	context (list[object]) – list of items to be selected from title (str) – window title width (int) – window width height (int) – window height button_name (str) – name of select button

Example

>>> from pyrevit import forms
>>> class MyOption(object):
...     def __init__(self, name, state=False):
...         self.state = state
...         self.name = name
...
...     def __nonzero__(self):
...         return self.state
...
...     def __str__(self):
...         return self.name
>>> ops = [MyOption('op1'), MyOption('op2', True), MyOption('op3')]
>>> res = forms.SelectFromCheckBoxes.show(ops,
...                                       button_name='Select Item')
>>> [bool(x) for x in res]  # or [x.state for x in res]
[True, False, True]

This module also provides a wrapper base class BaseCheckBoxItem for when the checkbox option is wrapping another element, e.g. a Revit ViewSheet. Derive from this base class and define the name property to customize how the checkbox is named on the dialog.

>>> from pyrevit import forms
>>> class MyOption(forms.BaseCheckBoxItem)
...    @property
...    def name(self):
...        return '{} - {}{}'.format(self.item.SheetNumber,
...                                  self.item.SheetNumber)
>>> ops = [MyOption('op1'), MyOption('op2', True), MyOption('op3')]
>>> res = forms.SelectFromCheckBoxes.show(ops,
...                                       button_name='Select Item')
>>> [bool(x) for x in res]  # or [x.state for x in res]
[True, False, True]

class pyrevit.forms.BaseCheckBoxItem(orig_item): Base class for checkbox option wrapping another object.

Base Forms¶

Input Dialog for pyRevit Search¶

pyrevit.forms.SearchPrompt(search_db, width, height, **kwargs)

Standard prompt for pyRevit search.

Parameters:	search_db (list) – list of possible search targets search_tip (str) – text to show in grayscale when search box is empty switches (str) – list of switches width (int) – width of search prompt window height (int) – height of search prompt window
Returns:	matched strings, and dict of switches if provided str: matched string if switches are not provided.
Return type:	str, dict

Example

>>> from pyrevit import forms
>>> # assume search input of '/switch1 target1'
>>> matched_str, switches = forms.SearchPrompt.show(
...     search_db=['target1', 'target2', 'target3', 'target4'],
...     switches=['/switch1', '/switch2'],
...     search_tip='pyRevit Search'
...     )
... matched_str
'target1'
... switches
{'/switch1': True, '/switch2': False}

Generic Forms¶

class pyrevit.forms.TemplatePromptBar(height=32, **kwargs)

Template context-manager class for creating prompt bars.

Prompt bars are show at the top of the active Revit window and are designed for better prompt visibility.

Parameters:	height (int) – window height **kwargs – other arguments to be passed to `_setup()`

class pyrevit.forms.TemplateUserInputWindow(context, title, width, height, **kwargs)

Base class for pyRevit user input standard forms.

Parameters:	context (any) – window context element(s) title (str) – window title width (int) – window width height (int) – window height **kwargs – other arguments to be passed to `_setup()`

class pyrevit.forms.WPFWindow(xaml_source, literal_string=False)

WPF Window base class for all pyRevit forms.

Parameters:	xaml_source (str) – xaml source filepath or xaml content literal_string (bool) – xaml_source contains xaml content, not filepath

Example

>>> from pyrevit import forms
>>> layout = '<Window ShowInTaskbar="False" ResizeMode="NoResize" ' \
>>>          'WindowStartupLocation="CenterScreen" ' \
>>>          'HorizontalContentAlignment="Center">' \
>>>          '</Window>'
>>> w = forms.WPFWindow(layout, literal_string=True)
>>> w.show()

Graphs¶

Step 1: Create a chart object for the chart type that you want. We’ll add data to this later…

from pyrevit import script

output = script.get_output()

# Line chart
chart = output.make_line_chart()
# Bar chart
chart = output.make_bar_chart()
# Bubble chart
chart = output.make_bubble_chart()
# Radar chart
chart = output.make_radar_chart()
# Polar chart
chart = output.make_polar_chart()
# Pie chart
chart = output.make_pie_chart()
# Doughnut chart
chart = output.make_doughnut_chart()

Step 1-a: Optional: Setup the chart title, and other options. the full list of options for every chart is available on Charts.js Documentation page. Some of the properties have their own sub-properties, for example the title option for the charts has multiple sub-properties as shown below. The value for these type of properties should be a dictionary of the sub-properties you’d like to set. All this is explained clearly in the Charts.js Documentation

chart.set_style('height:150px')

chart.options.title = {'display': True,
                       'text':'Chart Title',
                       'fontSize': 18,
                       'fontColor': '#000',
                       'fontStyle': 'bold'}

Step 2: Now let’s add data to the chart. Every chart object has a data property chart.data that we can interact with to add datasets to the chart. Different types of charts need different types of data sets in terms of how data is organized, so the chart can present multiple data sets correctly. I’m providing two examples here, one for a simple line chart (showing 3 different data sets) and another for a radial chart (also showing 3 different data sets within the same chart). They’re all very similar to each other though.

# setting the charts x line data labels
chart.data.labels = ['Monday', 'Tuesday',
                     'Wednesday', 'Thursday',
                     'Friday', 'Saturday', 'Sunday']

# Let's add the first dataset to the chart object
# we'll give it a name: set_a
set_a = chart.data.new_dataset('set_a')
# And let's add data to it.
# These are the data for the Y axis of the graph
# The data length should match the length of data for the X axis
set_a.data = [12, 19, 3, 17, 6, 3, 7]
# Set the color for this graph
set_a.set_color(0xFF, 0x8C, 0x8D, 0.8)

Step 3: The last step is to ask the chart object to draw itself.

# Before drawing the chart you can randomize the colors
# if you have not added any color to the datasets.
chart.randomize_colors()

# Finally let's draw the chart
chart.draw()