pyrevit.script¶

Provide basic utilities for pyRevit scripts.

Example

>>> from pyrevit import script
>>> script.clipboard_copy('some text')
>>> data = script.journal_read('data-key')
>>> script.exit()

pyrevit.script.clipboard_copy(string_to_copy)¶: Copy string to Windows Clipboard.

pyrevit.script.data_exists(slot_name, this_project=True)¶

Checks if data file in a specified slot and for certain project exists.

Parameters:	slot_name (type) – desc this_project (bool) – data belongs to this project only
Returns:	true if the path exists
Return type:	bool

pyrevit.script.dump_csv(data, filepath)¶

Dumps given data into given csv file.

Parameters:	data (list[list[str]]) – data to be dumped filepath (str) – csv file path

pyrevit.script.dump_json(data, filepath)¶

Dumps given data into given json file.

Parameters:	data (object) – serializable data to be dumped filepath (str) – json file path

pyrevit.script.exit()¶: Stop the script execution and exit.

pyrevit.script.get_all_buttons()¶

Find and return all ui buttons matching current script command name.

Sometimes tools are duplicated across extensions for user access control so this would help smart buttons to find all the loaded buttons and make icon adjustments.

Returns:	list of ui button objects
Return type:	`list(pyrevit.coreutils.ribbon._PyRevitRibbonButton)`

pyrevit.script.get_alt_script_path()¶

Return config script path of the current pyRevit command.

Returns:	config script path
Return type:	str

pyrevit.script.get_bundle_file(file_name)¶

Return full path to file under current script bundle.

Parameters:	file_name (str) – bundle file name
Returns:	full bundle file path
Return type:	str

pyrevit.script.get_bundle_files(sub_path=None)¶

Return full path to all file under current script bundle.

Returns:	list of bundle file paths
Return type:	list[str]

pyrevit.script.get_bundle_name()¶

Return bundle name of the current pyRevit command.

Returns:	bundle name (e.g. MyButton.pushbutton)
Return type:	str

pyrevit.script.get_button()¶

Find and return current script ui button.

Returns:	ui button object
Return type:	`pyrevit.coreutils.ribbon._PyRevitRibbonButton`

pyrevit.script.get_config(section=None)¶

Create and return config section parser object for current script.

Parameters:	section (str, optional) – config section name
Returns:	Config section parser object
Return type:	`pyrevit.coreutils.configparser.PyRevitConfigSectionParser`

pyrevit.script.get_data_file(file_id, file_ext, add_cmd_name=False)¶

Return filename to be used by a user script to store data.

File name is generated in this format: pyRevit_{Revit Version}_{file_id}.{file_ext}

Example

>>> script.get_data_file('mydata', 'data')
'.../pyRevit_2018_mydata.data'
>>> script.get_data_file('mydata', 'data', add_cmd_name=True)
'.../pyRevit_2018_Command Name_mydata.data'

Data files are not cleaned up at pyRevit startup. Script should manage cleaning up these files.

Parameters:	file_id (str) – unique id for the filename file_ext (str) – file extension add_cmd_name (bool, optional) – add command name to file name
Returns:	full file path
Return type:	str

pyrevit.script.get_document_data_file(file_id, file_ext, add_cmd_name=False)¶

Return filename to be used by a user script to store data.

File name is generated in this format: pyRevit_{Revit Version}_{file_id}_{Project Name}.{file_ext}

Example

>>> script.get_document_data_file('mydata', 'data')
'.../pyRevit_2018_mydata_Project1.data'
>>> script.get_document_data_file('mydata', 'data', add_cmd_name=True)
'.../pyRevit_2018_Command Name_mydata_Project1.data'

Document data files are not cleaned up at pyRevit startup. Script should manage cleaning up these files.

Parameters:	file_id (str) – unique id for the filename file_ext (str) – file extension add_cmd_name (bool, optional) – add command name to file name
Returns:	full file path
Return type:	str

pyrevit.script.get_envvar(envvar)¶

Return value of give pyRevit environment variable.

The environment variable system is used to retain small values in memory between script runs (e.g. active/inactive state for toggle tools). Do not store large objects in memory using this method. List of currently set environment variables could be sees in pyRevit settings window.

Parameters:	envvar (str) – name of environment variable
Returns:	type of object stored in environment variable
Return type:	any

Example

>>> script.get_envvar('ToolActiveState')
True

pyrevit.script.get_extension_name()¶

Return extension name of the current pyRevit command.

Returns:	extension name (e.g. MyExtension.extension)
Return type:	str

pyrevit.script.get_info()¶

Return info on current pyRevit command.

Returns:	Command info object
Return type:	`pyrevit.extensions.genericcomps.GenericUICommand`

pyrevit.script.get_instance_data_file(file_id, add_cmd_name=False)¶

Return filename to be used by a user script to store data.

File name is generated in this format: pyRevit_{Revit Version}_{Process Id}_{file_id}.{file_ext}

Example

>>> script.get_instance_data_file('mydata')
'.../pyRevit_2018_6684_mydata.tmp'
>>> script.get_instance_data_file('mydata', add_cmd_name=True)
'.../pyRevit_2018_6684_Command Name_mydata.tmp'

Instance data files are cleaned up at pyRevit startup.

Parameters:	file_id (str) – unique id for the filename add_cmd_name (bool, optional) – add command name to file name
Returns:	full file path
Return type:	str

pyrevit.script.get_logger()¶

Create and return logger named for current script.

Returns:	Logger object
Return type:	`pyrevit.coreutils.logger.LoggerWrapper`

pyrevit.script.get_output()¶

Return object wrapping output window for current script.

Returns:	Output wrapper object
Return type:	`pyrevit.output.PyRevitOutputWindow`

pyrevit.script.get_pyrevit_version()¶

Return pyRevit version.

Returns:	pyRevit version provider
Return type:	`pyrevit.versionmgr._PyRevitVersion`

pyrevit.script.get_results()¶

Return command results dictionary for logging.

Returns:	Command results dict
Return type:	`pyrevit.telemetry.record.CommandCustomResults`

pyrevit.script.get_script_path()¶

Return script path of the current pyRevit command.

Returns:	script path
Return type:	str

pyrevit.script.get_unique_id()¶

Return unique id of the current pyRevit command.

Returns:	command unique id
Return type:	str

pyrevit.script.get_universal_data_file(file_id, file_ext, add_cmd_name=False)¶

Return filename to be used by a user script to store data.

File name is generated in this format: pyRevit_{file_id}.{file_ext}

Example

>>> script.get_universal_data_file('mydata', 'data')
'.../pyRevit_mydata.data'
>>> script.get_universal_data_file('mydata', 'data', add_cmd_name=True)
'.../pyRevit_Command Name_mydata.data'

Universal data files are not cleaned up at pyRevit startup. Script should manage cleaning up these files.

Parameters:	file_id (str) – unique id for the filename file_ext (str) – file extension add_cmd_name (bool, optional) – add command name to file name
Returns:	full file path
Return type:	str

pyrevit.script.journal_read(data_key)¶

Read value for provided key from active Revit journal.

Parameters:	data_key (str) – data key
Returns:	data value string
Return type:	str

pyrevit.script.journal_write(data_key, msg)¶

Write key and value to active Revit journal for current command.

Parameters:	data_key (str) – data key msg (str) – data value string

pyrevit.script.load_csv(filepath)¶

Read lines from given csv file

Parameters:	filepath (str) – csv file path
Returns:	csv data
Return type:	list[list[str]]

pyrevit.script.load_data(slot_name, this_project=True)¶

Wraps python pickle.load() to easily load data from pyRevit data files

To recover native Revit objects, use revit.deserialize(). See Example

Similar to pickle module, the custom data types must be defined in the main scope so the loader can create an instance and return original stored data

Parameters:	slot_name (type) – desc this_project (bool) – data belongs to this project only
Returns:	stored data
Return type:	obj

Example

>>> from pyrevit import revit
... from pyrevit import script
...
...
... class CustomData(object):
...     def __init__(self, count, element_ids):
...         self._count = count
...         # serializes the Revit native objects
...         self._elmnt_ids = [revit.serialize(x) for x in element_ids]
...
...     @property
...     def count(self):
...         return self._count
...
...     @property
...     def element_ids(self):
...         # de-serializes the Revit native objects
...         return [x.deserialize() for x in self._elmnt_ids]
...
...
... mydata = script.load_data("Selected Elements", element_ids)
... mydata.element_ids
[<DB.ElementId>, <DB.ElementId>, <DB.ElementId>]

pyrevit.script.load_index(index_file='index.html')¶

Load html file into output window.

This method expects index.html file in the current command bundle, unless full path to an html file is provided.

Parameters:	index_file (str, optional) – full path of html file.

pyrevit.script.load_json(filepath)¶

Loads data from given json file.

Parameters:	filepath (str) – json file path
Returns:	deserialized data
Return type:	object

pyrevit.script.open_url(url)¶: Open url in a new tab in default webbrowser.

pyrevit.script.remove_data_file(filepath)¶: Remove given data file

pyrevit.script.reset_config(section=None)¶

Reset pyRevit config.

Script should call this to reset any save configuration by removing section related to current script.

Parameters:	section (str, optional) – config section name

pyrevit.script.save_config()¶

Save pyRevit config.

Scripts should call this to save any changes they have done to their config section object received from script.get_config() method.

pyrevit.script.set_envvar(envvar, value)¶

Set value of give pyRevit environment variable.

The environment variable system is used to retain small values in memory between script runs (e.g. active/inactive state for toggle tools). Do not store large objects in memory using this method. List of currently set environment variables could be sees in pyRevit settings window.

Parameters:	envvar (str) – name of environment variable value (any) – value of environment variable

Example

>>> script.set_envvar('ToolActiveState', False)
>>> script.get_envvar('ToolActiveState')
False

pyrevit.script.show_file_in_explorer(file_path)¶: Show file in Windows Explorer.

pyrevit.script.show_folder_in_explorer(folder_path)¶: Show folder in Windows Explorer.

pyrevit.script.store_data(slot_name, data, this_project=True)¶

Wraps python pickle.dump() to easily store data to pyRevit data files

To store native Revit objects, use revit.serialize(). See Example

Parameters:	slot_name (type) – desc data (obj) – any pickalable data this_project (bool) – data belongs to this project only

Example

>>> from pyrevit import revit
... from pyrevit import script
...
...
... class CustomData(object):
...     def __init__(self, count, element_ids):
...         self._count = count
...         # serializes the Revit native objects
...         self._elmnt_ids = [revit.serialize(x) for x in element_ids]
...
...     @property
...     def count(self):
...         return self._count
...
...     @property
...     def element_ids(self):
...         # de-serializes the Revit native objects
...         return [x.deserialize() for x in self._elmnt_ids]
...
...
... mydata = CustomData(
...     count=3,
...     element_ids=[<DB.ElementId>, <DB.ElementId>, <DB.ElementId>]
... )
...
... script.store_data("Selected Elements", mydata)

pyrevit.script.toggle_icon(new_state, on_icon_path=None, off_icon_path=None)¶

Set the state of button icon (on or off).

This method expects on.png and off.png in command bundle for on and off icon states, unless full path of icon states are provided.

Parameters:	new_state (bool) – state of the ui button icon. on_icon_path (str, optional) – full path of icon for on state. default=’on.png’ off_icon_path (str, optional) – full path of icon for off state. default=’off.png’