Skip to content

write

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.write

CHAR_WIDTH module-attribute 

CHAR_WIDTH = 80

SYNTAX module-attribute 

SYNTAX = {
    "block_header": {
        "single": {"open": "[", "close": "]"},
        "list": {"open": "[[", "close": "]]"},
    },
    "nested": {"open": "[", "close": "]"},
    "embedded": {
        "open": "{{{",
        "close": "END FOS EMBED }}}",
        "prefix": "#",
    },
    "key_value": {
        "delimiter": ":",
        "require_value": True,
        "prefix": False,
    },
    "comment": {"prefix": "//", "allow_leading_ws": True},
    "calc_comment": {
        "prefix": "!",
        "allow_leading_ws": True,
    },
    "indent_size": 4,
}

_debug module-attribute 

_debug = Debug()

mk module-attribute 

mk = {
    "comments": "_fos_comments",
    "key_comments": "_fos_key_comments",
    "list_type": "_list_type",
    "routine_paths": "_routine_paths",
}

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}}')

_indent 

_indent(st, ind)
Source code in FoSpy/parsing/format_fos.py 
6
7
def _indent(st:str, ind):
    return f"{' '*ind*SYNTAX["indent_size"]}{st}"

block_list_to_lines 

block_list_to_lines(blocklist, indent=0)
Source code in FoSpy/parsing/write.py 
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def block_list_to_lines(blocklist:list, indent=0):
    lines = []

    if len(blocklist)==0:
        return [""]
    else:
        intersect = set.intersection(*(set(d.keys()) for d in blocklist))
        loop_keys = [k for k in blocklist[0] if k in intersect]

    for meta_key in mk.values():
        if meta_key in loop_keys:
            loop_keys.remove(meta_key)
    typ_key = mk["list_type"]
    typ = blocklist[0][typ_key] if typ_key in blocklist[0] else "explicit"
    for block in blocklist[1:]:
        new_typ = block.get(mk["list_type"], "explicit")
        if new_typ != typ:
            raise ValueError(f"All blocks in a multi-block section must have the same {mk["list_type"]}, either 'explicit' or 'looped'.")

    if typ == "looped":
        key_comments = {}
        for key in loop_keys:
            key_comments[key] = []

        for block in blocklist:
            comments = block.get(mk["key_comments"])
            if not comments: continue
            for key in loop_keys:
                for comment in comments[key]:
                    key_comments[key].append(comment)

        template_keys = []
        for key in loop_keys:
            for comment in key_comments[key]:
                lines.append(format_comment(comment,indent))

            #scan for template fields

            for block in blocklist:
                val = block.get(key, None)
                if val == format_field("template"):
                    template_keys.append(key)
                    key = f"-{key}"
            lines.append(format_loop_key(key,indent))

        # all blocks in a list block must have the same template fields.
        for temp_key in template_keys:
            for block in blocklist:
                block[temp_key] = format_field("template")

        lines.append("")

    for block in blocklist: 
        for line in block_to_lines(block, indent=indent+1 if typ=="looped" else indent, loop_keys=loop_keys):
            lines.append(line)

    return lines

block_to_lines 

block_to_lines(block, indent=0, loop_keys=[])
Source code in FoSpy/parsing/write.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def block_to_lines(block, indent=0, loop_keys=[]):
    block = block.copy()
    typ = block.pop(mk["list_type"], "explicit")
    comments = block.pop(mk["comments"], {})
    key_comments = block.pop(mk["key_comments"], None)
    for remaining_key in mk.values():
        block.pop(remaining_key, None)
    lines = []

    if typ == "explicit":
        for key, val in block.items():
            key_comments = comments.get(key, [])
            if key_comments:
                for comment in key_comments:
                    lines.append(format_comment(comment, indent))
            for line in expand_lists(key, val, indent):
                lines.append(line)
    elif typ == "looped":
        for key in loop_keys:
            val = block.pop(key)
            key_comments = comments.get(key)
            if key_comments:
                for comment in key_comments:
                    lines.append(format_comment(comment, indent))
            for line in expand_lists(key, val, indent, looped=True):
                lines.append(line)
        for key,val in block.items():
            key_comments = comments.get(key)
            if key_comments:
                for comment in key_comments:
                    lines.append(format_comment(comment, indent))
            for line in expand_lists(key, val, indent, looped=False):
                lines.append(line)
    else:
        raise ValueError(f"Unexpected list type: '{typ}'. Expected 'explicit' or 'looped'.")

    lines.append("")

    return lines

empty_nested 

empty_nested(is_list)
Source code in FoSpy/parsing/format_fos.py 
64
65
66
67
68
69
70
71
def empty_nested(is_list):
    spec = SYNTAX["nested"]
    open_br = spec["open"]
    opn = open_br * (2 if is_list else 1)
    close_br = spec["close"]
    close = close_br *(2 if is_list else 1)

    return f"{opn}{close}"

expand_lists 

expand_lists(key, val, indent, looped=False)
Source code in FoSpy/parsing/write.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def expand_lists(key, val, indent, looped=False):
    lines = []
    key = f"-{key}" if val == format_field("template") else key

    if key == "embedded":
        lines.append(format_embed_start(key, indent, looped))
        for line in val:
            lines.append(line.rstrip())
        lines.append(f'{SYNTAX["embedded"]["prefix"]*20} {SYNTAX["embedded"]["close"]}')
    elif isinstance(val, list):
        if len(val) == 0:
            lines.append(format_key_value(key, empty_nested(False), indent, looped))
        else:
            lines.append(format_nested_start(key,len(val)>1, looped,indent))
            for line in block_list_to_lines(val, indent=indent+1):
                lines.append(line)
            lines.pop()
            lines.append(format_nested_end(len(val)>1,indent))
    elif isinstance(val, dict):
        return expand_lists(key, [val], indent, looped)
    elif isinstance(val, str):
        key_val = format_key_value(key, val, indent, looped)
        key_val_width = len(key_val)
        if key_val_width <= CHAR_WIDTH:
            lines.append(key_val)
        else:
            indent_width = len(_indent("", indent))
            lines.append(format_key_value(key, f"{empty_nested(False)[0]};;;", indent, looped))
            for line in textwrap.wrap(val+empty_nested(False)[1:], width=CHAR_WIDTH-indent_width):
                lines.append(_indent(line, indent))

    else:
        lines.append(format_key_value(key, val, indent, looped))

    return lines

format_block_header 

format_block_header(name, list_type)
Source code in FoSpy/parsing/format_fos.py 
 9
10
11
12
13
14
def format_block_header(name: str, list_type: str):
    spec = SYNTAX["block_header"]
    if list_type == "list":
        return f"{spec['list']['open']}{name.capitalize()}{spec['list']['close']}"
    else:
        return f"{spec['single']['open']}{name.capitalize()}{spec['single']['close']}"

format_calc_comment 

format_calc_comment(text)
Source code in FoSpy/parsing/format_fos.py 
45
46
47
48
def format_calc_comment(text:str):
    spec = SYNTAX["calc_comment"]
    prefix = spec["prefix"]
    return f"{prefix} {text}"

format_comment 

format_comment(text, ind=0)
Source code in FoSpy/parsing/format_fos.py 
40
41
42
43
def format_comment(text: str, ind: int = 0):
    spec = SYNTAX["comment"]
    prefix = spec["prefix"]
    return _indent(f"{prefix} {text}", ind)

format_embed_start 

format_embed_start(key, ind=0, looped=False)
Source code in FoSpy/parsing/format_fos.py 
29
30
31
32
33
34
35
36
37
def format_embed_start(key:str, ind=0, looped=False):
    prefix = SYNTAX["key_value"].get("prefix")
    delim = SYNTAX["key_value"]["delimiter"]
    if looped:
        return _indent(SYNTAX["embedded"]["open"], ind)

    if prefix:
        key = f"{prefix}{key}"
    return _indent(f"{key}{delim}{"" if " " in delim else " "}{SYNTAX["embedded"]["open"]}", ind)

format_field 

format_field(label)
Source code in FoSpy/parsing/format_fos.py 
85
86
def format_field(label:str):
    return f"<!{label.upper()}-FIELD>"

format_key_value 

format_key_value(key, val, ind=0, looped=False)
Source code in FoSpy/parsing/format_fos.py 
17
18
19
20
21
22
23
24
25
26
27
def format_key_value(key: str, val: str, ind=0, looped=False):
    spec = SYNTAX["key_value"]
    delim = spec["delimiter"]
    prefix = spec.get("prefix")
    if looped:
        return _indent(val, ind)

    if prefix:
        key = f"{prefix}{key}"

    return _indent(f"{key}{delim}{"" if " " in delim else " "}{val}",ind)

format_loop_key 

format_loop_key(key, ind=0)
Source code in FoSpy/parsing/format_fos.py 
73
74
75
76
77
78
79
80
81
82
83
def format_loop_key(key: str, ind=0):
    spec = SYNTAX["key_value"]
    prefix = spec.get("prefix")
    delim  = spec["delimiter"]

    if prefix:
        # key_
        return _indent(f"{key}{prefix}",ind)
    else:
        # :key
        return _indent(f"{delim}{key}",ind)

format_nested_end 

format_nested_end(is_list, ind=0)
Source code in FoSpy/parsing/format_fos.py 
58
59
60
61
62
def format_nested_end(is_list, ind=0):
    spec = SYNTAX["nested"]
    close_br = spec["close"]
    close = close_br *(2 if is_list else 1)
    return _indent(close, ind)

format_nested_start 

format_nested_start(key, is_list, looped=False, ind=0)
Source code in FoSpy/parsing/format_fos.py 
50
51
52
53
54
55
56
def format_nested_start(key, is_list: bool, looped=False, ind=0):
    spec = SYNTAX["nested"]
    open_br = spec["open"]

    val = open_br * (2 if is_list else 1)

    return format_key_value(key, val, ind, looped)

write_dict_to_file 

write_dict_to_file(blocks, filepath)
Source code in FoSpy/parsing/write.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def write_dict_to_file(blocks, filepath):
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
    blocks = blocks.copy()
    block_comments = blocks.pop(mk["comments"])

    meta = [blocks.pop("metadata",{})]

    with open(filepath, "w") as f:
        for line in block_list_to_lines(meta):
            f.write(f'{line}\n')
        for name, block in blocks.items():
            if isinstance(block,dict):
                block = [block]
            if name in mk.values():
                continue
            if name != "metadata":
                comments = block_comments.get(name,[])
                for comment in comments:
                    f.write(f'{format_comment(comment)}\n')

                f.write(f'{format_block_header(name, "list" if len(block)>1 else "single")}\n')           

            for line in block_list_to_lines(block):
                f.write(f'{line}\n')