siliconcompiler 0.32.3__py3-none-any.whl → 0.33.0__py3-none-any.whl

siliconcompiler/{sphinx_ext → schema/docs}/schemagen.py

@@ -5,8 +5,9 @@ from docutils.statemachine import ViewList
 from sphinx.util.docutils import SphinxDirective
 
 import siliconcompiler
-from siliconcompiler.schema import Schema
-from siliconcompiler.sphinx_ext.utils import (
+from siliconcompiler import Schema
+from siliconcompiler.schema import utils, PerNode
+from siliconcompiler.schema.docs.utils import (
     strong,
     code,
     para,
@@ -15,8 +16,7 @@ from siliconcompiler.sphinx_ext.utils import (
     build_section_with_target,
     build_list
 )
-from siliconcompiler.schema import utils
-from siliconcompiler.sphinx_ext import sc_root as SC_ROOT
+from siliconcompiler.schema.docs import sc_root as SC_ROOT
 
 
 # Main Sphinx plugin
@@ -28,72 +28,71 @@ class SchemaGen(SphinxDirective):
         self.env.note_dependency(__file__)
         self.env.note_dependency(utils.__file__)
 
-        schema = Schema().cfg
-
-        return self.process_schema(schema)
-
-    def process_schema(self, schema, parents=[]):
-        if 'help' in schema:
-            entries = [[strong('Description'), para(schema['shorthelp'])],
-                       [strong('Type'), para(schema['type'])]]
-
-            if schema['pernode'] != utils.PerNode.NEVER:
-                entries.append([strong('Per step/index'), para(schema['pernode'])])
-
-            entries.append([strong('Scope'), para(schema['scope'])])
-
-            if 'enum' in schema['type']:
-                entries.append([strong('Allowed Values'),
-                                build_list([code(val) for val in schema['enum']])])
-
-            if 'unit' in schema:
-                entries.append([strong('Unit'), para(schema['unit'])])
-
-            defvalue = schema['node']['default']['default']['value']
-            switch_list = [code(switch) for switch in schema['switch']]
-            entries.extend([[strong('Default Value'), para(defvalue)],
-                            [strong('CLI Switch'), build_list(switch_list)]])
-
-            examples = {}
-            for example in schema['example']:
-                name, ex = example.split(':', 1)
-                examples.setdefault(name, []).append(ex)
-
-            for name, exs in examples.items():
-                examples = [code(ex.strip()) for ex in exs]
-                p = None
-                for ex in examples:
-                    if not p:
-                        p = para("")
-                    else:
-                        p += para("")
-                    p += ex
-                entries.append([strong(f'Example ({name.upper()})'), p])
-
-            table = build_table(entries, colwidths=[25, 75])
-            body = self.parse_rst(utils.trim(schema['help']))
-
-            return [table, body]
-        else:
-            sections = []
-            for key in schema.keys():
-                if key == 'default':
-                    for n in self.process_schema(schema['default'], parents=parents):
-                        sections.append(n)
+        self.schema = Schema()
+
+        return self.process_schema([])
+
+    def process_parameter(self, parameter):
+        entries = [[strong('Description'), para(parameter.get(field='shorthelp'))],
+                   [strong('Type'), para(parameter.get(field='type'))]]
+
+        if parameter.get(field='pernode') != PerNode.NEVER:
+            entries.append([strong('Per step/index'),
+                            para(str(parameter.get(field='pernode').value).lower())])
+
+        entries.append([strong('Scope'), para(str(parameter.get(field='scope').value).lower())])
+
+        if parameter.get(field='unit'):
+            entries.append([strong('Unit'), para(parameter.get(field='unit'))])
+
+        switch_list = [code(switch) for switch in parameter.get(field='switch')]
+        entries.extend([[strong('Default Value'), para(parameter.default.get())],
+                        [strong('CLI Switch'), build_list(switch_list)]])
+
+        examples = {}
+        for example in parameter.get(field='example'):
+            name, ex = example.split(':', 1)
+            examples.setdefault(name, []).append(ex)
+
+        for name, exs in examples.items():
+            examples = [code(ex.strip()) for ex in exs]
+            p = None
+            for ex in examples:
+                if not p:
+                    p = para("")
                 else:
-                    if not parents and key in ('history', 'library'):
-                        continue
-                    section_key = 'param-' + '-'.join(parents + [key])
-                    section = build_section_with_target(key, section_key, self.state.document)
-                    for n in self.process_schema(schema[key], parents=parents + [key]):
-                        section += n
-                    sections.append(section)
-
-            # Sort all sections alphabetically by title. We may also have nodes
-            # in this list that aren't sections if  `schema` has a 'default'
-            # entry that's a leaf. In this case, we sort this as an empty string
-            # in order to put this node at the beginning of the list.
-            return sorted(sections, key=lambda s: s[0][0] if isinstance(s, nodes.section) else '')
+                    p += para("")
+                p += ex
+            entries.append([strong(f'Example ({name.upper()})'), p])
+
+        table = build_table(entries, colwidths=[25, 75])
+        body = self.parse_rst(utils.trim(parameter.get(field='help')))
+
+        return [table, body]
+
+    def process_schema(self, keypath):
+        if self.schema.valid(*keypath, default_valid=True, check_complete=True):
+            return self.process_parameter(self.schema.get(*keypath, field=None))
+
+        sections = []
+        if self.schema.valid(*keypath, "default"):
+            for n in self.process_schema(keypath + ["default"]):
+                sections.append(n)
+        for key in self.schema.getkeys(*keypath):
+            if not keypath and key in ('history', 'library'):
+                continue
+            section_key = 'param-' + '-'.join(
+                [key for key in (keypath + [key]) if key != "default"])
+            section = build_section_with_target(key, section_key, self.state.document)
+            for n in self.process_schema(keypath + [key]):
+                section += n
+            sections.append(section)
+
+        # Sort all sections alphabetically by title. We may also have nodes
+        # in this list that aren't sections if  `schema` has a 'default'
+        # entry that's a leaf. In this case, we sort this as an empty string
+        # in order to put this node at the beginning of the list.
+        return sorted(sections, key=lambda s: s[0][0] if isinstance(s, nodes.section) else '')
 
     def parse_rst(self, content):
         rst = ViewList()
@@ -143,17 +142,6 @@ class CategorySummary(SphinxDirective):
 
 class CategoryGroupTable(SphinxDirective):
 
-    def count_keys(self, schema, *keypath):
-        cfgs = schema.getdict(*keypath)
-        count = 0
-        for key, cfg in cfgs.items():
-            if schema._is_leaf(cfg):
-                count += 1
-            else:
-                count += self.count_keys(schema, *keypath, key)
-
-        return count
-
     def run(self):
         self.env.note_dependency(__file__)
 
@@ -182,22 +170,22 @@ class CategoryGroupTable(SphinxDirective):
             "arg": "",
         }
 
-        schema = Schema()
+        self.schema = Schema()
 
         # Check if all groups have desc
-        for group in schema.getkeys():
+        for group in self.schema.getkeys():
             if group not in desc:
                 raise ValueError(f"{group} not found in group descriptions")
 
         # Check if all groups have schema
         for group in desc.keys():
-            if group not in schema.getkeys():
+            if group not in self.schema.getkeys():
                 raise ValueError(f"{group} not found in schema")
 
         table = [[strong('Group'), strong('Parameters'), strong('Description')]]
 
         total = 0
-        for group in schema.getkeys():
+        for group in self.schema.getkeys():
             text = desc[group]
             if len(text) == 0:
                 continue
@@ -205,7 +193,7 @@ class CategoryGroupTable(SphinxDirective):
             key = para('')
             key += keypath([group], self.env.docname)
 
-            count = self.count_keys(schema, group)
+            count = len(self.schema.allkeys(group, include_default=True))
             total += count
 
             table.append([key, para(f'{count}'), para(text)])

siliconcompiler/{sphinx_ext → schema/docs}/utils.py

@@ -1,7 +1,7 @@
 from docutils import nodes
 import sphinx.addnodes
 
-from siliconcompiler.schema import Schema
+from siliconcompiler import Schema
 
 
 # Docutils helpers
@@ -127,32 +127,31 @@ def keypath(key_path, refdoc, key_text=None):
     '''Helper function for displaying Schema keypaths.'''
     text_parts = []
     key_parts = []
-    cfg = Schema().cfg
+    schema = Schema()
     for key in key_path:
-        if list(cfg.keys()) != ['default']:
-            text_parts.append(f"'{key}'")
-            key_parts.append(key)
-            try:
-                cfg = cfg[key]
-            except KeyError:
-                raise ValueError(f'Invalid keypath {key_path}')
-        else:
-            cfg = cfg['default']
+        if schema.valid(*key_parts, "default", default_valid=True):
+            key_parts.append("default")
             if key.startswith('<') and key.endswith('>'):
                 # Placeholder
                 text_parts.append(key)
             else:
                 # Fully-qualified
                 text_parts.append(f"'{key}'")
+        else:
+            key_parts.append(key)
+            text_parts.append(f"'{key}'")
+
+        if not schema.valid(*key_parts, default_valid=True):
+            raise ValueError(f'Invalid keypath {key_path}')
 
-    if 'help' not in cfg:
+    if not schema.valid(*key_parts, default_valid=True, check_complete=True):
         # Not leaf
         text_parts.append('...')
 
     if key_text:
         text_parts = key_text
     text = f"[{', '.join(text_parts)}]"
-    refid = get_ref_id('param-' + '-'.join(key_parts))
+    refid = get_ref_id('param-' + '-'.join([key for key in key_parts if key != "default"]))
 
     opt = {'refdoc': refdoc,
            'refdomain': 'sc',

siliconcompiler/schema/editableschema.py

@@ -0,0 +1,136 @@
+# Copyright 2025 Silicon Compiler Authors. All Rights Reserved.
+
+# NOTE: this file cannot rely on any third-party dependencies, including other
+# SC dependencies outside of its directory, since it may be used by tool drivers
+# that have isolated Python environments.
+
+from .parameter import Parameter
+from .baseschema import BaseSchema
+
+
+class EditableSchema:
+    '''
+    This class provides access to modify the underlying schema.
+    This should only be used when creating new schema entries.
+
+    Args:
+        schema (:class:`BaseSchema`): schema to modify
+    '''
+
+    def __init__(self, schema):
+        # Grab manifest from base class
+        self.__schema = schema
+
+    def __insert(self, keypath, value, fullkey, clobber):
+        key = keypath[0]
+        keypath = keypath[1:]
+
+        if len(keypath) == 0:
+            if key in self.__schema._BaseSchema__manifest and not clobber:
+                raise KeyError(f"[{','.join(fullkey)}] is already defined")
+
+            if key == "default":
+                self.__schema._BaseSchema__default = value
+            else:
+                self.__schema._BaseSchema__manifest[key] = value
+            return
+
+        new_schema = BaseSchema()
+        if key == "default":
+            if self.__schema._BaseSchema__default:
+                new_schema = self.__schema._BaseSchema__default
+            else:
+                self.__schema._BaseSchema__default = new_schema
+        else:
+            new_schema = self.__schema._BaseSchema__manifest.setdefault(key, new_schema)
+        EditableSchema(new_schema).__insert(keypath, value, fullkey, clobber)
+
+    def __remove(self, keypath, fullkey):
+        key = keypath[0]
+        keypath = keypath[1:]
+
+        if key == "default":
+            next_param = self.__schema._BaseSchema__default
+        else:
+            next_param = self.__schema._BaseSchema__manifest.get(key, None)
+
+        if not next_param:
+            raise KeyError(f"[{','.join(fullkey)}] cannot be found")
+
+        if len(keypath) == 0:
+            if key == "default":
+                self.__schema._BaseSchema__default = None
+            else:
+                del self.__schema._BaseSchema__manifest[key]
+        else:
+            EditableSchema(next_param).__remove(keypath, fullkey)
+
+    def insert(self, *args, clobber=False):
+        '''
+        Inserts a :class:`Parameter` or a :class:`BaseSchema` to the schema,
+        based on the keypath and value provided in the ``*args``.
+
+        Args:
+            args (list): Parameter keypath followed by a item to add.
+            clobber (boolean): If true, will overwrite existing value,
+                otherwise will raise a KeyError if it is already defined.
+
+        Examples:
+            >>> schema.insert('option', 'value', Parameter('str'))
+            Adds the keypath [option,value] with a string parameter.
+        '''
+
+        value = args[-1]
+        keypath = args[0:-1]
+
+        if not keypath:
+            raise ValueError("A keypath is required")
+
+        if any([not isinstance(key, str) for key in keypath]):
+            raise ValueError("Keypath must only be strings")
+
+        if not isinstance(value, (Parameter, BaseSchema)):
+            raise ValueError(f"Value ({type(value)}) must be schema type: Parameter, BaseSchema")
+
+        self.__insert(keypath, value, keypath, clobber=clobber)
+
+    def remove(self, *keypath):
+        '''
+        Removes a keypath from the schema.
+
+        Args:
+            keypath (list): keypath to be removed.
+
+        Examples:
+            >>> schema.remove('option', 'value')
+            Removes the keypath [option,value] from the schema.
+        '''
+
+        if not keypath:
+            raise ValueError("A keypath is required")
+
+        if any([not isinstance(key, str) for key in keypath]):
+            raise ValueError("Keypath must only be strings")
+
+        self.__remove(keypath, keypath)
+
+    def search(self, *keypath):
+        '''
+        Finds an item in the schema. This will raise a KeyError if
+        the path is not found.
+
+        Args:
+            keypath (list): keypath to be found.
+
+        Examples:
+            >>> schema.search('option', 'value')
+            Returns the parameter stored in at [option,value].
+        '''
+
+        if not keypath:
+            raise ValueError("A keypath is required")
+
+        if any([not isinstance(key, str) for key in keypath]):
+            raise ValueError("Keypath must only be strings")
+
+        return self.__schema._BaseSchema__search(*keypath, require_leaf=False)

siliconcompiler/schema/journalingschema.py

@@ -0,0 +1,238 @@
+import copy
+import types
+
+from .baseschema import BaseSchema
+from .baseschema import json
+
+
+class JournalingSchema(BaseSchema):
+    """
+    This class provides the ability to record the schema transactions:
+    :meth:`set`, :meth:`add`, :meth:`remove`, and :meth:`unset`.
+
+    Args:
+        schema (:class:`BaseSchema`): schema to track
+        keyprefix (list of str): keypath to prefix on to recorded path
+    """
+
+    def __init__(self, schema, keyprefix=None):
+        if not isinstance(schema, BaseSchema):
+            raise TypeError(f"schema must be of BaseSchema type, not: {type(schema)}")
+        if isinstance(schema, JournalingSchema):
+            raise TypeError("schema must be of cannot be a JournalingSchema")
+
+        self.__schema = schema
+
+        journal_attrs = dir(self)
+
+        # Transfer access to internal schema
+        for param, value in self.__schema.__dict__.items():
+            setattr(self, param, value)
+        for param in dir(type(self.__schema)):
+            if param in journal_attrs:
+                continue
+            method = getattr(type(self.__schema), param)
+            if callable(method):
+                setattr(self, param, types.MethodType(method, self))
+
+        if not keyprefix:
+            self.__keyprefix = tuple()
+        else:
+            self.__keyprefix = tuple(keyprefix)
+
+        self.__record_types = set()
+        self.stop_journal()
+
+        self.__parent = self
+
+    def get(self, *keypath, field='value', step=None, index=None):
+        get_ret = super().get(*keypath, field=field, step=step, index=index)
+        self.__record_journal("get", keypath, field=field, step=step, index=index)
+        if field == 'schema':
+            child = JournalingSchema(get_ret, keyprefix=[*self.__keyprefix, *keypath])
+            child.__parent = self.__parent
+            return child
+
+        return get_ret
+
+    def set(self, *args, field='value', clobber=True, step=None, index=None):
+        ret = super().set(*args, field=field, clobber=clobber, step=step, index=index)
+        if ret:
+            *keypath, value = args
+            self.__record_journal("set", keypath, value=value, field=field, step=step, index=index)
+        return ret
+
+    def add(self, *args, field='value', step=None, index=None):
+        ret = super().add(*args, field=field, step=step, index=index)
+        if ret:
+            *keypath, value = args
+            self.__record_journal("add", keypath, value=value, field=field, step=step, index=index)
+        return ret
+
+    def remove(self, *keypath):
+        self.__record_journal("remove", keypath)
+        return super().remove(*keypath)
+
+    def unset(self, *keypath, step=None, index=None):
+        self.__record_journal("unset", keypath, step=step, index=index)
+        return super().unset(*keypath, step=step, index=index)
+
+    def _from_dict(self, manifest, keypath, version=None):
+        if "__journal__" in manifest:
+            self.__journal = manifest["__journal__"]
+            del manifest["__journal__"]
+
+        self.__schema._from_dict(manifest, keypath, version=version)
+
+    def getdict(self, *keypath, include_default=True):
+        manifest = super().getdict(*keypath, include_default=include_default)
+
+        if self.__journal:
+            manifest["__journal__"] = self.get_journal()
+
+        return manifest
+
+    def get_journal(self):
+        """
+        Returns a copy of the current journal
+        """
+
+        return copy.deepcopy(self.__journal)
+
+    def is_journaling(self):
+        """
+        Returns true if the schema is currently setup for journaling
+        """
+        return self.__journal is not None
+
+    def get_journaling_types(self):
+        """
+        Returns the current schema accesses that are being recorded
+        """
+
+        return self.__record_types.copy()
+
+    def add_journaling_type(self, value):
+        """
+        Adds a new access type to the journal record.
+
+        Args:
+            value (str): access type
+        """
+
+        if value not in ("set", "add", "remove", "unset", "get"):
+            raise ValueError(f"{value} is not a valid type")
+
+        return self.__record_types.add(value)
+
+    def remove_journaling_type(self, value):
+        """
+        Removes a new access type to the journal record.
+
+        Args:
+            value (str): access type
+        """
+
+        try:
+            self.__record_types.remove(value)
+        except KeyError:
+            pass
+
+    def get_base_schema(self):
+        """
+        Returns the base schema
+        """
+
+        return self.__schema
+
+    def __record_journal(self, record_type, key, value=None, field=None, step=None, index=None):
+        '''
+        Record the schema transaction
+        '''
+
+        if self.__parent.__journal is None:
+            return
+
+        if record_type not in self.__parent.__record_types:
+            return
+
+        self.__parent.__journal.append({
+            "type": record_type,
+            "key": tuple([*self.__keyprefix, *key]),
+            "value": value,
+            "field": field,
+            "step": step,
+            "index": index
+        })
+
+    def start_journal(self):
+        '''
+        Start journaling the schema transactions
+        '''
+        self.__journal = []
+        self.add_journaling_type("set")
+        self.add_journaling_type("add")
+        self.add_journaling_type("remove")
+        self.add_journaling_type("unset")
+
+    def stop_journal(self):
+        '''
+        Stop journaling the schema transactions
+        '''
+        self.__journal = None
+        self.__record_types.clear()
+
+    def read_journal(self, filename):
+        '''
+        Reads a manifest and replays the journal
+        '''
+
+        with open(filename) as f:
+            data = json.loads(f.read())
+
+        self.import_journal(cfg=data)
+
+    def import_journal(self, schema=None, cfg=None):
+        '''
+        Import the journaled transactions from a different schema.
+        Only one argument is supported at a time.
+
+        Args:
+            schema (:class:`JournalingSchema`): schema to replay transactions from
+            cfg (dict): dictionary to replay transactions from
+        '''
+
+        if schema and cfg:
+            raise ValueError("only one argument is supported")
+
+        journal = []
+        if schema:
+            if isinstance(schema, JournalingSchema):
+                journal = schema.__journal
+            else:
+                raise TypeError(f"schema must be a JournalingSchema, not {type(schema)}")
+        elif cfg and "__journal__" in cfg:
+            journal = cfg["__journal__"]
+
+        if journal is None:
+            return
+
+        for action in journal:
+            record_type = action['type']
+            keypath = action['key']
+            value = action['value']
+            field = action['field']
+            step = action['step']
+            index = action['index']
+            if record_type == 'set':
+                self.set(*keypath, value, field=field, step=step, index=index)
+            elif record_type == 'add':
+                self.add(*keypath, value, field=field, step=step, index=index)
+            elif record_type == 'unset':
+                self.unset(*keypath, step=step, index=index)
+            elif record_type == 'remove':
+                self.remove(*keypath)
+            elif record_type == 'get':
+                continue
+            else:
+                raise ValueError(f'Unknown record type {record_type}')

siliconcompiler/schema/namedschema.py

@@ -0,0 +1,41 @@
+# Copyright 2025 Silicon Compiler Authors. All Rights Reserved.
+
+# NOTE: this file cannot rely on any third-party dependencies, including other
+# SC dependencies outside of its directory, since it may be used by tool drivers
+# that have isolated Python environments.
+
+from .baseschema import BaseSchema
+
+
+class NamedSchema(BaseSchema):
+    '''
+    This object provides a named :class:`BaseSchema`.
+
+    Args:
+        name (str): name of the schema
+    '''
+
+    def __init__(self, name=None):
+        super().__init__()
+
+        self.__name = name
+
+    def name(self):
+        '''
+        Returns the name of the schema
+        '''
+        return self.__name
+
+    def _from_dict(self, manifest, keypath, version=None):
+        if keypath:
+            self.__name = keypath[-1]
+
+        return super()._from_dict(manifest, keypath, version=version)
+
+    def copy(self, key=None):
+        copy = super().copy(key=key)
+
+        if not self.__name and key and key[-1] != "default":
+            copy.__name = key[-1]
+
+        return copy