Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ the git log and on [PyPI](https://pypi.org/project/bust/#history).
- `doc/<module>.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/<module>.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.
Expand Down
2 changes: 2 additions & 0 deletions bust/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
DocumentationGenerator,
GeneratorFactory,
)
from bust.bundle import bundle_zip
from bust.generation import generate_files

__all__ = [
Expand All @@ -39,4 +40,5 @@
"DocumentationGenerator",
"GeneratorFactory",
"generate_files",
"bundle_zip",
]
90 changes: 90 additions & 0 deletions bust/bundle.py
Original file line number Diff line number Diff line change
@@ -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)
79 changes: 79 additions & 0 deletions tests/test_bundle.py
Original file line number Diff line number Diff line change
@@ -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"})
Loading