appdata

Utility functions for creating data files within pyRevit environment.

Most times, scripts need to save some data to share between different scripts that work on a similar topic or between script executions. This module provides the necessary and consistent mechanism for creating and maintaining such files.

Examples:

from pyrevit.coreutils import appdata
appdata.list_data_files()

Attributes

mlogger = logger.get_logger(__name__) module-attribute

TEMP_FILE_EXT = 'tmp' module-attribute

Functions

get_universal_data_file(file_id, file_ext, name_only=False)

Get path to file that is shared between all host versions.

These data files are not cleaned up at Revit restart. e.g pyrevit_pyrevitlabs_file_id.file_ext

Parameters:

Name	Type	Description	Default
file_id	str	Unique identifier for the file	required
file_ext	str	File extension	required
name_only	bool	If true, function returns file name only	False

Returns:

Type	Description
str	File name or full file path (depending on name_only)

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def get_universal_data_file(file_id, file_ext, name_only=False):
    """Get path to file that is shared between all host versions.

    These data files are not cleaned up at Revit restart.
    e.g pyrevit_pyrevitlabs_file_id.file_ext

    Args:
        file_id (str): Unique identifier for the file
        file_ext (str): File extension
        name_only (bool): If true, function returns file name only

    Returns:
        (str): File name or full file path (depending on name_only)
    """
    return _get_app_file(file_id, file_ext,
                         filename_only=name_only, universal=True)

get_data_file(file_id, file_ext, name_only=False)

Get path to file that will not be cleaned up at Revit load.

e.g pyrevit_2016_pyrevitlabs_file_id.file_ext

Parameters:

Name	Type	Description	Default
file_id	str	Unique identifier for the file	required
file_ext	str	File extension	required
name_only	bool	If true, function returns file name only	False

Returns:

Type	Description
str	File name or full file path (depending on name_only)

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def get_data_file(file_id, file_ext, name_only=False):
    """Get path to file that will not be cleaned up at Revit load.

    e.g pyrevit_2016_pyrevitlabs_file_id.file_ext

    Args:
        file_id (str): Unique identifier for the file
        file_ext (str): File extension
        name_only (bool): If true, function returns file name only

    Returns:
        (str): File name or full file path (depending on name_only)
    """
    return _get_app_file(file_id, file_ext, filename_only=name_only)

get_instance_data_file(file_id, file_ext=TEMP_FILE_EXT, name_only=False)

Get path to file that should be used by current instance only.

These data files will be cleaned up at Revit restart. e.g pyrevit_2016_pyrevitlabs_2353_file_id.file_ext

Parameters:

Name	Type	Description	Default
file_id	str	Unique identifier for the file	required
file_ext	str	File extension	TEMP_FILE_EXT
name_only	bool	If true, function returns file name only	False

Returns:

Type	Description
str	File name or full file path (depending on name_only)

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def get_instance_data_file(file_id, file_ext=TEMP_FILE_EXT, name_only=False):
    """Get path to file that should be used by current instance only.

    These data files will be cleaned up at Revit restart.
    e.g pyrevit_2016_pyrevitlabs_2353_file_id.file_ext

    Args:
        file_id (str): Unique identifier for the file
        file_ext (str): File extension
        name_only (bool): If true, function returns file name only

    Returns:
        (str): File name or full file path (depending on name_only)
    """
    return _get_app_file(file_id, file_ext,
                         filename_only=name_only, stamped=True)

is_pyrevit_data_file(file_name)

Check if given file is a pyRevit data file.

Parameters:

Name	Type	Description	Default
file_name	str	file name	required

Returns:

Type	Description
bool	True if file is a pyRevit data file

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def is_pyrevit_data_file(file_name):
    """Check if given file is a pyRevit data file.

    Args:
        file_name (str): file name

    Returns:
        (bool): True if file is a pyRevit data file
    """
    return pyrevit.PYREVIT_FILE_PREFIX in file_name

is_file_available(file_name, file_ext, universal=False)

Check if given file is available within appdata directory.

Parameters:

Name	Type	Description	Default
file_name	str	file name	required
file_ext	str	file extension	required
universal	bool	Check against universal data files	False

Returns:

Type	Description
str | bool	file path if file is available

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def is_file_available(file_name, file_ext, universal=False):
    """Check if given file is available within appdata directory.

    Args:
        file_name (str): file name
        file_ext (str): file extension
        universal (bool): Check against universal data files

    Returns:
        (str | bool): file path if file is available
    """
    if universal:
        full_filename = op.join(
            pyrevit.PYREVIT_APP_DIR,
            coreutils.make_canonical_name(file_name, file_ext))
    else:
        full_filename = op.join(
            pyrevit.PYREVIT_VERSION_APP_DIR,
            coreutils.make_canonical_name(file_name, file_ext))
    if op.exists(full_filename):
        return full_filename
    else:
        return False

is_data_file_available(file_id, file_ext)

Check if given file is available within appdata directory.

Parameters:

Name	Type	Description	Default
file_id	str	data file id	required
file_ext	str	file extension	required

Returns:

Type	Description
str	file path if file is available

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def is_data_file_available(file_id, file_ext):
    """Check if given file is available within appdata directory.

    Args:
        file_id (str): data file id
        file_ext (str): file extension

    Returns:
        (str): file path if file is available
    """
    full_filename = _get_app_file(file_id, file_ext)
    if op.exists(full_filename):
        return full_filename
    else:
        return False

list_data_files(file_ext, universal=False)

List all data files with given extension.

Parameters:

Name	Type	Description	Default
file_ext	str	file extension	required
universal	bool	Check against universal data files	False

Returns:

Type	Description
list[str]	list of files

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def list_data_files(file_ext, universal=False):
    """List all data files with given extension.

    Args:
        file_ext (str): file extension
        universal (bool): Check against universal data files

    Returns:
        (list[str]): list of files
    """
    return _list_app_files(
        pyrevit.PYREVIT_FILE_PREFIX,
        file_ext,
        universal=universal
        )

list_instance_data_files(file_ext)

List all data files associated with current session.

Parameters:

Name	Type	Description	Default
file_ext	str	data files with this extension will be listed only.	required

Returns:

Type	Description
list[str]	list of data files

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def list_instance_data_files(file_ext):
    """List all data files associated with current session.

    Args:
        file_ext (str): data files with this extension will be listed only.

    Returns:
        (list[str]): list of data files

    """
    return _list_app_files(pyrevit.PYREVIT_FILE_PREFIX_STAMPED, file_ext)

find_data_files(file_ext)

Find data files in all data files directories.

Parameters:

Name	Type	Description	Default
file_ext	str	data files with this extension will be listed only	required

Returns:

Type	Description
list[str]	list of files

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def find_data_files(file_ext):
    """Find data files in all data files directories.

    Args:
        file_ext (str): data files with this extension will be listed only

    Returns:
        (list[str]): list of files
    """
    all_datafiles = set()
    for app_folder in _list_app_folders():
        for appdata_file in os.listdir(app_folder):
            file_naming_dict = _match_file(
                op.basename(appdata_file)
            )
            if file_naming_dict \
                    and file_naming_dict['fname'].endswith(file_ext):
                all_datafiles.add(
                    op.join(app_folder, appdata_file)
                    )
    return all_datafiles

find_instance_data_files(file_ext, instance_id)

Find instance data files in all data files directories.

Parameters:

Name	Type	Description	Default
file_ext	str	data files with this extension will be listed only	required
instance_id	int	list data files for this instance id only	required

Returns:

Type	Description
list[str]	list of files

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def find_instance_data_files(file_ext, instance_id):
    """Find instance data files in all data files directories.

    Args:
        file_ext (str): data files with this extension will be listed only
        instance_id (int): list data files for this instance id only

    Returns:
        (list[str]): list of files
    """
    # instance files names are like pyRevit_2018_14422_
    instance_files = set()
    for appdata_file in find_data_files(file_ext):
        file_naming_dict = _match_file(
            op.basename(appdata_file)
        )
        if 'pid' in file_naming_dict:
            try:
                pid = int(file_naming_dict['pid'])
                if instance_id == pid:
                    instance_files.add(appdata_file)
            except Exception:
                pass
    return instance_files

garbage_data_file(file_path)

Mark and remove the given appdata file.

Current implementation removes the file immediately.

Parameters:

Name	Type	Description	Default
file_path	str	path to the target file	required

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def garbage_data_file(file_path):
    """Mark and remove the given appdata file.

    Current implementation removes the file immediately.

    Args:
        file_path (str): path to the target file
    """
    _remove_app_file(file_path)

cleanup_appdata_folder()

Cleanup appdata folder of all temporary appdata files.

Source code in pyrevitlib/pyrevit/coreutils/appdata.py

def cleanup_appdata_folder():
    """Cleanup appdata folder of all temporary appdata files."""
    if EXEC_PARAMS.first_load:
        hostapp_pids = \
            [x.ProcessId
             for x in TargetApps.Revit.RevitController.ListRunningRevits()]
        for appdata_file in os.listdir(pyrevit.PYREVIT_VERSION_APP_DIR):
            file_naming_dict = _match_file(appdata_file)
            if 'pid' in file_naming_dict:
                try:
                    pid = int(file_naming_dict['pid'])
                    if pid not in hostapp_pids:
                        _remove_app_file(
                            op.join(pyrevit.PYREVIT_VERSION_APP_DIR,
                                    appdata_file)
                            )
                except Exception:
                    pass