filenames

Full documentation pages are generated for docstring reference only and may contain symbols imported from other modules. Imported symbols are not distinguished from locally defined symbols and will appear in any module that they are imported into. For better information on where symbols should be imported from, review the sourcecode on the github.

FoSpy.parsing.validators.filenames

EXT_RE module-attribute

EXT_RE = re.compile('^[A-Za-z0-9_-]+$')

FILENAME_RE module-attribute

FILENAME_RE = re.compile('^[A-Za-z0-9._\\-,]+$')

_debug module-attribute

_debug = Debug()

basePath module-attribute

basePath = type(Path(''))

Debug

Source code in FoSpy/_debug.py

class Debug:
    def __init__(self):
        self.on = False

        frame = inspect.currentframe().f_back
        self.module_name = frame.f_globals.get("__name__", "<unknown>")
        self.label = f"|(Debug message from {self.module_name})"
        self.label_width = len(self.label)

    def _get_text_width(self, module=None):
        if module:
            label = f"|(Debug message from {module} via {self.module_name})"
            label_width = len(label)
        else:
            label = self.label
            label_width = self.label_width

        text_width = DEBUG_WIDTH - label_width
        return text_width, label, label_width


    def msg(self,msg, module=None):
        if not self.on:
            return

        text_width, label, label_width = self._get_text_width(module)

        wrapped = textwrap.fill(str(msg), width=text_width)

        for line in wrapped.splitlines():
            print(f'{line:<{text_width}}{label:>{label_width}}')

    def pmsg(self,msg,module=None,**kwargs):
        if not self.on:
            return

        text_width, label, label_width = self._get_text_width(module)

        buf = io.StringIO()
        pprint(msg,stream=buf, width=text_width,**kwargs)
        txt = buf.getvalue()
        for line in txt.splitlines():
            print(f'{line:<{text_width}}{label:>{label_width}}')

label instance-attribute

label = f'|(Debug message from {self.module_name})'

label_width instance-attribute

label_width = len(self.label)

module_name instance-attribute

module_name = frame.f_globals.get('__name__', '<unknown>')

on instance-attribute

on = False

__init__

__init__()

Source code in FoSpy/_debug.py

def __init__(self):
    self.on = False

    frame = inspect.currentframe().f_back
    self.module_name = frame.f_globals.get("__name__", "<unknown>")
    self.label = f"|(Debug message from {self.module_name})"
    self.label_width = len(self.label)

_get_text_width

_get_text_width(module=None)

Source code in FoSpy/_debug.py

def _get_text_width(self, module=None):
    if module:
        label = f"|(Debug message from {module} via {self.module_name})"
        label_width = len(label)
    else:
        label = self.label
        label_width = self.label_width

    text_width = DEBUG_WIDTH - label_width
    return text_width, label, label_width

msg

msg(msg, module=None)

Source code in FoSpy/_debug.py

def msg(self,msg, module=None):
    if not self.on:
        return

    text_width, label, label_width = self._get_text_width(module)

    wrapped = textwrap.fill(str(msg), width=text_width)

    for line in wrapped.splitlines():
        print(f'{line:<{text_width}}{label:>{label_width}}')

pmsg

pmsg(msg, module=None, **kwargs)

Source code in FoSpy/_debug.py

def pmsg(self,msg,module=None,**kwargs):
    if not self.on:
        return

    text_width, label, label_width = self._get_text_width(module)

    buf = io.StringIO()
    pprint(msg,stream=buf, width=text_width,**kwargs)
    txt = buf.getvalue()
    for line in txt.splitlines():
        print(f'{line:<{text_width}}{label:>{label_width}}')

PathPosix

Bases: basePath

Source code in FoSpy/parsing/validators/filenames.py

class PathPosix(basePath):
    def serialize(self, *args, **kwargs):
        return self.as_posix()

serialize

serialize(*args, **kwargs)

Source code in FoSpy/parsing/validators/filenames.py

def serialize(self, *args, **kwargs):
    return self.as_posix()

file_extension

file_extension(ext)

Validate a file extension. Accepts either 'png' or '.png' and normalizes to '.png'.

Source code in FoSpy/parsing/validators/filenames.py

def file_extension(ext: str) -> str:
    """
    Validate a file extension.
    Accepts either 'png' or '.png' and normalizes to '.png'.
    """
    if not isinstance(ext, str):
        raise TypeError("Extension must be a string")

    if not ext:
        raise ValueError("Extension cannot be empty")

    # Normalize: strip leading dot if present
    if ext.startswith("."):
        ext = ext[1:]

    # Validate characters
    if not EXT_RE.match(ext):
        raise ValueError(
            "Extension contains invalid characters. Allowed: letters, digits, '_', '-'"
        )

    return f".{ext}"

file_name

file_name(name, sourceDict={})

Validate a filename (no path, no separators, allowed characters only).

Source code in FoSpy/parsing/validators/filenames.py

def file_name(name: str, sourceDict={}) -> str:
    """
    Validate a filename (no path, no separators, allowed characters only).
    """
    #_debug.pmsg(f"Validating {name} with dict:")
    #_debug.pmsg(sourceDict)
    if "extension" in sourceDict:
        ext = file_extension(sourceDict["extension"])
        if name.endswith(ext):
            new_name = name[:-len(ext)]
            _debug.msg(f"Converted filename: {name} into {new_name}")
            name = new_name

    if not isinstance(name, str):
        raise TypeError("Filename must be a string")

    if not name:
        raise ValueError("Filename cannot be empty")

    if "/" in name or "\\" in name:
        raise ValueError("Filename must not contain path separators")

    if "," in name:
        from warnings import warn
        warn(f"Comma in embedded filename: '{name}' may lead to unexpected behavior.",SyntaxWarning)

    if not FILENAME_RE.match(name):
        raise ValueError(
            "Filename contains invalid characters. Allowed: letters, digits, '_', '-', '.'"
        )

    return name