DFProject

DFProject acts as a container for all other schema nodes allowing complex design hierarchies, interconnect definitions, and constants to be transferred between different parts of the workflow. It acts as the root node when dumping out the design, and drives the re-construction of all elements when loading back from file.

The project contains a list of nodes - these are separated into two categories:

  • Principal nodes are nominated objects that provide focus to downstream workflow stages (i.e. those that reload a dumped design). For example, it might be used to nominate specific top-level blocks that you want to be automatically generated by a code templating engine.

  • Reference nodes contain further information about the design that is needed to support the principal nodes. For example, these might be used to declare the interconnects used by different ports throughout the hierarchy, as in this case they won’t be the primary focus for downstream tools.

Principal nodes are nominated by setting a PRINCIPAL attribute to true on the node in question.

Just like every other tag, DFProject inherits from DFBase, so has support for all of the core attributes (id, description, and attributes).

{
    "id": "my_design",
    "description": "My fantastic hierarchical design",
    "attributes": { },
    "created": 1562319325309,
    "path": "/path/to/my/root/document.yaml",
    "version": 1.3,
    "nodes": [
        {
            "__type__": "DFBlock",
            "__dump__": {
                "id": "principal_node",
                "attributes": { "PRINCIPAL": true }
            }
        },
        {
            "__type__": "DFInterconnect",
            "__dump__": {
                "id": "reference_node",
                "attributes": { }
            }
        }
    ]
}
Property Usage
created Date that the project was created, in milliseconds since epoch
path Path to the source file used to create the project
version Version of the DesignFormat project, to detect compatibility
nodes List of encapsulated dumped nodes, see note below on encapsulation

Note

As discussed in the Storage Format section, dumped nodes in the DFProject definition are encapsulated to help the library identify what type they represent. As shown above __type__ indicates which schema node the data refers to, while __dump__ contains the dumped data from the node.

Python API

class designformat.project.DFProject(id=None, path=None)

DesignFormat top level project container, can collect nodes of different types which can be dumped out as a single entity and re-imported, automatically classifying the nodes. Nodes can be marked as ‘principal’ entities, in order to specify a focus for downstream tools.

__init__(id=None, path=None)

Constructor for the project object.

Parameters

  • id – Name for the project

  • path – Path to the source file used to create the project

addPrincipalNode(node)

Add a new principal node to the project. The principal attribute can be applied to as many nodes as required, but should be used to provide a focus for downstream tools.

Parameters

node – Any instance inheriting from DFBase

addReferenceNode(node)

Add a new non-principal node, this should be used for object types that are referenced by another object in the design. For example, it can be used to store an interconnect definition, which can then be referred to by a port.

Parameters

node – Any instance inheriting from DFBase

dumpObject()

Dump out the project into a primitive dictionary, suitable for reloading at a later date. This dictionary can be separately saved to file as JSON.

findNode(id, type)

Return a node matching a specific ID and type

Parameters

  • id – The ID value to match

  • type – The class type to match

getAllPrincipalNodes(desired=None)

Return a list of principal nodes held in the project, optionally filtering for a specific type of object.

Parameters

desired – The optional object type to filter for

getAllUsedInterconnectionTypes()

Return a unique, ordered list of all of the interconnect types used in the design. This is not the same as a list of all interconnect types stored in the project, as the project may contain interconnects that are not instantiated.

getDefinition(key)

Return a DFDefine matching a specific identifier

Parameters

def – The name of the define to match

getInterconnectType(intc_id)

Return a DFInterconnect matching a specific identifier.

Parameters

intc_id – The ID to match

loadObject(obj)

Populate this project with data from a primitive dictionary that has been previously dumped. This will construct child nodes, and then populate them with relevant details.

Parameters

obj – The dictionary to reload from

mergeProject(project)

Merge another DFProject with this project

Parameters

project – The DFProject instance to merge with

resolvePath(path)

Return a port or block definition based on a hierarchical path, only examines principal DFBlock nodes.

Parameters

path – The hierarchical path to resolve

Javascript API

class DFProject(id, path)

DesignFormat top level project container, can collect nodes of different types which can be dumped out as a single entity and re-imported, automatically classifying the nodes. Nodes can be marked as ‘principal’ entities, in order to specify a focus for downstream tools.

Constructor for the project object.

Arguments

  • id (string) – Name for the project

  • path (string) – Path to the source file used to create the project

DFProject.addPrincipalNode(node)

Add a new principal node to the project. The principal attribute can be applied to as many nodes as required, but should be used to provide a focus for downstream tools.

Arguments

  • node (DFBase) – Any instance inheriting from DFBase

DFProject.addReferenceNode(node)

Add a new non-principal node, this should be used for object types that are referenced by another object in the design. For example, it can be used to store an interconnect definition, which can then be referred to by a port.

Arguments

  • node (DFBase) – Any instance inheriting from DFBase

DFProject.dumpObject()

Dump out the project into a primitive dictionary, suitable for reloading at a later date. This dictionary can be separately saved to file as JSON.

DFProject.findNode(id, type)

Return a node matching a specific ID and type

Arguments

  • id (string) – The ID value to match

  • type (class) – The class type to match

DFProject.getAllPrincipalNodes(desired)

Return a list of principal nodes held in the project, optionally filtering for a specific type of object.

Arguments

  • desired (class) – The optional object type to filter for

DFProject.getAllUsedInterconnectionTypes()

Return a unique, ordered list of all of the interconnect types used in the design. This is not the same as a list of all interconnect types stored in the project, as the project may contain interconnects that are not instantiated.

DFProject.getDefinition(def)

Return a DFDefine matching a specific identifier

Arguments

  • def (string) – The name of the define to match

DFProject.getInterconnectType(intc_id)

Return a DFInterconnect matching a specific identifier.

Arguments

  • intc_id (string) – The ID to match

DFProject.loadObject(obj)

Populate this project with data from a primitive dictionary that has been previously dumped. This will construct child nodes, and then populate them with relevant details.

Arguments

  • obj (object) – The dictionary to reload from

DFProject.mergeProject(project)

Merge another DFProject with this project

Arguments

  • project (DFProject) – The DFProject instance to merge with

DFProject.resolvePath(path)

Return a port or block definition based on a hierarchical path, only examines principal DFBlock nodes.

Arguments

  • path (string) – The hierarchical path to resolve