Skip to content

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 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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 
10
11
12
13
14
15
16
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 
18
19
20
21
22
23
24
25
26
27
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 
30
31
32
33
34
35
36
37
38
39
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 
41
42
43
44
45
46
47
48
49
50
51
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 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
@_validator_rules(
    "Mutually exclusive with `embedded` property.",
    "A valid relative filepath to a directory.",
    "Path is relative to the directory containing the parent `FileBlock`.",
    '"`.`" should be used to indicate the same directory as the parent `FileBlock`.',
    '"`..`" can be used to walk up the directory tree.',
    "Paths to nonexistent directories will be validated, but may raise errors when the parent `FileBlock` attempts to track the file.",
    "Examples for a `FileBlock` at `/home/user/synthesis.fos`:", [
        "\"`.`\" is `/home/user`",
        "\"`..`\" is `/home`",
        "\"`../foo`\" is `/home/foo`",
        "\"`./bar`\" is `/home/user/bar`",
    ]
)
class PathPosix(basePath):
    def __init__(self, path, **kwargs):
        path = path.replace("%20", " ")
        super().__init__(path)
    def serialize(self, *args, **kwargs):
        return self.as_posix().replace(" ", "%20")

__init__ 

__init__(path, **kwargs)
Source code in FoSpy/parsing/validators/filenames.py 
28
29
30
def __init__(self, path, **kwargs):
    path = path.replace("%20", " ")
    super().__init__(path)

serialize 

serialize(*args, **kwargs)
Source code in FoSpy/parsing/validators/filenames.py 
31
32
def serialize(self, *args, **kwargs):
    return self.as_posix().replace(" ", "%20")

_validator_rules 

_validator_rules(*args, inherit_from=None)
Source code in FoSpy/_docs/properties/__init__.py 
756
757
758
759
760
761
762
763
764
765
766
767
768
def _validator_rules(*args, inherit_from=None):
    from ..._docs.properties import val_rules
    def decorator(func, a=args, ih=inherit_from):
        inherited = val_rules.get(ih, [])
        a = list(a)
        a.extend(inherited)
        a = tuple(a)

        if len(a) > 0:
            val_rules[func] = a

        return func
    return decorator

embedded 

embedded(txt, **kwargs)
Source code in FoSpy/parsing/validators/filenames.py 
35
36
37
38
39
40
@_validator_rules(
    "Mutually exclusive with `path` property.",
    "Attachment content as a raw `utf-8` string."
)
def embedded(txt, **kwargs):
    return str(txt)

file_name 

file_name(name, sourceDict={}, **kwargs)

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

Source code in FoSpy/parsing/validators/filenames.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@_validator_rules(
    "A valid filename (no path, no separators, allowed characters only).",
    "Must include a valid extension.",
    "Allowed characters: letters, digits, '`_`', '`-`', '`.`'",
    "Commas are allowed, but may lead to unexpected behavior for some OS or software.",
    "Paths to nonexistent files will be validated, but may raise errors when the parent `FileBlock` attempts to track the file."
)
def file_name(name: str, sourceDict={}, **kwargs) -> str:
    """
    Validate a filename (no path, no separators, allowed characters only).
    """
    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, '_', '-', '.'"
        )

    if len(name.split(".")) < 2 or name.split(".")[1] == "":
        raise ValueError("Filename must have an extension")

    return name