noodle-bucket 2.7.3__tar.gz

noodle_bucket-2.7.3/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=v[0-9]*)$

noodle_bucket-2.7.3/.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt export-subst

noodle_bucket-2.7.3/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+
+# Distribution / packaging
+uv.lock
+
+# pyenv
+.python-version
+
+# ZSH autocomplete
+bin/zsh/.zcompdump
+
+example_file_store.db
+example_*.bktgz
+example_*.db
+
+# test coverage
+.coverage
+
+dist/
+dev-dist/
+# Demo report written at the repo root; anchored so the pattern doesn't also
+# exclude viewer/index.html (hatchling applies these patterns to builds).
+/index.html
+
+# macOS
+.DS_Store
+*.iconset/
+
+# Node modules
+electron/node_modules/
+
+# VSCode settings (do not check in)
+.vscode/settings.json
+
+# Local Copilot instructions (do not check in)
+.github/copilot-instructions.md
+.vscode/settings.json
+
+# Example coverage files (do not check in)
+example*.bktgz
+
+# Stress example local output
+/output/

noodle_bucket-2.7.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2025 Noodle-Bytes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

noodle_bucket-2.7.3/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: noodle-bucket
+Version: 2.7.3
+Summary: Functional coverage written in Python
+Project-URL: Homepage, https://github.com/Noodle-Bytes/bucket
+Project-URL: Documentation, https://noodle-bytes.github.io/bucket/docs/
+Project-URL: Repository, https://github.com/Noodle-Bytes/bucket
+Project-URL: Coverage viewer, https://noodle-bytes.github.io/bucket/
+Project-URL: Issues, https://github.com/Noodle-Bytes/bucket/issues
+Author-email: Stuart Alldred <stuartalldred@gmail.com>, Edward Kotarski <edktrsk@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cocotb,functional-coverage,verification
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.3
+Requires-Dist: pydantic>=2.8.2
+Requires-Dist: rich>=13.3.4
+Requires-Dist: sqlalchemy>=2.0.40
+Provides-Extra: dev
+Requires-Dist: mkdocs>=1.6.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<!--
+  ~ SPDX-License-Identifier: MIT
+  ~ Copyright (c) 2023-2026 Noodle-Bytes. All Rights Reserved
+  -->
+
+<!--
+  ~ SPDX-License-Identifier: MIT
+  ~ Copyright (c) 2023-2024 Vypercore. All Rights Reserved
+  -->
+<div align="center">
+<img alt="Bucket logo" src="https://raw.githubusercontent.com/Noodle-Bytes/bucket/main/.github/images/Logo-192x192.png">
+</div>
+
+# Bucket
+
+
+Bucket is a python library to create nicer functional coverpoints. There are several benefits writing the coverage in python, such as:
+
+* Easier integration into cocotb and other python testbenches
+* No commercial EDA license required
+* Vendor independence - easily collect coverage from multiple tools/sources (eg. models, log parsers, etc)
+
+## Install
+
+```bash
+pip install noodle-bucket
+```
+
+This installs the Python library (`import bucket`) and the `bucket` CLI.
+It is enough to write coverpoints, collect coverage, and export `.bktgz` /
+SQL / JSON / console output. View results in the [hosted viewer](https://noodle-bytes.github.io/bucket/)
+or the desktop app.
+
+Generating standalone HTML (`bucket write html` / `bucket write report`)
+needs a source checkout of this repository and Node.js; it is not part of
+the pip package.
+
+## Documentation
+
+The user documentation lives in the `docs/` directory and can be read directly on GitHub, starting from [`docs/index.md`](docs/index.md).
+
+For a richer browsing experience, you can also run the MkDocs site locally:
+
+```bash
+./bin/shell
+mkdocs serve
+```
+
+Then open `http://127.0.0.1:8000/` in your browser.
+
+## Viewer
+
+A copy of the viewer is hosted at: https://noodle-bytes.github.io/bucket/
+
+## Support
+
+This library is being actively built, and is expected to change while it matures and key features are added.
+We are not providing external support for use of this library, however we are aiming to make it as easy to use as possible.
+
+As per the licence:
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contributions
+
+**We will be introducing a contributor licence agreement in the near future. In the meantime, if you want to contribute please get in touch.**
+
+Please feel free to contribute to the project, following these guidelines:
+
+* Please contribute by creating a fork and submitting a pull request.
+* Pull requests should be as small as possible to resolve the issue they are trying to address.
+* Pull requests must respect the goals of the library, as stated in the documentation.
+* Pull requests should take care not to make performance worse except for cases which require bug fixes.
+* Pull requests should update the documentation for any added/changed functionality.

noodle_bucket-2.7.3/README.md

@@ -0,0 +1,79 @@
+<!--
+  ~ SPDX-License-Identifier: MIT
+  ~ Copyright (c) 2023-2026 Noodle-Bytes. All Rights Reserved
+  -->
+
+<!--
+  ~ SPDX-License-Identifier: MIT
+  ~ Copyright (c) 2023-2024 Vypercore. All Rights Reserved
+  -->
+<div align="center">
+<img alt="Bucket logo" src="https://raw.githubusercontent.com/Noodle-Bytes/bucket/main/.github/images/Logo-192x192.png">
+</div>
+
+# Bucket
+
+
+Bucket is a python library to create nicer functional coverpoints. There are several benefits writing the coverage in python, such as:
+
+* Easier integration into cocotb and other python testbenches
+* No commercial EDA license required
+* Vendor independence - easily collect coverage from multiple tools/sources (eg. models, log parsers, etc)
+
+## Install
+
+```bash
+pip install noodle-bucket
+```
+
+This installs the Python library (`import bucket`) and the `bucket` CLI.
+It is enough to write coverpoints, collect coverage, and export `.bktgz` /
+SQL / JSON / console output. View results in the [hosted viewer](https://noodle-bytes.github.io/bucket/)
+or the desktop app.
+
+Generating standalone HTML (`bucket write html` / `bucket write report`)
+needs a source checkout of this repository and Node.js; it is not part of
+the pip package.
+
+## Documentation
+
+The user documentation lives in the `docs/` directory and can be read directly on GitHub, starting from [`docs/index.md`](docs/index.md).
+
+For a richer browsing experience, you can also run the MkDocs site locally:
+
+```bash
+./bin/shell
+mkdocs serve
+```
+
+Then open `http://127.0.0.1:8000/` in your browser.
+
+## Viewer
+
+A copy of the viewer is hosted at: https://noodle-bytes.github.io/bucket/
+
+## Support
+
+This library is being actively built, and is expected to change while it matures and key features are added.
+We are not providing external support for use of this library, however we are aiming to make it as easy to use as possible.
+
+As per the licence:
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contributions
+
+**We will be introducing a contributor licence agreement in the near future. In the meantime, if you want to contribute please get in touch.**
+
+Please feel free to contribute to the project, following these guidelines:
+
+* Please contribute by creating a fork and submitting a pull request.
+* Pull requests should be as small as possible to resolve the issue they are trying to address.
+* Pull requests must respect the goals of the library, as stated in the documentation.
+* Pull requests should take care not to make performance worse except for cases which require bug fixes.
+* Pull requests should update the documentation for any added/changed functionality.

noodle_bucket-2.7.3/bucket/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2023-2026 Noodle-Bytes. All Rights Reserved
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from . import rw
+from .axisutils import AxisUtils
+from .context import CoverageContext
+from .covergroup import Covergroup
+from .coverpoint import Coverpoint
+from .covertop import Covertop
+
+# PyPI distribution name. The import package remains `bucket`; `bucket` itself
+# is already taken on PyPI (an unrelated Bitbucket CLI).
+DIST_NAME = "noodle-bucket"
+
+try:
+    __version__ = _version(DIST_NAME)
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+version = __version__
+
+assert all((CoverageContext, Covergroup, Coverpoint, Covertop, AxisUtils, rw))

noodle_bucket-2.7.3/bucket/__main__.py

@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2023-2026 Noodle-Bytes. All Rights Reserved
+
+from pathlib import Path
+from typing import Iterable
+
+import click
+
+from . import DIST_NAME
+from .rw import (
+    ArchiveAccessor,
+    ConsoleWriter,
+    HTMLWriter,
+    JSONAccessor,
+    ReportWriter,
+    SQLAccessor,
+)
+from .rw.common import MergeReadout, Readout
+from .rw.html import DEFAULT_WEB_PATH
+
+
+@click.group()
+@click.pass_context
+@click.version_option(package_name=DIST_NAME, prog_name="bucket")
+@click.option(
+    "--web-path",
+    help="Path to the web viewer (only used by html/report)",
+    default=DEFAULT_WEB_PATH,
+    show_default=True,
+    type=click.Path(path_type=Path),
+)
+def cli(ctx, web_path):
+    ctx.obj = {"web_path": web_path}
+
+
+_VALID_READERS = ["sql", "json", "archive"]
+
+
+def _split_spec(spec: str) -> tuple[str | None, str, str]:
+    """
+    Split a readout spec into its components.
+
+    Valid Formats:
+        - `<record>@<type>:<URI>`
+        - `<record>@:<URI>`
+        - `<type>:<URI>`
+        - `<URI>`
+
+    Returns: (record: str | None, type: str, uri: str)
+    """
+    record = None
+
+    # Get record if present
+    if "@" in spec:
+        record, spec = spec.split("@", 1)
+        record = int(record)
+
+    # Get type if present
+    if ":" in spec:
+        head, tail = spec.split(":", 1)
+        if head in _VALID_READERS:
+            typ, uri = head, tail
+        elif head == "":
+            # `<record>@:<URI>` form — type omitted, infer it from the URI
+            typ, uri = None, tail
+        else:
+            typ, uri = None, spec
+    else:
+        typ, uri = None, spec
+
+    # Infer type if missing
+    if typ is None:
+        if uri.endswith(".db"):
+            typ = "sql"
+        elif uri.endswith(".json"):
+            typ = "json"
+        elif uri.endswith(".bktgz"):
+            typ = "archive"
+        else:
+            raise ValueError(
+                f"Could not infer reader type from '{uri}'; please specify explicitly."
+            )
+
+    return record, typ, uri
+
+
+def get_readouts_from_spec(*specs: str) -> Iterable[Readout]:
+    "Parse readout specs into Readout objects."
+    for spec in specs:
+        record, typ, uri = _split_spec(spec)
+
+        if typ == "sql":
+            sql_path = Path(uri)
+            assert sql_path.exists(), f"SQL path does not exist: {sql_path}"
+            assert sql_path.is_file(), f"SQL path is not a file: {sql_path}"
+
+            reader = SQLAccessor.File(sql_path).reader()
+
+        elif typ == "json":
+            json_path = Path(uri)
+            assert json_path.exists(), f"JSON path does not exist: {uri}"
+            assert json_path.is_file(), f"JSON path is not a file: {uri}"
+
+            reader = JSONAccessor(json_path).reader()
+
+        elif typ == "archive":
+            archive_path = Path(uri)
+            assert archive_path.exists(), f"Archive path does not exist: {uri}"
+            assert archive_path.is_file(), f"Archive path is not a file: {uri}"
+
+            reader = ArchiveAccessor(archive_path).reader()
+        else:
+            raise ValueError(f"Unknown reader type: {typ}")
+
+        if record is None:
+            yield from reader.read_all()
+        else:
+            yield reader.read(record)
+
+
+@cli.group()
+@click.pass_context
+@click.option(
+    "--read",
+    "-r",
+    "readout_specs",
+    multiple=True,
+    type=str,
+    help=f"""Can be specified multiple times.
+    Valid Formats:
+        - `<record>@<type>:<URI>`
+        - `<record>@:<URI>`
+        - `<type>:<URI>`
+        - `<URI>`
+
+    If the <record> is omitted, all records from the source are read.
+    If the <type> is omitted, it is inferred from the URI extension.
+    <URI> is interpreted according to the <type> as follows:
+        - `sql`: path to an SQL database file
+        - `json`: path to a JSON file
+        - `archive`: path to a .bktgz archive
+
+    Valid <type> values are: {', '.join(_VALID_READERS)}.
+    """,
+)
+@click.option("--merge", "-m", is_flag=True, default=False, help="Merge all readouts.")
+def write(ctx, readout_specs: Iterable[str], merge: bool):
+    ctx.obj = ctx.obj or {}
+    readouts = get_readouts_from_spec(*readout_specs)
+
+    if merge:
+        readouts = [MergeReadout(*readouts)]
+
+    ctx.obj["readouts"] = readouts
+
+
+@write.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    help="Path to output the JSON",
+    required=True,
+    type=click.Path(path_type=Path),
+)
+def json(ctx, output: Path):
+    readouts = ctx.obj["readouts"]
+    writer = JSONAccessor(output).writer()
+
+    for readout in readouts:
+        writer.write(readout)
+
+
+@write.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    help="Path to output the Archive",
+    required=True,
+    type=click.Path(path_type=Path),
+)
+def archive(ctx, output: Path):
+    readouts = ctx.obj["readouts"]
+    writer = ArchiveAccessor(output).writer()
+
+    for readout in readouts:
+        writer.write(readout)
+
+
+@write.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    help="Path to output the SQL",
+    required=True,
+    type=click.Path(path_type=Path),
+)
+def sql(ctx, output: Path):
+    readouts = ctx.obj["readouts"]
+    writer = SQLAccessor.File(output).writer()
+
+    for readout in readouts:
+        writer.write(readout)
+
+
+@write.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    help="Path to output the HTML report",
+    required=True,
+    type=click.Path(path_type=Path),
+)
+def html(ctx, output: Path):
+    readouts = ctx.obj["readouts"]
+    web_path = ctx.obj["web_path"]
+    try:
+        writer = HTMLWriter(web_path, output)
+        for readout in readouts:
+            writer.write(readout)
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@write.command()
+@click.pass_context
+@click.option(
+    "--output",
+    "-o",
+    help="Path to output the HTML coverage report",
+    required=True,
+    type=click.Path(path_type=Path),
+)
+@click.option(
+    "--max-axis-values",
+    "max_axis_values",
+    default=64,
+    type=click.IntRange(min=0),
+    help="Cap on listed values per axis; 0 means unlimited",
+)
+@click.option(
+    "--max-tier",
+    "max_tier",
+    default=None,
+    type=click.IntRange(min=0),
+    help="Only include coverpoints with tier <= this value",
+)
+@click.option(
+    "--tags",
+    default=None,
+    type=str,
+    help="Only include coverpoints with at least one of these comma-separated tags",
+)
+@click.option(
+    "--point",
+    default=None,
+    type=str,
+    help="Only include coverpoints matching this dotted-path glob, e.g. 'Pets.dogs*'",
+)
+def report(
+    ctx,
+    output: Path,
+    max_axis_values: int,
+    max_tier: int | None,
+    tags: str | None,
+    point: str | None,
+):
+    readouts = ctx.obj["readouts"]
+    web_path = ctx.obj["web_path"]
+    try:
+        writer = ReportWriter(
+            web_path,
+            output,
+            max_axis_values=max_axis_values,
+            max_tier=max_tier,
+            tags=[tag.strip() for tag in tags.split(",") if tag.strip()]
+            if tags
+            else None,
+            point=point,
+        )
+        # A single write: the writer is single-use and all readouts belong in
+        # one report document.
+        writer.write(list(readouts))
+    except RuntimeError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@write.command()
+@click.pass_context
+@click.option("--axes/--no-axes", default=False)
+@click.option("--goals/--no-goals", default=False)
+@click.option("--points/--no-points", default=False)
+@click.option("--summary/--no-summary", default=True)
+def console(
+    ctx,
+    axes: bool,
+    goals: bool,
+    points: bool,
+    summary: bool,
+):
+    readouts = ctx.obj["readouts"]
+    writer = ConsoleWriter(axes=axes, goals=goals, points=points, summary=summary)
+    for readout in readouts:
+        writer.write(readout)
+
+
+if __name__ == "__main__":
+    cli()