siliconcompiler 0.34.2__py3-none-any.whl → 0.34.3__py3-none-any.whl

siliconcompiler/design.py

@@ -1,4 +1,3 @@
-import contextlib
 import re
 
 import os.path
@@ -7,29 +6,60 @@ from typing import List, Union, Tuple, Dict
 
 from siliconcompiler import utils
 
-from siliconcompiler import PackageSchema
+from siliconcompiler import LibrarySchema
 
 from siliconcompiler.dependencyschema import DependencySchema
-from siliconcompiler.pathschema import PathSchema
 from siliconcompiler.schema import NamedSchema
 from siliconcompiler.schema import EditableSchema, Parameter, Scope
 from siliconcompiler.schema.utils import trim
 
 
 ###########################################################################
-class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
+class DesignSchema(LibrarySchema, DependencySchema):
+    '''
+    Schema for a 'design', which is a chip object that can be compiled.
+
+    This class inherits from :class:`~siliconcompiler.LibrarySchema` and
+    :class:`~siliconcompiler.DependencySchema`, and adds parameters and methods
+    specific to describing a design, such as its top module, source filesets,
+    and compilation settings.
+    '''
 
     def __init__(self, name: str = None):
+        '''
+        Initializes a new DesignSchema object.
+
+        Args:
+            name (str, optional): The name of the design. Defaults to None.
+        '''
         super().__init__()
         self.set_name(name)
 
         schema_design(self)
 
     def add_dep(self, obj: NamedSchema, clobber: bool = True) -> bool:
+        '''
+        Adds a module dependency to this design.
+
+        This method extends the base `add_dep` to prevent a design from
+        adding a dependency on itself.
+
+        Args:
+            obj (NamedSchema): The dependency object to add.
+            clobber (bool): If True, overwrite an existing dependency with the
+                same name.
+
+        Returns:
+            bool: True if the dependency was added, False otherwise.
+
+        Raises:
+            TypeError: If `obj` is not a `NamedSchema`.
+            ValueError: If `obj` has the same name as the current design.
+        '''
         if not isinstance(obj, NamedSchema):
             raise TypeError(f"Cannot add an object of type: {type(obj)}")
 
-        if obj.name() == self.name():
+        if obj.name == self.name:
             raise ValueError("Cannot add a dependency with the same name")
 
         return super().add_dep(obj, clobber=clobber)
@@ -42,7 +72,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
            value (str): Topmodule name.
-           fileset (str, optional): Fileset name.
+           fileset (str, optional): Fileset name. If not provided, the active
+            fileset is used.
 
         Returns:
            str: Topmodule name
@@ -63,7 +94,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Returns the topmodule of a fileset.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
            str: Topmodule name
@@ -80,9 +112,10 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
            value (str or Path): Include directory name.
-           fileset (str, optional): Fileset name.
-           clobber (bool, optional): Clears existing list before adding item
-           dataroot (str, optional): Data directory reference name
+           fileset (str, optional): Fileset name. If not provided, the active
+            fileset is used.
+           clobber (bool, optional): Clears existing list before adding item.
+           dataroot (str, optional): Data directory reference name.
 
         Returns:
            list[str]: List of include directories
@@ -94,7 +127,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Returns include directories for a fileset.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
            list[str]: List of include directories
@@ -110,7 +144,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
            value (str or List[str]): Macro definition.
-           fileset (str, optional): Fileset name.
+           fileset (str, optional): Fileset name. If not provided, the active
+            fileset is used.
            clobber (bool, optional): Clears existing list before adding item.
 
         Returns:
@@ -123,7 +158,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Returns defined macros for a fileset.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
            list[str]: List of macro definitions
@@ -139,8 +175,9 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
            value (str or List[str]): Macro (un)definition.
-           fileset (str, optional): Fileset name.
-           clobber (bool, optional): CClears existing list before adding item.
+           fileset (str, optional): Fileset name. If not provided, the active
+            fileset is used.
+           clobber (bool, optional): Clears existing list before adding item.
 
         Returns:
            list[str]: List of macro (un)definitions
@@ -151,7 +188,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Returns undefined macros for a fileset.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
        Returns:
            list[str]: List of macro (un)definitions
@@ -168,10 +206,11 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Adds dynamic library directories to a fileset.
 
         Args:
-           value (str or List[str]): Library directories
-           fileset (str, optional): Fileset name.
+           value (str or List[str]): Library directories.
+           fileset (str, optional): Fileset name. If not provided, the active
+            fileset is used.
            clobber (bool, optional): Clears existing list before adding item.
-           dataroot (str, optional): Data directory reference name
+           dataroot (str, optional): Data directory reference name.
 
         Returns:
            list[str]: List of library directories.
@@ -183,7 +222,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Returns dynamic library directories for a fileset.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
            list[str]: List of library directories.
@@ -198,8 +238,9 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Adds dynamic libraries to a fileset.
 
         Args:
-           value (str or List[str]): Libraries
-           fileset (str, optional): Fileset name.
+           value (str or List[str]): Libraries.
+           fileset (str, optional): Fileset name. If not provided, the active
+            fileset is used.
            clobber (bool, optional): Clears existing list before adding item.
 
         Returns:
@@ -211,7 +252,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         """Returns list of dynamic libraries for a fileset.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
            list[str]: List of libraries.
@@ -228,7 +270,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         Args:
             name (str): Parameter name.
             value (str): Parameter value.
-            fileset (str, optional): Fileset name.
+            fileset (str, optional): Fileset name. If not provided, the active
+                fileset is used.
 
         Returns:
             str: Parameter value
@@ -252,7 +295,8 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
            name (str): Parameter name.
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
             str: Parameter value
@@ -271,8 +315,9 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
            dep (:class:`DesignSchema` or str): Dependency name or object.
-           depfileset (str): Dependency fileset
-           fileset (str): Fileset name.
+           depfileset (str): Dependency fileset.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         """
         if fileset is None:
@@ -285,16 +330,16 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
             dep_name = dep
             dep = self.get_dep(dep_name)
         elif isinstance(dep, DesignSchema):
-            dep_name = dep.name()
+            dep_name = dep.name
             self.add_dep(dep, clobber=True)
         else:
             raise TypeError("dep is not a valid type")
 
         if not isinstance(dep, DesignSchema):
-            raise ValueError(f"cannot associate fileset ({depfileset}) with {dep.name()}")
+            raise ValueError(f"cannot associate fileset ({depfileset}) with {dep.name}")
 
-        if depfileset not in dep.getkeys("fileset"):
-            raise ValueError(f"{dep.name()} does not have {depfileset} as a fileset")
+        if not dep.has_fileset(depfileset):
+            raise ValueError(f"{dep.name} does not have {depfileset} as a fileset")
 
         return self.add("fileset", fileset, "depfileset", (dep_name, depfileset))
 
@@ -303,10 +348,11 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         Returns list of dependency filesets.
 
         Args:
-           fileset (str): Fileset name.
+           fileset (str): Fileset name. If not provided, the active fileset is
+            used.
 
         Returns:
-           list[str]: List of dependencies and filesets.
+           list[tuple(str, str)]: List of dependencies and filesets.
         """
         if fileset is None:
             fileset = self._get_active("fileset")
@@ -316,128 +362,22 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         return self.get("fileset", fileset, "depfileset")
 
-    ###############################################
-    def add_file(self,
-                 filename: str,
-                 fileset: str = None,
-                 filetype: str = None,
-                 clobber: bool = False,
-                 dataroot: str = None) -> List[str]:
-        """
-        Adds files to a fileset.
-
-        .v        → (source, verilog)
-        .vhd      → (source, vhdl)
-        .sdc      → (constraint, sdc)
-        .lef      → (input, lef)
-        .def      → (input, def)
-        ...       → etc.
-
-        Args:
-            filename (Path or list[Path]): File path or list of paths to add.
-            fileset (str): Logical group to associate the file with.
-            filetype (str, optional): Type of the file (e.g., 'verilog', 'sdc').
-            clobber (bool, optional): Clears list before adding item
-            dataroot (str, optional): Data directory reference name
-
-        Raises:
-            SiliconCompilerError: If fileset or filetype cannot be inferred from
-            the file extension.
-
-        Returns:
-           list[str]: List of file paths.
-
-        Notes:
-           - This method normalizes `filename` to a string for consistency.
-
-           - If no filetype is specified, filetype is inferred based on
-                the file extension via a mapping table. (eg. .v is verilog).
-        """
-
-        if fileset is None:
-            fileset = self._get_active("fileset")
-
-        if not isinstance(fileset, str):
-            raise ValueError("fileset key must be a string")
-
-        # handle list inputs
-        if isinstance(filename, (list, tuple)):
-            params = []
-            for item in filename:
-                params.extend(
-                    self.add_file(
-                        item,
-                        fileset=fileset,
-                        clobber=clobber,
-                        filetype=filetype))
-            return params
-
-        if filename is None:
-            raise ValueError("add_file cannot process None")
-
-        # Normalize value to string in case we receive a pathlib.Path
-        filename = str(filename)
-
-        # map extension to default filetype/fileset
-        if not filetype:
-            ext = utils.get_file_ext(filename)
-            iomap = utils.get_default_iomap()
-            if ext in iomap:
-                _, default_filetype = iomap[ext]
-                filetype = default_filetype
-            else:
-                raise ValueError(f"Unrecognized file extension: {ext}")
-
-        if not dataroot:
-            dataroot = self._get_active("package")
-
-        # adding files to dictionary
-        with self.active_dataroot(dataroot):
-            if clobber:
-                return self.set('fileset', fileset, 'file', filetype, filename)
-            else:
-                return self.add('fileset', fileset, 'file', filetype, filename)
-
-    ###############################################
-    def get_file(self,
-                 fileset: str = None,
-                 filetype: str = None):
-        """Returns a list of files from one or more filesets.
-
-        Args:
-            fileset (str or list[str]): Fileset(s) to query.
-            filetype (str or list[str], optional): File type(s) to filter by (e.g., 'verilog').
-
-        Returns:
-            list[str]: List of file paths.
-        """
-
-        if fileset is None:
-            fileset = self._get_active("fileset")
-
-        if not isinstance(fileset, list):
-            fileset = [fileset]
-
-        if filetype and not isinstance(filetype, list):
-            filetype = [filetype]
-
-        filelist = []
-        for fs in fileset:
-            if not isinstance(fs, str):
-                raise ValueError("fileset key must be a string")
-            # handle scalar+list in argument
-            if not filetype:
-                filetype = self.getkeys('fileset', fs, 'file')
-            # grab the files
-            for ftype in filetype:
-                filelist.extend(self.find_files('fileset', fs, 'file', ftype))
-
-        return filelist
-
     def __write_flist(self,
                       filename: str,
                       filesets: List[str],
                       depalias: Dict[str, Tuple[NamedSchema, str]]):
+        '''
+        Internal helper to write a Verilog-style file list (`.f` file).
+
+        This method iterates through the specified filesets (and their
+        dependencies), writing out `+incdir+`, `+define+`, and source file
+        paths.
+
+        Args:
+            filename (str): The path to the output file list.
+            filesets (List[str]): A list of fileset names to include.
+            depalias (Dict): A dictionary for aliasing dependencies.
+        '''
         written_cmd = set()
 
         with open(filename, "w") as f:
@@ -453,22 +393,35 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
             for lib, fileset in self.get_fileset(filesets, depalias):
                 if lib.get('fileset', fileset, 'idir'):
-                    write_header(f"{lib.name()} / {fileset} / include directories")
+                    write_header(f"{lib.name} / {fileset} / include directories")
                     for idir in lib.find_files('fileset', fileset, 'idir'):
                         write(f"+incdir+{idir}")
 
                 if lib.get('fileset', fileset, 'define'):
-                    write_header(f"{lib.name()} / {fileset} / defines")
+                    write_header(f"{lib.name} / {fileset} / defines")
                     for define in lib.get('fileset', fileset, 'define'):
                         write(f"+define+{define}")
 
                 for filetype in lib.getkeys('fileset', fileset, 'file'):
                     if lib.get('fileset', fileset, 'file', filetype):
-                        write_header(f"{lib.name()} / {fileset} / {filetype} files")
+                        write_header(f"{lib.name} / {fileset} / {filetype} files")
                         for file in lib.find_files('fileset', fileset, 'file', filetype):
                             write(file)
 
     def __map_fileformat(self, path):
+        '''
+        Internal helper to determine file format from a file extension.
+
+        Args:
+            path (str): The file path.
+
+        Returns:
+            str: The determined file format (e.g., "flist").
+
+        Raises:
+            ValueError: If the file format cannot be determined from the
+                extension.
+        '''
         _, ext = os.path.splitext(path)
 
         if ext == ".f":
@@ -490,9 +443,10 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         Args:
             filename (str or Path): Output file name.
-            fileset (str or list[str]): Fileset(s) to export.
+            fileset (str or list[str]): Fileset(s) to export. If not provided,
+                the active fileset is used.
             fileformat (str, optional): Export format.
-            depalias (dict of schema objects): Map of aliased objects
+            depalias (dict of schema objects): Map of aliased objects.
         """
 
         if filename is None:
@@ -518,6 +472,16 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
             raise ValueError(f"{fileformat} is not a supported filetype")
 
     def __read_flist(self, filename: str, fileset: str):
+        '''
+        Internal helper to read a Verilog-style file list (`.f` file).
+
+        This method parses the file list for `+incdir+`, `+define+`, and
+        source files, and populates the specified fileset in the schema.
+
+        Args:
+            filename (str): The path to the input file list.
+            fileset (str): The name of the fileset to populate.
+        '''
         # Extract information
         rel_path = os.path.dirname(os.path.abspath(filename))
 
@@ -549,7 +513,7 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         all_paths = include_dirs + [os.path.dirname(f) for f in files]
         all_paths = sorted(set(all_paths))
 
-        dataroot_root_name = f'flist-{self.name()}-{fileset}-{os.path.basename(filename)}'
+        dataroot_root_name = f'flist-{self.name}-{fileset}-{os.path.basename(filename)}'
         dataroots = {}
 
         for path_dir in all_paths:
@@ -597,9 +561,11 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         Intended to support other formats in the future.
 
         Args:
-            filename (str or Path): Output file name.
-            fileset (str or list[str]): Filesets to import.
-            fileformat (str, optional): Export format.
+            filename (str or Path): Input file name.
+            fileset (str or list[str]): Fileset to import into. If not
+                provided, the active fileset is used.
+            fileformat (str, optional): Import format. Inferred from file
+                extension if not provided.
         """
 
         if filename is None:
@@ -620,7 +586,20 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
     # Helper Functions
     ################################################
     def __set_add(self, fileset, option, value, clobber=False, typelist=None, dataroot=None):
-        '''Sets a parameter value in schema.
+        '''
+        Internal helper to set or add a parameter value in the schema.
+
+        This function handles common tasks for setters like `add_idir` and
+        `add_define`, such as resolving the active fileset, checking value
+        types, and calling the underlying schema `set()` or `add()` methods.
+
+        Args:
+            fileset (str): The fileset to modify.
+            option (str): The parameter key to modify.
+            value: The value to set or add.
+            clobber (bool): If True, overwrite the existing value.
+            typelist (list): A list of allowed types for the value.
+            dataroot (str): The dataroot to associate with the value.
         '''
 
         if fileset is None:
@@ -654,7 +633,17 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
         return params
 
     def __get(self, fileset, option, is_file=False):
-        '''Gets a parameter value from schema.
+        '''
+        Internal helper to get a parameter value from the schema.
+
+        This function handles common tasks for getters, such as resolving the
+        active fileset and optionally resolving file paths.
+
+        Args:
+            fileset (str): The fileset to query.
+            option (str): The parameter key to retrieve.
+            is_file (bool): If True, treat the value as a file path and
+                resolve it using `find_files`.
         '''
         if fileset is None:
             fileset = self._get_active("fileset")
@@ -665,44 +654,34 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
             return self.find_files('fileset', fileset, option)
         return self.get('fileset', fileset, option)
 
-    @contextlib.contextmanager
-    def active_fileset(self, fileset: str):
+    @classmethod
+    def _getdict_type(cls) -> str:
         """
-        Use this context to temporarily set a design fileset.
+        Returns the meta data for getdict.
 
-        Raises:
-            TypeError: if fileset is not a string
-            ValueError: if fileset if an empty string
-
-        Args:
-            fileset (str): name of the fileset
-
-        Example:
-            >>> with design.active_fileset("rtl"):
-            ...     design.set_topmodule("top")
-            Sets the top module for the rtl fileset as top.
+        This is used to identify the object type during serialization.
         """
-        if not isinstance(fileset, str):
-            raise TypeError("fileset must a string")
-        if not fileset:
-            raise ValueError("fileset cannot be an empty string")
 
-        with self._active(fileset=fileset):
-            yield
+        return DesignSchema.__name__
 
     def get_fileset(self,
                     filesets: Union[List[str], str],
                     alias: Dict[str, Tuple[NamedSchema, str]] = None) -> \
             List[Tuple[NamedSchema, str]]:
         """
-        Computes the filesets this object required for a given set of filesets
+        Computes the full, recursive list of (dependency, fileset) tuples
+        required for a given set of top-level filesets.
+
+        This method traverses the design's dependency graph.
 
         Args:
-            filesets (list of str): List of filesets to evaluate
-            alias (dict of schema objects): Map of aliased objects
+            filesets (list of str): List of top-level filesets to evaluate.
+            alias (dict of schema objects): Map of aliased objects to
+                substitute during traversal.
 
         Returns:
-            List of tuples (dependency object, fileset)
+            List[Tuple[NamedSchema, str]]: A flattened, unique list of
+            (dependency, fileset) tuples.
         """
         if alias is None:
             alias = {}
@@ -713,8 +692,7 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 
         mapping = []
         for fileset in filesets:
-            if not self.valid("fileset", fileset):
-                raise ValueError(f"{fileset} is not defined in {self.name()}")
+            self._assert_fileset(fileset)
 
             mapping.append((self, fileset))
             for dep, depfileset in self.get("fileset", fileset, "depfileset"):
@@ -744,29 +722,20 @@ class DesignSchema(PackageSchema, NamedSchema, DependencySchema, PathSchema):
 # Schema
 ###########################################################################
 def schema_design(schema):
+    '''
+    Defines the schema parameters specific to a design.
 
-    schema = EditableSchema(schema)
+    This function is called by the `DesignSchema` constructor to set up
+    its unique schema elements, such as `topmodule`, `idir`, `define`, etc.,
+    under the `fileset` key.
 
-    ###########################
-    # Files
-    ###########################
+    Args:
+        schema (DesignSchema): The schema object to configure.
+    '''
+
+    schema = EditableSchema(schema)
 
     fileset = 'default'
-    filetype = 'default'
-    schema.insert(
-        'fileset', fileset, 'file', filetype,
-        Parameter(
-            ['file'],
-            scope=Scope.GLOBAL,
-            shorthelp="Design files",
-            example=[
-                "api: chip.set('fileset', 'rtl', 'file', 'verilog', 'mytop.v')",
-                "api: chip.set('fileset', 'testbench', 'file', 'verilog', 'tb.v')"],
-            help=trim("""
-            List of files grouped as a named set ('fileset'). The exact names of
-            filetypes and filesets must match the names used in tasks
-            called during flowgraph execution. The files are processed in
-            the order specified by the ordered file list.""")))
 
     ###########################
     # Options