coreutils

Misc Helper functions for pyRevit.

Examples:

from pyrevit import coreutils
coreutils.cleanup_string('some string')

Attributes

DEFAULT_SEPARATOR = ';' module-attribute

UNICODE_NONPRINTABLE_CHARS = ['\u2000', '\u2001', '\u2002', '\u2003', '\u2004', '\u2005', '\u2006', '\u2007', '\u2008', '\u2009', '\u200a', '\u200b', '\u200c', '\u200d', '\u200e', '\u200f', '\u2028', '\u2029', '\u202a', '\u202b', '\u202c', '\u202d', '\u202e', '\u202f', '\u205f', '\u2060', '\u2066', '\u2067', '\u2068', '\u2069', '\u206a', '\u206b', '\u206c\u206d', '\u206e', '\u206f'] module-attribute

SPECIAL_CHARS = {' ': '', '~': '', '!': 'EXCLAM', '@': 'AT', '#': 'SHARP', '$': 'DOLLAR', '%': 'PERCENT', '^': '', '&': 'AND', '*': 'STAR', '+': 'PLUS', ';': '', ':': '', ',': '', '"': '', '{': '', '}': '', '[': '', ']': '', '\\(': '', '\\)': '', '-': 'MINUS', '=': 'EQUALS', '<': '', '>': '', '?': 'QMARK', '.': 'DOT', '_': 'UNDERS', '|': 'VERT', '\\/': '', '\\': ''} module-attribute

Classes

Timer()

Bases: object

Timer class using python native time module.

Examples:

timer = Timer()
timer.get_time()

12

Initialize and Start Timer.

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

def __init__(self):
    """Initialize and Start Timer."""
    self.start = time.time()

Attributes

start = time.time() instance-attribute

Methods:

restart()

Restart Timer.

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

def restart(self):
    """Restart Timer."""
    self.start = time.time()

get_time()

Get Elapsed Time.

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

def get_time(self):
    """Get Elapsed Time."""
    return time.time() - self.start

ScriptFileParser(file_address)

Bases: object

Parse python script to extract variables and docstrings.

Primarily designed to assist pyRevit in determining script configurations but can work for any python script.

Examples:

finder = ScriptFileParser('/path/to/coreutils/__init__.py')
finder.docstring()

"Misc Helper functions for pyRevit."

finder.extract_param('SomeValue', [])

[]

Initialize and read provided python script.

Parameters:

Name	Type	Description	Default
file_address	str	python script file path	required

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

def __init__(self, file_address):
    """Initialize and read provided python script.

    Args:
        file_address (str): python script file path
    """
    self.ast_tree = None
    self.file_addr = file_address
    with codecs.open(file_address, "r", "utf-8") as source_file:
        contents = source_file.read()
        if contents:
            self.ast_tree = ast.parse(contents)

Attributes

ast_tree = None instance-attribute

file_addr = file_address instance-attribute

Methods:

extract_node_value(node)

Manual extraction of values from node.

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

def extract_node_value(self, node):
    """Manual extraction of values from node."""
    if isinstance(node, ast.Assign):
        node_value = node.value
    else:
        node_value = node

    if isinstance(node_value, ast.Num):
        return node_value.n
    elif PY2 and isinstance(node_value, ast.Name):
        return node_value.id
    elif PY3 and isinstance(node_value, ast.NameConstant):
        return node_value.value
    elif isinstance(node_value, ast.Str):
        return node_value.s
    elif isinstance(node_value, ast.List):
        return node_value.elts
    elif isinstance(node_value, ast.Dict):
        return {
            self.extract_node_value(k): self.extract_node_value(v)
            for k, v in zip(node_value.keys, node_value.values)
        }

get_docstring()

Get global docstring.

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

def get_docstring(self):
    """Get global docstring."""
    if self.ast_tree:
        doc_str = ast.get_docstring(self.ast_tree)
        if doc_str:
            return doc_str.decode("utf-8")

extract_param(param_name, default_value=None)

Find variable and extract its value.

Parameters:

Name	Type	Description	Default
param_name	str	variable name	required
default_value	any	default value to be returned if variable does not exist	None

Returns:

Type	Description
Any	value of the variable or None

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

def extract_param(self, param_name, default_value=None):
    """Find variable and extract its value.

    Args:
        param_name (str): variable name
        default_value (any):
            default value to be returned if variable does not exist

    Returns:
        (Any): value of the variable or None
    """
    if self.ast_tree:
        try:
            for node in ast.iter_child_nodes(self.ast_tree):
                if isinstance(node, ast.Assign):
                    for target in node.targets:
                        if hasattr(target, "id") and target.id == param_name:
                            return ast.literal_eval(node.value)
        except Exception as err:
            raise PyRevitException(
                "Error parsing parameter: {} in script file for : {} | {}".format(
                    param_name, self.file_addr, err
                )
            )
    return default_value

FileWatcher(filepath)

Bases: object

Simple file version watcher.

This is a simple utility class to look for changes in a file based on its timestamp.

Examples:

watcher = FileWatcher('/path/to/file.ext')
watcher.has_changed

True

Initialize and read timestamp of provided file.

Parameters:

Name	Type	Description	Default
filepath	str	file path	required

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

def __init__(self, filepath):
    """Initialize and read timestamp of provided file.

    Args:
        filepath (str): file path
    """
    self._cached_stamp = 0
    self._filepath = filepath
    self.update_tstamp()

Attributes

has_changed property

Compare current file timestamp to the cached timestamp.

Methods:

update_tstamp()

Update the cached timestamp for later comparison.

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

def update_tstamp(self):
    """Update the cached timestamp for later comparison."""
    self._cached_stamp = os.stat(self._filepath).st_mtime

SafeDict

Bases: dict

Dictionary that does not fail on any key.

This is a dictionary subclass to help with string formatting with unknown key values.

Examples:

string = '{target} {attr} is {color}.'
safedict = SafeDict({'target': 'Apple',
                     'attr':   'Color'})
string.format(safedict)  # will not fail with missing 'color' key

'Apple Color is {color}.'

Functions:

get_all_subclasses(parent_classes)

Return all subclasses of a python class.

Parameters:

Name	Type	Description	Default
parent_classes	list	list of python classes	required

Returns:

Type	Description
list	list of python subclasses

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

def get_all_subclasses(parent_classes):
    """Return all subclasses of a python class.

    Args:
        parent_classes (list): list of python classes

    Returns:
        (list): list of python subclasses
    """
    sub_classes = []
    # if super-class, get a list of sub-classes.
    # Otherwise use component_class to create objects.
    for parent_class in parent_classes:
        try:
            derived_classes = parent_class.__subclasses__()
            if not derived_classes:
                sub_classes.append(parent_class)
            else:
                sub_classes.extend(derived_classes)
        except AttributeError:
            sub_classes.append(parent_class)
    return sub_classes

get_sub_folders(search_folder)

Get a list of all subfolders directly inside provided folder.

Parameters:

Name	Type	Description	Default
search_folder	str	folder path	required

Returns:

Type	Description
list[str]	list of subfolder names

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

def get_sub_folders(search_folder):
    """Get a list of all subfolders directly inside provided folder.

    Args:
        search_folder (str): folder path

    Returns:
        (list[str]): list of subfolder names
    """
    sub_folders = []
    for sub_folder in os.listdir(search_folder):
        if op.isdir(op.join(search_folder, sub_folder)):
            sub_folders.append(sub_folder)
    return sub_folders

verify_directory(folder)

Check if the folder exists and if not create the folder.

Parameters:

Name	Type	Description	Default
folder	str	path of folder to verify	required

Returns:

Type	Description
str	path of verified folder, equals to provided folder

Raises:

Type	Description
OSError	on folder creation error.

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

def verify_directory(folder):
    """Check if the folder exists and if not create the folder.

    Args:
        folder (str): path of folder to verify

    Returns:
        (str): path of verified folder, equals to provided folder

    Raises:
        OSError: on folder creation error.
    """
    if not op.exists(folder):
        try:
            os.makedirs(folder)
        except OSError as err:
            raise err
    return folder

join_strings(str_list, separator=DEFAULT_SEPARATOR)

Join strings using provided separator.

Parameters:

Name	Type	Description	Default
str_list	list	list of string values	required
separator	str	single separator character, defaults to DEFAULT_SEPARATOR	DEFAULT_SEPARATOR

Returns:

Type	Description
str	joined string

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

def join_strings(str_list, separator=DEFAULT_SEPARATOR):
    """Join strings using provided separator.

    Args:
        str_list (list): list of string values
        separator (str): single separator character,
            defaults to DEFAULT_SEPARATOR

    Returns:
        (str): joined string
    """
    if str_list:
        if any(not isinstance(x, str) for x in str_list):
            str_list = [str(x) for x in str_list]
        return separator.join(str_list)
    return ""

cleanup_string(input_str, skip=None)

Replace special characters in string with another string.

This function was created to help cleanup pyRevit command unique names from any special characters so C# class names can be created based on those unique names.

coreutils.SPECIAL_CHARS is the conversion table for this function.

Parameters:

Name	Type	Description	Default
input_str	str	input string to be cleaned	required
skip	Container[str]	special characters to keep	None

Examples:

src_str = 'TEST@Some*<value>'
cleanup_string(src_str)

"TESTATSomeSTARvalue"

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

def cleanup_string(input_str, skip=None):
    """Replace special characters in string with another string.

    This function was created to help cleanup pyRevit command unique names from
    any special characters so C# class names can be created based on those
    unique names.

    ``coreutils.SPECIAL_CHARS`` is the conversion table for this function.

    Args:
        input_str (str): input string to be cleaned
        skip (Container[str]): special characters to keep

    Examples:
        ```python
        src_str = 'TEST@Some*<value>'
        cleanup_string(src_str)
        ```
        "TESTATSomeSTARvalue"
    """
    # remove spaces and special characters from strings
    for char, repl in SPECIAL_CHARS.items():
        if skip and char in skip:
            continue
        input_str = input_str.replace(char, repl)

    return input_str

get_revit_instance_count()

Return number of open host app instances.

Returns:

Type	Description
int	number of open host app instances.

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

def get_revit_instance_count():
    """Return number of open host app instances.

    Returns:
        (int): number of open host app instances.
    """
    return len(list(framework.Process.GetProcessesByName(HOST_APP.proc_name)))

run_process(proc, cwd='C:')

Run shell process silently.

Parameters:

Name	Type	Description	Default
proc	str	process executive name	required
cwd	str	current working directory	'C:'

Exmaple

run_process('notepad.exe', 'c:/')

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

def run_process(proc, cwd="C:"):
    """Run shell process silently.

    Args:
        proc (str): process executive name
        cwd (str): current working directory

    Exmaple:
        ```python
        run_process('notepad.exe', 'c:/')
        ```
    """
    import subprocess

    return subprocess.Popen(
        proc, stdout=subprocess.PIPE, stderr=subprocess.PIPE, cwd=cwd, shell=True
    )

inspect_calling_scope_local_var(variable_name)

Trace back the stack to find the variable in the caller local stack.

PyRevitLoader defines revit in builtins and window in locals. Thus, modules have access to revit but not to window. This function is used to find window in the caller stack.

Parameters:

Name	Type	Description	Default
variable_name	str	variable name to look up in caller local scope	required

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

def inspect_calling_scope_local_var(variable_name):
    """Trace back the stack to find the variable in the caller local stack.

    PyRevitLoader defines __revit__ in builtins and __window__ in locals.
    Thus, modules have access to __revit__ but not to __window__.
    This function is used to find __window__ in the caller stack.

    Args:
        variable_name (str): variable name to look up in caller local scope
    """
    import inspect

    frame = inspect.stack()[1][0]
    while variable_name not in frame.f_locals:
        frame = frame.f_back
        if frame is None:
            return None
    return frame.f_locals[variable_name]

inspect_calling_scope_global_var(variable_name)

Trace back the stack to find the variable in the caller global stack.

Parameters:

Name	Type	Description	Default
variable_name	str	variable name to look up in caller global scope	required

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

def inspect_calling_scope_global_var(variable_name):
    """Trace back the stack to find the variable in the caller global stack.

    Args:
        variable_name (str): variable name to look up in caller global scope
    """
    import inspect

    frame = inspect.stack()[1][0]
    while variable_name not in frame.f_globals:
        frame = frame.f_back
        if frame is None:
            return None
    return frame.f_locals[variable_name]

make_canonical_name(*args)

Join arguments with dot creating a unique id.

Parameters:

Name	Type	Description	Default
*args	str	Variable length argument list	()

Returns:

Type	Description
str	dot separated unique name

Examples:

make_canonical_name('somename', 'someid', 'txt')

"somename.someid.txt"

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

def make_canonical_name(*args):
    """Join arguments with dot creating a unique id.

    Args:
        *args (str): Variable length argument list

    Returns:
        (str): dot separated unique name

    Examples:
        ```python
        make_canonical_name('somename', 'someid', 'txt')
        ```
        "somename.someid.txt"
    """
    return ".".join(args)

get_canonical_parts(canonical_string)

Splots argument using dot, returning all composing parts.

Parameters:

Name	Type	Description	Default
canonical_string	str	Source string e.g. "Config.SubConfig"	required

Returns:

Type	Description
list[str]	list of composing parts

Examples:

get_canonical_parts("Config.SubConfig")

['Config', 'SubConfig']

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

def get_canonical_parts(canonical_string):
    """Splots argument using dot, returning all composing parts.

    Args:
        canonical_string (str): Source string e.g. "Config.SubConfig"

    Returns:
        (list[str]): list of composing parts

    Examples:
        ```python
        get_canonical_parts("Config.SubConfig")
        ```
        ['Config', 'SubConfig']
    """
    return canonical_string.split(".")

get_file_name(file_path)

Return file basename of the given file.

Parameters:

Name	Type	Description	Default
file_path	str	file path	required

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

def get_file_name(file_path):
    """Return file basename of the given file.

    Args:
        file_path (str): file path
    """
    return op.splitext(op.basename(file_path))[0]

get_str_hash(source_str)

Calculate hash value of given string.

Current implementation uses :func:hashlib.md5 hash function.

Parameters:

Name	Type	Description	Default
source_str	str	source str	required

Returns:

Type	Description
str	hash value as string

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

def get_str_hash(source_str):
    """Calculate hash value of given string.

    Current implementation uses :func:`hashlib.md5` hash function.

    Args:
        source_str (str): source str

    Returns:
        (str): hash value as string
    """
    return hashlib.md5(source_str.encode("utf-8", "ignore")).hexdigest()

calculate_dir_hash(dir_path, dir_filter, file_filter)

Create a unique hash to represent state of directory.

Parameters:

Name	Type	Description	Default
dir_path	str	target directory	required
dir_filter	str	exclude directories matching this regex	required
file_filter	str	exclude files matching this regex	required

Returns:

Type	Description
str	hash value as string

Examples:

calculate_dir_hash(source_path, '\.extension', '\.json')

"1a885a0cae99f53d6088b9f7cee3bf4d"

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

def calculate_dir_hash(dir_path, dir_filter, file_filter):
    r"""Create a unique hash to represent state of directory.

    Args:
        dir_path (str): target directory
        dir_filter (str): exclude directories matching this regex
        file_filter (str): exclude files matching this regex

    Returns:
        (str): hash value as string

    Examples:
        ```python
        calculate_dir_hash(source_path, '\.extension', '\.json')
        ```
        "1a885a0cae99f53d6088b9f7cee3bf4d"
    """
    mtime_sum = 0
    for root, dirs, files in os.walk(dir_path):  # pylint: disable=W0612
        if re.search(dir_filter, op.basename(root), flags=re.IGNORECASE):
            mtime_sum += op.getmtime(root)
            for filename in files:
                if re.search(file_filter, filename, flags=re.IGNORECASE):
                    modtime = op.getmtime(op.join(root, filename))
                    mtime_sum += modtime
    return get_str_hash(safe_strtype(mtime_sum))

prepare_html_str(input_string)

Reformat html string and prepare for pyRevit output window.

pyRevit output window renders html content. But this means that < and > characters in outputs from python (e.g. ) will be treated as html tags. To avoid this, all <> characters that are defining html content need to be replaced with special phrases. pyRevit output later translates these phrases back in to < and >. That is how pyRevit distinquishes between <> printed from python and <> that define html.

Parameters:

Name	Type	Description	Default
input_string	str	input html string	required

Examples:

prepare_html_str('<p>Some text</p>')

"&clt;p&cgt;Some text&clt;/p&cgt;"

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

def prepare_html_str(input_string):
    """Reformat html string and prepare for pyRevit output window.

    pyRevit output window renders html content. But this means that < and >
    characters in outputs from python (e.g. <class at xxx>) will be treated
    as html tags. To avoid this, all <> characters that are defining
    html content need to be replaced with special phrases. pyRevit output
    later translates these phrases back in to < and >. That is how pyRevit
    distinquishes between <> printed from python and <> that define html.

    Args:
        input_string (str): input html string

    Examples:
        ```python
        prepare_html_str('<p>Some text</p>')
        ```
        "&clt;p&cgt;Some text&clt;/p&cgt;"
    """
    return input_string.replace("<", "&clt;").replace(">", "&cgt;")

reverse_html(input_html)

Reformat codified pyRevit output html string back to normal html.

pyRevit output window renders html content. But this means that < and > characters in outputs from python (e.g. ) will be treated as html tags. To avoid this, all <> characters that are defining html content need to be replaced with special phrases. pyRevit output later translates these phrases back in to < and >. That is how pyRevit distinquishes between <> printed from python and <> that define html.

Parameters:

Name	Type	Description	Default
input_html	str	input codified html string	required

Examples:

prepare_html_str('&clt;p&cgt;Some text&clt;/p&cgt;')

"

Some text

"

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

def reverse_html(input_html):
    """Reformat codified pyRevit output html string back to normal html.

    pyRevit output window renders html content. But this means that < and >
    characters in outputs from python (e.g. <class at xxx>) will be treated
    as html tags. To avoid this, all <> characters that are defining
    html content need to be replaced with special phrases. pyRevit output
    later translates these phrases back in to < and >. That is how pyRevit
    distinquishes between <> printed from python and <> that define html.

    Args:
        input_html (str): input codified html string

    Examples:
        ```python
        prepare_html_str('&clt;p&cgt;Some text&clt;/p&cgt;')
        ```
        "<p>Some text</p>"
    """
    return input_html.replace("&clt;", "<").replace("&cgt;", ">")

escape_for_html(input_string)

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

def escape_for_html(input_string):
    return input_string.replace("<", "&lt;").replace(">", "&gt;")

read_url(url_to_open)

Get the url and return response.

Parameters:

Name	Type	Description	Default
url_to_open	str	url to check access for	required

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

def read_url(url_to_open):
    """Get the url and return response.

    Args:
        url_to_open (str): url to check access for
    """
    client = framework.WebClient()
    return client.DownloadString(url_to_open)

touch(fname, times=None)

Update the timestamp on the given file.

Parameters:

Name	Type	Description	Default
fname	str	target file path	required
times	int	number of times to touch the file	None

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

def touch(fname, times=None):
    """Update the timestamp on the given file.

    Args:
        fname (str): target file path
        times (int): number of times to touch the file
    """
    with open(fname, "a"):
        os.utime(fname, times)

read_source_file(source_file_path)

Read text file and return contents.

Parameters:

Name	Type	Description	Default
source_file_path	str	target file path	required

Returns:

Type	Description
str	file contents

Raises:

Type	Description
PyRevitException	on read error

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

def read_source_file(source_file_path):
    """Read text file and return contents.

    Args:
        source_file_path (str): target file path

    Returns:
        (str): file contents

    Raises:
        PyRevitException: on read error
    """
    try:
        with open(source_file_path, "r") as code_file:
            return code_file.read()
    except Exception as read_err:
        raise PyRevitException(
            "Error reading source file: {} | {}".format(source_file_path, read_err)
        )

open_folder_in_explorer(folder_path)

Open given folder in Windows Explorer.

Parameters:

Name	Type	Description	Default
folder_path	str	directory path	required

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

def open_folder_in_explorer(folder_path):
    """Open given folder in Windows Explorer.

    Args:
        folder_path (str): directory path
    """
    import subprocess

    subprocess.Popen(r'explorer /open,"{}"'.format(os.path.normpath(folder_path)))

show_entry_in_explorer(entry_path)

Show given entry in Windows Explorer.

Parameters:

Name	Type	Description	Default
entry_path	str	directory or file path	required

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

def show_entry_in_explorer(entry_path):
    """Show given entry in Windows Explorer.

    Args:
        entry_path (str): directory or file path
    """
    import subprocess

    subprocess.Popen(r'explorer /select,"{}"'.format(os.path.normpath(entry_path)))

fully_remove_dir(dir_path)

Remove directory recursively.

Parameters:

Name	Type	Description	Default
dir_path	str	directory path	required

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

def fully_remove_dir(dir_path):
    """Remove directory recursively.

    Args:
        dir_path (str): directory path
    """

    def del_rw(action, name, exc):  # pylint: disable=W0613
        """Force delete entry."""
        os.chmod(name, stat.S_IWRITE)
        os.remove(name)

    shutil.rmtree(dir_path, onerror=del_rw)

cleanup_filename(file_name, windows_safe=False)

Cleanup file name from special characters.

Parameters:

Name	Type	Description	Default
file_name	str	file name	required
windows_safe	bool	whether to use windows safe characters	False

Returns:

Type	Description
str	cleaned up file name

Examples:

cleanup_filename('Myfile-(3).txt')

"Myfile(3).txt"

cleanup_filename('Perforations 1/8" (New)')

"Perforations 18 (New).txt"

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

def cleanup_filename(file_name, windows_safe=False):
    """Cleanup file name from special characters.

    Args:
        file_name (str): file name
        windows_safe (bool): whether to use windows safe characters

    Returns:
        (str): cleaned up file name

    Examples:
        ```python
        cleanup_filename('Myfile-(3).txt')
        ```
        "Myfile(3).txt"

        ```python
        cleanup_filename('Perforations 1/8" (New)')
        ```
        "Perforations 18 (New).txt"
    """
    if windows_safe:
        return re.sub(r'[\/:*?"<>|]', "", file_name)
    else:
        return re.sub(r'[^\w_.() -#]|["]', "", file_name)

increment_str(input_str, step=1, expand=False)

Incremenet identifier.

Parameters:

Name	Type	Description	Default
input_str	str	identifier e.g. A310a	required
step	int	number of steps to change the identifier	1
expand	bool	removes leading zeroes and duplicate letters	False

Returns:

Type	Description
str	modified identifier

Examples:

increment_str('A319z')

'A320a'

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

def increment_str(input_str, step=1, expand=False):
    """Incremenet identifier.

    Args:
        input_str (str): identifier e.g. A310a
        step (int): number of steps to change the identifier
        expand (bool): removes leading zeroes and duplicate letters

    Returns:
        (str): modified identifier

    Examples:
        ```python
        increment_str('A319z')
        ```
        'A320a'
    """
    return _inc_or_dec_string(input_str, abs(step), refit=expand)

decrement_str(input_str, step=1, shrink=False)

Decrement identifier.

Parameters:

Name	Type	Description	Default
input_str	str	identifier e.g. A310a	required
step	int	number of steps to change the identifier	1
shrink	bool	removes leading zeroes or duplicate letters	False

Returns:

Type	Description
str	modified identifier

Examples:

decrement_str('A310a')

'A309z'

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

def decrement_str(input_str, step=1, shrink=False):
    """Decrement identifier.

    Args:
        input_str (str): identifier e.g. A310a
        step (int): number of steps to change the identifier
        shrink (bool): removes leading zeroes or duplicate letters

    Returns:
        (str): modified identifier

    Examples:
        ```python
        decrement_str('A310a')
        ```
        'A309z'
    """
    return _inc_or_dec_string(input_str, -abs(step), refit=shrink)

extend_counter(input_str, upper=True, use_zero=False)

Add a new level to identifier. e.g. A310 -> A310A.

Parameters:

Name	Type	Description	Default
input_str	str	identifier e.g. A310	required
upper	bool	use UPPERCASE characters for extension	True
use_zero	bool	start from 0 for numeric extension	False

Returns:

Type	Description
str	extended identifier

Examples:

extend_counter('A310')

'A310A'

extend_counter('A310A', use_zero=True)

'A310A0'

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

def extend_counter(input_str, upper=True, use_zero=False):
    """Add a new level to identifier. e.g. A310 -> A310A.

    Args:
        input_str (str): identifier e.g. A310
        upper (bool): use UPPERCASE characters for extension
        use_zero (bool): start from 0 for numeric extension

    Returns:
        (str): extended identifier

    Examples:
        ```python
        extend_counter('A310')
        ```
        'A310A'
        ```python
        extend_counter('A310A', use_zero=True)
        ```
        'A310A0'
    """
    if input_str[-1].isdigit():
        return input_str + ("A" if upper else "a")
    else:
        return input_str + ("0" if use_zero else "1")

filter_null_items(src_list)

Remove None items in the given list.

Parameters:

Name	Type	Description	Default
src_list	list[Any]	list of any items	required

Returns:

Type	Description
list[Any]	cleaned list

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

def filter_null_items(src_list):
    """Remove None items in the given list.

    Args:
        src_list (list[Any]): list of any items

    Returns:
        (list[Any]): cleaned list
    """
    return list(filter(bool, src_list))

reverse_dict(input_dict)

Reverse the key, value pairs.

Parameters:

Name	Type	Description	Default
input_dict	dict	source ordered dict	required

Returns:

Type	Description
defaultdict	reversed dictionary

Examples:

reverse_dict({1: 2, 3: 4})

defaultdict(, {2: [1], 4: [3]})

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

def reverse_dict(input_dict):
    """Reverse the key, value pairs.

    Args:
        input_dict (dict): source ordered dict

    Returns:
        (defaultdict): reversed dictionary

    Examples:
        ```python
        reverse_dict({1: 2, 3: 4})
        ```
        defaultdict(<type 'list'>, {2: [1], 4: [3]})
    """
    output_dict = defaultdict(list)
    for key, value in input_dict.items():
        output_dict[value].append(key)
    return output_dict

timestamp()

Return timestamp for current time.

Returns:

Type	Description
str	timestamp in string format

Examples:

timestamp()

'01003075032506808'

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

def timestamp():
    """Return timestamp for current time.

    Returns:
        (str): timestamp in string format

    Examples:
        ```python
        timestamp()
        ```
        '01003075032506808'
    """
    return datetime.datetime.now().strftime("%m%j%H%M%S%f")

current_time()

Return formatted current time.

Current implementation uses %H:%M:%S to format time.

Returns:

Type	Description
str	formatted current time.

Examples:

current_time()

'07:50:53'

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

def current_time():
    """Return formatted current time.

    Current implementation uses %H:%M:%S to format time.

    Returns:
        (str): formatted current time.

    Examples:
        ```python
        current_time()
        ```
        '07:50:53'
    """
    return datetime.datetime.now().strftime("%H:%M:%S")

current_date()

Return formatted current date.

Current implementation uses %Y-%m-%d to format date.

Returns:

Type	Description
str	formatted current date.

Examples:

current_date()

'2018-01-03'

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

def current_date():
    """Return formatted current date.

    Current implementation uses %Y-%m-%d to format date.

    Returns:
        (str): formatted current date.

    Examples:
        ```python
        current_date()
        ```
        '2018-01-03'
    """
    return datetime.datetime.now().strftime("%Y-%m-%d")

is_blank(input_string)

Check if input string is blank (multiple white spaces is blank).

Parameters:

Name	Type	Description	Default
input_string	str	input string	required

Returns:

Type	Description
bool	True if string is blank

Examples:

is_blank('   ')

True

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

def is_blank(input_string):
    """Check if input string is blank (multiple white spaces is blank).

    Args:
        input_string (str): input string

    Returns:
        (bool): True if string is blank

    Examples:
        ```python
        is_blank('   ')
        ```
        True
    """
    if input_string and input_string.strip():
        return False
    return True

is_url_valid(url_string)

Check if given URL is in valid format.

Parameters:

Name	Type	Description	Default
url_string	str	URL string	required

Returns:

Type	Description
bool	True if URL is in valid format

Examples:

is_url_valid('https://www.google.com')

True

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

def is_url_valid(url_string):
    """Check if given URL is in valid format.

    Args:
        url_string (str): URL string

    Returns:
        (bool): True if URL is in valid format

    Examples:
        ```python
        is_url_valid('https://www.google.com')
        ```
        True
    """
    regex = re.compile(
        r"^(?:http|ftp)s?://"  # http:// or https://
        r"(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+"
        r"(?:[A-Z]{2,6}\.?|[A-Z0-9-]{2,}\.?)|"  # domain...
        r"localhost|"  # localhost...
        r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})"  # ...or ip
        r"(?::\d+)?"  # optional port
        r"(?:/?|[/?]\S+)$",
        re.IGNORECASE,
    )

    return regex.match(url_string)

reformat_string(orig_str, orig_format, new_format)

Reformat a string into a new format.

Extracts information from a string based on a given pattern, and recreates a new string based on the given new pattern.

Parameters:

Name	Type	Description	Default
orig_str	str	Original string to be reformatted	required
orig_format	str	Pattern of the original str (data to be extracted)	required
new_format	str	New pattern (how to recompose the data)	required

Returns:

Type	Description
str	Reformatted string

Examples:

reformat_string('150 - FLOOR/CEILING - WD - 1 HR - FLOOR ASSEMBLY',
                    '{section} - {loc} - {mat} - {rating} - {name}',
                    '{section}:{mat}:{rating} - {name} ({loc})'))

'150:WD:1 HR - FLOOR ASSEMBLY (FLOOR/CEILING)'

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

def reformat_string(orig_str, orig_format, new_format):
    """Reformat a string into a new format.

    Extracts information from a string based on a given pattern,
    and recreates a new string based on the given new pattern.

    Args:
        orig_str (str): Original string to be reformatted
        orig_format (str): Pattern of the original str (data to be extracted)
        new_format (str): New pattern (how to recompose the data)

    Returns:
        (str): Reformatted string

    Examples:
        ```python
        reformat_string('150 - FLOOR/CEILING - WD - 1 HR - FLOOR ASSEMBLY',
                            '{section} - {loc} - {mat} - {rating} - {name}',
                            '{section}:{mat}:{rating} - {name} ({loc})'))
        ```
        '150:WD:1 HR - FLOOR ASSEMBLY (FLOOR/CEILING)'
    """
    # find the tags
    tag_extractor = re.compile("{(.+?)}")
    tags = tag_extractor.findall(orig_format)

    # replace the tags with regex patterns
    # to create a regex pattern that finds values
    tag_replacer = re.compile("{.+?}")
    value_extractor_pattern = tag_replacer.sub("(.+)", orig_format)
    # find all values
    value_extractor = re.compile(value_extractor_pattern)
    match = value_extractor.match(orig_str)
    values = match.groups()

    # create a dictionary of tags and values
    reformat_dict = {}
    for key, value in zip(tags, values):
        reformat_dict[key] = value

    # use dictionary to reformat the string into new
    return new_format.format(**reformat_dict)

get_mapped_drives_dict()

Return a dictionary of currently mapped network drives.

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

def get_mapped_drives_dict():
    """Return a dictionary of currently mapped network drives."""
    searcher = framework.ManagementObjectSearcher(
        "root\\CIMV2", "SELECT * FROM Win32_MappedLogicalDisk"
    )

    return {x["DeviceID"]: x["ProviderName"] for x in searcher.Get()}

dletter_to_unc(dletter_path)

Convert drive letter path into UNC path of that drive.

Parameters:

Name	Type	Description	Default
dletter_path	str	drive letter path	required

Returns:

Type	Description
str	UNC path

Examples:

# assuming J: is mapped to //filestore/server/jdrive
dletter_to_unc('J:/somefile.txt')

'//filestore/server/jdrive/somefile.txt'

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

def dletter_to_unc(dletter_path):
    """Convert drive letter path into UNC path of that drive.

    Args:
        dletter_path (str): drive letter path

    Returns:
        (str): UNC path

    Examples:
        ```python
        # assuming J: is mapped to //filestore/server/jdrive
        dletter_to_unc('J:/somefile.txt')
        ```
        '//filestore/server/jdrive/somefile.txt'
    """
    drives = get_mapped_drives_dict()
    dletter = dletter_path[:2]
    for mapped_drive, server_path in drives.items():
        if dletter.lower() == mapped_drive.lower():
            return dletter_path.replace(dletter, server_path)

unc_to_dletter(unc_path)

Convert UNC path into drive letter path.

Parameters:

Name	Type	Description	Default
unc_path	str	UNC path	required

Returns:

Type	Description
str	drive letter path

Examples:

# assuming J: is mapped to //filestore/server/jdrive
unc_to_dletter('//filestore/server/jdrive/somefile.txt')

'J:/somefile.txt'

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

def unc_to_dletter(unc_path):
    """Convert UNC path into drive letter path.

    Args:
        unc_path (str): UNC path

    Returns:
        (str): drive letter path

    Examples:
        ```python
        # assuming J: is mapped to //filestore/server/jdrive
        unc_to_dletter('//filestore/server/jdrive/somefile.txt')
        ```
        'J:/somefile.txt'
    """
    drives = get_mapped_drives_dict()
    for mapped_drive, server_path in drives.items():
        if server_path in unc_path:
            return unc_path.replace(server_path, mapped_drive)

random_color()

Return a random color channel value (between 0 and 255).

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

def random_color():
    """Return a random color channel value (between 0 and 255)."""
    return random.randint(0, 255)

random_alpha()

Return a random alpha value (between 0 and 1.00).

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

def random_alpha():
    """Return a random alpha value (between 0 and 1.00)."""
    return round(random.random(), 2)

random_hex_color()

Return a random color in hex format.

Examples:

random_hex_color()

'#FF0000'

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

def random_hex_color():
    """Return a random color in hex format.

    Examples:
        ```python
        random_hex_color()
        ```
        '#FF0000'
    """
    return "#%02X%02X%02X" % (random_color(), random_color(), random_color())

random_rgb_color()

Return a random color in rgb format.

Examples:

random_rgb_color()

'rgb(255, 0, 0)'

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

def random_rgb_color():
    """Return a random color in rgb format.

    Examples:
        ```python
        random_rgb_color()
        ```
        'rgb(255, 0, 0)'
    """
    return "rgb(%d, %d, %d)" % (random_color(), random_color(), random_color())

random_rgba_color()

Return a random color in rgba format.

Examples:

random_rgba_color()

'rgba(255, 0, 0, 0.5)'

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

def random_rgba_color():
    """Return a random color in rgba format.

    Examples:
        ```python
        random_rgba_color()
        ```
        'rgba(255, 0, 0, 0.5)'
    """
    return "rgba(%d, %d, %d, %.2f)" % (
        random_color(),
        random_color(),
        random_color(),
        random_alpha(),
    )

distinct_rgb_colors(count, attempts=200)

Generate visually distinct RGB colors.

Uses a greedy max-distance approach: each new color is chosen so its minimum distance to existing colors is maximized.

Parameters:

Name	Type	Description	Default
count	int	number of colors to generate	required
attempts	int	random candidates evaluated per color	200

Returns:

Name	Type	Description
list		list of (r, g, b) tuples

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

def distinct_rgb_colors(count, attempts=200):
    """Generate visually distinct RGB colors.

    Uses a greedy max-distance approach: each new color is chosen so its
    minimum distance to existing colors is maximized.

    Args:
        count (int): number of colors to generate
        attempts (int): random candidates evaluated per color

    Returns:
        list: list of (r, g, b) tuples
    """
    colors = []

    for _ in range(count):
        best_color = None
        best_distance = -1

        for _ in range(attempts):
            candidate = (
                random.randint(0, 255),
                random.randint(0, 255),
                random.randint(0, 255),
            )

            if not colors:
                best_color = candidate
                break

            min_dist = min(_color_distance_sq(candidate, c) for c in colors)

            if min_dist > best_distance:
                best_distance = min_dist
                best_color = candidate

        colors.append(best_color)

    return colors

distinct_hex_colors(count)

Return visually distinct colors in hex format.

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

def distinct_hex_colors(count):
    """Return visually distinct colors in hex format."""
    colors = distinct_rgb_colors(count)
    return ["#%02X%02X%02X" % c for c in colors]

distinct_rgb_strings(count)

Return visually distinct colors in rgb(...) format.

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

def distinct_rgb_strings(count):
    """Return visually distinct colors in rgb(...) format."""
    colors = distinct_rgb_colors(count)
    return ["rgb(%d, %d, %d)" % c for c in colors]

distinct_rgba_strings(count, alpha=None)

Return visually distinct colors in rgba(...) format. If alpha is None, it will get randomized.

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

def distinct_rgba_strings(count, alpha=None):
    """Return visually distinct colors in rgba(...) format. If alpha is None, it will get randomized."""
    colors = distinct_rgb_colors(count)

    result = []
    for r, g, b in colors:
        a = alpha if alpha is not None else random_alpha()
        result.append("rgba(%d, %d, %d, %.2f)" % (r, g, b, a))

    return result

extract_range(formatted_str, max_range=500)

Extract range from formatted string.

String must be formatted as below A103 No range A103-A106 A103 to A106 A103:A106 A103 to A106 A103,A105a A103 and A105a A103;A105a A103 and A105a

Parameters:

Name	Type	Description	Default
formatted_str	str	string specifying range	required
max_range	int	maximum number of items to create.	500

Returns:

Type	Description
list[str]	names in the specified range

Examples:

exract_range('A103:A106')

['A103', 'A104', 'A105', 'A106']

exract_range('S203-S206')

['S203', 'S204', 'S205', 'S206']

exract_range('M00A,M00B')

['M00A', 'M00B']

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

def extract_range(formatted_str, max_range=500):
    """Extract range from formatted string.

    String must be formatted as below
    A103            No range
    A103-A106       A103 to A106
    A103:A106       A103 to A106
    A103,A105a      A103 and A105a
    A103;A105a      A103 and A105a

    Args:
        formatted_str (str): string specifying range
        max_range (int): maximum number of items to create.

    Returns:
        (list[str]): names in the specified range

    Examples:
        ```python
        exract_range('A103:A106')
        ```
        ['A103', 'A104', 'A105', 'A106']
        ```python
        exract_range('S203-S206')
        ```
        ['S203', 'S204', 'S205', 'S206']
        ```python
        exract_range('M00A,M00B')
        ```
        ['M00A', 'M00B']
    """
    for rchar, rchartype in {
        "::": "range",
        "--": "range",
        ",": "list",
        ";": "list",
    }.items():
        if rchar in formatted_str:
            if rchartype == "range" and formatted_str.count(rchar) == 1:
                items = []
                start, end = formatted_str.split(rchar)
                assert len(start) == len(end), (
                    "Range start and end must have same length"
                )
                items.append(start)
                item = increment_str(start, 1)
                safe_counter = 0
                while item != end:
                    items.append(item)
                    item = increment_str(item, 1)
                    safe_counter += 1
                    assert safe_counter < max_range, "Max range reached."
                items.append(end)
                return items
            elif rchartype == "list":
                return [x.strip() for x in formatted_str.split(rchar)]
    return [formatted_str]

check_encoding_bom(filename, bom_bytes=codecs.BOM_UTF8)

Check if given file contains the given BOM bytes at the start.

Parameters:

Name	Type	Description	Default
filename	str	file path	required
bom_bytes	bytes	BOM bytes to check	BOM_UTF8

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

def check_encoding_bom(filename, bom_bytes=codecs.BOM_UTF8):
    """Check if given file contains the given BOM bytes at the start.

    Args:
        filename (str): file path
        bom_bytes (bytes, optional): BOM bytes to check
    """
    with open(filename, "rb") as rtfile:
        return rtfile.read()[: len(bom_bytes)] == bom_bytes

has_nonprintable(input_str)

Check input string for non-printable characters.

Parameters:

Name	Type	Description	Default
input_str	str	input string	required

Returns:

Type	Description
bool	True if contains non-printable characters

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

def has_nonprintable(input_str):
    """Check input string for non-printable characters.

    Args:
        input_str (str): input string

    Returns:
        (bool): True if contains non-printable characters
    """
    return any([x in input_str for x in UNICODE_NONPRINTABLE_CHARS])

get_enum_values(enum_type)

Returns enum values.

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

def get_enum_values(enum_type):
    """Returns enum values."""
    return framework.Enum.GetValues(enum_type)

get_enum_value(enum_type, value_string)

Return enum value matching given value string (case insensitive).

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

def get_enum_value(enum_type, value_string):
    """Return enum value matching given value string (case insensitive)."""
    for ftype in get_enum_values(enum_type):
        if str(ftype).lower() == value_string.lower():
            return ftype

get_enum_none(enum_type)

Returns the None value in given Enum.

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

def get_enum_none(enum_type):
    """Returns the None value in given Enum."""
    for val in get_enum_values(enum_type):
        if str(val) == "None":
            return val

extract_guid(source_str)

Extract GUID number from a string.

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

def extract_guid(source_str):
    """Extract GUID number from a string."""
    guid_match = re.match(
        ".*([0-9A-Fa-f]{8}"
        "[-][0-9A-Fa-f]{4}"
        "[-][0-9A-Fa-f]{4}"
        "[-][0-9A-Fa-f]{4}"
        "[-][0-9A-Fa-f]{12}).*",
        source_str,
    )
    if guid_match:
        return guid_match.groups()[0]

format_hex_rgb(rgb_value)

Formats rgb value as #RGB value string.

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

def format_hex_rgb(rgb_value):
    """Formats rgb value as #RGB value string."""
    if isinstance(rgb_value, str):
        if not rgb_value.startswith("#"):
            return "#%s" % rgb_value
        else:
            return rgb_value
    elif isinstance(rgb_value, int):
        return "#%x" % rgb_value

new_uuid()

Create a new UUID (using dotnet Guid.NewGuid).

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

def new_uuid():
    """Create a new UUID (using dotnet Guid.NewGuid)."""
    # RE: https://github.com/pyrevitlabs/pyRevit/issues/413
    # return uuid.uuid1()
    return str(Guid.NewGuid())

is_box_visible_on_screens(left, top, width, height)

Check if given box is visible on any screen.

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

def is_box_visible_on_screens(left, top, width, height):
    """Check if given box is visible on any screen."""
    bounds = framework.Drawing.Rectangle(
        framework.Convert.ToInt32(0 if math.isnan(left) else left),
        framework.Convert.ToInt32(0 if math.isnan(top) else top),
        framework.Convert.ToInt32(0 if math.isnan(width) else width),
        framework.Convert.ToInt32(0 if math.isnan(height) else height),
    )
    for scr in framework.Forms.Screen.AllScreens:
        if bounds.IntersectsWith(scr.Bounds):
            return True
    return False

fuzzy_search_ratio(target_string, sfilter, regex=False)

Match target string against the filter and return a match ratio.

Parameters:

Name	Type	Description	Default
target_string	str	target string	required
sfilter	str	search term	required
regex	bool	treat the sfilter as regular expression pattern	False

Returns:

Type	Description
int	integer between 0 to 100, with 100 being the exact match

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

def fuzzy_search_ratio(target_string, sfilter, regex=False):
    """Match target string against the filter and return a match ratio.

    Args:
        target_string (str): target string
        sfilter (str): search term
        regex (bool): treat the sfilter as regular expression pattern

    Returns:
        (int): integer between 0 to 100, with 100 being the exact match
    """
    tstring = target_string

    # process regex here. It's a yes no situation (100 or 0)
    if regex:
        try:
            if re.search(sfilter, tstring):
                return 100
        except Exception:
            pass
        return 0

    # 100 for identical matches
    if sfilter == tstring:
        return 100

    # 98 to 99 reserved (2 scores)

    # 97 for identical non-case-sensitive matches
    lower_tstring = tstring.lower()
    lower_sfilter_str = sfilter.lower()
    if lower_sfilter_str == lower_tstring:
        return 97

    # 95  to 96 reserved (2 scores)

    # 93 to 94 for inclusion matches
    if sfilter in tstring:
        return 94
    if lower_sfilter_str in lower_tstring:
        return 93

    # 91  to 92 reserved (2 scores)

    # 80 to 90 for parts matches
    tstring_parts = tstring.split()
    sfilter_parts = sfilter.split()
    if all(x in tstring_parts for x in sfilter_parts):
        return 90

    # 88 to 89 reserved (2 scores)

    lower_tstring_parts = [x.lower() for x in tstring_parts]
    lower_sfilter_parts = [x.lower() for x in sfilter_parts]
    # exclude override
    if any(x[0] == "!" for x in sfilter_parts):
        exclude_indices = [
            lower_sfilter_parts.index(i) for i in lower_sfilter_parts if i[0] == "!"
        ]
        exclude_indices.reverse()
        exclude_list = [lower_sfilter_parts.pop(i) for i in exclude_indices]
        for e in exclude_list:
            # doesn't contain
            if len(e) > 1:
                exclude_string = e[1:]
                if any([exclude_string in part for part in lower_tstring_parts]):
                    return 0
    if all(x in lower_tstring_parts for x in lower_sfilter_parts):
        return 87

    # 85 to 86 reserved (2 scores)

    if all(x in tstring for x in sfilter_parts):
        return 84

    # 82 to 83 reserved (2 scores)

    if all(x in lower_tstring for x in lower_sfilter_parts):
        return 81

    # 80 reserved

    return 0

get_exe_version(exepath)

Extract Product Version value from EXE file.

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

def get_exe_version(exepath):
    """Extract Product Version value from EXE file."""
    version_info = framework.Diagnostics.FileVersionInfo.GetVersionInfo(exepath)
    return version_info.ProductVersion

get_reg_key(key, subkey)

Get value of the given Windows registry key and subkey.

Parameters:

Name	Type	Description	Default
key	PyHKEY	parent registry key	required
subkey	str	subkey path	required

Returns:

Type	Description
PyHKEY	registry key if found, None if not found

Examples:

get_reg_key(wr.HKEY_CURRENT_USER, 'Control Panel/International')

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

def get_reg_key(key, subkey):
    """Get value of the given Windows registry key and subkey.

    Args:
        key (PyHKEY): parent registry key
        subkey (str): subkey path

    Returns:
        (PyHKEY): registry key if found, None if not found

    Examples:
        ```python
        get_reg_key(wr.HKEY_CURRENT_USER, 'Control Panel/International')
        ```
        <PyHKEY at 0x...>
    """
    try:
        return wr.OpenKey(key, subkey, 0, wr.KEY_READ)
    except Exception:
        return None

kill_tasks(task_name)

Kill running tasks matching task_name.

Parameters:

Name	Type	Description	Default
task_name	str	task name	required

Examples:

kill_tasks('Revit.exe')

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

def kill_tasks(task_name):
    """Kill running tasks matching task_name.

    Args:
        task_name (str): task name

    Examples:
        ```python
        kill_tasks('Revit.exe')
        ```
    """
    os.system("taskkill /f /im %s" % task_name)

int2hex_long(number)

Integer to hexadecimal string.

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

def int2hex_long(number):
    """Integer to hexadecimal string."""
    # python 2 fix of addin 'L' to long integers
    return hex(number).replace("L", "")

hex2int_long(hex_string)

Hexadecimal string to Integer.

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

def hex2int_long(hex_string):
    """Hexadecimal string to Integer."""
    # python 2 fix of addin 'L' to long integers
    hex_string.replace("L", "")
    return int(hex_string, 16)

split_words(input_string)

Splits given string by uppercase characters.

Parameters:

Name	Type	Description	Default
input_string	str	input string	required

Returns:

Type	Description
list[str]	split string

Examples:

split_words("UIApplication_ApplicationClosing")

['UIApplication', 'Application', 'Closing']

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

def split_words(input_string):
    """Splits given string by uppercase characters.

    Args:
        input_string (str): input string

    Returns:
        (list[str]): split string

    Examples:
        ```python
        split_words("UIApplication_ApplicationClosing")
        ```
        ['UIApplication', 'Application', 'Closing']
    """
    parts = []
    part = ""
    for c in input_string:
        if c.isalpha():
            if c.isupper() and part and part[-1].islower():
                if part:
                    parts.append(part.strip())
                part = c
            else:
                part += c
    parts.append(part)
    return parts

get_paper_sizes(printer_name=None)

Get paper sizes defined on this system.

Returns:

Type	Description
list[]	list of papersize instances

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

def get_paper_sizes(printer_name=None):
    """Get paper sizes defined on this system.

    Returns:
        (list[]): list of papersize instances
    """
    print_settings = framework.Drawing.Printing.PrinterSettings()
    if printer_name:
        print_settings.PrinterName = printer_name
    return list(print_settings.PaperSizes)

get_integer_length(number)

Return digit length of given number.

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

def get_integer_length(number):
    """Return digit length of given number."""
    return 1 if number == 0 else (math.floor(math.log10(number)) + 1)

get_my_ip()

Return local ip address of this machine.

Note

socket is imported here so that a session that never asks for the address does not pay to import it.

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

def get_my_ip():
    """Return local ip address of this machine.

    Note:
        socket is imported here so that a session that never asks for the
        address does not pay to import it.
    """
    import socket

    return socket.gethostbyname(socket.gethostname())

unique_name(base_name, existing_names)

Return a name that does not collide with any existing name.

Appends " (2)", " (3)", ... until unique.

Parameters:

Name	Type	Description	Default
base_name		preferred name	required
existing_names		pre-fetched set of existing names	required

Returns:

Name	Type	Description
str		a unique view name

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

def unique_name(base_name, existing_names):
    """Return a name that does not collide with any existing name.

    Appends " (2)", " (3)", ... until unique.

    Args:
        base_name: preferred name
        existing_names: pre-fetched set of existing  names

    Returns:
        str: a unique view name
    """
    name = base_name
    counter = 2
    while name in existing_names:
        name = "{0} ({1})".format(base_name, counter)
        counter += 1
    return name