Skip to content

pathtemplate

Folder path templates with placeholders such as {date} and {time}.

Lets a tool turn folder names a user types, like C:\Exports\{model}\{date}_{time}, into one safe Windows path. Every template accepts {date} (yymmdd) and {time} (HHMMSS); callers add their own placeholders as values.

Important

Folder names are cleaned by pyrevit.coreutils.cleanup_filename, so importing this module loads pyrevit and needs a Revit host. The standalone tests stub that import with the real function's source. It must stay source-compatible with IronPython 2.7, IronPython 3 and CPython 3. Paths follow Windows rules (ntpath) on every platform.

Note

Nothing here touches the filesystem; creating the folder is left to the caller. Error messages are plain English; tools that localize their UI should build their own text from the error attributes.

Examples:

from pyrevit.coreutils import pathtemplate
pathtemplate.resolve_folder(
    "C:\\Exports\\{model}", "{date}", values={"model": "Tower"}
)
"C:\Exports\Tower\261017"

Classes

PathTemplateError(template, message)

Bases: Exception

A folder template cannot be turned into a usable path.

Attributes:

Name Type Description
template str

the template as the caller passed it.

Source code in pyrevitlib/pyrevit/coreutils/pathtemplate.py
def __init__(self, template, message):
    super(PathTemplateError, self).__init__(message)
    self.template = template

Attributes

template = template instance-attribute

InvalidTemplateError(template, placeholders)

Bases: PathTemplateError

A template uses an unknown placeholder or has broken braces.

Attributes:

Name Type Description
placeholders list[str]

sorted placeholder names the template could use.

Source code in pyrevitlib/pyrevit/coreutils/pathtemplate.py
def __init__(self, template, placeholders):
    super(InvalidTemplateError, self).__init__(
        template,
        'Folder template "{}" can only use {}.'.format(
            template, ", ".join("{" + name + "}" for name in placeholders)
        ),
    )
    self.placeholders = placeholders

Attributes

placeholders = placeholders instance-attribute
template = template instance-attribute

NotFullPathError(template)

Bases: PathTemplateError

A root folder is relative or drive-relative once filled in.

Source code in pyrevitlib/pyrevit/coreutils/pathtemplate.py
def __init__(self, template):
    super(NotFullPathError, self).__init__(
        template,
        'Folder "{}" must be a full path, such as C:\\Exports '
        "or \\\\server\\share\\Exports.".format(template),
    )

Attributes

template = template instance-attribute

Functions:

fill(template, values=None, now=None)

Fill a template's placeholders and return a safe relative path.

Backslashes or forward slashes typed in the template create nested folders; slashes inside values do not. Characters Windows rejects in folder names, including control characters such as tabs, are removed, trailing dots and spaces are trimmed, and empty or dot-only folder names are dropped.

Parameters:

Name Type Description Default
template str

folder template, such as {model}\{date}.

required
values dict[str, str]

placeholder values; these override {date} and {time} when they use the same name.

None
now datetime

moment {date} and {time} describe; defaults to the current time.

None

Returns:

Type Description
str

relative path, or an empty string for an empty template.

Raises:

Type Description
InvalidTemplateError

the template cannot be filled in.

Source code in pyrevitlib/pyrevit/coreutils/pathtemplate.py
def fill(template, values=None, now=None):
    r"""Fill a template's placeholders and return a safe relative path.

    Backslashes or forward slashes typed in the template create nested
    folders; slashes inside values do not. Characters Windows rejects in
    folder names, including control characters such as tabs, are removed,
    trailing dots and spaces are trimmed, and
    empty or dot-only folder names are dropped.

    Args:
        template (str): folder template, such as ``{model}\{date}``.
        values (dict[str, str]): placeholder values; these override
            ``{date}`` and ``{time}`` when they use the same name.
        now (datetime.datetime): moment ``{date}`` and ``{time}`` describe;
            defaults to the current time.

    Returns:
        (str): relative path, or an empty string for an empty template.

    Raises:
        InvalidTemplateError: the template cannot be filled in.
    """
    return _safe_relative_path(_format(template.strip(), values, now))

resolve_folder(root, subfolder='', values=None, now=None)

Resolve a root folder template and a subfolder template to one path.

The root may also use ~ and %VARS% and must be a full path once filled in. Both templates are filled at the same now.

Parameters:

Name Type Description Default
root str

root folder template, such as C:\Exports\{model}.

required
subfolder str

template for folders under the root; empty means the root itself.

''
values dict[str, str]

placeholder values, as for fill.

None
now datetime

moment {date} and {time} describe; defaults to the current time.

None

Returns:

Type Description
str

full Windows path.

Raises:

Type Description
NotFullPathError

the root is not a full path once filled in.

InvalidTemplateError

either template cannot be filled in.

Source code in pyrevitlib/pyrevit/coreutils/pathtemplate.py
def resolve_folder(root, subfolder="", values=None, now=None):
    r"""Resolve a root folder template and a subfolder template to one path.

    The root may also use ``~`` and ``%VARS%`` and must be a full path once
    filled in. Both templates are filled at the same ``now``.

    Args:
        root (str): root folder template, such as ``C:\Exports\{model}``.
        subfolder (str): template for folders under the root; empty means
            the root itself.
        values (dict[str, str]): placeholder values, as for `fill`.
        now (datetime.datetime): moment ``{date}`` and ``{time}`` describe;
            defaults to the current time.

    Returns:
        (str): full Windows path.

    Raises:
        NotFullPathError: the root is not a full path once filled in.
        InvalidTemplateError: either template cannot be filled in.
    """
    now = now or datetime.datetime.now()
    expanded = ntpath.expandvars(ntpath.expanduser(root.strip()))
    drive, rest = ntpath.splitdrive(_format(expanded, values, now))
    if not _is_full_path(drive, rest):
        raise NotFullPathError(root)
    full_root = drive + "\\" + _safe_relative_path(rest)
    relative_folder = fill(subfolder, values, now)
    if not relative_folder:
        return full_root
    return ntpath.join(full_root, relative_folder)