files

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.blocks.files

FileBlock

Bases: SingleBlock

Represents a set of blocks loaded from a file.

All public attributes of FileBlock objects are either SingleBlock or ListBlock objects. Attributes without a header at the start of the file are parsed into {"metadata": blockDict} before passing to FileBlock.

Noteable Subclasses:

Synthesis(FileBlock)
TemplateSet(FileBlock)

Source code in FoSpy/blocks/files.py

class FileBlock(SingleBlock):
    """
    Represents a set of blocks loaded from a file.

    All public attributes of `FileBlock` objects are either `SingleBlock` or
    `ListBlock` objects. Attributes without a header at the start of the file
    are parsed into `{"metadata": blockDict}` before passing to `FileBlock`.

    Noteable Subclasses:
    ```
    Synthesis(FileBlock)
    TemplateSet(FileBlock)
    ```
    """

    def __init__(self, blockDict, _sourceFile=None, _dispatched=True):
        """
        Optionally specify _sourceFile before constructing from blockDict using parent `SingleBlock` constructor.
        """
        self._sourceFile = _sourceFile

        self._tempdir = tempfile.TemporaryDirectory()
        self._temppath = Path(self._tempdir.name)
        atexit.register(self.cleanup)

        super().__init__(blockDict, _dispatched=_dispatched)
        self.refresh_attachments()

    def cleanup(self):
        if self._tempdir is not None:
            self._tempdir.cleanup()

    @classmethod
    def fromFile(cls, filepath):
        from .metadata import MetaData
        from ._blockUtils import _unwrap_block
        abspath = os.path.abspath(filepath)
        pathstr = str(abspath)
        try:
            ext = pathstr.lower().split(".")[-1]
        except IndexError:
            raise ValueError(f"Could not determine extension for filepath: {pathstr}")

        ext_map = {
            "fos": dict_from_file,
            "json": lambda fp: json.load(open(fp, "r"))
        }

        if ext not in ext_map:
            raise ValueError(f"Unrecognized file extension '{ext}'. Supported extensions are: {list(ext_map.keys())}")

        blockDict = ext_map[ext](abspath)
        if "metadata" not in blockDict:
            raise ValueError(f"Could not find metadata block in file {abspath}")

        metadata = _unwrap_block(blockDict["metadata"])
        if "fos_type" not in metadata:
            raise ValueError(f"Could not find fos_type in metadata block in file {abspath}")

        typ = metadata.get("fos_type","").lower()
        subcls = MetaData.dispatch.get(typ, ("", cls))[1]

        if not issubclass(subcls, cls):
            raise ValueError(f"Cannot construct {cls.__name__} from file '{abspath}' with incompatible fos_type '{typ}'.")

        return subcls.dispatch_subclass(blockDict, _sourceFile = abspath)

    def save(self, filepath:str=None, json_indent=4, **kwargs):
        """
        Sends a serialized dict to be written to file.

        Args:
            filepath:
                If specified, writes serialized dict to filepath. ks to `self._sourceFile`.
            json_indent:
                Indent to use for json.dump when saving as json
            **kwargs:
                Optional kwargs to pass to saving routine (unique to each file extension)

        Raises:
            ValueError:
                If _sourceFile is not specified (if `FileBlock` was copied from
                another object or constructed directly from a blockDict),
                filepath must be specified.
        """
        from warnings import warn
        saving_as = filepath is not None
        try:
            if not saving_as:
                if self._sourceFile is None:
                    raise ValueError("Synthesis object was constructed without a sourceFile. A save destination must be specified.")
                else:
                    filepath = self._sourceFile
            self._sourceFile = os.path.abspath(filepath)
            self.refresh_attachments()
            pathstr = str(self._sourceFile)
            try:
                ext = pathstr.lower().split(".")[-1]
            except IndexError:
                raise ValueError(f"Could not determine extension for filepath: {pathstr}")

            ext_map = {
                "fos": write_dict_to_file,
                "json": lambda blockDict, fp, **kwargs: json.dump(blockDict, open(fp, "w"), indent=json_indent, **kwargs)
            }

            ext = str(filepath).lower().split(".")[-1]

            if ext not in ext_map:
                raise ValueError(f"Unrecognized file extension '{ext}'. Supported extensions are: {list(ext_map.keys())}")

            blockDict = self.serialize(clean=ext!="fos")

            ext_map[ext](blockDict, self._sourceFile, **kwargs)

        except Exception as e:
            if not saving_as:
                warn(f"Could not save file. Disconnected from source file for safety. Exception: {e}", RuntimeWarning)
                self._sourceFile = None
                return e
            else:
                raise e
        return True

    def check_attachments(self):
        pass

    def matches_file(self):
        reloaded = self.fromFile(self._sourceFile)

        return self.__eq__(reloaded, suppress_routine_paths=True)

_sourceFile instance-attribute

_sourceFile = _sourceFile

_tempdir instance-attribute

_tempdir = tempfile.TemporaryDirectory()

_temppath instance-attribute

_temppath = Path(self._tempdir.name)

__init__

__init__(blockDict, _sourceFile=None, _dispatched=True)

Optionally specify _sourceFile before constructing from blockDict using parent SingleBlock constructor.

Source code in FoSpy/blocks/files.py

def __init__(self, blockDict, _sourceFile=None, _dispatched=True):
    """
    Optionally specify _sourceFile before constructing from blockDict using parent `SingleBlock` constructor.
    """
    self._sourceFile = _sourceFile

    self._tempdir = tempfile.TemporaryDirectory()
    self._temppath = Path(self._tempdir.name)
    atexit.register(self.cleanup)

    super().__init__(blockDict, _dispatched=_dispatched)
    self.refresh_attachments()

check_attachments

check_attachments()

Source code in FoSpy/blocks/files.py

def check_attachments(self):
    pass

cleanup

cleanup()

Source code in FoSpy/blocks/files.py

def cleanup(self):
    if self._tempdir is not None:
        self._tempdir.cleanup()

fromFile classmethod

fromFile(filepath)

Source code in FoSpy/blocks/files.py

@classmethod
def fromFile(cls, filepath):
    from .metadata import MetaData
    from ._blockUtils import _unwrap_block
    abspath = os.path.abspath(filepath)
    pathstr = str(abspath)
    try:
        ext = pathstr.lower().split(".")[-1]
    except IndexError:
        raise ValueError(f"Could not determine extension for filepath: {pathstr}")

    ext_map = {
        "fos": dict_from_file,
        "json": lambda fp: json.load(open(fp, "r"))
    }

    if ext not in ext_map:
        raise ValueError(f"Unrecognized file extension '{ext}'. Supported extensions are: {list(ext_map.keys())}")

    blockDict = ext_map[ext](abspath)
    if "metadata" not in blockDict:
        raise ValueError(f"Could not find metadata block in file {abspath}")

    metadata = _unwrap_block(blockDict["metadata"])
    if "fos_type" not in metadata:
        raise ValueError(f"Could not find fos_type in metadata block in file {abspath}")

    typ = metadata.get("fos_type","").lower()
    subcls = MetaData.dispatch.get(typ, ("", cls))[1]

    if not issubclass(subcls, cls):
        raise ValueError(f"Cannot construct {cls.__name__} from file '{abspath}' with incompatible fos_type '{typ}'.")

    return subcls.dispatch_subclass(blockDict, _sourceFile = abspath)

matches_file

matches_file()

Source code in FoSpy/blocks/files.py

def matches_file(self):
    reloaded = self.fromFile(self._sourceFile)

    return self.__eq__(reloaded, suppress_routine_paths=True)

save

save(filepath=None, json_indent=4, **kwargs)

Sends a serialized dict to be written to file.

Parameters:

Name	Type	Description	Default
filepath	str	If specified, writes serialized dict to filepath. ks to self._sourceFile.	None
json_indent		Indent to use for json.dump when saving as json	4
**kwargs		Optional kwargs to pass to saving routine (unique to each file extension)	{}

Raises:

Type	Description
ValueError	If _sourceFile is not specified (if FileBlock was copied from another object or constructed directly from a blockDict), filepath must be specified.

Source code in FoSpy/blocks/files.py

def save(self, filepath:str=None, json_indent=4, **kwargs):
    """
    Sends a serialized dict to be written to file.

    Args:
        filepath:
            If specified, writes serialized dict to filepath. ks to `self._sourceFile`.
        json_indent:
            Indent to use for json.dump when saving as json
        **kwargs:
            Optional kwargs to pass to saving routine (unique to each file extension)

    Raises:
        ValueError:
            If _sourceFile is not specified (if `FileBlock` was copied from
            another object or constructed directly from a blockDict),
            filepath must be specified.
    """
    from warnings import warn
    saving_as = filepath is not None
    try:
        if not saving_as:
            if self._sourceFile is None:
                raise ValueError("Synthesis object was constructed without a sourceFile. A save destination must be specified.")
            else:
                filepath = self._sourceFile
        self._sourceFile = os.path.abspath(filepath)
        self.refresh_attachments()
        pathstr = str(self._sourceFile)
        try:
            ext = pathstr.lower().split(".")[-1]
        except IndexError:
            raise ValueError(f"Could not determine extension for filepath: {pathstr}")

        ext_map = {
            "fos": write_dict_to_file,
            "json": lambda blockDict, fp, **kwargs: json.dump(blockDict, open(fp, "w"), indent=json_indent, **kwargs)
        }

        ext = str(filepath).lower().split(".")[-1]

        if ext not in ext_map:
            raise ValueError(f"Unrecognized file extension '{ext}'. Supported extensions are: {list(ext_map.keys())}")

        blockDict = self.serialize(clean=ext!="fos")

        ext_map[ext](blockDict, self._sourceFile, **kwargs)

    except Exception as e:
        if not saving_as:
            warn(f"Could not save file. Disconnected from source file for safety. Exception: {e}", RuntimeWarning)
            self._sourceFile = None
            return e
        else:
            raise e
    return True

SingleBlock

Bases: Block

Represents a single block of key:value pairs parsed from a FOS file.

Subclasses are mapped to expected keys and validation routines in ..parsing.validation. Expected values are validated and assigned to public attributes. Unexpected values are assigned to attributes of self.ext for safety, but can still be accessed as an attribute of the SingleBlock object if not overwritten

Notable Subclasses: FileBlock(SingleBlock) Synthesis(FileBlock) Reaction(SingleBlock) Material(SingleBlock) TemplateBlock(SingleBlock)

Source code in FoSpy/blocks/blocks.py

class SingleBlock(Block):
    """
    Represents a single block of key:value pairs parsed from a FOS file.

    Subclasses are mapped to expected keys and validation routines in
    [`..parsing.validation`][FoSpy.parsing.validation]. Expected values are validated and assigned to
    public attributes. Unexpected values are assigned to attributes of
    `self.ext` for safety, but can still be accessed as an attribute of the
    SingleBlock object if not overwritten

    Notable Subclasses:
    [`FileBlock(SingleBlock)`][FoSpy.blocks.files.FileBlock]
    [`Synthesis(FileBlock)`][FoSpy.blocks.synthesis.Synthesis]
    [`Reaction(SingleBlock)`][FoSpy.blocks.metadata.Reaction]
    [`Material(SingleBlock)`][FoSpy.blocks.materials.Material]
    [`TemplateBlock(SingleBlock)`][FoSpy.blocks.template.TemplateBlock]
    """
    dispatch = {}
    _aliases = None

    @classmethod
    def TemplateClass(cls,*args:str):
        """
        Create a template for a subclass of `SingleBlock`.

        Generates a hybridized subclass of the current block class and
        [`TemplateBlock`][FoSpy.blocks.template.TemplateBlock]. Template
        subclasses override original expected validators with either a
        [`TemplateField`][FoSpy.blocks.template.TemplateField],
        [`TemplateBlock`][FoSpy.blocks.template.TemplateBlock], or
        [`TemplateList`][FoSpy.blocks.template.TemplateList] depending on the
        type of the original validator.

        Args:
            *args: A list of properties to override as template types.
        """
        from .template import TemplateBlock, TemplateField, TemplateList
        from ..parsing.validation import required_keys, optional_keys
        if issubclass(cls, TemplateBlock):
            class ExtendedTemplate(cls):
                pass
            SubTemplate = ExtendedTemplate
        else:
            class NewTemplate(TemplateBlock, cls):
                dispatch = {}
                def __init__(self, blockDict, _dispatched=False):
                    super().__init__(blockDict, _dispatched=_dispatched)
                    self._full_class = cls
            SubTemplate = NewTemplate
        required_keys[SubTemplate] = {}
        optional_keys[SubTemplate] = {}
        required_validators = cls.build_req_validators()
        all_validators = cls.build_validators()
        for key in args:
            req_val = required_validators.get(key,None)
            val = all_validators.get(key,None) or req_val

            if isinstance(val,type) and issubclass(val,SingleBlock):
                all_fields = list(val.build_req_validators().keys())
                field = val.TemplateClass(*all_fields)

            elif isinstance(val,type) and issubclass(val, ListBlock):
                field = TemplateList.Simple(val._reqCls)
            else:
                field = TemplateField

            if req_val:
                required_keys[SubTemplate][key] = field
            else:
                optional_keys[SubTemplate][key] = field

        finished_reqs = required_keys[SubTemplate]
        finished_opts = optional_keys[SubTemplate]
        for typ, sub in cls.dispatch.items():
            dispatched_sub = sub.TemplateClass(*args)
            SubTemplate.dispatch[typ] = dispatched_sub

            required_keys[dispatched_sub] = finished_reqs
            optional_keys[dispatched_sub] = finished_opts

        SubTemplate.__name__ = f"{cls.__name__}Template"
        SubTemplate.__qualname__ = f"{cls.__name__}.Template"
        SubTemplate.__module__ = cls.__module__

        return SubTemplate

    @classmethod
    def reflex(cls, serialize=True, **kwargs:dict):
        """
        Generate a flexible template for the current class.

        Flexibly generates a template for the current class where any required
        properties missing from `kwargs` are automatically converted to template
        types (See
        [`FlexTemplate`][FoSpy.blocks.template.FlexTemplate]).
        Returns an instance of the flexible template constructed from `kwargs`,
        or a serial dictionary of that instance.

        Args:
            serialize (bool):
                Whether to return the serialized dictionary of the reflexed
                template, or the object itself.
            **kwargs (str): Known properties to pass to the template constructor.
        """
        from .template import FlexTemplate
        class Flex(FlexTemplate, cls):
            _baseReq = cls

        kwargs.setdefault("template_name", f"Reflexed {cls.__name__}")

        empty = Flex.dispatch_subclass(kwargs)
        if serialize:
            return empty.serialize()
        return empty

    @classmethod
    def dispatch_subclass(cls, blockDict:dict, **kwargs:any):
        """
        Recommended dispatcher to allow subclass delegation when constructing.

        Overridden in some subclasses, usually to assign subclass based on the
        value of one or more properties.

        Default behavior passes `blockDict` and `**kwargs` to `__init__`
        constructor.
        """
        # k: construct normally.
        return cls(blockDict,_dispatched=True, **kwargs)

    @classmethod
    def build_req_validators(cls):
        """
        Builds required keys and validators mapped to subclass.

        Walks all parent classes and builds a map of all keys that are required
        during `__init__`, and their respective validation routines. Subclasses
        are mapped to expected keys and validations in
        [`parsing.validation`][FoSpy.parsing.validation]. Subclass validations
        override parent classes when applicable.

        Returns:
            merged (dict):
                Maps required keys to validation routines. Routines may be
                a class constructor or a func taking one arg.
        Example:
            ``` 
            >>> SingleBlock.build_req_validators()
            {
                "name": str,
                "type": str,
                "formula": ChemFormula, # class constructor
                "supplier": str,
                "cas": str,
                "form": str,
                "env": str,
                "ratio": validators.material.ratio # validator function
            }
            ```
        """
        from ..parsing.validation import required_keys
        merged = {}
        for base in reversed(cls.__mro__):
            base_reqs = required_keys.get(base,{})
            for key, validator in base_reqs.items():
                # allow subclasses to remove parent requirements.
                if validator is False:
                    merged.pop(key, None)
                else:
                    merged[key] = validator
        return merged

    @classmethod
    def build_validators(cls):
        """
        Builds expected keys and validators mapped to subclass.

        Walks all parent classes and builds a map of all keys that are expected
        (required or optional), and their respective validation routines.
        Subclasses are mapped to keys and validations in
        [`parsing.validation`][FoSpy.parsing.validation]. Subclass validations
        override parent classes when applicable.

        See
        [`build_req_validators`][FoSpy.blocks.blocks.SingleBlock.build_req_validators]
        """
        from ..parsing.validation import required_keys, optional_keys
        merged = {}
        for base in reversed(cls.__mro__):
            for key_set in (required_keys, optional_keys):
                base_reqs = key_set.get(base,{})
                for key, validator in base_reqs.items():
                    # allow subclasses to remove parent requirements.
                    if validator is False:
                        merged.pop(key, None)
                    else:
                        merged[key] = validator

        return merged

    def get_validators(self):
        """
        Overrides class validators with any renamed properties.

        Similar to class method:
        [`build_validators`][FoSpy.blocks.blocks.SingleBlock.build_validators],
        but uses
        [`_rename_validators`][FoSpy.blocks.blocks.SingleBlock._rename_validators]
        to align any renamed properties with their original validators. Also
        adds any optional key overrides added by key$alias syntax.

        Returns:
            vals (dict): maps expected keys to validation routines.
        """
        vals = self._rename_validators(self.build_validators())
        if hasattr(self, "_key_overrides"):
            for key, val in self._key_overrides.items():
                vals[key] = val
        return vals

    def get_req_validators(self):
        """
        Overrides class validators with any renamed properties.

        Similar to class method:
        [`build_req_validators`][FoSpy.blocks.blocks.SingleBlock.build_req_validators],
        but uses
        [`_rename_validators`][FoSpy.blocks.blocks.SingleBlock._rename_validators]
        to align any renamed properties with their original validators.
        """
        return self._rename_validators(self.build_req_validators())

    def __init__(self, blockDict:dict, _dispatched=False):
        """
        Constructs a SingleBlock object from a dictionary.

        Avoid using this constructor for unfamiliar block classes, it may bypass
        subclass delegation. Use
        [`dispatch_subclass`][FoSpy.blocks.blocks.SingleBlock.dispatch_subclass]
        instead.

        SingleBlocks are constructed recursively from an arbitrarily nested
        dictionary. All keys identified by `SingleBlock.build_req_validators()`
        must be present at the top level. Required keys at nested levels are
        handled by the recursed constructor.

        Args:
            blockDict:
                An arbitrarily nested dictionary mapping attribute names to
                values. 

                Unexpected attributes will be assigned under `self.ext` instead
                (see `SingleBlock.__setattr__`). 

                It is possible to pass a blockDict already containing objects,
                but validation routines will fail if objects are not the correct
                type. Best practice is to serialize all nested objects into
                lists, dicts, and strings to allow full type coersion.
            _dispatched:
                Flag passed by
                [`dispatch_subclass`][FoSpy.blocks.blocks.SingleBlock.dispatch_subclass]
                to signal that the safer construction method was used. Warning
                issued for False


        Raises:
            ValueError:
                A key required by `SingleBlock.build_req_validators()` is not
                present.
            TypeError:
                The value passed as `blockDict` was not able to be unwrapped
                into a dict, either by serialization of a passed `Block` object
                or by list index.

        """

        if not _dispatched:
            from warnings import warn
            warn(f"You should avoid directly constructing a {type(self).__name__} object. Use the dispatch_subclass() "
                 "method instead to allow for subclass delegation when constructing.", stacklevel=2)

        self.track_attachments(**cfg.track_attachments())

        from ..parsing.validation import aliases as als
        new_als = als.copy()
        new_als.update(self._aliases or {})
        self._aliases = new_als
        self._reserved = ['ext']

        blockDict = _unwrap_block(blockDict)
        self._sourceDict = blockDict.copy()

        if not isinstance(blockDict, dict):
            raise TypeError("A SingleBlock must be constructed from either a dictionary or another SingleBlock. "
                            "The passed source can optionally be wrapped in lists of length == 1.")

        blockDict = blockDict.copy()

        rename = blockDict.pop("rename",None)
        if rename:
            setattr(self, "rename", _unwrap_block(rename))

        req = self.get_req_validators()
        req.pop("ext",None)
        for key, validator in req.items():
            if key not in blockDict:
                from .template import TemplateBlock, TemplateList, TemplateField, FlexTemplate
                is_type = isinstance(validator, type)
                if is_type and issubclass(validator, TemplateField):
                    blockDict[key] = ""
                elif is_type and issubclass(validator, FlexTemplate):
                    blockDict[key] = {"template_name": f"Empty {self._baseReq.__name__} Template"}
                elif is_type and issubclass(validator, TemplateBlock):
                    blockDict[key] = validator.reflex()
                elif is_type and issubclass(validator, TemplateList):
                    blockDict[key] = []
                else:
                    raise ValueError(f"Missing required property: '{key}' for '{type(self).__name__}' object.")

        self._meta = SubContainer()
        self._calc_comments = {}
        self._calc_routines = []
        self._key_overrides = {}

        for attr, key in mk.items():
            try:
                k = md[key].copy()
            except:
                k = md[key]
            setattr(self._meta, attr, blockDict.pop(key,k))

        self._key_order = []
        self.ext = SubContainer()

        for key, val in blockDict.items():
            self._key_order.append(key)
            setattr(self, key, val)



    def __setattr__(self, name:str, value):
        """
        Assign an attribute with validation and controlled namespace behavior.

        Contract:
            `SingleBlock` enforces type correctness and validator execution for
            all public attributes defined for its subclass.

            Required types and validators are mapped by subclass in
            [`parsing.validation`][FoSpy.parsing.validation]

            Comment-mutating methods are attached to every object assigned to an
            attribute. (See
            [`add_comments`][FoSpy.blocks.blocks._add_comments_to_parent])

        Rules:
            1. Private attributes (`_`-prefixed) bypass validation.
            2. Attributes with registered validators are processed through the
            validator before assignment.
            3. Attributes with required types are coerced by calling the type
            constructor when necessary.
            4. Unrecognized attributes can be assigned to a validator mapped to
            an alias in [`parsing.validation`][FoSpy.parsing.validation], using
            the syntax `name="name$alias"`.
            5. Unrecognized attribute names are redirected as attributes of
            `self.ext`.

        Raises:
            ValueError:
                - If a required `SingleBlock` is passed as a list with length > 1.
                - If a block alias cannot be parsed from a key containing `$`.
                - If a block alias is unrecognized.
                - If a template field is found when constructing a non-template
                  subclass.
        """
        from ..parsing.format_fos import format_field
        from .template import TemplateField, TemplateBlock

        from inspect import signature as sign

        if name.startswith("_") or name in self._reserved:
            return super().__setattr__(name, value)

        validators = self.get_validators()

        if "$" in name:
            try:
                name, alias = name.split("$")
            except:
                raise ValueError(f"Unable to parse a block alias from key: '{name}'.")

            try:
                val = self._aliases[alias]
            except KeyError:
                raise ValueError(f"Unrecognized block alias: '{alias}'")

            if name in validators and val != validators[name]:
                raise ValueError(f"Key: '{name}' is already reserved for '{validators[name].__name__}' validator, "
                                 f"it cannot be overwritten to '{val.__name__}'.")
            if name not in validators:
                validators[name] = val
                self._key_overrides[name] = val

        if name in validators:
            validator = validators[name]
            val_kwargs = {}
            for kw, arg in (("sourceDict", self._sourceDict),("cls", type(self))):
                try:
                    if kw in sign(validator).parameters:
                        val_kwargs[kw] = arg
                except:
                    pass


            if isinstance(validator, type):
                if issubclass(validator, SingleBlock):
                    if not isinstance(value, validator):
                        validator = validator.dispatch_subclass
                        if isinstance(value, list):
                            if len(value) > 1:
                                raise ValueError(f"Block '{name}' must be a single block. It can only be constructed from a list of length 1.")
                            value = value[0]
                        elif isinstance(value,SingleBlock):
                            value = value.serialize(keepListType=True)

                elif issubclass(validator, ListBlock):
                    try: 
                        value = [block.serialize(keepListType=True) for block in value]
                    except Exception as e:
                        if isinstance(value, ListBlock):
                            value = value.serialize()
                elif value == format_field("template") and not issubclass(validator, TemplateField):
                    if isinstance(self,TemplateBlock):
                        validator = TemplateField
                    else:       
                        raise ValueError(f"You cannot create a '{type(self).__name__}' object with an un-filled '{name}' template field.")
                if isinstance(validator, type) and isinstance(value, validator):
                    return self._assign_and_inject(name, value)




            return self._assign_and_inject(name,
                                            validator(value,**val_kwargs)
                                            if val_kwargs != {}
                                            else validator(value))
        else:
            return self._assign_and_inject(name, value, extended=True)

    def __getattr__(self, name:str):
        """
        Check both `self` and `self.ext` for attribute before returning.

        A matching attribute of `self` will be returned first, but if `self` has
        no matching attribute, a matching attribute of `self.ext` can be
        returned instead.
        """
        try:
            if name != 'ext':
                return getattr(self.ext, name)
            raise AttributeError()
        except AttributeError:
            raise AttributeError(
                f"{type(self).__name__} object "
                f"has no attribute {name!r}."
            )

    def __eq__(self, other, suppress_routine_paths:bool=False):
        """
        Check equality of two `SingleBlock` objects.

        Equality is checked by a deep difference of their
        [serialized][FoSpy.blocks.blocks.SingleBlock.serialize] dictionaries.

        Args:
            suppress_routine_paths:
                Optional flag to still return true if the only differences found
                are in [calculation
                routine][FoSpy.blocks.blocks.SingleBlock.add_calc_routine]
                metadata. Calculation routines are for user information only and
                may not be relevant for equality.
        """
        from .._debug import deep_diff as dd, _debug as db
        try:
            db.msg("Serializing Blocks to check equality:", module = "SingleBlock.__eq__()")
            diffs = dd(self.serialize(), other.serialize(), suppress_routine_paths=suppress_routine_paths)
            passed = len(diffs) == 0
            if not passed:
                db.pmsg(diffs,module = "SingleBlock.__eq__()")
            return passed
        except Exception as e:
            db.msg(f"Equality failed by exception: {e}",module = "SingleBlock.__eq__()")
            return False

    def __hash__(self):
        return id(self)

    def _rename_validators(self, validators:dict):
        """
        Realigns any [renamed][FoSpy.blocks.blocks.SingleBlock.rename_block]
        attributes with their expected validator.

        Args:
            validators:
                A dictionary mapping attribute names to validators, returned by
                either
                [`build_validators`][FoSpy.blocks.blocks.SingleBlock.build_validators]
                or
                [`build_req_validators`][FoSpy.blocks.blocks.SingleBlock.build_req_validators]
        """
        if hasattr(self, "rename"):
            for name, rename in self.rename.serialize(shallow=True).items():
                if name in validators and rename not in validators:
                    val = validators.pop(name)
                    validators[rename] = val
        return validators

    def _assign_and_inject(self, name, value, extended=False):
        """
        Attaches attributes and methods to any value before assigning it as an
        attribute of `self` or `self.ext`.

        Attributes Attached to Object:
            `_parent_block`: refers to `self`

        Methods Attached to Object:
            [`add_comments_to_parent`][FoSpy.blocks.blocks._add_comments_to_parent]
            [`clear_comments_from_parent`][FoSpy.blocks.blocks._clear_comments_from_parent]
        """
        from .attachments import Attachment

        if name == 'ext':
            return super().__setattr__('ext', value)
        if not hasattr(value, "__dict__"):
            value = SimpleWrapper(value)

        if extended:
            setattr(self.ext, name, value)
        else:
            super().__setattr__(name, value)

        attr_obj = getattr(self.ext if extended else self, name)

        setattr(attr_obj, "_parent_block", self)

        if isinstance(attr_obj, Attachment):
            attr_obj._get_filepath()
        elif hasattr(attr_obj, "refresh_attachments"):
            attr_obj.refresh_attachments()

        methods = ((_add_comments_to_parent(name), "add_comments"),
                (_clear_comments_from_parent(name), "clear_comments"))

        attr_obj._reserved = ['ext'] if not hasattr(attr_obj,"_reserved") else attr_obj._reserved
        for method, method_name in methods:
            attr_obj._reserved.append(method_name)
            bound = method.__get__(attr_obj, type(attr_obj))
            setattr(attr_obj, method_name, bound)


    def add_comments(self, *comments):
        """
        Default behavior to be overwritten when attached to a parent block.

        If a `SingleBlock` is stored as an attribute of another `SingleBlock`,
        this method will be overwritten by the parent's `__setattr__`.
        """
        keys = list(self.get_req_validators())

        keys = [k for k in keys if k != "metadata"]
        fallback = [k for k in self._key_order if k != "metadata"]
        if not (keys or fallback):
            raise ValueError("This object has not been correctly attached to a parent block "
                             "and could not identify a required key to attach to.")

        first = keys[0] if keys else fallback[0]

        self._meta.comments.setdefault(first, [])
        for comment in comments:
            self._meta.comments[first].append(comment)

    def add_block(self, block_name:str, type_alias:str, value=[]):
        """
        Adds an unexpected attribute with a validator mapped by `type_alias`.
        Unexpected attributes not requiring a validator can be set directly
        without using this method.

        Args:
            block_name: new unexpected attribute name
            type_alias:
                Alias mapped to the desired validator in
                [`parsing.validation.aliases`][FoSpy.parsing.validation.aliases].
                For more information on how aliases are used, see
                [`__setattr__`][FoSpy.blocks.blocks.SingleBlock.__setattr__].
        """
        if hasattr(self,block_name):
            raise ValueError(f"This object already has attribute: '{block_name}'.")
        return setattr(self, f"{block_name}${type_alias}", value)

    def serialize(self, keepListType:bool=False, shallow:bool=False, clean:bool=False):
        """
        Return a recursively serialized `dict` representation of `self`.

        Fully serialized `SingleBlock`s are a single dict that can be passed to
        another constructor or emitted into lines for a FOS file. Serialized
        values at any nest level are either dicts, lists, or strings to allow
        full type-coersion when reconstructing or simplified emission when
        writing files.

        Serialized dict is deep copied to prevent object mutation.

        Args:
            keepListType:
                When True, maintains its current FOS printing mode (looped keys
                or explicit key:value lines), instead of explicit default

            shallow:
                When True, no recursive serialization occurs. Recommended when
                serialization is used only to inspect top-level keys.

            clean:
                When True, no FOS format read/write metadata is included in the
                serial. Recommended for sending output to other formats like
                JSON.

        Private attributes starting with "_" are either skipped or unpacked in
        special cases:

        * `_key_order`:
            attributes are added to the serialized dict in the order they
            appear in this list.

        * `_calc_comments`:
            calculated comments are attached to their mapped attribute after
            serialization to avoid mutation of object comments

        * `_calc_routines`:
            A list of functions scheduled to be called right before
            serialization to update _calc_comments. Scheduling calc routines
            ensures that their calculated values are up-to-date.

        * `_meta`:
            attributes of this container are given their own private `_key`s
            mapped by `FoSpy.parsing.syntax.meta_keys` in the serialized
            dict.

        * `_key_overrides`:
            per-instance override mapping that tracks which unexpected
            attributes require $alias suffixes.

        * `_aliases`:
            maps attribute names to alias tags used to emit $alias suffixed
            keys.

        * `_reserved`:
            attribute names in reserved are non-private attributes which
            should *not* be serialized. This usually applies to the `ext`
            attribute or methods attached after construction.
        """
        from copy import deepcopy
        from ..parsing.format_fos import format_calc_comment
        from .template import TemplateBlock

        val_to_alias = {v:k for k,v in self._aliases.items()}

        all_attrs = {}
        out = {}

        for routine in self._calc_routines:
            routine()

        def add_alias(key):
            if key in self._key_overrides:
                alias = val_to_alias[self._key_overrides[key]]
                return f"{key}${alias}"
            return key


        def try_serial(obj):
            serialize = getattr(obj, "serialize", None)
            if isinstance(obj, SimpleWrapper):
                obj = obj()
            if callable(serialize) and not shallow:
                return obj.serialize(clean=clean)
            if isinstance(obj, list):
                return [try_serial(item) for item in obj]
            if isinstance(obj, dict):
                return {k:try_serial(v) for k,v in obj.items()}
            return str(obj)

        for attr,val in self.__dict__.items():
            if attr == "ext" and val is not None:
                for ext_attr, ext_val in val.__dict__.items():
                    all_attrs[ext_attr] = ext_val
            elif not (attr.startswith("_") or attr in self._reserved):
                all_attrs[attr] = val


        for key in self._key_order:
            if key in all_attrs:
                val = all_attrs.pop(key)
                out[add_alias(key)] = try_serial(val)

        for key, val in all_attrs.items():
            out[add_alias(key)] = try_serial(val)

        for attr, key in mk.items():
            try:
                k = md[key].copy()
            except:
                k = md[key]
            val = getattr(self._meta,attr,k)
            out[key] = val

        comments = {}
        for key, comment_list in out[mk["comments"]].items():
            comments[add_alias(key)] = comment_list
        out[mk["comments"]] = comments

        out = deepcopy(out)

        # _debug.pmsg(self._calc_comments)
        for key, comments in self._calc_comments.items():
            for comment in comments.values():
                out[mk["comments"]].setdefault(add_alias(key),[])
                out[mk["comments"]][add_alias(key)].append(format_calc_comment(comment))

        if not keepListType:
            out[mk["list_type"]] = "explicit"

        if "template_name" in out and not isinstance(self, TemplateBlock):
            out.pop("template_name")

        if clean:
            scan = out.copy()
            for key, val in scan.items():
                if key.startswith("_") or val is None:
                    out.pop(key)

        return out

    def to_json(self, filepath=None, clean:bool=True, indent:int=4, **kwargs):
        """
        Converts `self` into a JSON-formatted string or file.

        [Serializes][FoSpy.blocks.blocks.SingleBlock.serialize] and either
        returns as a JSON-formatted string or saves to a JSON file.

        Args:
            filepath (pathlike):
                JSON file save destination. If `None`, returns JSON-formatted
                string instead.

            clean:
                When True, no FOS format read/write metadata is included in the
                serial. FOS metadata has no impact on JSON format but may be
                useful to view in JSON for troubleshooting.

            indent:
                `indent` value passed to `json.dump` for file saving.

            **kwargs (any):
                other arguments passed to `json.dump` for file saving.
        """
        import json
        serial = self.serialize(clean=clean)

        if filepath is None:
            return json.dumps(serial)

        with open(filepath, "w") as f:
            json.dump(serial, f, indent=indent, **kwargs)

    def add_calc_comment(self, key:str, comment:str, calc_id:str):
        """
        Add a calculated comment to be injected during serialization.

        WARNING: This function can leave outdated calculations in comments after
        serialization. Recommended to use `add_calc_routine()` instead.

        Calculated comments are for user information and will be formatted to be
        skipped by the parser when reading the file. This is useful for comments
        that should be recalculated and refreshed during saving/serialization,
        like weight percentages or summaries.

        Args:
            key:
                attribute to attach the calculated comment to. Comments appear
                above their attached attributes in FOS format.
            comment:
                comment text without comment formatting (don't include // or !)
            calc_id:
                unique identifier for the calculated comment. If it matches an
                existing comment (like when refreshing a value), the comment is
                overwritten

        """
        calc_comments = self._calc_comments.get(key, {})
        self._calc_comments[key] = calc_comments
        self._calc_comments[key][calc_id]=comment

    def make_template(self,template_name:str,*args:str):
        """
        Converts `self` into a template of its original subclass.

        Returns a copy of `self` as a template of its original subclass, with
        specified fields replaced with template types. See
        [`TemplateClass`][FoSpy.blocks.blocks.SingleBlock.TemplateClass] for
        more information on template generation.

        Args:
            template_name: All templates require an identifying name.
            *args: properties to clear and replace with template types.
        """

        from ..parsing.format_fos import format_field

        serial = self.serialize(keepListType=True)
        validators = self.get_validators()
        for key in args:
            val = validators.get(key, None)
            if isinstance(val,type) and (issubclass(val, SingleBlock) or issubclass(val, ListBlock)):
                serial[key] = []
            else:
                serial[key] = format_field("template")
        serial["template_name"] = template_name
        return type(self).TemplateClass(*args).dispatch_subclass(serial)

    def _resolve_relative_path(self, path: str):
        """
        Resolves a relative object path string into an object or function.

        Example:
        ```
            mySyn._resolve_relative_path("materials[1].ratio")
            ## returns mySyn.materials[1].ratio
        ```
        """
        import re

        _index_re = re.compile(r"^([A-Za-z_]\w*)\[(\d+)\]$")
        obj = self

        for part in path.split("."):

            # Case: attr[index]
            m = _index_re.match(part)
            if m:
                attr_name, idx_str = m.groups()
                idx = int(idx_str)

                # Get the ListBlock
                obj = getattr(obj, attr_name)

                # Index into its _objs
                obj = obj._objs[idx]
                continue

            # Case: simple attribute
            obj = getattr(obj, part)

        return obj

    def add_calc_routine(self, path:str, **kwargs):
        """
        Schedules a calculated comment.

        Appends a
        [`_calc_routine()`][FoSpy.blocks._blockUtils._calc_routine]-decorated
        function to `self._calc_routines` to be run at
        [serialization][FoSpy.blocks.blocks.SingleBlock.serialize].

        Used to add calculated comments that should be refreshed during
        serialization.

        Args:
            path:
                a relative path string that can be resolved into a
                `_calc_routine()`-decorated function
            **kwargs (any):
                optional key word arguments to be passed to the function at
                path.

        Raises:
            TypeError:
                the attr or method at path is not registered as a
                _calc_routine

        Example:
        ```
            mySyn.add_calc_routine("materials.add_weight_pcts", typ="reagent")
            ## mySyn.materials.add_weight_pcts(typ="reagent") is now scheduled
            ## to run at serialization
        ```
        """
        from functools import wraps

        func = self._resolve_relative_path(path)
        if not getattr(func, "_is_calc_routine", False):
            raise TypeError(f"'{path}' is not a registered calc routine.")

        self._meta.routine_paths.append(path)

        @wraps(func)
        def wrapped():
            __name__ = func.__name__
            return func(**kwargs)

        self._calc_routines.append(wrapped)

    def list_avail_routines(self, recursive:bool=False, prefix:str="", abbreviated:bool=False):
        """
        Lists all calc routines available to be added to `self._calc_routines`.

        Non-abbreviated calc routine strings can be passed directly to
        `self.add_calc_routine()`

        Args:
            recursive:
                If True, recursively walks all attributes and appends results
                from `self.attr.list_avail_routines()` to result. Otherwise only
                identifies methods of `self`.

            prefix: Used during recursion to build relative paths
            abbreviated:
                optionally abbreviate recursively repeated routines for similar
                objects into one line. This line cannot be passed to
                `self.add_calc_routine()`

        Returns:
            routines (list): 
                list of strings describing _calc_routine-decorated methods.
                Non-abbreviated calc routine strings can be passed directly to
                `self.add_calc_routine()`

        Example:
        ```
            mySyn.list_avail_routines()
            ## returns []
            mySyn.list_avail_routines(recursive=True)
            ## returns [
            ##     'reaction.add_nom_MW',
            ##     'materials.add_weight_pcts',
            ##     'materials[0].add_MW',
            ##     'materials[1].add_MW',
            ##     ... 6 total materials with the same calc_routine
            ##     'materials[5].add_MW'
            ## ]
            mySyn.list_avail_routines(recursive=True, abbreviated=True)
            ## returns [
            ##     'reaction.add_nom_MW',
            ##     'materials.add_weight_pcts',
            ##     'materials[i].add_MW; i = [0, 1, 2, 3, 4, 5]'
            ## ]
        ```
        """
        routines = []

        # Local routines
        for name in dir(self):
            attr = getattr(self, name)
            if callable(attr) and getattr(attr, "_is_calc_routine", False):
                routines.append(prefix + name)

        if recursive:
            for attr, val in self.__dict__.items():
                if attr.startswith("_"):
                    continue

                # Recurse into child blocks
                if hasattr(val, "list_avail_routines"):
                    child_prefix = f"{prefix}{attr}."
                    routines.extend(val.list_avail_routines(True, child_prefix, abbreviated))

        return routines

    def add_all_calc_routines(self, recursive:bool=False):
        """
        Schedule all available calculation routines.

        Adds all available calc_routines to `self._calc_routines` using
        [`list_avail_routines()`][FoSpy.blocks.blocks.SingleBlock.list_avail_routines]
        and
        [`add_calc_routine()`][FoSpy.blocks.blocks.SingleBlock.add_calc_routine].

        Args:
            recursive:
                Optional recursion. See `SingleBlock.list_avail_routines()`
        """
        for path in self.list_avail_routines(recursive=recursive, abbreviated=False):
            self.add_calc_routine(path)

    def copy(self):
        """
        Returns a deep-copy of `self` by serializing and reconstructing.

        _calc_comments are not preserved during copy, but _calc_routines are.
        This prevents mutation of the comments when reconstructing.
        """
        cls = type(self)
        c_cmts = self._calc_comments.copy()
        self._calc_comments = {}

        new_obj =  cls.dispatch_subclass(self.serialize(keepListType=True))
        self._calc_comments = c_cmts

        return new_obj

    def _meta_to_front(self):
        """
        Moves metadata to the front of `_key_order`. Metadata will always be
        serialized first, but being elsewhere in the order leads to unexpected
        results when moving other keys to desired indices.
        """
        try:
            meta_idx =self._key_order.index("metadata")
            self._key_order.pop(meta_idx)
        except:
            pass
        self._key_order.insert(0,"metadata")

    def keys_to_front(self,*args):
        """
        Reorder attributes for serialization.

        Move any attribute names in `*args` to the front of _key_order to be
        serialized first. Order within `*args` is maintained in result.
        """
        try:
            meta_idx = args.index("metadata")
            args.pop(meta_idx)
        except:
            pass

        new_order = []
        for key in args:
            new_order.append(key)
        for key in self._key_order:
            if key not in new_order:
                new_order.append(key)
        self._key_order = new_order
        self._meta_to_front()

    def default_key_order(self, deep:bool=False):
        """
        Set to default attribute order for serialization.

        Rearrange attribute order to the default order assigned by
        [`build_validators`][FoSpy.blocks.blocks.SingleBlock.build_validators]

        Args:
            deep:
                When true, recursively calls `default_key_order` on any other
                `SingleBlock` objects stored in attributes.
        """
        new_order = []
        for key in self.get_validators():
            if key != "ext" and key in self.serialize(shallow=True):
                new_order.append(key)
        for key in self._key_order:
            if key not in new_order:
                new_order.append(key)
        self._key_order = new_order
        self._meta_to_front()

        if deep:
            for name, obj in self.__dict__.items():
                if not name.startswith("_") and hasattr(obj, "default_key_order"):
                    obj.default_key_order(deep=True)

    def keys_to_end(self, *args):
        """
        Reorder attributes for serialization.

        Move any attribute names in `*args` to the end of _key_order to be
        serialized last. Order within `*args` is maintained in result.
        """
        def remove_alias(key):
            return key.split("$")[0] if "$" in key else key
        for key in self.serialize(shallow=True):
            if not key.startswith("_") and remove_alias(key) not in self._key_order:
                self._key_order.append(remove_alias(key))
        for key in args:
            try:
                idx = self._key_order.index(key)
                self._key_order.pop(idx)
            except:
                pass
            self._key_order.append(key)
        self._meta_to_front()

    def key_to_idx(self, key:str, idx:int):
        """
        Reorder attributes for serialization.

        Move any attribute name to a specific index in `_key_order` for
        serialization order. The invisible `"metadata"` key is always refreshed
        to the front of the list, so indices are effectively 1-based.

        Args:
            key: name of attribute to reorder
            idx: new index in _key_order
        """
        self._meta_to_front()
        try:
            old_idx = self._key_order.index(key)
            self._key_order.pop(old_idx)
        except:
            pass
        self._key_order.insert(idx, key)

    def clear_comments(self):
        """
        Clear comments attached to top-level attributes only.
        """
        self._meta.comments = {}

    def rename_block(self, old, new):
        validators = self.get_validators()
        req = self.get_req_validators()
        if True in [name.startswith("_") for name in (old, new)]:
            raise ValueError(f"You cannot set private attributes (starting with '_') using obj.rename_block()")

        if old in req and new in validators:
            raise ValueError(f"You cannot rename '{old}' to '{new}'. '{old}' is a required property that "
                                f"can only be renamed to an unregistered key; '{new}' is already registered "
                                "as an expected property.")

        if hasattr(self, new):
            raise ValueError(f"'{new}' is already a property for this object, you cannot overwrite it with "
                             "obj.rename_block()")

        if "rename" in (old, new):
            raise ValueError("obj.rename property cannot be set or changed by obj.rename_block()")

        if old in self._key_overrides:
            val = self._key_overrides.pop(old)
            self._key_overrides[new] = val
        else:
            _debug.msg(f"Registering '{old}':'{new}' into rename block")
            if not hasattr(self,"rename"):
                self.rename = {}
            setattr(self.rename, old, new)
        _debug.msg(f"Moving '{old}' over to '{new}'.")
        setattr(self,new,getattr(self, old))
        delattr(self,old)

        try:
            idx = self._key_order.index(old)
            self._key_order[idx] = new
        except:
            self._key_order.append(new)

    def __delattr__(self, attr):
        if attr in self.get_req_validators():
            raise AttributeError(f"Cannot delete property: '{attr}'. It is registered as a required property for this object.")
        return super().__delattr__(attr)

    def clear_all_comments(self):
        self._meta.comments = {}
        for attr, val in self.__dict__.items():
            if attr.startswith("_") or attr in self._reserved:
                continue
            if hasattr(val, "clear_all_comments"):
                val.clear_all_comments()

    def refresh_attachments(self, new_copy=None, overwrite=None, **kwargs):
        from .attachments import Attachment

        if new_copy is None:
            new_copy = self._att_new_copy
        if overwrite is None:
            overwrite = self._att_overwrite

        for propDict in self.__dict__, self.ext.__dict__:
            for key, val in propDict.items():
                if key.startswith("_") or key in self._reserved:
                    continue
                if hasattr(val, "refresh_attachments"):
                    val.refresh_attachments(new_copy=new_copy, overwrite=overwrite, **kwargs)
                elif isinstance(val, Attachment) and hasattr(val, "refresh"):
                    val.refresh(new_copy=new_copy, overwrite=overwrite, **kwargs)

_aliases class-attribute instance-attribute

_aliases = new_als

_calc_comments instance-attribute

_calc_comments = {}

_calc_routines instance-attribute

_calc_routines = []

_key_order instance-attribute

_key_order = []

_key_overrides instance-attribute

_key_overrides = {}

_meta instance-attribute

_meta = SubContainer()

_reserved instance-attribute

_reserved = ['ext']

_sourceDict instance-attribute

_sourceDict = blockDict.copy()

dispatch class-attribute instance-attribute

dispatch = {}

ext instance-attribute

ext = SubContainer()

TemplateClass classmethod

TemplateClass(*args)

Create a template for a subclass of SingleBlock.

Generates a hybridized subclass of the current block class and TemplateBlock. Template subclasses override original expected validators with either a TemplateField, TemplateBlock, or TemplateList depending on the type of the original validator.

Parameters:

Name	Type	Description	Default
*args	str	A list of properties to override as template types.	()

Source code in FoSpy/blocks/blocks.py

@classmethod
def TemplateClass(cls,*args:str):
    """
    Create a template for a subclass of `SingleBlock`.

    Generates a hybridized subclass of the current block class and
    [`TemplateBlock`][FoSpy.blocks.template.TemplateBlock]. Template
    subclasses override original expected validators with either a
    [`TemplateField`][FoSpy.blocks.template.TemplateField],
    [`TemplateBlock`][FoSpy.blocks.template.TemplateBlock], or
    [`TemplateList`][FoSpy.blocks.template.TemplateList] depending on the
    type of the original validator.

    Args:
        *args: A list of properties to override as template types.
    """
    from .template import TemplateBlock, TemplateField, TemplateList
    from ..parsing.validation import required_keys, optional_keys
    if issubclass(cls, TemplateBlock):
        class ExtendedTemplate(cls):
            pass
        SubTemplate = ExtendedTemplate
    else:
        class NewTemplate(TemplateBlock, cls):
            dispatch = {}
            def __init__(self, blockDict, _dispatched=False):
                super().__init__(blockDict, _dispatched=_dispatched)
                self._full_class = cls
        SubTemplate = NewTemplate
    required_keys[SubTemplate] = {}
    optional_keys[SubTemplate] = {}
    required_validators = cls.build_req_validators()
    all_validators = cls.build_validators()
    for key in args:
        req_val = required_validators.get(key,None)
        val = all_validators.get(key,None) or req_val

        if isinstance(val,type) and issubclass(val,SingleBlock):
            all_fields = list(val.build_req_validators().keys())
            field = val.TemplateClass(*all_fields)

        elif isinstance(val,type) and issubclass(val, ListBlock):
            field = TemplateList.Simple(val._reqCls)
        else:
            field = TemplateField

        if req_val:
            required_keys[SubTemplate][key] = field
        else:
            optional_keys[SubTemplate][key] = field

    finished_reqs = required_keys[SubTemplate]
    finished_opts = optional_keys[SubTemplate]
    for typ, sub in cls.dispatch.items():
        dispatched_sub = sub.TemplateClass(*args)
        SubTemplate.dispatch[typ] = dispatched_sub

        required_keys[dispatched_sub] = finished_reqs
        optional_keys[dispatched_sub] = finished_opts

    SubTemplate.__name__ = f"{cls.__name__}Template"
    SubTemplate.__qualname__ = f"{cls.__name__}.Template"
    SubTemplate.__module__ = cls.__module__

    return SubTemplate

__delattr__

__delattr__(attr)

Source code in FoSpy/blocks/blocks.py

def __delattr__(self, attr):
    if attr in self.get_req_validators():
        raise AttributeError(f"Cannot delete property: '{attr}'. It is registered as a required property for this object.")
    return super().__delattr__(attr)

__eq__

__eq__(other, suppress_routine_paths=False)

Check equality of two SingleBlock objects.

Equality is checked by a deep difference of their serialized dictionaries.

Parameters:

Name	Type	Description	Default
suppress_routine_paths	bool	Optional flag to still return true if the only differences found are in calculation routine metadata. Calculation routines are for user information only and may not be relevant for equality.	False

Source code in FoSpy/blocks/blocks.py

def __eq__(self, other, suppress_routine_paths:bool=False):
    """
    Check equality of two `SingleBlock` objects.

    Equality is checked by a deep difference of their
    [serialized][FoSpy.blocks.blocks.SingleBlock.serialize] dictionaries.

    Args:
        suppress_routine_paths:
            Optional flag to still return true if the only differences found
            are in [calculation
            routine][FoSpy.blocks.blocks.SingleBlock.add_calc_routine]
            metadata. Calculation routines are for user information only and
            may not be relevant for equality.
    """
    from .._debug import deep_diff as dd, _debug as db
    try:
        db.msg("Serializing Blocks to check equality:", module = "SingleBlock.__eq__()")
        diffs = dd(self.serialize(), other.serialize(), suppress_routine_paths=suppress_routine_paths)
        passed = len(diffs) == 0
        if not passed:
            db.pmsg(diffs,module = "SingleBlock.__eq__()")
        return passed
    except Exception as e:
        db.msg(f"Equality failed by exception: {e}",module = "SingleBlock.__eq__()")
        return False

__getattr__

__getattr__(name)

Check both self and self.ext for attribute before returning.

A matching attribute of self will be returned first, but if self has no matching attribute, a matching attribute of self.ext can be returned instead.

Source code in FoSpy/blocks/blocks.py

def __getattr__(self, name:str):
    """
    Check both `self` and `self.ext` for attribute before returning.

    A matching attribute of `self` will be returned first, but if `self` has
    no matching attribute, a matching attribute of `self.ext` can be
    returned instead.
    """
    try:
        if name != 'ext':
            return getattr(self.ext, name)
        raise AttributeError()
    except AttributeError:
        raise AttributeError(
            f"{type(self).__name__} object "
            f"has no attribute {name!r}."
        )

__hash__

__hash__()

Source code in FoSpy/blocks/blocks.py

def __hash__(self):
    return id(self)

__init__

__init__(blockDict, _dispatched=False)

Constructs a SingleBlock object from a dictionary.

Avoid using this constructor for unfamiliar block classes, it may bypass subclass delegation. Use dispatch_subclass instead.

SingleBlocks are constructed recursively from an arbitrarily nested dictionary. All keys identified by SingleBlock.build_req_validators() must be present at the top level. Required keys at nested levels are handled by the recursed constructor.

Parameters:

Name	Type	Description	Default
blockDict	dict	An arbitrarily nested dictionary mapping attribute names to values. Unexpected attributes will be assigned under self.ext instead (see SingleBlock.__setattr__). It is possible to pass a blockDict already containing objects, but validation routines will fail if objects are not the correct type. Best practice is to serialize all nested objects into lists, dicts, and strings to allow full type coersion.	required
_dispatched		Flag passed by dispatch_subclass to signal that the safer construction method was used. Warning issued for False	False

Raises:

Type	Description
ValueError	A key required by SingleBlock.build_req_validators() is not present.
TypeError	The value passed as blockDict was not able to be unwrapped into a dict, either by serialization of a passed Block object or by list index.

Source code in FoSpy/blocks/blocks.py

def __init__(self, blockDict:dict, _dispatched=False):
    """
    Constructs a SingleBlock object from a dictionary.

    Avoid using this constructor for unfamiliar block classes, it may bypass
    subclass delegation. Use
    [`dispatch_subclass`][FoSpy.blocks.blocks.SingleBlock.dispatch_subclass]
    instead.

    SingleBlocks are constructed recursively from an arbitrarily nested
    dictionary. All keys identified by `SingleBlock.build_req_validators()`
    must be present at the top level. Required keys at nested levels are
    handled by the recursed constructor.

    Args:
        blockDict:
            An arbitrarily nested dictionary mapping attribute names to
            values. 

            Unexpected attributes will be assigned under `self.ext` instead
            (see `SingleBlock.__setattr__`). 

            It is possible to pass a blockDict already containing objects,
            but validation routines will fail if objects are not the correct
            type. Best practice is to serialize all nested objects into
            lists, dicts, and strings to allow full type coersion.
        _dispatched:
            Flag passed by
            [`dispatch_subclass`][FoSpy.blocks.blocks.SingleBlock.dispatch_subclass]
            to signal that the safer construction method was used. Warning
            issued for False


    Raises:
        ValueError:
            A key required by `SingleBlock.build_req_validators()` is not
            present.
        TypeError:
            The value passed as `blockDict` was not able to be unwrapped
            into a dict, either by serialization of a passed `Block` object
            or by list index.

    """

    if not _dispatched:
        from warnings import warn
        warn(f"You should avoid directly constructing a {type(self).__name__} object. Use the dispatch_subclass() "
             "method instead to allow for subclass delegation when constructing.", stacklevel=2)

    self.track_attachments(**cfg.track_attachments())

    from ..parsing.validation import aliases as als
    new_als = als.copy()
    new_als.update(self._aliases or {})
    self._aliases = new_als
    self._reserved = ['ext']

    blockDict = _unwrap_block(blockDict)
    self._sourceDict = blockDict.copy()

    if not isinstance(blockDict, dict):
        raise TypeError("A SingleBlock must be constructed from either a dictionary or another SingleBlock. "
                        "The passed source can optionally be wrapped in lists of length == 1.")

    blockDict = blockDict.copy()

    rename = blockDict.pop("rename",None)
    if rename:
        setattr(self, "rename", _unwrap_block(rename))

    req = self.get_req_validators()
    req.pop("ext",None)
    for key, validator in req.items():
        if key not in blockDict:
            from .template import TemplateBlock, TemplateList, TemplateField, FlexTemplate
            is_type = isinstance(validator, type)
            if is_type and issubclass(validator, TemplateField):
                blockDict[key] = ""
            elif is_type and issubclass(validator, FlexTemplate):
                blockDict[key] = {"template_name": f"Empty {self._baseReq.__name__} Template"}
            elif is_type and issubclass(validator, TemplateBlock):
                blockDict[key] = validator.reflex()
            elif is_type and issubclass(validator, TemplateList):
                blockDict[key] = []
            else:
                raise ValueError(f"Missing required property: '{key}' for '{type(self).__name__}' object.")

    self._meta = SubContainer()
    self._calc_comments = {}
    self._calc_routines = []
    self._key_overrides = {}

    for attr, key in mk.items():
        try:
            k = md[key].copy()
        except:
            k = md[key]
        setattr(self._meta, attr, blockDict.pop(key,k))

    self._key_order = []
    self.ext = SubContainer()

    for key, val in blockDict.items():
        self._key_order.append(key)
        setattr(self, key, val)

__setattr__

__setattr__(name, value)

Assign an attribute with validation and controlled namespace behavior.

Contract

SingleBlock enforces type correctness and validator execution for all public attributes defined for its subclass.

Required types and validators are mapped by subclass in parsing.validation

Comment-mutating methods are attached to every object assigned to an attribute. (See add_comments)

Rules

1. Private attributes (_-prefixed) bypass validation.
2. Attributes with registered validators are processed through the validator before assignment.
3. Attributes with required types are coerced by calling the type constructor when necessary.
4. Unrecognized attributes can be assigned to a validator mapped to an alias in parsing.validation, using the syntax name="name$alias".
5. Unrecognized attribute names are redirected as attributes of self.ext.

Raises:

Type	Description
ValueError	If a required SingleBlock is passed as a list with length > 1. If a block alias cannot be parsed from a key containing $. If a block alias is unrecognized. If a template field is found when constructing a non-template subclass.

Source code in FoSpy/blocks/blocks.py

def __setattr__(self, name:str, value):
    """
    Assign an attribute with validation and controlled namespace behavior.

    Contract:
        `SingleBlock` enforces type correctness and validator execution for
        all public attributes defined for its subclass.

        Required types and validators are mapped by subclass in
        [`parsing.validation`][FoSpy.parsing.validation]

        Comment-mutating methods are attached to every object assigned to an
        attribute. (See
        [`add_comments`][FoSpy.blocks.blocks._add_comments_to_parent])

    Rules:
        1. Private attributes (`_`-prefixed) bypass validation.
        2. Attributes with registered validators are processed through the
        validator before assignment.
        3. Attributes with required types are coerced by calling the type
        constructor when necessary.
        4. Unrecognized attributes can be assigned to a validator mapped to
        an alias in [`parsing.validation`][FoSpy.parsing.validation], using
        the syntax `name="name$alias"`.
        5. Unrecognized attribute names are redirected as attributes of
        `self.ext`.

    Raises:
        ValueError:
            - If a required `SingleBlock` is passed as a list with length > 1.
            - If a block alias cannot be parsed from a key containing `$`.
            - If a block alias is unrecognized.
            - If a template field is found when constructing a non-template
              subclass.
    """
    from ..parsing.format_fos import format_field
    from .template import TemplateField, TemplateBlock

    from inspect import signature as sign

    if name.startswith("_") or name in self._reserved:
        return super().__setattr__(name, value)

    validators = self.get_validators()

    if "$" in name:
        try:
            name, alias = name.split("$")
        except:
            raise ValueError(f"Unable to parse a block alias from key: '{name}'.")

        try:
            val = self._aliases[alias]
        except KeyError:
            raise ValueError(f"Unrecognized block alias: '{alias}'")

        if name in validators and val != validators[name]:
            raise ValueError(f"Key: '{name}' is already reserved for '{validators[name].__name__}' validator, "
                             f"it cannot be overwritten to '{val.__name__}'.")
        if name not in validators:
            validators[name] = val
            self._key_overrides[name] = val

    if name in validators:
        validator = validators[name]
        val_kwargs = {}
        for kw, arg in (("sourceDict", self._sourceDict),("cls", type(self))):
            try:
                if kw in sign(validator).parameters:
                    val_kwargs[kw] = arg
            except:
                pass


        if isinstance(validator, type):
            if issubclass(validator, SingleBlock):
                if not isinstance(value, validator):
                    validator = validator.dispatch_subclass
                    if isinstance(value, list):
                        if len(value) > 1:
                            raise ValueError(f"Block '{name}' must be a single block. It can only be constructed from a list of length 1.")
                        value = value[0]
                    elif isinstance(value,SingleBlock):
                        value = value.serialize(keepListType=True)

            elif issubclass(validator, ListBlock):
                try: 
                    value = [block.serialize(keepListType=True) for block in value]
                except Exception as e:
                    if isinstance(value, ListBlock):
                        value = value.serialize()
            elif value == format_field("template") and not issubclass(validator, TemplateField):
                if isinstance(self,TemplateBlock):
                    validator = TemplateField
                else:       
                    raise ValueError(f"You cannot create a '{type(self).__name__}' object with an un-filled '{name}' template field.")
            if isinstance(validator, type) and isinstance(value, validator):
                return self._assign_and_inject(name, value)




        return self._assign_and_inject(name,
                                        validator(value,**val_kwargs)
                                        if val_kwargs != {}
                                        else validator(value))
    else:
        return self._assign_and_inject(name, value, extended=True)

_assign_and_inject

_assign_and_inject(name, value, extended=False)

Attaches attributes and methods to any value before assigning it as an attribute of self or self.ext.

Attributes Attached to Object

_parent_block: refers to self

Methods Attached to Object

add_comments_to_parent clear_comments_from_parent

Source code in FoSpy/blocks/blocks.py

def _assign_and_inject(self, name, value, extended=False):
    """
    Attaches attributes and methods to any value before assigning it as an
    attribute of `self` or `self.ext`.

    Attributes Attached to Object:
        `_parent_block`: refers to `self`

    Methods Attached to Object:
        [`add_comments_to_parent`][FoSpy.blocks.blocks._add_comments_to_parent]
        [`clear_comments_from_parent`][FoSpy.blocks.blocks._clear_comments_from_parent]
    """
    from .attachments import Attachment

    if name == 'ext':
        return super().__setattr__('ext', value)
    if not hasattr(value, "__dict__"):
        value = SimpleWrapper(value)

    if extended:
        setattr(self.ext, name, value)
    else:
        super().__setattr__(name, value)

    attr_obj = getattr(self.ext if extended else self, name)

    setattr(attr_obj, "_parent_block", self)

    if isinstance(attr_obj, Attachment):
        attr_obj._get_filepath()
    elif hasattr(attr_obj, "refresh_attachments"):
        attr_obj.refresh_attachments()

    methods = ((_add_comments_to_parent(name), "add_comments"),
            (_clear_comments_from_parent(name), "clear_comments"))

    attr_obj._reserved = ['ext'] if not hasattr(attr_obj,"_reserved") else attr_obj._reserved
    for method, method_name in methods:
        attr_obj._reserved.append(method_name)
        bound = method.__get__(attr_obj, type(attr_obj))
        setattr(attr_obj, method_name, bound)

_meta_to_front

_meta_to_front()

Moves metadata to the front of _key_order. Metadata will always be serialized first, but being elsewhere in the order leads to unexpected results when moving other keys to desired indices.

Source code in FoSpy/blocks/blocks.py

def _meta_to_front(self):
    """
    Moves metadata to the front of `_key_order`. Metadata will always be
    serialized first, but being elsewhere in the order leads to unexpected
    results when moving other keys to desired indices.
    """
    try:
        meta_idx =self._key_order.index("metadata")
        self._key_order.pop(meta_idx)
    except:
        pass
    self._key_order.insert(0,"metadata")

_rename_validators

_rename_validators(validators)

Realigns any renamed attributes with their expected validator.

Parameters:

Name	Type	Description	Default
validators	dict	A dictionary mapping attribute names to validators, returned by either build_validators or build_req_validators	required

Source code in FoSpy/blocks/blocks.py

def _rename_validators(self, validators:dict):
    """
    Realigns any [renamed][FoSpy.blocks.blocks.SingleBlock.rename_block]
    attributes with their expected validator.

    Args:
        validators:
            A dictionary mapping attribute names to validators, returned by
            either
            [`build_validators`][FoSpy.blocks.blocks.SingleBlock.build_validators]
            or
            [`build_req_validators`][FoSpy.blocks.blocks.SingleBlock.build_req_validators]
    """
    if hasattr(self, "rename"):
        for name, rename in self.rename.serialize(shallow=True).items():
            if name in validators and rename not in validators:
                val = validators.pop(name)
                validators[rename] = val
    return validators

_resolve_relative_path

_resolve_relative_path(path)

Resolves a relative object path string into an object or function.

Example:

    mySyn._resolve_relative_path("materials[1].ratio")
    ## returns mySyn.materials[1].ratio

Source code in FoSpy/blocks/blocks.py

def _resolve_relative_path(self, path: str):
    """
    Resolves a relative object path string into an object or function.

    Example:
    ```
        mySyn._resolve_relative_path("materials[1].ratio")
        ## returns mySyn.materials[1].ratio
    ```
    """
    import re

    _index_re = re.compile(r"^([A-Za-z_]\w*)\[(\d+)\]$")
    obj = self

    for part in path.split("."):

        # Case: attr[index]
        m = _index_re.match(part)
        if m:
            attr_name, idx_str = m.groups()
            idx = int(idx_str)

            # Get the ListBlock
            obj = getattr(obj, attr_name)

            # Index into its _objs
            obj = obj._objs[idx]
            continue

        # Case: simple attribute
        obj = getattr(obj, part)

    return obj

add_all_calc_routines

add_all_calc_routines(recursive=False)

Schedule all available calculation routines.

Adds all available calc_routines to self._calc_routines using list_avail_routines() and add_calc_routine().

Parameters:

Name	Type	Description	Default
recursive	bool	Optional recursion. See SingleBlock.list_avail_routines()	False

Source code in FoSpy/blocks/blocks.py

def add_all_calc_routines(self, recursive:bool=False):
    """
    Schedule all available calculation routines.

    Adds all available calc_routines to `self._calc_routines` using
    [`list_avail_routines()`][FoSpy.blocks.blocks.SingleBlock.list_avail_routines]
    and
    [`add_calc_routine()`][FoSpy.blocks.blocks.SingleBlock.add_calc_routine].

    Args:
        recursive:
            Optional recursion. See `SingleBlock.list_avail_routines()`
    """
    for path in self.list_avail_routines(recursive=recursive, abbreviated=False):
        self.add_calc_routine(path)

add_block

add_block(block_name, type_alias, value=[])

Adds an unexpected attribute with a validator mapped by type_alias. Unexpected attributes not requiring a validator can be set directly without using this method.

Parameters:

Name	Type	Description	Default
block_name	str	new unexpected attribute name	required
type_alias	str	Alias mapped to the desired validator in parsing.validation.aliases. For more information on how aliases are used, see __setattr__.	required

Source code in FoSpy/blocks/blocks.py

def add_block(self, block_name:str, type_alias:str, value=[]):
    """
    Adds an unexpected attribute with a validator mapped by `type_alias`.
    Unexpected attributes not requiring a validator can be set directly
    without using this method.

    Args:
        block_name: new unexpected attribute name
        type_alias:
            Alias mapped to the desired validator in
            [`parsing.validation.aliases`][FoSpy.parsing.validation.aliases].
            For more information on how aliases are used, see
            [`__setattr__`][FoSpy.blocks.blocks.SingleBlock.__setattr__].
    """
    if hasattr(self,block_name):
        raise ValueError(f"This object already has attribute: '{block_name}'.")
    return setattr(self, f"{block_name}${type_alias}", value)

add_calc_comment

add_calc_comment(key, comment, calc_id)

Add a calculated comment to be injected during serialization.

WARNING: This function can leave outdated calculations in comments after serialization. Recommended to use add_calc_routine() instead.

Calculated comments are for user information and will be formatted to be skipped by the parser when reading the file. This is useful for comments that should be recalculated and refreshed during saving/serialization, like weight percentages or summaries.

Parameters:

Name	Type	Description	Default
key	str	attribute to attach the calculated comment to. Comments appear above their attached attributes in FOS format.	required
comment	str	comment text without comment formatting (don't include // or !)	required
calc_id	str	unique identifier for the calculated comment. If it matches an existing comment (like when refreshing a value), the comment is overwritten	required

Source code in FoSpy/blocks/blocks.py

def add_calc_comment(self, key:str, comment:str, calc_id:str):
    """
    Add a calculated comment to be injected during serialization.

    WARNING: This function can leave outdated calculations in comments after
    serialization. Recommended to use `add_calc_routine()` instead.

    Calculated comments are for user information and will be formatted to be
    skipped by the parser when reading the file. This is useful for comments
    that should be recalculated and refreshed during saving/serialization,
    like weight percentages or summaries.

    Args:
        key:
            attribute to attach the calculated comment to. Comments appear
            above their attached attributes in FOS format.
        comment:
            comment text without comment formatting (don't include // or !)
        calc_id:
            unique identifier for the calculated comment. If it matches an
            existing comment (like when refreshing a value), the comment is
            overwritten

    """
    calc_comments = self._calc_comments.get(key, {})
    self._calc_comments[key] = calc_comments
    self._calc_comments[key][calc_id]=comment

add_calc_routine

add_calc_routine(path, **kwargs)

Schedules a calculated comment.

Appends a _calc_routine()-decorated function to self._calc_routines to be run at serialization.

Used to add calculated comments that should be refreshed during serialization.

Parameters:

Name	Type	Description	Default
path	str	a relative path string that can be resolved into a _calc_routine()-decorated function	required
**kwargs	any	optional key word arguments to be passed to the function at path.	{}

Raises:

Type	Description
TypeError	the attr or method at path is not registered as a _calc_routine

Example:

    mySyn.add_calc_routine("materials.add_weight_pcts", typ="reagent")
    ## mySyn.materials.add_weight_pcts(typ="reagent") is now scheduled
    ## to run at serialization

Source code in FoSpy/blocks/blocks.py

def add_calc_routine(self, path:str, **kwargs):
    """
    Schedules a calculated comment.

    Appends a
    [`_calc_routine()`][FoSpy.blocks._blockUtils._calc_routine]-decorated
    function to `self._calc_routines` to be run at
    [serialization][FoSpy.blocks.blocks.SingleBlock.serialize].

    Used to add calculated comments that should be refreshed during
    serialization.

    Args:
        path:
            a relative path string that can be resolved into a
            `_calc_routine()`-decorated function
        **kwargs (any):
            optional key word arguments to be passed to the function at
            path.

    Raises:
        TypeError:
            the attr or method at path is not registered as a
            _calc_routine

    Example:
    ```
        mySyn.add_calc_routine("materials.add_weight_pcts", typ="reagent")
        ## mySyn.materials.add_weight_pcts(typ="reagent") is now scheduled
        ## to run at serialization
    ```
    """
    from functools import wraps

    func = self._resolve_relative_path(path)
    if not getattr(func, "_is_calc_routine", False):
        raise TypeError(f"'{path}' is not a registered calc routine.")

    self._meta.routine_paths.append(path)

    @wraps(func)
    def wrapped():
        __name__ = func.__name__
        return func(**kwargs)

    self._calc_routines.append(wrapped)

add_comments

add_comments(*comments)

Default behavior to be overwritten when attached to a parent block.

If a SingleBlock is stored as an attribute of another SingleBlock, this method will be overwritten by the parent's __setattr__.

Source code in FoSpy/blocks/blocks.py

def add_comments(self, *comments):
    """
    Default behavior to be overwritten when attached to a parent block.

    If a `SingleBlock` is stored as an attribute of another `SingleBlock`,
    this method will be overwritten by the parent's `__setattr__`.
    """
    keys = list(self.get_req_validators())

    keys = [k for k in keys if k != "metadata"]
    fallback = [k for k in self._key_order if k != "metadata"]
    if not (keys or fallback):
        raise ValueError("This object has not been correctly attached to a parent block "
                         "and could not identify a required key to attach to.")

    first = keys[0] if keys else fallback[0]

    self._meta.comments.setdefault(first, [])
    for comment in comments:
        self._meta.comments[first].append(comment)

build_req_validators classmethod

build_req_validators()

Builds required keys and validators mapped to subclass.

Walks all parent classes and builds a map of all keys that are required during __init__, and their respective validation routines. Subclasses are mapped to expected keys and validations in parsing.validation. Subclass validations override parent classes when applicable.

Returns:

Name	Type	Description
merged	dict	Maps required keys to validation routines. Routines may be a class constructor or a func taking one arg.

Example:

>>> SingleBlock.build_req_validators()
{
    "name": str,
    "type": str,
    "formula": ChemFormula, # class constructor
    "supplier": str,
    "cas": str,
    "form": str,
    "env": str,
    "ratio": validators.material.ratio # validator function
}

Source code in FoSpy/blocks/blocks.py

@classmethod
def build_req_validators(cls):
    """
    Builds required keys and validators mapped to subclass.

    Walks all parent classes and builds a map of all keys that are required
    during `__init__`, and their respective validation routines. Subclasses
    are mapped to expected keys and validations in
    [`parsing.validation`][FoSpy.parsing.validation]. Subclass validations
    override parent classes when applicable.

    Returns:
        merged (dict):
            Maps required keys to validation routines. Routines may be
            a class constructor or a func taking one arg.
    Example:
        ``` 
        >>> SingleBlock.build_req_validators()
        {
            "name": str,
            "type": str,
            "formula": ChemFormula, # class constructor
            "supplier": str,
            "cas": str,
            "form": str,
            "env": str,
            "ratio": validators.material.ratio # validator function
        }
        ```
    """
    from ..parsing.validation import required_keys
    merged = {}
    for base in reversed(cls.__mro__):
        base_reqs = required_keys.get(base,{})
        for key, validator in base_reqs.items():
            # allow subclasses to remove parent requirements.
            if validator is False:
                merged.pop(key, None)
            else:
                merged[key] = validator
    return merged

build_validators classmethod

build_validators()

Builds expected keys and validators mapped to subclass.

Walks all parent classes and builds a map of all keys that are expected (required or optional), and their respective validation routines. Subclasses are mapped to keys and validations in parsing.validation. Subclass validations override parent classes when applicable.

See build_req_validators

Source code in FoSpy/blocks/blocks.py

@classmethod
def build_validators(cls):
    """
    Builds expected keys and validators mapped to subclass.

    Walks all parent classes and builds a map of all keys that are expected
    (required or optional), and their respective validation routines.
    Subclasses are mapped to keys and validations in
    [`parsing.validation`][FoSpy.parsing.validation]. Subclass validations
    override parent classes when applicable.

    See
    [`build_req_validators`][FoSpy.blocks.blocks.SingleBlock.build_req_validators]
    """
    from ..parsing.validation import required_keys, optional_keys
    merged = {}
    for base in reversed(cls.__mro__):
        for key_set in (required_keys, optional_keys):
            base_reqs = key_set.get(base,{})
            for key, validator in base_reqs.items():
                # allow subclasses to remove parent requirements.
                if validator is False:
                    merged.pop(key, None)
                else:
                    merged[key] = validator

    return merged

clear_all_comments

clear_all_comments()

Source code in FoSpy/blocks/blocks.py

def clear_all_comments(self):
    self._meta.comments = {}
    for attr, val in self.__dict__.items():
        if attr.startswith("_") or attr in self._reserved:
            continue
        if hasattr(val, "clear_all_comments"):
            val.clear_all_comments()

clear_comments

clear_comments()

Clear comments attached to top-level attributes only.

Source code in FoSpy/blocks/blocks.py

def clear_comments(self):
    """
    Clear comments attached to top-level attributes only.
    """
    self._meta.comments = {}

copy

copy()

Returns a deep-copy of self by serializing and reconstructing.

_calc_comments are not preserved during copy, but _calc_routines are. This prevents mutation of the comments when reconstructing.

Source code in FoSpy/blocks/blocks.py

def copy(self):
    """
    Returns a deep-copy of `self` by serializing and reconstructing.

    _calc_comments are not preserved during copy, but _calc_routines are.
    This prevents mutation of the comments when reconstructing.
    """
    cls = type(self)
    c_cmts = self._calc_comments.copy()
    self._calc_comments = {}

    new_obj =  cls.dispatch_subclass(self.serialize(keepListType=True))
    self._calc_comments = c_cmts

    return new_obj

default_key_order

default_key_order(deep=False)

Set to default attribute order for serialization.

Rearrange attribute order to the default order assigned by build_validators

Parameters:

Name	Type	Description	Default
deep	bool	When true, recursively calls default_key_order on any other SingleBlock objects stored in attributes.	False

Source code in FoSpy/blocks/blocks.py

def default_key_order(self, deep:bool=False):
    """
    Set to default attribute order for serialization.

    Rearrange attribute order to the default order assigned by
    [`build_validators`][FoSpy.blocks.blocks.SingleBlock.build_validators]

    Args:
        deep:
            When true, recursively calls `default_key_order` on any other
            `SingleBlock` objects stored in attributes.
    """
    new_order = []
    for key in self.get_validators():
        if key != "ext" and key in self.serialize(shallow=True):
            new_order.append(key)
    for key in self._key_order:
        if key not in new_order:
            new_order.append(key)
    self._key_order = new_order
    self._meta_to_front()

    if deep:
        for name, obj in self.__dict__.items():
            if not name.startswith("_") and hasattr(obj, "default_key_order"):
                obj.default_key_order(deep=True)

dispatch_subclass classmethod

dispatch_subclass(blockDict, **kwargs)

Recommended dispatcher to allow subclass delegation when constructing.

Overridden in some subclasses, usually to assign subclass based on the value of one or more properties.

Default behavior passes blockDict and **kwargs to __init__ constructor.

Source code in FoSpy/blocks/blocks.py

@classmethod
def dispatch_subclass(cls, blockDict:dict, **kwargs:any):
    """
    Recommended dispatcher to allow subclass delegation when constructing.

    Overridden in some subclasses, usually to assign subclass based on the
    value of one or more properties.

    Default behavior passes `blockDict` and `**kwargs` to `__init__`
    constructor.
    """
    # k: construct normally.
    return cls(blockDict,_dispatched=True, **kwargs)

get_req_validators

get_req_validators()

Overrides class validators with any renamed properties.

Similar to class method: build_req_validators, but uses _rename_validators to align any renamed properties with their original validators.

Source code in FoSpy/blocks/blocks.py

def get_req_validators(self):
    """
    Overrides class validators with any renamed properties.

    Similar to class method:
    [`build_req_validators`][FoSpy.blocks.blocks.SingleBlock.build_req_validators],
    but uses
    [`_rename_validators`][FoSpy.blocks.blocks.SingleBlock._rename_validators]
    to align any renamed properties with their original validators.
    """
    return self._rename_validators(self.build_req_validators())

get_validators

get_validators()

Overrides class validators with any renamed properties.

Similar to class method: build_validators, but uses _rename_validators to align any renamed properties with their original validators. Also adds any optional key overrides added by key$alias syntax.

Returns:

Name	Type	Description
vals	dict	maps expected keys to validation routines.

Source code in FoSpy/blocks/blocks.py

def get_validators(self):
    """
    Overrides class validators with any renamed properties.

    Similar to class method:
    [`build_validators`][FoSpy.blocks.blocks.SingleBlock.build_validators],
    but uses
    [`_rename_validators`][FoSpy.blocks.blocks.SingleBlock._rename_validators]
    to align any renamed properties with their original validators. Also
    adds any optional key overrides added by key$alias syntax.

    Returns:
        vals (dict): maps expected keys to validation routines.
    """
    vals = self._rename_validators(self.build_validators())
    if hasattr(self, "_key_overrides"):
        for key, val in self._key_overrides.items():
            vals[key] = val
    return vals

key_to_idx

key_to_idx(key, idx)

Reorder attributes for serialization.

Move any attribute name to a specific index in _key_order for serialization order. The invisible "metadata" key is always refreshed to the front of the list, so indices are effectively 1-based.

Parameters:

Name	Type	Description	Default
key	str	name of attribute to reorder	required
idx	int	new index in _key_order	required

Source code in FoSpy/blocks/blocks.py

def key_to_idx(self, key:str, idx:int):
    """
    Reorder attributes for serialization.

    Move any attribute name to a specific index in `_key_order` for
    serialization order. The invisible `"metadata"` key is always refreshed
    to the front of the list, so indices are effectively 1-based.

    Args:
        key: name of attribute to reorder
        idx: new index in _key_order
    """
    self._meta_to_front()
    try:
        old_idx = self._key_order.index(key)
        self._key_order.pop(old_idx)
    except:
        pass
    self._key_order.insert(idx, key)

keys_to_end

keys_to_end(*args)

Reorder attributes for serialization.

Move any attribute names in *args to the end of _key_order to be serialized last. Order within *args is maintained in result.

Source code in FoSpy/blocks/blocks.py

def keys_to_end(self, *args):
    """
    Reorder attributes for serialization.

    Move any attribute names in `*args` to the end of _key_order to be
    serialized last. Order within `*args` is maintained in result.
    """
    def remove_alias(key):
        return key.split("$")[0] if "$" in key else key
    for key in self.serialize(shallow=True):
        if not key.startswith("_") and remove_alias(key) not in self._key_order:
            self._key_order.append(remove_alias(key))
    for key in args:
        try:
            idx = self._key_order.index(key)
            self._key_order.pop(idx)
        except:
            pass
        self._key_order.append(key)
    self._meta_to_front()

keys_to_front

keys_to_front(*args)

Reorder attributes for serialization.

Move any attribute names in *args to the front of _key_order to be serialized first. Order within *args is maintained in result.

Source code in FoSpy/blocks/blocks.py

def keys_to_front(self,*args):
    """
    Reorder attributes for serialization.

    Move any attribute names in `*args` to the front of _key_order to be
    serialized first. Order within `*args` is maintained in result.
    """
    try:
        meta_idx = args.index("metadata")
        args.pop(meta_idx)
    except:
        pass

    new_order = []
    for key in args:
        new_order.append(key)
    for key in self._key_order:
        if key not in new_order:
            new_order.append(key)
    self._key_order = new_order
    self._meta_to_front()

list_avail_routines

list_avail_routines(
    recursive=False, prefix="", abbreviated=False
)

Lists all calc routines available to be added to self._calc_routines.

Non-abbreviated calc routine strings can be passed directly to self.add_calc_routine()

Parameters:

Name	Type	Description	Default
recursive	bool	If True, recursively walks all attributes and appends results from self.attr.list_avail_routines() to result. Otherwise only identifies methods of self.	False
prefix	str	Used during recursion to build relative paths	''
abbreviated	bool	optionally abbreviate recursively repeated routines for similar objects into one line. This line cannot be passed to self.add_calc_routine()	False

Returns:

Name	Type	Description
routines	list	list of strings describing _calc_routine-decorated methods. Non-abbreviated calc routine strings can be passed directly to self.add_calc_routine()

Example:

    mySyn.list_avail_routines()
    ## returns []
    mySyn.list_avail_routines(recursive=True)
    ## returns [
    ##     'reaction.add_nom_MW',
    ##     'materials.add_weight_pcts',
    ##     'materials[0].add_MW',
    ##     'materials[1].add_MW',
    ##     ... 6 total materials with the same calc_routine
    ##     'materials[5].add_MW'
    ## ]
    mySyn.list_avail_routines(recursive=True, abbreviated=True)
    ## returns [
    ##     'reaction.add_nom_MW',
    ##     'materials.add_weight_pcts',
    ##     'materials[i].add_MW; i = [0, 1, 2, 3, 4, 5]'
    ## ]

Source code in FoSpy/blocks/blocks.py

def list_avail_routines(self, recursive:bool=False, prefix:str="", abbreviated:bool=False):
    """
    Lists all calc routines available to be added to `self._calc_routines`.

    Non-abbreviated calc routine strings can be passed directly to
    `self.add_calc_routine()`

    Args:
        recursive:
            If True, recursively walks all attributes and appends results
            from `self.attr.list_avail_routines()` to result. Otherwise only
            identifies methods of `self`.

        prefix: Used during recursion to build relative paths
        abbreviated:
            optionally abbreviate recursively repeated routines for similar
            objects into one line. This line cannot be passed to
            `self.add_calc_routine()`

    Returns:
        routines (list): 
            list of strings describing _calc_routine-decorated methods.
            Non-abbreviated calc routine strings can be passed directly to
            `self.add_calc_routine()`

    Example:
    ```
        mySyn.list_avail_routines()
        ## returns []
        mySyn.list_avail_routines(recursive=True)
        ## returns [
        ##     'reaction.add_nom_MW',
        ##     'materials.add_weight_pcts',
        ##     'materials[0].add_MW',
        ##     'materials[1].add_MW',
        ##     ... 6 total materials with the same calc_routine
        ##     'materials[5].add_MW'
        ## ]
        mySyn.list_avail_routines(recursive=True, abbreviated=True)
        ## returns [
        ##     'reaction.add_nom_MW',
        ##     'materials.add_weight_pcts',
        ##     'materials[i].add_MW; i = [0, 1, 2, 3, 4, 5]'
        ## ]
    ```
    """
    routines = []

    # Local routines
    for name in dir(self):
        attr = getattr(self, name)
        if callable(attr) and getattr(attr, "_is_calc_routine", False):
            routines.append(prefix + name)

    if recursive:
        for attr, val in self.__dict__.items():
            if attr.startswith("_"):
                continue

            # Recurse into child blocks
            if hasattr(val, "list_avail_routines"):
                child_prefix = f"{prefix}{attr}."
                routines.extend(val.list_avail_routines(True, child_prefix, abbreviated))

    return routines

make_template

make_template(template_name, *args)

Converts self into a template of its original subclass.

Returns a copy of self as a template of its original subclass, with specified fields replaced with template types. See TemplateClass for more information on template generation.

Parameters:

Name	Type	Description	Default
template_name	str	All templates require an identifying name.	required
*args	str	properties to clear and replace with template types.	()

Source code in FoSpy/blocks/blocks.py

def make_template(self,template_name:str,*args:str):
    """
    Converts `self` into a template of its original subclass.

    Returns a copy of `self` as a template of its original subclass, with
    specified fields replaced with template types. See
    [`TemplateClass`][FoSpy.blocks.blocks.SingleBlock.TemplateClass] for
    more information on template generation.

    Args:
        template_name: All templates require an identifying name.
        *args: properties to clear and replace with template types.
    """

    from ..parsing.format_fos import format_field

    serial = self.serialize(keepListType=True)
    validators = self.get_validators()
    for key in args:
        val = validators.get(key, None)
        if isinstance(val,type) and (issubclass(val, SingleBlock) or issubclass(val, ListBlock)):
            serial[key] = []
        else:
            serial[key] = format_field("template")
    serial["template_name"] = template_name
    return type(self).TemplateClass(*args).dispatch_subclass(serial)

reflex classmethod

reflex(serialize=True, **kwargs)

Generate a flexible template for the current class.

Flexibly generates a template for the current class where any required properties missing from kwargs are automatically converted to template types (See FlexTemplate). Returns an instance of the flexible template constructed from kwargs, or a serial dictionary of that instance.

Parameters:

Name	Type	Description	Default
serialize	bool	Whether to return the serialized dictionary of the reflexed template, or the object itself.	True
**kwargs	str	Known properties to pass to the template constructor.	{}

Source code in FoSpy/blocks/blocks.py

@classmethod
def reflex(cls, serialize=True, **kwargs:dict):
    """
    Generate a flexible template for the current class.

    Flexibly generates a template for the current class where any required
    properties missing from `kwargs` are automatically converted to template
    types (See
    [`FlexTemplate`][FoSpy.blocks.template.FlexTemplate]).
    Returns an instance of the flexible template constructed from `kwargs`,
    or a serial dictionary of that instance.

    Args:
        serialize (bool):
            Whether to return the serialized dictionary of the reflexed
            template, or the object itself.
        **kwargs (str): Known properties to pass to the template constructor.
    """
    from .template import FlexTemplate
    class Flex(FlexTemplate, cls):
        _baseReq = cls

    kwargs.setdefault("template_name", f"Reflexed {cls.__name__}")

    empty = Flex.dispatch_subclass(kwargs)
    if serialize:
        return empty.serialize()
    return empty

refresh_attachments

refresh_attachments(
    new_copy=None, overwrite=None, **kwargs
)

Source code in FoSpy/blocks/blocks.py

def refresh_attachments(self, new_copy=None, overwrite=None, **kwargs):
    from .attachments import Attachment

    if new_copy is None:
        new_copy = self._att_new_copy
    if overwrite is None:
        overwrite = self._att_overwrite

    for propDict in self.__dict__, self.ext.__dict__:
        for key, val in propDict.items():
            if key.startswith("_") or key in self._reserved:
                continue
            if hasattr(val, "refresh_attachments"):
                val.refresh_attachments(new_copy=new_copy, overwrite=overwrite, **kwargs)
            elif isinstance(val, Attachment) and hasattr(val, "refresh"):
                val.refresh(new_copy=new_copy, overwrite=overwrite, **kwargs)

rename_block

rename_block(old, new)

Source code in FoSpy/blocks/blocks.py

def rename_block(self, old, new):
    validators = self.get_validators()
    req = self.get_req_validators()
    if True in [name.startswith("_") for name in (old, new)]:
        raise ValueError(f"You cannot set private attributes (starting with '_') using obj.rename_block()")

    if old in req and new in validators:
        raise ValueError(f"You cannot rename '{old}' to '{new}'. '{old}' is a required property that "
                            f"can only be renamed to an unregistered key; '{new}' is already registered "
                            "as an expected property.")

    if hasattr(self, new):
        raise ValueError(f"'{new}' is already a property for this object, you cannot overwrite it with "
                         "obj.rename_block()")

    if "rename" in (old, new):
        raise ValueError("obj.rename property cannot be set or changed by obj.rename_block()")

    if old in self._key_overrides:
        val = self._key_overrides.pop(old)
        self._key_overrides[new] = val
    else:
        _debug.msg(f"Registering '{old}':'{new}' into rename block")
        if not hasattr(self,"rename"):
            self.rename = {}
        setattr(self.rename, old, new)
    _debug.msg(f"Moving '{old}' over to '{new}'.")
    setattr(self,new,getattr(self, old))
    delattr(self,old)

    try:
        idx = self._key_order.index(old)
        self._key_order[idx] = new
    except:
        self._key_order.append(new)

serialize

serialize(keepListType=False, shallow=False, clean=False)

Return a recursively serialized dict representation of self.

Fully serialized SingleBlocks are a single dict that can be passed to another constructor or emitted into lines for a FOS file. Serialized values at any nest level are either dicts, lists, or strings to allow full type-coersion when reconstructing or simplified emission when writing files.

Serialized dict is deep copied to prevent object mutation.

Parameters:

Name	Type	Description	Default
keepListType	bool	When True, maintains its current FOS printing mode (looped keys or explicit key:value lines), instead of explicit default	False
shallow	bool	When True, no recursive serialization occurs. Recommended when serialization is used only to inspect top-level keys.	False
clean	bool	When True, no FOS format read/write metadata is included in the serial. Recommended for sending output to other formats like JSON.	False

Private attributes starting with "_" are either skipped or unpacked in special cases:

• _key_order: attributes are added to the serialized dict in the order they appear in this list.

• _calc_comments: calculated comments are attached to their mapped attribute after serialization to avoid mutation of object comments

• _calc_routines: A list of functions scheduled to be called right before serialization to update _calc_comments. Scheduling calc routines ensures that their calculated values are up-to-date.

• _meta: attributes of this container are given their own private _keys mapped by FoSpy.parsing.syntax.meta_keys in the serialized dict.

• _key_overrides: per-instance override mapping that tracks which unexpected attributes require $alias suffixes.

• _aliases: maps attribute names to alias tags used to emit $alias suffixed keys.

• _reserved: attribute names in reserved are non-private attributes which should not be serialized. This usually applies to the ext attribute or methods attached after construction.

Source code in FoSpy/blocks/blocks.py

def serialize(self, keepListType:bool=False, shallow:bool=False, clean:bool=False):
    """
    Return a recursively serialized `dict` representation of `self`.

    Fully serialized `SingleBlock`s are a single dict that can be passed to
    another constructor or emitted into lines for a FOS file. Serialized
    values at any nest level are either dicts, lists, or strings to allow
    full type-coersion when reconstructing or simplified emission when
    writing files.

    Serialized dict is deep copied to prevent object mutation.

    Args:
        keepListType:
            When True, maintains its current FOS printing mode (looped keys
            or explicit key:value lines), instead of explicit default

        shallow:
            When True, no recursive serialization occurs. Recommended when
            serialization is used only to inspect top-level keys.

        clean:
            When True, no FOS format read/write metadata is included in the
            serial. Recommended for sending output to other formats like
            JSON.

    Private attributes starting with "_" are either skipped or unpacked in
    special cases:

    * `_key_order`:
        attributes are added to the serialized dict in the order they
        appear in this list.

    * `_calc_comments`:
        calculated comments are attached to their mapped attribute after
        serialization to avoid mutation of object comments

    * `_calc_routines`:
        A list of functions scheduled to be called right before
        serialization to update _calc_comments. Scheduling calc routines
        ensures that their calculated values are up-to-date.

    * `_meta`:
        attributes of this container are given their own private `_key`s
        mapped by `FoSpy.parsing.syntax.meta_keys` in the serialized
        dict.

    * `_key_overrides`:
        per-instance override mapping that tracks which unexpected
        attributes require $alias suffixes.

    * `_aliases`:
        maps attribute names to alias tags used to emit $alias suffixed
        keys.

    * `_reserved`:
        attribute names in reserved are non-private attributes which
        should *not* be serialized. This usually applies to the `ext`
        attribute or methods attached after construction.
    """
    from copy import deepcopy
    from ..parsing.format_fos import format_calc_comment
    from .template import TemplateBlock

    val_to_alias = {v:k for k,v in self._aliases.items()}

    all_attrs = {}
    out = {}

    for routine in self._calc_routines:
        routine()

    def add_alias(key):
        if key in self._key_overrides:
            alias = val_to_alias[self._key_overrides[key]]
            return f"{key}${alias}"
        return key


    def try_serial(obj):
        serialize = getattr(obj, "serialize", None)
        if isinstance(obj, SimpleWrapper):
            obj = obj()
        if callable(serialize) and not shallow:
            return obj.serialize(clean=clean)
        if isinstance(obj, list):
            return [try_serial(item) for item in obj]
        if isinstance(obj, dict):
            return {k:try_serial(v) for k,v in obj.items()}
        return str(obj)

    for attr,val in self.__dict__.items():
        if attr == "ext" and val is not None:
            for ext_attr, ext_val in val.__dict__.items():
                all_attrs[ext_attr] = ext_val
        elif not (attr.startswith("_") or attr in self._reserved):
            all_attrs[attr] = val


    for key in self._key_order:
        if key in all_attrs:
            val = all_attrs.pop(key)
            out[add_alias(key)] = try_serial(val)

    for key, val in all_attrs.items():
        out[add_alias(key)] = try_serial(val)

    for attr, key in mk.items():
        try:
            k = md[key].copy()
        except:
            k = md[key]
        val = getattr(self._meta,attr,k)
        out[key] = val

    comments = {}
    for key, comment_list in out[mk["comments"]].items():
        comments[add_alias(key)] = comment_list
    out[mk["comments"]] = comments

    out = deepcopy(out)

    # _debug.pmsg(self._calc_comments)
    for key, comments in self._calc_comments.items():
        for comment in comments.values():
            out[mk["comments"]].setdefault(add_alias(key),[])
            out[mk["comments"]][add_alias(key)].append(format_calc_comment(comment))

    if not keepListType:
        out[mk["list_type"]] = "explicit"

    if "template_name" in out and not isinstance(self, TemplateBlock):
        out.pop("template_name")

    if clean:
        scan = out.copy()
        for key, val in scan.items():
            if key.startswith("_") or val is None:
                out.pop(key)

    return out

to_json

to_json(filepath=None, clean=True, indent=4, **kwargs)

Converts self into a JSON-formatted string or file.

Serializes and either returns as a JSON-formatted string or saves to a JSON file.

Parameters:

Name	Type	Description	Default
filepath	pathlike	JSON file save destination. If None, returns JSON-formatted string instead.	None
clean	bool	When True, no FOS format read/write metadata is included in the serial. FOS metadata has no impact on JSON format but may be useful to view in JSON for troubleshooting.	True
indent	int	indent value passed to json.dump for file saving.	4
**kwargs	any	other arguments passed to json.dump for file saving.	{}

Source code in FoSpy/blocks/blocks.py

def to_json(self, filepath=None, clean:bool=True, indent:int=4, **kwargs):
    """
    Converts `self` into a JSON-formatted string or file.

    [Serializes][FoSpy.blocks.blocks.SingleBlock.serialize] and either
    returns as a JSON-formatted string or saves to a JSON file.

    Args:
        filepath (pathlike):
            JSON file save destination. If `None`, returns JSON-formatted
            string instead.

        clean:
            When True, no FOS format read/write metadata is included in the
            serial. FOS metadata has no impact on JSON format but may be
            useful to view in JSON for troubleshooting.

        indent:
            `indent` value passed to `json.dump` for file saving.

        **kwargs (any):
            other arguments passed to `json.dump` for file saving.
    """
    import json
    serial = self.serialize(clean=clean)

    if filepath is None:
        return json.dumps(serial)

    with open(filepath, "w") as f:
        json.dump(serial, f, indent=indent, **kwargs)

dict_from_file

dict_from_file(filepath)

Source code in FoSpy/parsing/read.py

def dict_from_file(filepath):
    blocks = {}
    comments = {}
    current_block = "metadata"
    current_type = "single"
    embedding = False
    break_line = None
    break_num = 0
    with open(filepath, "r", encoding="utf-8") as f:
        endComments = []
        for line in f:
            break_num += 1
            if rx.EMBEDDED_END.match(line):
                embedding = False
                block.append(line)
                continue

            if embedding:
                if rx.EMBEDDED_START.match(line):
                    break_line = line
                    break
                block.append(line)
                continue

            txt = line.strip()     
            if txt == "" or rx.CALC_COMMENT_LINE.match(txt):
                continue

            if rx.EMBEDDED_START.match(txt):
                _debug.msg(f"Starting Embedding on line: {txt}")
                embedding = True

            block = blocks.get(current_block)
            if block is None:
                blocks[current_block] = (current_type,[])
                block = blocks[current_block][1]
            else:
                block = block[1]


            m = rx.BLOCK_HEADER.match(txt)
            if m:
                name_found = False
                for regex_name, typ in zip(("list_name", "single_name"),("list","single")):
                    if m.group(regex_name) is not None:
                        current_block = m.group(regex_name).lower()
                        current_type = typ
                        name_found = True
                        break
                if not name_found:
                    raise SyntaxError(f"Line: '{txt}' was identified as a block header but no header name could be identified")

                #_debug.msg(f"Identified {current_type} block header in line: {txt}")
                #_debug.msg(f"Block name: {current_block}")

                comments[current_block] = [rx.COMMENT_LINE.match(l).group("text").lstrip() for l in endComments]
                endComments = []
                continue

            if rx.COMMENT_LINE.match(txt):
                endComments.append(txt)
                continue

            for l in [*endComments,txt]:
                block.append(l.strip())
            endComments = []
    if embedding:
        raise SyntaxError("An embedded document was never closed before the end of the file or starting a new embed.\n"
                          f"Current Line (line #{break_num}): {"<end of FOS file>\n" if not break_line else break_line}"
                          "Ensure that there are spaces between '#', 'END FOS EMBED', and '}}}' when ending an "
                          "embedded document.")

    for block, (typ, lines) in blocks.items():
        if typ == "single":
            blockDict = create_single_block_dict(lines)
            if blockDict == {}:
                blocks[block] = []
            else:
                blocks[block] = [blockDict]
        elif typ == "list":
            blocks[block] = create_list_block_dict(lines)
        else:
            raise ValueError(f"Unrecognized block type: '{typ}', expected either single or list")
    blocks[mk["comments"]] = comments

    for meta_key in mk.values():
        if meta_key not in blocks:
            try:
                blocks[meta_key] = md[meta_key].copy()
            except:
                blocks[meta_key] = md[meta_key]

    return blocks

write_dict_to_file

write_dict_to_file(blocks, filepath)

Source code in FoSpy/parsing/write.py

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