diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e43f9f..e9b802a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history). - `doc/.html`, the documentation as one self-contained HTML page with inline SVG bit diagrams, links between the register list and the registers, a sidebar and a print stylesheet. - `doc/.md`, the documentation as Markdown, with the register list and a bits table per register, readable on GitHub. - The documentation hosts the register map JSON Schema at https://bust.readthedocs.io/en/stable/register-map.schema.json. A register map may point to it with a `"$schema"` key, which gives completion, hover text and errors in editors with JSON Schema support. The editor adds the key to new register maps. +- `bust.bundle_zip` turns the result of `generate_files` into one zip, in the folder layout the CLI writes, with a `README.md` that lists what each file is. ### Changed - bust builds the PDF only when `pdflatex` is on `PATH`. Without it, bust writes the `.tex` and `.html` files and prints one line saying the PDF was skipped. diff --git a/bust/__init__.py b/bust/__init__.py index 42def8c..8432c56 100644 --- a/bust/__init__.py +++ b/bust/__init__.py @@ -26,6 +26,7 @@ DocumentationGenerator, GeneratorFactory, ) +from bust.bundle import bundle_zip from bust.generation import generate_files __all__ = [ @@ -39,4 +40,5 @@ "DocumentationGenerator", "GeneratorFactory", "generate_files", + "bundle_zip", ] diff --git a/bust/bundle.py b/bust/bundle.py new file mode 100644 index 0000000..9f31a54 --- /dev/null +++ b/bust/bundle.py @@ -0,0 +1,90 @@ +"""Bundle generated files into one zip archive. + +The archive keeps the folder layout the CLI writes and adds a README.md that +lists what each file is, so a caller such as cloudbust can hand a user one +download. +""" + +import io +import posixpath +import zipfile +from typing import Iterable, Mapping, Union + +from bust._version import __VERSION__ + +README_NAME = "README.md" + +# Fixed so the same files always give the same zip bytes. +_ZIP_DATE_TIME = (1980, 1, 1, 0, 0, 0) + +# Checked in order, so the longer suffixes come before the ones they end with. +_SUFFIX_DESCRIPTIONS = ( + ( + "_localbus_pkg.vhd", + "Local-bus types shared by the register file and the endpoint.", + ), + ("_regfile_pkg.vhd", "Register types, addresses and reset values."), + ("_regfile.vhd", "Register file."), + ("_endpoint.vhd", "Bus endpoint that connects the bus to the register file."), + ("_tb.vhd", "Self-checking UVVM testbench."), + (".vhd", "Starter top level. It is yours to edit."), + (".h", "C header."), + (".hpp", "C++ header."), + (".py", "Python header."), + (".xml", "IPBus address table."), + (".tex", "LaTeX documentation."), + (".pdf", "PDF documentation."), + (".html", "HTML documentation."), + (".md", "Markdown documentation."), +) + + +def describe_file(path: str) -> str: + """Return a one-line description of a generated file, or "" if unknown.""" + filename = posixpath.basename(path) + for suffix, description in _SUFFIX_DESCRIPTIONS: + if filename.endswith(suffix): + return description + return "" + + +def build_readme(paths: Iterable[str]) -> str: + """Return a README.md that lists each of `paths` with what it is.""" + rows = "".join(f"| `{path}` | {describe_file(path)} |\n" for path in sorted(paths)) + return ( + "# Generated files\n" + "\n" + f"Generated by bust {__VERSION__}.\n" + "\n" + "| File | What it is |\n" + "| --- | --- |\n" + f"{rows}" + ) + + +def bundle_zip(files: Mapping[str, Union[str, bytes]]) -> bytes: + """Return a zip of `files` with a README.md at its root. + + Args: + files: Generated files as {path: content}, such as the result of + `generate_files`, with paths relative to the output directory and + separated by "/". Text is encoded as UTF-8. + + Raises: + ValueError: If `files` already has a README.md at its root. + """ + if README_NAME in files: + raise ValueError(f"{README_NAME} is reserved for the file list") + archive = io.BytesIO() + with zipfile.ZipFile(archive, "w") as zip_file: + _add_entry(zip_file, README_NAME, build_readme(files)) + for path in sorted(files): + _add_entry(zip_file, path, files[path]) + return archive.getvalue() + + +def _add_entry(zip_file: zipfile.ZipFile, path: str, content: Union[str, bytes]): + entry = zipfile.ZipInfo(path, date_time=_ZIP_DATE_TIME) + entry.compress_type = zipfile.ZIP_DEFLATED + entry.external_attr = 0o644 << 16 + zip_file.writestr(entry, content) diff --git a/tests/test_bundle.py b/tests/test_bundle.py new file mode 100644 index 0000000..85bc7c2 --- /dev/null +++ b/tests/test_bundle.py @@ -0,0 +1,79 @@ +import io +import os +import zipfile + +import pytest + +from bust.bundle import README_NAME, build_readme, bundle_zip, describe_file +from bust.generation import generate_files + +_EXAMPLE_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "example") + + +def _generate_example(example): + with open(os.path.join(_EXAMPLE_DIR, f"{example}.json")) as fp: + return generate_files(fp.read()) + + +def _unzip(archive): + with zipfile.ZipFile(io.BytesIO(archive)) as zip_file: + return {name: zip_file.read(name) for name in zip_file.namelist()} + + +@pytest.mark.parametrize( + "example", + ["example_axi", "example_ipbus", "example_prototype", "example_access_matrix"], +) +def test_zip_of_generate_files_describes_every_file(example): + files = _generate_example(example) + + entries = _unzip(bundle_zip(files)) + + assert set(entries) == set(files) | {README_NAME} + readme = entries[README_NAME].decode("utf-8") + for path, content in files.items(): + assert entries[path] == content.encode("utf-8") + assert describe_file(path), path + assert f"| `{path}` |" in readme + + +def test_zip_stores_bytes_unchanged(): + pdf = b"%PDF-1.5\x00\xff" + + entries = _unzip(bundle_zip({"m/doc/m.pdf": pdf})) + + assert entries["m/doc/m.pdf"] == pdf + + +def test_zip_is_the_same_for_the_same_files(): + files = _generate_example("example_axi") + + assert bundle_zip(files) == bundle_zip(dict(reversed(list(files.items())))) + + +@pytest.mark.parametrize( + "path, expected", + [ + ("m/hdl/m_localbus_pkg.vhd", "Local-bus types"), + ("m/hdl/m_regfile_pkg.vhd", "Register types"), + ("m/hdl/m_regfile.vhd", "Register file."), + ("m/hdl/m_apb_endpoint.vhd", "Bus endpoint"), + ("m/tb/m_tb.vhd", "Self-checking UVVM testbench"), + ("m/hdl/m.vhd", "Starter top level"), + ("m/header/m.hpp", "C++ header"), + ("m/header/m.h", "C header"), + ("m/header/m.xml", "IPBus address table"), + ("m/doc/m.tex", "LaTeX documentation"), + ], +) +def test_describe_file(path, expected): + assert describe_file(path).startswith(expected) + + +def test_readme_lists_unknown_files_without_description(): + assert "| `m/notes.txt` | |" in build_readme(["m/notes.txt"]) + + +def test_readme_name_is_reserved(): + with pytest.raises(ValueError): + bundle_zip({README_NAME: "mine"})