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.
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
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.
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’