librelane 2.4.0.dev2__py3-none-any.whl → 2.4.7__py3-none-any.whl

librelane/__init__.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 """
 The LibreLane API
-----------------
+-----------------
 
 Documented elements of this API represent the primary programming interface for
 the LibreLane infrastructure.

librelane/__main__.py

@@ -1,4 +1,4 @@
-# Copyright 2025 The American University in Cairo
+# Copyright 2025 LibreLane Contributors
 #
 # Adapted from OpenLane
 #
@@ -22,7 +22,6 @@ import shutil
 import marshal
 import tempfile
 import traceback
-import subprocess
 from textwrap import dedent
 from functools import partial
 from typing import Any, Dict, Sequence, Tuple, Type, Optional, List
@@ -221,7 +220,10 @@ def print_version(ctx: click.Context, param: click.Parameter, value: bool):
     if len(discovered_plugins) > 0:
         print("Discovered plugins:")
         for name, module in discovered_plugins.items():
-            print(f"{name} -> {module.__version__}")
+            if hasattr(module, "__version__"):
+                print(f"{name} -> {module.__version__}")
+            else:
+                print(f"{name}")
 
     ctx.exit(0)
 
@@ -278,20 +280,12 @@ def run_included_example(
         if os.path.isdir(final_path):
             print(f"A directory named {value} already exists.", file=sys.stderr)
             ctx.exit(1)
-        # 1. Copy the files
-        shutil.copytree(
-            example_path,
-            final_path,
-            symlinks=False,
-        )
-
-        # 2. Make files writable
-        if os.name == "posix":
-            subprocess.check_call(["chmod", "-R", "755", final_path])
 
+        # 1. Copy the files
+        common.recreate_tree(example_path, final_path)
         config_file = glob.glob(os.path.join(final_path, "config.*"))[0]
 
-        # 3. Run
+        # 2. Run
         run(
             ctx,
             config_files=[config_file],
@@ -321,28 +315,38 @@ def cli_in_container(
     if not value:
         return
 
-    docker_mounts = list(ctx.params.get("docker_mounts") or ())
-    docker_tty: bool = ctx.params.get("docker_tty", True)
+    mounts = list(ctx.params.get("docker_mounts") or ())
+    tty: bool = ctx.params.get("docker_tty", True)
     pdk_root = ctx.params.get("pdk_root")
-    argv = sys.argv[sys.argv.index("--dockerized") + 1 :]
+
+    try:
+        containerized_index = sys.argv.index("--dockerized")
+    except ValueError:
+        containerized_index = sys.argv.index("--containerized")
+
+    argv = sys.argv[containerized_index + 1 :]
 
     final_argv = ["zsh"]
     if len(argv) != 0:
-        final_argv = ["librelane"] + argv
+        final_argv = ["python3", "-m", "librelane"] + argv
 
-    docker_image = os.getenv(
+    container_image = os.getenv(
         "LIBRELANE_IMAGE_OVERRIDE", f"ghcr.io/librelane/librelane:{__version__}"
     )
 
     try:
         run_in_container(
-            docker_image,
+            container_image,
             final_argv,
             pdk_root=pdk_root,
-            other_mounts=docker_mounts,
-            tty=docker_tty,
+            other_mounts=mounts,
+            tty=tty,
         )
+    except ValueError as e:
+        err(e)
+        ctx.exit(1)
     except Exception as e:
+        traceback.print_exc(file=sys.stderr)
         err(e)
         ctx.exit(1)
 
@@ -377,25 +381,28 @@ o = partial(option, show_default=True)
     "Containerization options",
     o(
         "--docker-mount",
+        "--container-mount",
         "-m",
         "docker_mounts",
         multiple=True,
-        is_eager=True,  # docker options should be processed before anything else
+        is_eager=True,  # container options should be processed before anything else
         default=(),
-        help="Used to mount more directories in dockerized mode. If a valid directory is specified, it will be mounted in the same path in the container. Otherwise, the value of the option will be passed to the Docker-compatible container engine verbatim. Must be passed before --dockerized, has no effect if --dockerized is not set.",
+        help="Used to mount more directories in dockerized mode. If a valid directory is specified, it will be mounted in the same path in the container. Otherwise, the value of the option will be passed to the container engine verbatim. Must be passed before --containerized/--dockerized, has no effect if not set.",
     ),
     o(
         "--docker-tty/--docker-no-tty",
-        is_eager=True,  # docker options should be processed before anything else
+        "--container-tty/--container-no-tty",
+        is_eager=True,  # container options should be processed before anything else
         default=True,
-        help="Controls the allocation of a virtual terminal by passing -t to the Docker-compatible container engine invocation. Must be passed before --dockerized, has no effect if --dockerized is not set.",
+        help="Controls the allocation of a virtual terminal by passing -t to the Docker-compatible container engine invocation. Must be passed before --containerized/--dockerized, has no effect if not set.",
     ),
     o(
         "--dockerized",
+        "--containerized",
         default=False,
         is_flag=True,
         is_eager=True,  # docker options should be processed before anything else
-        help="Run the remaining flags using a Docker container. Some caveats apply. Must precede all options except --docker-mount, --docker-tty/--docker-no-tty.",
+        help="Run the remaining flags using a containerized version of LibreLane. Some caveats apply. Must precede all options except --{docker,container}-mount, --{docker,container}-[no-]tty.",
         callback=cli_in_container,
     ),
 )

librelane/common/__init__.py

@@ -41,8 +41,10 @@ from .misc import (
     format_size,
     format_elapsed_time,
     Filter,
+    recreate_tree,
     get_latest_file,
     process_list_file,
+    count_occurences,
     _get_process_limit,
 )
 from .types import (

librelane/common/cli.py

@@ -67,7 +67,7 @@ class IntEnumChoice(Choice):
                 f"{value} is not a not a valid value for IntEnum {self.__enum.__name__}"
             )
 
-    def get_metavar(self, param: "Parameter") -> str:
+    def get_metavar(self, param: Parameter) -> str:
         _bk = self.choices
         self.choices = [f"{e.name} or {e.value}" for e in self.__enum]
         result = super().get_metavar(param)

librelane/common/drc.py

@@ -208,6 +208,7 @@ class DRC:
         from lxml import etree as ET
 
         with ET.xmlfile(out, encoding="utf8", buffered=False) as xf:
+            xf.write_declaration()
             with xf.element("report-database"):
                 # 1. Cells
                 with xf.element("cells"):

librelane/common/generic_dict.py

@@ -69,7 +69,7 @@ VT = TypeVar("VT")
 
 class GenericDict(Mapping[KT, VT]):
     """
-    A dictionary with generic keys and values that is compatible with Python 3.8.
+    A dictionary with generic keys and values that is compatible with Python 3.8.1.
 
     :param copying: A base Mapping object to copy values from.
     :param overrides: Another mapping object to override the value from `copying`

librelane/common/metrics/__main__.py

@@ -286,7 +286,7 @@ cli.add_command(compare_multiple)
 @cloup.option(
     "-m",
     "--metric-repo",
-    default="efabless/librelane-metrics",
+    default="librelane/librelane-metrics",
     help="The repository storing metrics for --repo",
 )
 @cloup.option(

librelane/common/misc.py

@@ -11,16 +11,19 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+import io
 import os
 import re
 import glob
 import gzip
+import shutil
 import typing
 import fnmatch
 import pathlib
 import unicodedata
 from math import inf
 from typing import (
+    IO,
     Any,
     Generator,
     Iterable,
@@ -109,6 +112,8 @@ def get_opdks_rev() -> str:
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 def slugify(value: str, lower: bool = False) -> str:
     """
+    Adapted from Django slugify. In practice it works more like a kebabify…
+
     :param value: Input string
     :returns: The input string converted to lower case, with all characters
         except alphanumerics, underscores and hyphens removed, and spaces and\
@@ -314,6 +319,37 @@ class Filter(object):
                 yield input
 
 
+def recreate_tree(
+    source: AnyPath,
+    target: AnyPath,
+):
+    """
+    This function attempts to recreate a file tree from a source path in another
+    target path.
+
+    Permissions are not copied over. Symlinks and hardlinks are followed.
+
+    Directories are not recreated unless they contain files as (grand)children.
+
+    If the source and target are the same, the function returns early and does
+    nothing.
+
+    :param source: The source file tree to replicate
+    :param target: The target path to recreate the file tree within
+    """
+    source = os.path.abspath(source)
+    target = os.path.abspath(target)
+    if os.path.exists(target) and os.path.samefile(source, target):
+        return
+    for dirname, _, files in os.walk(source):
+        for file in files:
+            resolved = os.path.join(dirname, file)
+            resolved_target = os.path.join(target, os.path.relpath(resolved, source))
+            os.makedirs(os.path.dirname(resolved_target), exist_ok=True)
+            with open(resolved, "rb") as fi, open(resolved_target, "wb") as fo:
+                shutil.copyfileobj(fi, fo)
+
+
 def get_latest_file(in_path: Union[str, os.PathLike], filename: str) -> Optional[Path]:
     """
     :param in_path: A directory to search in
@@ -378,9 +414,9 @@ def _get_process_limit() -> int:
     return int(os.getenv("_OPENLANE_MAX_CORES", os.cpu_count() or 1))
 
 
-def gzopen(filename, mode="rt"):
+def gzopen(filename: AnyPath, mode="rt") -> IO[Any]:
     """
-    This method (tries to?) emulate the gzopen from the Linux Standard Base,
+    This function (tries to?) emulate the gzopen from the Linux Standard Base,
     specifically this part:
 
     If path refers to an uncompressed file, and mode refers to a read mode,
@@ -388,6 +424,11 @@ def gzopen(filename, mode="rt"):
     for reading directly from the file without any decompression.
 
     gzip.open does not have this behavior.
+
+    :param filename: The full path to the uncompressed or gzipped file.
+    :param mode: "r", "rb", "w", "wb", "x", "xb", "a" or "ab" for
+        binary mode, or "rt", "wt", "xt" or "at" for text mode.
+    :returns: An I/O wrapper that may very slightly based on the mode.
     """
     try:
         g = gzip.open(filename, mode=mode)
@@ -400,3 +441,18 @@ def gzopen(filename, mode="rt"):
     except gzip.BadGzipFile:
         g.close()
         return open(filename, mode=mode)
+
+
+def count_occurences(fp: io.TextIOWrapper, pattern: str = "") -> int:
+    """
+    Counts the occurences of a certain string in a stream, line-by-line, without
+    necessarily loading the entire file into memory.
+
+    Equivalent to: ``grep -c 'pattern' <file>`` (but without regex support).
+
+    :param fp: the text stream
+    :param pattern: the substring to search for. if set to "", it will simply
+        count the lines in the file.
+    :returns: the number of matching lines
+    """
+    return sum(pattern in line for line in fp)

librelane/common/tcl.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import re
-import tkinter
 from typing import Dict, Mapping, Any, Iterable
 
 _env_rx = re.compile(r"(?:\:\:)?env\((\w+)\)")
@@ -55,6 +54,8 @@ class TclUtils(object):
 
     @staticmethod
     def _eval_env(env_in: Mapping[str, Any], tcl_in: str) -> Dict[str, Any]:
+        import tkinter
+
         interpreter = tkinter.Tcl()
 
         interpreter.eval("array unset ::env")

librelane/common/types.py

@@ -16,6 +16,7 @@ import sys
 import tempfile
 from math import isfinite
 from decimal import Decimal
+from weakref import finalize
 from collections import UserString
 from typing import Any, Union, ClassVar, Tuple, Optional
 
@@ -112,6 +113,4 @@ class ScopedFile(Path):
         super().__init__(self._ntf.name)
         self._ntf.write(contents)
         self._ntf.close()
-
-    def __del__(self):
-        os.unlink(self._ntf.name)
+        self._ntf_cleanup = finalize(self, os.unlink, self._ntf.name)

librelane/config/__main__.py

@@ -14,7 +14,6 @@
 import os
 import sys
 import json
-import functools
 from decimal import Decimal
 
 import click
@@ -111,9 +110,7 @@ def create_config(
                 print("At least one source RTL file is required.", file=sys.stderr)
                 exit(1)
     source_rtl_key = "VERILOG_FILES"
-    if not functools.reduce(
-        lambda acc, x: acc and (x.endswith(".sv") or x.endswith(".v")), source_rtl, True
-    ):
+    if not all(file.endswith(".sv") or file.endswith(".v") for file in source_rtl):
         print(
             "Only Verilog/SystemVerilog files are supported by create-config.",
             file=sys.stderr,

librelane/config/flow.py

@@ -153,13 +153,13 @@ pdk_variables = [
     Variable(
         "FP_IO_HLAYER",
         str,
-        "The metal layer on which to place horizontal IO pins, i.e., the top and bottom of the die.",
+        "The metal layer on which to place horizontally-aligned (long side parallel with the horizon) pins alongside the east and west edges of the die.",
         pdk=True,
     ),
     Variable(
         "FP_IO_VLAYER",
         str,
-        "The metal layer on which to place vertical IO pins, i.e., the top and bottom of the die.",
+        "The metal layer on which to place vertically-aligned (long side perpendicular to the horizon) pins alongside the north and south edges of the die.",
         pdk=True,
     ),
     Variable("RT_MIN_LAYER", str, "The lowest metal layer to route on.", pdk=True),

librelane/config/preprocessor.py

@@ -190,7 +190,7 @@ class Expr(object):
                     elif token.value == "+":
                         result = number1 + number2
                     elif token.value == "-":
-                        result = number1 + number2
+                        result = number1 - number2
 
                     eval_stack.append(result)
                 except IndexError:

librelane/config/variable.py

@@ -24,9 +24,11 @@ from dataclasses import (
     fields,
     is_dataclass,
 )
+import textwrap
 from typing import (
     ClassVar,
     Dict,
+    Iterable,
     List,
     Literal,
     Optional,
@@ -238,7 +240,7 @@ def some_of(t: Type[Any]) -> Type[Any]:
     return new_union  # type: ignore
 
 
-def repr_type(t: Type[Any]) -> str:  # pragma: no cover
+def repr_type(t: Type[Any], for_document: bool = False) -> str:  # pragma: no cover
     optional = is_optional(t)
     some = some_of(t)
 
@@ -247,18 +249,25 @@ def repr_type(t: Type[Any]) -> str:  # pragma: no cover
     else:
         type_string = str(some)
 
+    if is_dataclass(t):
+        type_string = (
+            f"{{class}}`{some.__qualname__} <{some.__module__}.{some.__qualname__}>`"
+        )
+
+    separator = "｜<br />" if for_document else "｜"
+
     if inspect.isclass(some) and issubclass(some, Enum):
-        type_string = "｜".join([str(e.name) for e in some])
+        type_string = separator.join([str(e.name) for e in some])
         type_string = f"`{type_string}`"
     else:
         origin, args = get_origin(some), get_args(some)
         if origin is not None:
             if origin == Union:
                 arg_strings = [repr_type(arg) for arg in args]
-                type_string = "｜".join(arg_strings)
+                type_string = separator.join(arg_strings)
                 type_string = f"({type_string})"
             elif origin == Literal:
-                return "｜".join([repr(arg) for arg in args])
+                return separator.join([repr(arg) for arg in args])
             else:
                 arg_strings = [repr_type(arg) for arg in args]
                 type_string = f"{type_string}[{', '.join(arg_strings)}]"
@@ -377,9 +386,7 @@ class Variable:
             for easier wrapping by web browsers/PDF renderers/what have you
         :returns: A pretty Markdown string representation of the Variable's type.
         """
-        if for_document:
-            return repr_type(self.type).replace("｜", "｜<br />")
-        return repr_type(self.type)
+        return repr_type(self.type, for_document=for_document)
 
     def desc_repr_md(self) -> str:  # pragma: no cover
         """
@@ -387,6 +394,112 @@ class Variable:
         """
         return self.description.replace("\n", "<br />")
 
+    @staticmethod
+    def _render_table_md(
+        vars: Iterable["Variable"],
+        *,
+        myst_anchor_owner_id: Optional[str] = None,
+    ) -> str:  # pragma; no cover
+        """
+        Renders a markdown table for any iterable of configuration variables.
+
+        :param vars: Any iterable object returning configuration variables
+        :param myst_anchor_owner_id:
+            If set, the table is rendered for MyST using a mix of HTML and
+            Markdown, with anchors and a detail tag containing deprecated names.
+
+            For universal flow variables, set the anchor id to "".
+        :returns: A markdown string representing the table
+        """
+        include_units = any(c.units is not None for c in vars)
+        if myst_anchor_owner_id is None:
+            # Markdown mode
+            result = textwrap.dedent(
+                f"""
+                | Variable Name | Type | Description | Default | {'Units |' * include_units}
+                | - | - | - | - | {'- |' * include_units}
+                """
+            )
+            for var in vars:
+                units = var.units or ""
+                pdk_superscript = "<sup>PDK</sup>" if var.pdk else ""
+                result += f"| `{var.name}` {pdk_superscript} | {var.type_repr_md(for_document=True)} | {var.desc_repr_md()} | `{var.default}` |"
+                if include_units:
+                    result += f" {units} |"
+                result += "\n"
+            result += "\n"
+        else:
+            if myst_anchor_owner_id == "":
+                # for _get_docs_identifier, where None is the behavior we want
+                # for a literal ""
+                myst_anchor_owner_id = None
+            result = textwrap.dedent(
+                f"""
+                <div class="table-wrapper colwidths-auto docutils container">
+                <table class="docutils align-default">
+                <thead><tr>
+                <th class="head">Variable Name</th>
+                <th class="head">Type</th>
+                <th class="head">Description</th>
+                <th class="head">Default</th>
+                {'<th class="head">Units</th>' * include_units}
+                </tr></thead>
+                <tbody>
+                """
+            )
+            for var in vars:
+                units = var.units or ""
+                pdk_superscript = "<sup>PDK</sup>" if var.pdk else ""
+                var_anchor = f"{{#{var._get_docs_identifier(myst_anchor_owner_id)}}}"
+
+                result += textwrap.dedent(
+                    f"""
+                    <tr>
+                    <td>
+
+                    `{var.name}`{var_anchor} {pdk_superscript}
+                    """
+                )
+                if len(var.deprecated_names):
+                    result += "<details><summary>Deprecated names</summary>\n\n"
+                    for dn in var.deprecated_names:
+                        if isinstance(dn, tuple):
+                            dn = dn[0]
+                        result += f"* `{dn}`\n"
+                    result += "\n</details>\n"
+                result += textwrap.dedent(
+                    f"""
+                    </td>
+                    <td>
+
+                    {var.type_repr_md(for_document=True)}
+
+                    </td>
+                    <td>
+
+                    {var.desc_repr_md()}
+
+                    </td>
+                    <td>
+
+                    `{var.default}`
+
+                    </td>
+                    """
+                )
+                result += include_units * textwrap.dedent(
+                    f"""
+                    <td>
+
+                    {units}
+
+                    </td>
+                    """
+                )
+                result += "\n</tr>"
+            result += "</tbody></table></div>\n"
+        return result
+
     def __process(
         self,
         key_path: str,
@@ -435,6 +548,9 @@ class Variable:
             return_value = list()
             raw = value
             if isinstance(raw, list) or isinstance(raw, tuple):
+                if validating_type == List[Path]:
+                    if any(isinstance(item, List) for item in raw):
+                        Variable.__flatten_list(value)
                 pass
             elif is_string(raw):
                 if not permissive_typing:
@@ -720,3 +836,16 @@ class Variable:
             and self.type == rhs.type
             and self.default == rhs.default
         )
+
+    # Flatten list. Note: Must modify value, not return a new list.
+    @staticmethod
+    def __flatten_list(value: list):
+        new_list = []
+        for item in value:
+            if isinstance(item, list):
+                for sub_item in item:
+                    new_list.append(sub_item)
+            else:
+                new_list.append(item)
+
+        value[:] = new_list