Skip to content

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 
50
51
52
53
54
55
56
57
58
def get_info():
    """Return info on current pyRevit command.

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

get_script_path()

Return script path of the current pyRevit command.

Returns:

Type Description
str

script path
Source code in pyrevitlib/pyrevit/script.py 
61
62
63
64
65
66
67
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 
70
71
72
73
74
75
76
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 
79
80
81
82
83
84
85
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 
88
89
90
91
92
93
94
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 
 97
 98
 99
100
101
102
103
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 
106
107
108
109
110
111
112
113
114
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 
117
118
119
120
121
122
123
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 
126
127
128
129
130
131
132
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 
135
136
137
138
139
140
141
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 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
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 
166
167
168
169
170
171
172
173
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 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
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 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
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 
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
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 
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
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 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
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 
347
348
349
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 
352
353
354
355
356
357
358
359
360
361
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 
364
365
366
367
368
369
370
371
372
373
374
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 
377
378
379
380
381
382
383
384
385
386
387
388
389
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 
392
393
394
395
396
397
398
399
400
401
402
403
404
405
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 
408
409
410
411
412
413
414
415
416
417
418
419
420
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 
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
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 
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
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 
486
487
488
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 
491
492
493
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 
496
497
498
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 
501
502
503
504
505
506
507
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 
510
511
512
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 
515
516
517
518
519
520
521
522
523
524
525
526
527
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 
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
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 
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
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 
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
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 
602
603
604
605
606
607
608
609
610
611
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 
614
615
616
617
618
619
620
621
622
623
624
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 
627
628
629
630
631
632
633
634
635
636
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 
639
640
641
642
643
644
645
646
647
648
649
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 
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
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 
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
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 
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
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)