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

siliconcompiler/packageschema.py

@@ -2,23 +2,338 @@ import os
 
 import os.path
 
-from siliconcompiler.schema import BaseSchema
-from siliconcompiler.schema import EditableSchema, Parameter, Scope
+from typing import Union, Dict, List
+
+from siliconcompiler.pathschema import PathSchema
+from siliconcompiler.schema import BaseSchema, EditableSchema, Parameter, Scope
 from siliconcompiler.schema.utils import trim
 from siliconcompiler.package import Resolver
 
 
-class PackageSchema(BaseSchema):
+class PackageSchema(PathSchema):
+    """
+    A class for managing package-related schema data.
+    """
     def __init__(self):
+        """
+        Initializes a PackageSchema object.
+        """
         super().__init__()
 
         schema_package(self)
 
-        self.__cache = {}
+    def set_description(self, desc: str):
+        """
+        Set the description of the package.
+
+        Args:
+            desc (str): The description string.
+        """
+        return self.set("package", "description", trim(desc))
+
+    def get_description(self) -> str:
+        """
+        Get the description of the package.
+
+        Returns:
+            str: The description string.
+        """
+
+        return self.get("package", "description")
+
+    def set_version(self, version: str):
+        """
+        Set the version of the package.
+
+        Args:
+            version (str): The version string.
+        """
+        return self.set("package", "version", version)
+
+    def get_version(self) -> str:
+        """
+        Get the version of the package.
+
+        Returns:
+            str: The version string.
+        """
+        return self.get("package", "version")
+
+    def set_vendor(self, vendor: str):
+        """
+        Set the vendor of the package.
+
+        Args:
+            vendor (str): The vendor name.
+        """
+        return self.set("package", "vendor", vendor)
+
+    def get_vendor(self) -> str:
+        """
+        Get the vendor of the package.
+
+        Returns:
+            str: The vendor name.
+        """
+        return self.get("package", "vendor")
+
+    def add_license(self, name: str):
+        """
+        Add a license name to the package.
+
+        Args:
+            name (str): The name of the license.
+        """
+        return self.add("package", "license", name)
+
+    def add_licensefile(self, file: str, dataroot: str = None):
+        """
+        Add a license file to the package.
+
+        Args:
+            file (str): The path to the license file.
+            dataroot (str, optional): The data reference for the package. Defaults to None,
+                                    which uses the active package.
+        """
+        if not dataroot:
+            dataroot = self._get_active("package")
+        with self.active_dataroot(dataroot):
+            return self.add("package", "licensefile", file)
+
+    def get_license(self) -> List[str]:
+        """
+        Get a list of license names associated with the package.
+
+        Returns:
+            List[str]: A list of license names.
+        """
+        return self.get("package", "license")
+
+    def get_licensefile(self) -> List[str]:
+        """
+        Get a list of license file paths associated with the package.
+
+        Returns:
+            List[str]: A list of file paths.
+        """
+        return self.find_files("package", "licensefile")
+
+    def add_author(self,
+                   identifier: str,
+                   name: str = None,
+                   email: str = None,
+                   organization: str = None):
+        """
+        Add or update author information for the package.
+
+        Args:
+            identifier (str): A unique identifier for the author.
+            name (str, optional): The author's name. Defaults to None.
+            email (str, optional): The author's email address. Defaults to None.
+            organization (str, optional): The author's organization. Defaults to None.
+        """
+        params = []
+        if name:
+            params.append(self.set("package", "author", identifier, "name", name))
+        if email:
+            params.append(self.set("package", "author", identifier, "email", email))
+        if organization:
+            params.append(self.set("package", "author", identifier, "organization", organization))
+        return [p for p in params if p]
+
+    def get_author(self, identifier: str = None):
+        """
+        Returns the author information for a specific author or all authors.
+
+        Args:
+            identifier (str): A unique identifier for the author, if None returns all
+        """
+        if identifier is None:
+            authors = []
+            for author in self.getkeys("package", "author"):
+                authors.append(self.get_author(author))
+            return authors
+        return {
+            "name": self.get("package", "author", identifier, "name"),
+            "email": self.get("package", "author", identifier, "email"),
+            "organization": self.get("package", "author", identifier, "organization")
+        }
+
+    def add_doc(self, type: str, path: str, dataroot: str = None):
+        """
+        Add documentation to the package.
+
+        Args:
+            type (str): The type of documentation (e.g., "manual", "api").
+            path (str): The path to the documentation file.
+            dataroot (str, optional): The data reference for the package. Defaults to None,
+                                    which uses the active package.
+
+        Returns:
+            The result of the `add` operation.
+        """
+        if not dataroot:
+            dataroot = self._get_active("package")
+        with self.active_dataroot(dataroot):
+            return self.add("package", "doc", type, path)
+
+    def get_doc(self, type: str = None) -> Union[List[str], Dict[str, List[str]]]:
+        """
+        Get documentation files for the package.
+
+        Args:
+            type (str, optional): The type of documentation to retrieve. If None,
+                                returns all documentation organized by type. Defaults to None.
+        """
+        if type:
+            return self.find_files("package", "doc", type)
+
+        docs = {}
+        for type in self.getkeys("package", "doc"):
+            doc_files = self.find_files("package", "doc", type)
+            if doc_files:
+                docs[type] = doc_files
+        return docs
+
+    @classmethod
+    def _getdict_type(cls) -> str:
+        """
+        Returns the meta data for getdict
+        """
+
+        return PackageSchema.__name__
+
+
+############################################
+# Package information
+############################################
+def schema_package(schema):
+    """
+    Adds package schema parameters to the given schema.
+
+    Args:
+        schema (EditableSchema): The schema to modify.
+    """
+    schema = EditableSchema(schema)
+
+    schema.insert(
+        'package', 'version',
+        Parameter(
+            'str',
+            scope=Scope.GLOBAL,
+            shorthelp="Package: version",
+            switch="-package_version <str>",
+            example=[
+                "cli: -package_version 1.0",
+                "api: chip.set('package', 'version', '1.0')"],
+            help=trim("""Package version. Can be a branch, tag, commit hash,
+            or a semver compatible version.""")))
+
+    schema.insert(
+        'package', 'vendor',
+        Parameter(
+            'str',
+            scope=Scope.GLOBAL,
+            shorthelp="Package: vendor",
+            switch="-package_vendor <str>",
+            example=[
+                "cli: -package_vendor acme",
+                "api: chip.set('package', 'vendor', 'acme')"],
+            help=trim("""Package vendor.""")))
+
+    schema.insert(
+        'package', 'description',
+        Parameter(
+            'str',
+            scope=Scope.GLOBAL,
+            shorthelp="Package: description",
+            switch="-package_description <str>",
+            example=[
+                "cli: -package_description 'Yet another cpu'",
+                "api: chip.set('package', 'description', 'Yet another cpu')"],
+            help=trim("""Package short one line description for package
+            managers and summary reports.""")))
+
+    for item in [
+            'datasheet',
+            'reference',
+            'userguide',
+            'quickstart',
+            'releasenotes',
+            'testplan',
+            'signoff',
+            'tutorial']:
+        schema.insert(
+            'package', 'doc', item,
+            Parameter(
+                '[file]',
+                scope=Scope.GLOBAL,
+                shorthelp=f"Package: {item} document",
+                switch=f"-package_doc_{item} <file>",
+                example=[
+                    f"cli: -package_doc_{item} {item}.pdf",
+                    f"api: chip.set('package', 'doc', '{item}', '{item}.pdf')"],
+                help=trim(f"""Package list of {item} documents.""")))
+
+    schema.insert(
+        'package', 'license',
+        Parameter(
+            '[str]',
+            scope=Scope.GLOBAL,
+            shorthelp="Package: license identifiers",
+            switch="-package_license <str>",
+            example=[
+                "cli: -package_license 'Apache-2.0'",
+                "api: chip.set('package', 'license', 'Apache-2.0')"],
+            help=trim("""Package list of SPDX license identifiers.""")))
+
+    schema.insert(
+        'package', 'licensefile',
+        Parameter(
+            '[file]',
+            scope=Scope.GLOBAL,
+            shorthelp="Package: license files",
+            switch="-package_licensefile <file>",
+            example=[
+                "cli: -package_licensefile './LICENSE'",
+                "api: chip.set('package', 'licensefile', './LICENSE')"],
+            help=trim("""Package list of license files for to be
+            applied in cases when a SPDX identifier is not available.
+            (eg. proprietary licenses).""")))
+
+    for item in [
+            'name',
+            'email',
+            'organization']:
+        schema.insert(
+            'package', 'author', 'default', item,
+            Parameter(
+                'str',
+                scope=Scope.GLOBAL,
+                shorthelp=f"Package: author {item}",
+                switch=f"-package_author_{item} 'userid <str>'",
+                example=[
+                    f"cli: -package_author_{item} 'wiley wiley@acme.com'",
+                    f"api: chip.set('package', 'author', 'wiley', '{item}', 'wiley@acme.com')"],
+                help=trim(f"""Package author {item} provided with full name as key and
+                {item} as value.""")))
+
+
+class PackageSchemaTmp(BaseSchema):
+    """
+    A temporary package schema used for development and testing.
+    """
+    def __init__(self):
+        """
+        Initializes a temporary PackageSchemaTmp object.
+        """
+        super().__init__()
+
+        schema_package_tmp(self)
 
     def register(self, name, path, ref=None, clobber=True):
         """
-        Registers a package by its name with the source path and reference
+        Registers a package by its name with the source path and reference.
 
         Registered package sources are stored in the package section of the schema.
 
@@ -50,40 +365,50 @@ class PackageSchema(BaseSchema):
         return success
 
     def get_resolver(self, package):
-        '''
-        Returns a specific resolver
+        """
+        Returns a specific resolver for a package.
 
         Args:
             package (str): name of package
-        '''
+        """
         resolver_cls = Resolver.find_resolver(self.get("source", package, "path"))
         resolver = resolver_cls(package, self._parent(root=True),
                                 self.get("source", package, "path"),
                                 self.get("source", package, "ref"))
-        resolver.set_cache(self.__cache)
         return resolver
 
     def get_resolvers(self):
-        '''
+        """
         Returns a dictionary of packages with their resolver method.
-        '''
+
+        Returns:
+            Dict[str, callable]: A dictionary of package names mapped to their resolver methods.
+        """
         resolvers = {}
         for package in self.getkeys("source"):
             resolvers[package] = self.get_resolver(package).get_path
 
         return resolvers
 
-    def _set_cache(self, package, path):
-        self.__cache[package] = path
+    @classmethod
+    def _getdict_type(cls) -> str:
+        """
+        Returns the meta data for getdict
+        """
 
-    def get_path_cache(self):
-        return self.__cache.copy()
+        return PackageSchemaTmp.__name__
 
 
 ############################################
 # Package information
 ############################################
-def schema_package(schema):
+def schema_package_tmp(schema):
+    """
+    Adds temporary package schema parameters to the given schema.
+
+    Args:
+        schema (EditableSchema): The schema to modify.
+    """
     schema = EditableSchema(schema)
 
     schema.insert(

siliconcompiler/pathschema.py

@@ -0,0 +1,255 @@
+import contextlib
+import logging
+
+import os.path
+
+from siliconcompiler.schema.baseschema import BaseSchema
+from siliconcompiler.schema.editableschema import EditableSchema
+from siliconcompiler.schema.parameter import Parameter, Scope
+from siliconcompiler.schema.utils import trim
+
+from siliconcompiler.package import Resolver
+
+
+class PathSchemaBase(BaseSchema):
+    '''
+    Schema extension to add simpler find_files and check_filepaths
+    '''
+
+    def find_files(self, *keypath,
+                   missing_ok=False,
+                   step=None, index=None):
+        """
+        Returns absolute paths to files or directories based on the keypath
+        provided.
+
+        The keypath provided must point to a schema parameter of type file, dir,
+        or lists of either. Otherwise, it will trigger an error.
+
+        Args:
+            keypath (list of str): Variable length schema key list.
+            missing_ok (bool): If True, silently return None when files aren't
+                found. If False, print an error and set the error flag.
+            step (str): Step name to access for parameters that may be specified
+                on a per-node basis.
+            index (str): Index name to access for parameters that may be specified
+                on a per-node basis.
+
+        Returns:
+            If keys points to a scalar entry, returns an absolute path to that
+            file/directory, or None if not found. It keys points to a list
+            entry, returns a list of either the absolute paths or None for each
+            entry, depending on whether it is found.
+
+        Examples:
+            >>> schema.find_files('input', 'verilog')
+            Returns a list of absolute paths to source files, as specified in
+            the schema.
+        """
+        schema_root = self._parent(root=True)
+        cwd = getattr(schema_root, "cwd", os.getcwd())
+        collection_dir = getattr(schema_root, "collection_dir",
+                                 getattr(schema_root, "getcollectiondir", None))
+        if collection_dir:
+            collection_dir = collection_dir()
+
+        return super().find_files(*keypath,
+                                  missing_ok=missing_ok,
+                                  step=step, index=index,
+                                  collection_dir=collection_dir,
+                                  cwd=cwd)
+
+    def check_filepaths(self, ignore_keys=None):
+        '''
+        Verifies that paths to all files in manifest are valid.
+
+        Args:
+            ignore_keys (list of keypaths): list of keypaths to ignore while checking
+
+        Returns:
+            True if all file paths are valid, otherwise False.
+        '''
+        schema_root = self._parent(root=True)
+        cwd = getattr(schema_root, "cwd", os.getcwd())
+        logger = getattr(schema_root,
+                         "logger",
+                         logging.getLogger("siliconcompiler.check_filepaths"))
+        collection_dir = getattr(schema_root, "collection_dir",
+                                 getattr(schema_root, "getcollectiondir",
+                                         None))
+        if collection_dir:
+            collection_dir = collection_dir()
+
+        return super().check_filepaths(
+            ignore_keys=ignore_keys,
+            logger=logger,
+            collection_dir=collection_dir,
+            cwd=cwd)
+
+
+class PathSchemaSimpleBase(PathSchemaBase):
+    def find_files(self, *keypath, missing_ok=False):
+        """
+        Returns absolute paths to files or directories based on the keypath
+        provided.
+        The keypath provided must point to a schema parameter of type file, dir,
+        or lists of either. Otherwise, it will trigger an error.
+        Args:
+            keypath (list of str): Variable length schema key list.
+            missing_ok (bool): If True, silently return None when files aren't
+                found. If False, print an error and set the error flag.
+        Returns:
+            If keys points to a scalar entry, returns an absolute path to that
+            file/directory, or None if not found. It keys points to a list
+            entry, returns a list of either the absolute paths or None for each
+            entry, depending on whether it is found.
+        Examples:
+            >>> schema.find_files('input', 'verilog')
+            Returns a list of absolute paths to source files, as specified in
+            the schema.
+        """
+        return super().find_files(*keypath,
+                                  missing_ok=missing_ok,
+                                  step=None, index=None)
+
+
+class PathSchema(PathSchemaBase):
+    '''
+    Schema extension to add support for path handling with dataroots
+    '''
+
+    def __init__(self):
+        super().__init__()
+
+        schema = EditableSchema(self)
+
+        schema.insert(
+            'dataroot', 'default', 'path',
+            Parameter(
+                'str',
+                scope=Scope.GLOBAL,
+                shorthelp="Data directory path",
+                example=[
+                    "api: chip.set('dataroot', "
+                    "'freepdk45_data', 'path', 'ssh://git@github.com/siliconcompiler/freepdk45/')"],
+                help=trim("""
+                    Data directory path, this points the location where the data can be
+                    retrieved or accessed.
+                    Allowed roots:
+
+                    * /path/on/network/drive
+                    * file:///path/on/network/drive
+                    * git+https://github.com/xyz/xyz
+                    * git://github.com/xyz/xyz
+                    * git+ssh://github.com/xyz/xyz
+                    * ssh://github.com/xyz/xyz
+                    * https://github.com/xyz/xyz/archive
+                    * https://zeroasic.com/xyz.tar.gz
+                    * github://siliconcompiler/lambdapdk/v1.0/asap7.tar.gz
+                    * python://siliconcompiler
+                    """)))
+
+        schema.insert(
+            'dataroot', 'default', 'tag',
+            Parameter(
+                'str',
+                scope=Scope.GLOBAL,
+                shorthelp="Data directory reference tag/version",
+                example=[
+                    "api: chip.set('dataroot', 'freepdk45_data', 'tag', '07ec4aa')"],
+                help=trim("""
+                    Data directory reference tag. The meaning of the this tag depends on the
+                    context of the path.
+                    For git, this can be a tag, branch, or commit id. For https this is the version
+                    of the file that will be downloaded.
+                    """)))
+
+    def set_dataroot(self, name: str, path: str, tag: str = None):
+        """
+        Registers a data directory by its name with the root and associated tag. If the path
+        provided is a file, the path recorded will be the directory the file is located in.
+
+        Args:
+            name (str): Data directory name
+            path (str): Path to the root of the data directory, can be directory, git url,
+                archive url, or path to a file
+            tag (str): Reference of the sources, can be commitid, branch name, tag
+
+        Examples:
+            >>> schema.set_dataroot('siliconcompiler_data',
+                    'git+https://github.com/siliconcompiler/siliconcompiler',
+                    'v1.0.0')
+            Records the data directory for siliconcompiler_data as a git clone for tag v1.0.0
+            >>> schema.set_dataroot('file_data', __file__)
+            Records the data directory for file_data as the directory that __file__ is found in.
+        """
+
+        if os.path.isfile(path):
+            path = os.path.dirname(os.path.abspath(path))
+
+        BaseSchema.set(self, "dataroot", name, "path", path)
+        if tag:
+            BaseSchema.set(self, "dataroot", name, "tag", tag)
+
+    def get_dataroot(self, name: str) -> str:
+        """
+        Returns absolute path to the data directory.
+
+        Raises:
+            ValueError: is data directory is not found
+
+        Args:
+            name (str): name of the data directory to find.
+
+        Returns:
+            Path to the directory root.
+
+        Examples:
+            >>> schema.get_dataroot('siliconcompiler')
+            Returns the path to the root of the siliconcompiler data directory.
+        """
+
+        if not BaseSchema.valid(self, "dataroot", name):
+            raise ValueError(f"{name} is not a recognized source")
+
+        path = BaseSchema.get(self, "dataroot", name, "path")
+        tag = BaseSchema.get(self, "dataroot", name, "tag")
+
+        resolver = Resolver.find_resolver(path)
+        return resolver(name, self._parent(root=True), path, tag).get_path()
+
+    def _find_files_dataroot_resolvers(self):
+        """
+        Returns a dictionary of path resolevrs data directory handling for find_files
+
+        Returns:
+            dictionary of str to resolver mapping
+        """
+        schema_root = self._parent(root=True)
+        resolver_map = {}
+        for dataroot in self.getkeys("dataroot"):
+            path = BaseSchema.get(self, "dataroot", dataroot, "path")
+            tag = BaseSchema.get(self, "dataroot", dataroot, "tag")
+            resolver = Resolver.find_resolver(path)
+            resolver_map[dataroot] = resolver(dataroot, schema_root, path, tag).get_path
+        return resolver_map
+
+    @contextlib.contextmanager
+    def active_dataroot(self, dataroot: str = None):
+        '''
+        Use this context to set the dataroot parameter on files and directory parameters.
+
+        Args:
+            dataroot (str): name of the dataroot
+
+        Example:
+            >>> with schema.active_dataroot("lambdalib"):
+            ...     schema.set("file", "top.v")
+            Sets the file to top.v and associates lambdalib as the dataroot.
+        '''
+
+        if dataroot and dataroot not in self.getkeys("dataroot"):
+            raise ValueError(f"{dataroot} is not a recognized dataroot")
+
+        with self._active(package=dataroot):
+            yield