script

Provide basic utilities for pyRevit scripts.

Examples:

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

Attributes

mlogger = logger.get_logger(__name__) module-attribute

DATAFEXT = 'pym' module-attribute

ICON_SMALL = 16 module-attribute

ICON_MEDIUM = 24 module-attribute

ICON_LARGE = 32 module-attribute

Classes

Functions

get_info()

Return info on current pyRevit command.

Returns:

Type	Description
GenericUICommand	Command info object

Source code in pyrevitlib/pyrevit/script.py

def get_info():
    """Return info on current pyRevit command.

    Returns:
        (pyrevit.extensions.genericcomps.GenericUICommand):
            Command info object
    """
    return get_command_from_path(EXEC_PARAMS.command_path)

get_command_from_path(comp_path)

Returns a pyRevit command object from the given bundle directory.

Parameters:

Name	Type	Description	Default
comp_path	str	Full directory address of the command bundle	required

Returns:

Type	Description
GenericUICommand	A subclass of pyRevit command object.

Source code in pyrevitlib/pyrevit/script.py

def get_command_from_path(comp_path):
    """Returns a pyRevit command object from the given bundle directory.

    Args:
        comp_path (str): Full directory address of the command bundle

    Returns:
        (genericcomps.GenericUICommand): A subclass of pyRevit command object.
    """
    cmds = parse_comp_dir(comp_path, GenericUICommand)
    if cmds:
        return cmds[0]

    return None

get_script_path()

Return script path of the current pyRevit command.

Returns:

Type	Description
str	script path

Source code in pyrevitlib/pyrevit/script.py

def get_script_path():
    """Return script path of the current pyRevit command.

    Returns:
        (str): script path
    """
    return EXEC_PARAMS.command_path

get_alt_script_path()

Return config script path of the current pyRevit command.

Returns:

Type	Description
str	config script path

Source code in pyrevitlib/pyrevit/script.py

def get_alt_script_path():
    """Return config script path of the current pyRevit command.

    Returns:
        (str): config script path
    """
    return EXEC_PARAMS.command_config_path

get_bundle_name()

Return bundle name of the current pyRevit command.

Returns:

Type	Description
str	bundle name (e.g. MyButton.pushbutton)

Source code in pyrevitlib/pyrevit/script.py

def get_bundle_name():
    """Return bundle name of the current pyRevit command.

    Returns:
        (str): bundle name (e.g. MyButton.pushbutton)
    """
    return EXEC_PARAMS.command_bundle

get_extension_name()

Return extension name of the current pyRevit command.

Returns:

Type	Description
str	extension name (e.g. MyExtension.extension)

Source code in pyrevitlib/pyrevit/script.py

def get_extension_name():
    """Return extension name of the current pyRevit command.

    Returns:
        (str): extension name (e.g. MyExtension.extension)
    """
    return EXEC_PARAMS.command_extension

get_unique_id()

Return unique id of the current pyRevit command.

Returns:

Type	Description
str	command unique id

Source code in pyrevitlib/pyrevit/script.py

def get_unique_id():
    """Return unique id of the current pyRevit command.

    Returns:
        (str): command unique id
    """
    return EXEC_PARAMS.command_uniqueid

get_results()

Return command results dictionary for logging.

Returns:

Type	Description
CommandCustomResults	Command results dict

Source code in pyrevitlib/pyrevit/script.py

def get_results():
    """Return command results dictionary for logging.

    Returns:
        (pyrevit.telemetry.record.CommandCustomResults):
            Command results dict
    """
    from pyrevit.telemetry.record import CommandCustomResults
    return CommandCustomResults()

get_pyrevit_version()

Return pyRevit version.

Returns:

Type	Description
_PyRevitVersion	pyRevit version provider

Source code in pyrevitlib/pyrevit/script.py

def get_pyrevit_version():
    """Return pyRevit version.

    Returns:
        (pyrevit.versionmgr._PyRevitVersion): pyRevit version provider
    """
    return versionmgr.get_pyrevit_version()

get_logger()

Create and return logger named for current script.

Returns:

Type	Description
LoggerWrapper	Logger object

Source code in pyrevitlib/pyrevit/script.py

def get_logger():
    """Create and return logger named for current script.

    Returns:
        (pyrevit.coreutils.logger.LoggerWrapper): Logger object
    """
    return logger.get_logger(EXEC_PARAMS.command_name)

get_output()

Return object wrapping output window for current script.

Returns:

Type	Description
PyRevitOutputWindow	Output wrapper object

Source code in pyrevitlib/pyrevit/script.py

def get_output():
    """Return object wrapping output window for current script.

    Returns:
        (pyrevit.output.PyRevitOutputWindow): Output wrapper object
    """
    return output.get_output()

get_config(section=None)

Create and return config section parser object for current script.

Parameters:

Name	Type	Description	Default
section	str	config section name. If not provided, it will default to the command name plus the 'config' suffix.	None

Returns:

Type	Description
PyRevitConfigSectionParser	Config section parser object

Source code in pyrevitlib/pyrevit/script.py

def get_config(section=None):
    """Create and return config section parser object for current script.

    Args:
        section (str, optional): config section name. If not provided,
            it will default to the command name plus the 'config' suffix.

    Returns:
        (pyrevit.coreutils.configparser.PyRevitConfigSectionParser):
            Config section parser object
    """
    from pyrevit.userconfig import user_config
    if not section:
        script_cfg_postfix = 'config'
        section = EXEC_PARAMS.command_name + script_cfg_postfix

    try:
        return user_config.get_section(section)
    except AttributeError:
        return user_config.add_section(section)

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.

Source code in pyrevitlib/pyrevit/script.py

def 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.
    """
    from pyrevit.userconfig import user_config
    user_config.save_changes()

reset_config(section=None)

Reset pyRevit config.

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

Parameters:

Name	Type	Description	Default
section	str	config section name	None

Source code in pyrevitlib/pyrevit/script.py

def reset_config(section=None):
    """Reset pyRevit config.

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

    Args:
        section (str, optional): config section name
    """
    from pyrevit.userconfig import user_config
    if not section:
        script_cfg_postfix = 'config'
        section = EXEC_PARAMS.command_name + script_cfg_postfix
    elif section in [PyRevit.PyRevitConsts.ConfigsCoreSection]:
        raise PyRevitException('Can not remove internal config section: {}'
                               .format(section))

    try:
        user_config.remove_section(section)
        user_config.save_changes()
    except Exception:
        mlogger.debug('Failed resetting config for %s (%s)',
                      EXEC_PARAMS.command_name, section)

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}

Examples:

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:

Name	Type	Description	Default
file_id	str	unique id for the filename	required
file_ext	str	file extension	required
add_cmd_name	bool	add command name to file name	False

Returns:

Type	Description
str	full file path

Source code in pyrevitlib/pyrevit/script.py

def 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}``

    Examples:
        ```python
        script.get_universal_data_file('mydata', 'data')
        ```
        '/pyRevit_mydata.data'
        ```python
        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.

    Args:
        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:
        (str): full file path
    """
    if add_cmd_name:
        script_file_id = '{}_{}'.format(EXEC_PARAMS.command_name, file_id)
    else:
        script_file_id = file_id

    return appdata.get_universal_data_file(script_file_id, file_ext)

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}

Examples:

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:

Name	Type	Description	Default
file_id	str	unique id for the filename	required
file_ext	str	file extension	required
add_cmd_name	bool	add command name to file name	False

Returns:

Type	Description
str	full file path

Source code in pyrevitlib/pyrevit/script.py

def 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}``

    Examples:
        ```python
        script.get_data_file('mydata', 'data')
        ```
        '/pyRevit_2018_mydata.data'
        ```python
        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.

    Args:
        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:
        (str): full file path
    """
    if add_cmd_name:
        script_file_id = '{}_{}'.format(EXEC_PARAMS.command_name, file_id)
    else:
        script_file_id = file_id

    return appdata.get_data_file(script_file_id, file_ext)

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}

Examples:

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:

Name	Type	Description	Default
file_id	str	unique id for the filename	required
add_cmd_name	bool	add command name to file name	False

Returns:

Type	Description
str	full file path

Source code in pyrevitlib/pyrevit/script.py

def 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}``

    Examples:
        ```python
        script.get_instance_data_file('mydata')
        ```
        '/pyRevit_2018_6684_mydata.tmp'
        ```python
        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.

    Args:
        file_id (str): unique id for the filename
        add_cmd_name (bool, optional): add command name to file name

    Returns:
        (str): full file path
    """
    if add_cmd_name:
        script_file_id = '{}_{}'.format(EXEC_PARAMS.command_name, file_id)
    else:
        script_file_id = file_id

    return appdata.get_instance_data_file(script_file_id)

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}

Examples:

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:

Name	Type	Description	Default
file_id	str	unique id for the filename	required
file_ext	str	file extension	required
add_cmd_name	bool	add command name to file name	False

Returns:

Type	Description
str	full file path

Source code in pyrevitlib/pyrevit/script.py

def 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}``

    Examples:
        ```python
        script.get_document_data_file('mydata', 'data')
        ```
        '/pyRevit_2018_mydata_Project1.data'
        ```python
        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.

    Args:
        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:
        (str): full file path
    """
    proj_info = revit.query.get_project_info()

    if add_cmd_name:
        script_file_id = '{}_{}_{}'.format(EXEC_PARAMS.command_name,
                                           file_id,
                                           proj_info.filename
                                           or proj_info.name)
    else:
        script_file_id = '{}_{}'.format(file_id,
                                        proj_info.filename
                                        or proj_info.name)

    return appdata.get_data_file(script_file_id, file_ext)

remove_data_file(filepath)

Remove given data file.

Source code in pyrevitlib/pyrevit/script.py

def remove_data_file(filepath):
    """Remove given data file."""
    appdata.garbage_data_file(filepath)

get_bundle_file(file_name)

Return full path to file under current script bundle.

Parameters:

Name	Type	Description	Default
file_name	str	bundle file name	required

Returns:

Type	Description
str	full bundle file path

Source code in pyrevitlib/pyrevit/script.py

def get_bundle_file(file_name):
    """Return full path to file under current script bundle.

    Args:
        file_name (str): bundle file name

    Returns:
        (str): full bundle file path
    """
    return op.join(EXEC_PARAMS.command_path, file_name)

get_bundle_files(sub_path=None)

Return full path to all file under current script bundle.

Returns:

Type	Description
list[str]	list of bundle file paths

Source code in pyrevitlib/pyrevit/script.py

def get_bundle_files(sub_path=None):
    """Return full path to all file under current script bundle.

    Returns:
        (list[str]): list of bundle file paths
    """
    if sub_path:
        command_path = op.join(EXEC_PARAMS.command_path, sub_path)
    else:
        command_path = EXEC_PARAMS.command_path
    return [op.join(command_path, x) for x in os.listdir(command_path)]

journal_write(data_key, msg)

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

Parameters:

Name	Type	Description	Default
data_key	str	data key	required
msg	str	data value string	required

Source code in pyrevitlib/pyrevit/script.py

def journal_write(data_key, msg):
    """Write key and value to active Revit journal for current command.

    Args:
        data_key (str): data key
        msg (str): data value string
    """
    # Get the StringStringMap class which can write data into.
    data_map = EXEC_PARAMS.command_data.JournalData
    data_map.Clear()

    # Begin to add the support data
    data_map.Add(data_key, msg)

journal_read(data_key)

Read value for provided key from active Revit journal.

Parameters:

Name	Type	Description	Default
data_key	str	data key	required

Returns:

Type	Description
str	data value string

Source code in pyrevitlib/pyrevit/script.py

def journal_read(data_key):
    """Read value for provided key from active Revit journal.

    Args:
        data_key (str): data key

    Returns:
        (str): data value string
    """
    # Get the StringStringMap class which can write data into.
    data_map = EXEC_PARAMS.command_data.JournalData

    # Begin to get the support data
    return data_map[data_key]

get_button()

Find and return current script ui button.

Returns:

Type	Description
_PyRevitRibbonButton	ui button object

Source code in pyrevitlib/pyrevit/script.py

def get_button():
    """Find and return current script ui button.

    Returns:
        (pyrevit.coreutils.ribbon._PyRevitRibbonButton): ui button object
    """
    from pyrevit.coreutils.ribbon import get_current_ui
    pyrvt_tabs = get_current_ui().get_pyrevit_tabs()
    for tab in pyrvt_tabs:
        button = tab.find_child(EXEC_PARAMS.command_name)
        if button:
            return button
    return None

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:

Type	Description
list[_PyRevitRibbonButton]	list of ui button objects

Source code in pyrevitlib/pyrevit/script.py

def 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[pyrevit.coreutils.ribbon._PyRevitRibbonButton]):
            list of ui button objects
    """
    from pyrevit.coreutils.ribbon import get_current_ui
    pyrvt_tabs = get_current_ui().get_pyrevit_tabs()
    buttons = []
    for tab in pyrvt_tabs:
        button = tab.find_child(EXEC_PARAMS.command_name)
        if button:
            buttons.append(button)
    return buttons

toggle_icon(new_state, on_icon_path=None, off_icon_path=None, icon_size=ICON_MEDIUM)

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:

Name	Type	Description	Default
new_state	bool	state of the ui button icon.	required
on_icon_path	str	full path of icon for on state. default='on.png'	None
off_icon_path	str	full path of icon for off state. default='off.png'	None
icon_size	int	size of the icon. Defaults to medium (24x24)	ICON_MEDIUM

Source code in pyrevitlib/pyrevit/script.py

def toggle_icon(new_state, on_icon_path=None, off_icon_path=None, icon_size=ICON_MEDIUM):
    """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.

    Args:
        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'
        icon_size (int): size of the icon. Defaults to medium (24x24)
    """
    # find the ui button
    uibuttons = get_all_buttons()
    if not uibuttons:
        mlogger.debug('Can not find ui button.')
        return

    # get icon for on state
    if not on_icon_path:
        on_icon_path = ui.resolve_icon_file(EXEC_PARAMS.command_path, exts.DEFAULT_ON_ICON_FILE)
        if not on_icon_path:
            mlogger.debug('Script does not have icon for on state.')
            return

    # get icon for off state
    if not off_icon_path:
        off_icon_path = ui.resolve_icon_file(EXEC_PARAMS.command_path, exts.DEFAULT_OFF_ICON_FILE)
        if not off_icon_path:
            mlogger.debug('Script does not have icon for on state.')
            return

    icon_path = on_icon_path if new_state else off_icon_path
    mlogger.debug('Setting icon state to: %s (%s)',
                  new_state, icon_path)

    for uibutton in uibuttons:
        uibutton.set_icon(icon_path, icon_size)

exit()

Stop the script execution and exit.

Source code in pyrevitlib/pyrevit/script.py

def exit():     #pylint: disable=W0622
    """Stop the script execution and exit."""
    sys.exit()

show_file_in_explorer(file_path)

Show file in Windows Explorer.

Source code in pyrevitlib/pyrevit/script.py

def show_file_in_explorer(file_path):
    """Show file in Windows Explorer."""
    coreutils.show_entry_in_explorer(file_path)

show_folder_in_explorer(folder_path)

Show folder in Windows Explorer.

Source code in pyrevitlib/pyrevit/script.py

def show_folder_in_explorer(folder_path):
    """Show folder in Windows Explorer."""
    coreutils.open_folder_in_explorer(folder_path)

open_url(url)

Open url in a new tab in default webbrowser.

Source code in pyrevitlib/pyrevit/script.py

def open_url(url):
    """Open url in a new tab in default webbrowser."""
    import webbrowser
    if re.match('^https*://', url.lower()):
        webbrowser.open_new_tab(url)
    else:
        webbrowser.open_new_tab('http://' + url)

clipboard_copy(string_to_copy)

Copy string to Windows Clipboard.

Source code in pyrevitlib/pyrevit/script.py

def clipboard_copy(string_to_copy):
    """Copy string to Windows Clipboard."""
    framework.Clipboard.SetText(string_to_copy)

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:

Name	Type	Description	Default
index_file	str	full path of html file.	'index.html'

Source code in pyrevitlib/pyrevit/script.py

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

    Args:
        index_file (str, optional): full path of html file.
    """
    outputwindow = get_output()
    if not op.isfile(index_file):
        index_file = get_bundle_file(index_file)
    outputwindow.open_page(index_file)

load_ui(ui_instance, ui_file='ui.xaml', handle_esc=True, set_owner=True)

Load xaml file into given window instance.

If window instance defines a method named setup it will be called after loading

Parameters:

Name	Type	Description	Default
ui_instance	WPFWindow	ui form instance	required
ui_file	str	name of ui xaml file. defaults to: 'ui.xaml'	'ui.xaml'
handle_esc	bool	handle escape and close window	True
set_owner	bool	set window owner to Revit window	True

Source code in pyrevitlib/pyrevit/script.py

def load_ui(ui_instance, ui_file='ui.xaml', handle_esc=True, set_owner=True):
    """Load xaml file into given window instance.

    If window instance defines a method named `setup` it
    will be called after loading 

    Args:
        ui_instance (forms.WPFWindow): ui form instance
        ui_file (str, optional): name of ui xaml file. defaults to: 'ui.xaml'
        handle_esc (bool, optional): handle escape and close window
        set_owner (bool, optional): set window owner to Revit window
    """
    ui_file = get_bundle_file(ui_file)
    if ui_file:
        ui_instance.load_xaml(
            ui_file,
            literal_string=False,
            handle_esc=handle_esc,
            set_owner=set_owner
            )
        if hasattr(ui_instance, 'setup'):
            ui_instance.setup()
        return ui_instance

    raise PyRevitException("Missing bundle ui file: {}".format(ui_file))

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:

Name	Type	Description	Default
envvar	str	name of environment variable	required

Returns:

Type	Description
Any	object stored in environment variable

Examples:

script.get_envvar('ToolActiveState')

True

Source code in pyrevitlib/pyrevit/script.py

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

    Args:
        envvar (str): name of environment variable

    Returns:
        (Any): object stored in environment variable

    Examples:
        ```python
        script.get_envvar('ToolActiveState')
        ```
        True
    """
    return envvars.get_pyrevit_env_var(envvar)

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:

Name	Type	Description	Default
envvar	str	name of environment variable	required
value	any	value of environment variable	required

Examples:

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

False

Source code in pyrevitlib/pyrevit/script.py

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

    Args:
        envvar (str): name of environment variable
        value (any): value of environment variable

    Examples:
        ```python
        script.set_envvar('ToolActiveState', False)
        script.get_envvar('ToolActiveState')
        ```
        False
    """
    return envvars.set_pyrevit_env_var(envvar, value)

dump_json(data, filepath)

Dumps given data into given json file.

Parameters:

Name	Type	Description	Default
data	object	serializable data to be dumped	required
filepath	str	json file path	required

Source code in pyrevitlib/pyrevit/script.py

def dump_json(data, filepath):
    """Dumps given data into given json file.

    Args:
        data (object): serializable data to be dumped
        filepath (str): json file path
    """
    json_repr = json.dumps(data, indent=4, ensure_ascii=False)
    with codecs.open(filepath, 'w', "utf-8") as json_file:
        json_file.write(json_repr)

load_json(filepath)

Loads data from given json file.

Parameters:

Name	Type	Description	Default
filepath	str	json file path	required

Returns:

Type	Description
object	deserialized data

Source code in pyrevitlib/pyrevit/script.py

def load_json(filepath):
    """Loads data from given json file.

    Args:
        filepath (str): json file path

    Returns:
        (object): deserialized data
    """
    with codecs.open(filepath, 'r', "utf-8") as json_file:
        return json.load(json_file)

dump_csv(data, filepath)

Dumps given data into given csv file.

Parameters:

Name	Type	Description	Default
data	list[list[str]]	data to be dumped	required
filepath	str	csv file path	required

Source code in pyrevitlib/pyrevit/script.py

def dump_csv(data, filepath):
    """Dumps given data into given csv file.

    Args:
        data (list[list[str]]): data to be dumped
        filepath (str): csv file path
    """
    with codecs.open(filepath, 'wb', encoding='utf-8') as csvfile:
        writer = csv.writer(csvfile, delimiter=',', quotechar='\"')
        writer.writerows(data)

load_csv(filepath)

Read lines from given csv file.

Parameters:

Name	Type	Description	Default
filepath	str	csv file path	required

Returns:

Type	Description
list[list[str]]	csv data

Source code in pyrevitlib/pyrevit/script.py

def load_csv(filepath):
    """Read lines from given csv file.

    Args:
        filepath (str): csv file path

    Returns:
        (list[list[str]]): csv data
    """
    with codecs.open(filepath, 'rb', encoding='utf-8') as csvfile:
        return list(csv.reader(csvfile, delimiter=',', quotechar='\"'))

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:

Name	Type	Description	Default
slot_name	type	desc	required
data	obj	any pickalable data	required
this_project	bool	data belongs to this project only	True

Examples:

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)

Source code in pyrevitlib/pyrevit/script.py

def 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

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

    Examples:
        ```python
        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)
        ```

    """
    # for this specific project?
    if this_project:
        data_file = get_document_data_file(file_id=slot_name,
                                           file_ext=DATAFEXT,
                                           add_cmd_name=False)
    # for any project file
    else:
        data_file = get_data_file(file_id=slot_name,
                                  file_ext=DATAFEXT,
                                  add_cmd_name=False)

    with open(data_file, 'w') as dfile:
        pickle.dump(data, dfile)

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:

Name	Type	Description	Default
slot_name	type	desc	required
this_project	bool	data belongs to this project only	True

Returns:

Type	Description
object	stored data

Examples:

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")
    mydata.element_ids

[, , ]

Source code in pyrevitlib/pyrevit/script.py

def 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

    Args:
        slot_name (type): desc
        this_project (bool): data belongs to this project only

    Returns:
        (object): stored data

    Examples:
        ```python
        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")
            mydata.element_ids
        ```
        [<DB.ElementId>, <DB.ElementId>, <DB.ElementId>]
    """
    # for this specific project?
    if this_project:
        data_file = get_document_data_file(file_id=slot_name,
                                           file_ext=DATAFEXT,
                                           add_cmd_name=False)
    # for any project file
    else:
        data_file = get_data_file(file_id=slot_name,
                                  file_ext=DATAFEXT,
                                  add_cmd_name=False)

    with open(data_file, 'r') as dfile:
        return pickle.load(dfile)

data_exists(slot_name, this_project=True)

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

Parameters:

Name	Type	Description	Default
slot_name	type	desc	required
this_project	bool	data belongs to this project only	True

Returns:

Type	Description
bool	true if the path exists

Source code in pyrevitlib/pyrevit/script.py

def data_exists(slot_name, this_project=True):
    """Checks if data file in a specified slot and for certain project exists.

    Args:
        slot_name (type): desc
        this_project (bool): data belongs to this project only

    Returns:
        (bool): true if the path exists
    """
    # for this specific project?
    if this_project:
        data_file = get_document_data_file(file_id=slot_name,
                                           file_ext=DATAFEXT,
                                           add_cmd_name=False)
    # for any project file
    else:
        data_file = get_data_file(file_id=slot_name,
                                  file_ext=DATAFEXT,
                                  add_cmd_name=False)
    return os.path.exists(data_file)