librelane 2.4.0.dev0__py3-none-any.whl

librelane/common/metrics/util.py

@@ -0,0 +1,279 @@
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 re
+import textwrap
+from enum import IntEnum
+from dataclasses import dataclass
+from typing import (
+    List,
+    Mapping,
+    Tuple,
+    Dict,
+    Any,
+    Iterable,
+    Optional,
+    Union,
+)
+
+from .metric import Metric, MetricAggregator, MetricComparisonResult
+from ..misc import Filter
+
+modifier_rx = re.compile(r"([\w\-]+)\:([\w\-]+)")
+
+
+class TableVerbosity(IntEnum):
+    """
+    The verbosity of the table: whether to include everything, just changes, only
+    bad changes or only critical change. Or just nothing.
+    """
+
+    NONE = 0
+    CRITICAL = 1
+    WORSE = 2
+    CHANGED = 3
+    ALL = 4
+
+
+def parse_metric_modifiers(metric_name: str) -> Tuple[str, Mapping[str, str]]:
+    """
+    Parses a metric name into a base and modifiers as specified in
+    the METRICS2.1 naming convention.
+
+    :param metric_name: The name of the metric as generated by a utility.
+    :returns: A tuple of the base part as a string, then the modifiers as
+        a key-value mapping.
+    """
+    mn_mut = metric_name.split("__")
+    modifiers = {}
+    while ":" in mn_mut[-1]:
+        key, value = mn_mut.pop().split(":", maxsplit=1)
+        modifiers[key] = value
+    return "__".join(mn_mut), {k: modifiers[k] for k in reversed(modifiers)}
+
+
+def aggregate_metrics(
+    input: Mapping[str, Any],
+    aggregator_by_metric: Optional[
+        Mapping[str, Union[MetricAggregator, Metric]]
+    ] = None,
+) -> Dict[str, Any]:
+    """
+    Takes a set of metrics generated according to the METRICS2.1 naming
+    convention.
+
+    :param input: A mapping of strings to values of metrics.
+    :param aggregator_by_metric: A mapping of metric names to either:
+        - A tuple of the initial accumulator and reducer to aggregate the values from all modifier metrics
+        - A :class:`Metric` class
+    :returns: A tuple of the base part as a string, then the modifiers as
+        a key-value mapping.
+    """
+    if aggregator_by_metric is None:
+        aggregator_by_metric = Metric.by_name
+
+    aggregated: Dict[str, Any] = {}
+    for name, value in input.items():
+        metric_name, modifiers = parse_metric_modifiers(name)
+        if len(modifiers) < 1:
+            # No modifiers = final aggregate, don't double-represent in sums
+            continue
+
+        modifier_names = list(modifiers.keys())
+        dont_aggregate: Iterable[str] = []
+        entry = aggregator_by_metric.get(metric_name)
+        if isinstance(entry, Metric):
+            dont_aggregate = entry.dont_aggregate or []
+            entry = entry.aggregator
+
+        if entry is None:
+            continue
+
+        if len(set(modifier_names).intersection(set(dont_aggregate))):
+            continue
+
+        metric_name_so_far = metric_name
+        for modifier in modifier_names:
+            start, aggregation_fn = entry
+            current = aggregated.get(metric_name_so_far) or start
+            aggregated[metric_name_so_far] = aggregation_fn([current, value])
+            metric_name_so_far += f"__{modifier}:{modifiers[modifier]}"
+
+    final_values = dict(input)
+    final_values.update(aggregated)
+    return final_values
+
+
+def _key_from_metrics(fields: Iterable[str], metric: str) -> List[str]:
+    base, modifiers = parse_metric_modifiers(metric)
+    result = []
+    for field in fields:
+        if field == "":
+            result.append(base)
+        else:
+            result.append(modifiers.get(field, ""))
+    return result
+
+
+class MetricDiff(object):
+    """
+    Aggregates a number of ``MetricComparisonResult`` and allows a number of
+    functions to be performed on them.
+
+    :param differences: The metric comparison results.
+    """
+
+    @dataclass
+    class MetricStatistics:
+        """
+        A glorified namespace encapsulating a number of statistics of
+        :class:`MetricDiff`.
+
+        Should be generated using :meth:`MetricDiff.stats`.
+
+        :param better: The number of datapoints that represent a positive change.
+        :param worse: The number of datapoints that represent a negative change.
+        :param critical: The number of changes for critical metrics.
+        :param unchanged: Values that are unchanged.
+        """
+
+        better: int = 0
+        worse: int = 0
+        critical: int = 0
+        unchanged: int = 0
+
+    differences: List[MetricComparisonResult]
+
+    def __init__(self, differences: Iterable[MetricComparisonResult]) -> None:
+        self.differences = list(differences)
+
+    def render_md(
+        self,
+        sort_by: Optional[Iterable[str]] = None,
+        table_verbosity: TableVerbosity = TableVerbosity.ALL,
+    ) -> str:
+        """
+        :param sort_by: A list of tuples corresponding to modifiers to sort
+            metrics ascendingly by.
+        :param table_verbosity: The verbosity of the table: whether to include everything, just changes, only bad changes or only critical changes. Or just nothing.
+        :returns: A table of the differences in Markdown format.
+        """
+        if table_verbosity == TableVerbosity.NONE:
+            return ""
+
+        differences = self.differences
+        if fields := sort_by:
+            differences = sorted(
+                differences,
+                key=lambda x: _key_from_metrics(fields, x.metric_name),  # type: ignore # (mypy bug)
+            )
+
+        table = ""
+
+        changed = []
+        worse = []
+        critical = []
+        remaining = []
+
+        for row in differences:
+            if row.critical is True:
+                critical.append(row)
+            elif row.better is False:
+                worse.append(row)
+            elif row.is_changed():
+                changed.append(row)
+            else:
+                remaining.append(row)
+
+        listed_differences: List[MetricComparisonResult] = []
+        if table_verbosity >= TableVerbosity.CRITICAL:
+            listed_differences += critical
+        if table_verbosity >= TableVerbosity.WORSE:
+            listed_differences += worse
+        if table_verbosity >= TableVerbosity.CHANGED:
+            listed_differences += changed
+        if table_verbosity >= TableVerbosity.ALL:
+            listed_differences += remaining
+
+        if len(listed_differences) > 0:
+            table = textwrap.dedent(
+                f"""
+                | {'Metric':<70} | {'Before':<10} | {'After':<10} | {'Delta':<20} |
+                | {'-':<70} | {'-':<10} | {'-':<10} | {'-':<20} |
+                """
+            )
+
+            for row in listed_differences:
+                before, after, delta = row.format_values()
+                emoji = ""
+                if row.better is not None:
+                    if row.better:
+                        emoji = " ⭕"
+                    else:
+                        emoji = " ❗"
+                if row.critical and row.is_changed():
+                    emoji = " ‼️"
+                table += f"| {row.metric_name:<70} | {before:<10} | {after:<10} | {f'{delta}{emoji}':<20} |\n"
+
+        return table
+
+    def stats(self) -> MetricStatistics:
+        """
+        :returns: A :class:`MetricStatistics` object based on this aggregate.
+        """
+        stats = MetricDiff.MetricStatistics()
+        for row in self.differences:
+            if not row.is_changed():
+                stats.unchanged += 1
+            elif row.better is not None:
+                if row.better:
+                    stats.better += 1
+                else:
+                    stats.worse += 1
+            if row.critical:
+                stats.critical += 1
+        return stats
+
+    @classmethod
+    def from_metrics(
+        Self,
+        gold: dict,
+        new: dict,
+        significant_figures: int,
+        filter: Filter = Filter(["*"]),
+    ) -> "MetricDiff":
+        """
+        Creates a :class:`MetricDiff` object from two sets of metrics.
+
+        :param gold: The "gold-standard" metrics to compare against
+        :param new: The metrics being evaluated
+        :param filter: A :class:`Filter` for the names of the metrics to include
+            or exclude certain metrics.
+        :returns: The aggregate of the differences between gold and good
+        """
+
+        def generator(g, n):
+            for metric in filter.filter(sorted(n.keys())):
+                if metric not in g:
+                    continue
+                base_metric, modifiers = parse_metric_modifiers(metric)
+                lhs_value, rhs_value = g[metric], n[metric]
+                if type(lhs_value) != type(rhs_value):
+                    lhs_value = type(rhs_value)(lhs_value)
+
+                if metric_object := Metric.by_name.get(base_metric):
+                    yield metric_object.compare(
+                        lhs_value, rhs_value, significant_figures, modifiers=modifiers
+                    )
+
+        return MetricDiff(generator(gold, new))

librelane/common/misc.py

@@ -0,0 +1,402 @@
+# Copyright 2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 os
+import re
+import glob
+import gzip
+import typing
+import fnmatch
+import pathlib
+import unicodedata
+from math import inf
+from typing import (
+    Any,
+    Generator,
+    Iterable,
+    List,
+    TypeVar,
+    Optional,
+    SupportsFloat,
+    Union,
+)
+
+import httpx
+
+from .types import AnyPath, Path
+from ..__version__ import __version__
+
+T = TypeVar("T")
+
+
+def idem(obj: T, *args, **kwargs) -> T:
+    """
+    :returns: the parameter ``obj`` unchanged. Useful for some lambdas.
+    """
+    return obj
+
+
+def get_librelane_root() -> str:
+    """
+    Returns the root LibreLane folder, i.e., the folder containing the
+    ``__init__.py``.
+    """
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def get_script_dir() -> str:
+    """
+    Gets the LibreLane tool `scripts` directory.
+
+    :meta private:
+    """
+    return os.path.join(
+        get_librelane_root(),
+        "scripts",
+    )
+
+
+def get_opdks_rev() -> str:
+    """
+    Gets the Open_PDKs revision confirmed compatible with this version of LibreLane.
+    """
+    return (
+        open(os.path.join(get_librelane_root(), "open_pdks_rev"), encoding="utf8")
+        .read()
+        .strip()
+    )
+
+
+# The following code snippet has been adapted under the following license:
+#
+# Copyright (c) Django Software Foundation and individual contributors.
+# All rights reserved.
+
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+
+#     1. Redistributions of source code must retain the above copyright notice,
+#        this list of conditions and the following disclaimer.
+
+#     2. Redistributions in binary form must reproduce the above copyright
+#        notice, this list of conditions and the following disclaimer in the
+#        documentation and/or other materials provided with the distribution.
+
+#     3. Neither the name of Django nor the names of its contributors may be used
+#        to endorse or promote products derived from this software without
+#        specific prior written permission.
+
+
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+def slugify(value: str, lower: bool = False) -> str:
+    """
+    :param value: Input string
+    :returns: The input string converted to lower case, with all characters
+        except alphanumerics, underscores and hyphens removed, and spaces and\
+        dots converted into hyphens.
+
+        Leading and trailing whitespace is stripped.
+    """
+    if lower:
+        value = value.lower()
+    value = (
+        unicodedata.normalize("NFKD", value).encode("ascii", "ignore").decode("ascii")
+    )
+    value = re.sub(r"[^\w\s\-\.]", "", value).strip().lower()
+    return re.sub(r"[\s\.]+", "-", value)
+
+
+def protected(method):
+    """A decorator to indicate protected methods.
+
+    It dynamically adds a statement to the effect in the docstring as well
+    as setting an attribute, ``protected``, to ``True``, but has no other effects.
+
+    :param f: Method to mark as protected
+    """
+    if method.__doc__ is None:
+        method.__doc__ = ""
+    method.__doc__ = "**protected**\n" + method.__doc__
+
+    setattr(method, "protected", True)
+    return method
+
+
+final = typing.final
+final.__doc__ = """A decorator to indicate final methods and final classes.
+
+    Use this decorator to indicate to type checkers that the decorated
+    method cannot be overridden, and decorated class cannot be subclassed.
+    For example:
+
+
+    .. code-block:: python
+
+       class Base:
+           @final
+           def done(self) -> None:
+               ...
+       class Sub(Base):
+           def done(self) -> None:  # Error reported by type checker
+                 ...
+
+       @final
+       class Leaf:
+           ...
+       class Other(Leaf):  # Error reported by type checker
+           ...
+
+    There is no runtime checking of these properties.
+"""
+
+
+def mkdirp(path: typing.Union[str, os.PathLike]):
+    """
+    Attempts to create a directory and all of its parents.
+
+    Does not fail if the directory already exists, however, it does fail
+    if it is unable to create any of the components and/or if the path
+    already exists as a file.
+
+    :param path: A filesystem path for the directory
+    """
+    return pathlib.Path(path).mkdir(parents=True, exist_ok=True)
+
+
+class zip_first(object):
+    """
+    Works like ``zip_longest`` if ｜a｜ > ｜b｜ and ``zip`` if ｜a｜ <= ｜b｜.
+    """
+
+    def __init__(self, a: Iterable, b: Iterable, fillvalue: Any) -> None:
+        self.a = a
+        self.b = b
+        self.fillvalue = fillvalue
+
+    def __iter__(self):
+        self.iter_a = iter(self.a)
+        self.iter_b = iter(self.b)
+        return self
+
+    def __next__(self):
+        a = next(self.iter_a)
+        b = self.fillvalue
+        try:
+            b = next(self.iter_b)
+        except StopIteration:
+            pass
+        return (a, b)
+
+
+def format_size(byte_count: int) -> str:
+    units = [
+        "B",
+        "KiB",
+        "MiB",
+        "GiB",
+        "TiB",
+        "PiB",
+        "EiB",
+        # TODO: update LibreLane when zebibytes are a thing
+    ]
+
+    tracker = 0
+    so_far = byte_count
+    while (so_far // 1024) > 0 and tracker < (len(units) - 1):
+        tracker += 1
+        so_far //= 1024
+
+    return f"{so_far}{units[tracker]}"
+
+
+def format_elapsed_time(elapsed_seconds: SupportsFloat) -> str:
+    """
+    :param elapsed_seconds: Total time elapsed in seconds
+    :returns: A string in the format ``{hours}:{minutes}:{seconds}:{milliseconds}``
+    """
+    elapsed_seconds = float(elapsed_seconds)
+
+    hours = int(elapsed_seconds // 3600)
+    leftover = elapsed_seconds % 3600
+
+    minutes = int(leftover // 60)
+    leftover = leftover % 60
+
+    seconds = int(leftover // 1)
+    milliseconds = int((leftover % 1) * 1000)
+
+    return f"{hours:02}:{minutes:02}:{seconds:02}.{milliseconds:03}"
+
+
+class Filter(object):
+    """
+    Encapsulates commonly used wildcard-based filtering functions into an object.
+
+    :param filters: A list of a wildcards supporting the
+        `fnmatch spec <https://docs.python.org/3.10/library/fnmatch.html>`_.
+
+        The wildcards will be split into an "allow" and "deny" list based on whether
+        the filter is prefixed with a ``!``.
+    """
+
+    def __init__(self, filters: Iterable[str]):
+        self.allow = []
+        self.deny = []
+        for filter in filters:
+            if filter.startswith("!"):
+                self.deny.append(filter[1:])
+            else:
+                self.allow.append(filter)
+
+    def get_matching_wildcards(self, input: str) -> Generator[str, Any, None]:
+        """
+        :param input: An input to match wildcards against.
+        :returns: An iterable object for *all* wildcards in the allow list
+            accepting ``input``, and *all* wildcards in the deny list rejecting
+            ``input``.
+        """
+        for wildcard in self.allow:
+            if fnmatch.fnmatch(input, wildcard):
+                yield wildcard
+        for wildcard in self.deny:
+            if not fnmatch.fnmatch(input, wildcard):
+                yield wildcard
+
+    def match(self, input: str) -> bool:
+        """
+        :param input: An input string to either accept or reject
+        :returns: A boolean indicating whether the input:
+            * Has matched at least one wildcard in the allow list
+            * Has matched exactly 0 inputs in the deny list
+        """
+        allowed = False
+        for wildcard in self.allow:
+            if fnmatch.fnmatch(input, wildcard):
+                allowed = True
+                break
+        for wildcard in self.deny:
+            if fnmatch.fnmatch(input, wildcard):
+                allowed = False
+                break
+        return allowed
+
+    def filter(
+        self,
+        inputs: Iterable[str],
+    ) -> Generator[str, Any, None]:
+        """
+        :param inputs: A series of inputs to filter according to the wildcards.
+        :returns: An iterable object of any values in ``inputs`` that:
+            * Have matched at least one wildcard in the allow list
+            * Have matched exactly 0 inputs in the deny list
+        """
+        for input in inputs:
+            if self.match(input):
+                yield input
+
+
+def get_latest_file(in_path: Union[str, os.PathLike], filename: str) -> Optional[Path]:
+    """
+    :param in_path: A directory to search in
+    :param filename: The final filename
+    :returns: The latest file matching the parameters, by modification time
+    """
+    glob_results = glob.glob(os.path.join(in_path, "**", filename), recursive=True)
+    latest_time = -inf
+    latest_json = None
+    for result in glob_results:
+        time = os.path.getmtime(result)
+        if time > latest_time:
+            latest_time = time
+            latest_json = Path(result)
+
+    return latest_json
+
+
+def get_httpx_session(token: Optional[str] = None) -> httpx.Client:
+    """
+    Creates an ``httpx`` session client that follows redirects and has the
+    User-Agent header set to ``librelane/{__version__}``.
+
+    :param token: If this parameter is non-None and not empty, another header,
+        Authorization: Bearer {token}, is included.
+    :returns: The created client
+    """
+    session = httpx.Client(follow_redirects=True)
+    headers_raw = {"User-Agent": f"librelane/{__version__}"}
+    if token is not None and token.strip() != "":
+        headers_raw["Authorization"] = f"Bearer {token}"
+    session.headers = httpx.Headers(headers_raw)
+    return session
+
+
+def process_list_file(from_file: AnyPath) -> List[str]:
+    """
+    Convenience function to process text files in a ``.gitignore``-style format,
+    i.e., those where the lines may be:
+
+    * A list element
+    * A comment prefixed with ``#``
+    * Blank
+
+    :param from_file: The input text file.
+    :returns: A list of the strings listed in the file, ignoring lines
+        prefixed with a ``#`` and empty lines.
+    """
+    excluded_cells = []
+    list_str = open(str(from_file), encoding="utf8").read()
+    for line in list_str.splitlines():
+        line = line.strip()
+        if line == "":
+            continue
+        if line[0] == "#":
+            continue
+        excluded_cells.append(line)
+    return excluded_cells
+
+
+def _get_process_limit() -> int:
+    return int(os.getenv("_OPENLANE_MAX_CORES", os.cpu_count() or 1))
+
+
+def gzopen(filename, mode="rt"):
+    """
+    This method (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,
+    gzopen() shall attempt to open the file and return a gzFile object suitable
+    for reading directly from the file without any decompression.
+
+    gzip.open does not have this behavior.
+    """
+    try:
+        g = gzip.open(filename, mode=mode)
+        # Incredibly, it won't actually try to figure out if it's a gzipped
+        # file until you try to read from it.
+        if "r" in mode:
+            g.read(1)
+            g.seek(0)
+        return g
+    except gzip.BadGzipFile:
+        g.close()
+        return open(filename, mode=mode)