Skip to content

API

Generate an xlsx by merging a template xlsx with data.

Problem = BookProblem | SheetProblem | CellProblem

A problem reported in the output.

One of BookProblem, SheetProblem or CellProblem.

Value = str | int | float | bool | date | time | datetime | bytes | list[Value] | dict[str, Value] | None

A value in the input data.

BaseProblem dataclass

An error reported in the output while processing continues.

Source code in src/xlsxfill/_problems.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
@dataclass(frozen=True)
class BaseProblem:
    """An error reported in the output while processing continues."""

    kind: Literal["syntax", "data"]
    construct: str
    reason: str

    @property
    def message(self) -> str:
        """The string embedded in the output.

        ``#SYNTAX! <construct>: <reason>`` or ``#DATA! <construct>: <reason>``.
        """
        return f"#{self.kind.upper()}! {self.construct}: {self.reason}"

message property

The string embedded in the output.

#SYNTAX! <construct>: <reason> or #DATA! <construct>: <reason>.

BookProblem dataclass

Bases: BaseProblem

A problem in a workbook-level string container.

Source code in src/xlsxfill/_problems.py 
22
23
24
25
26
@dataclass(frozen=True)
class BookProblem(BaseProblem):
    """A problem in a workbook-level string container."""

    part: Literal["doc_props"]

CellProblem dataclass

Bases: BaseProblem

A problem in a cell or in a string container attached to a cell.

Source code in src/xlsxfill/_problems.py 
37
38
39
40
41
42
43
@dataclass(frozen=True)
class CellProblem(BaseProblem):
    """A problem in a cell or in a string container attached to a cell."""

    sheet: str
    cell: str
    part: Literal["cell", "comment", "tooltip", "validation"]

DataError

Bases: XlsxfillError

The input data as a whole is unusable; nothing is written.

Source code in src/xlsxfill/_exceptions.py 
5
6
class DataError(XlsxfillError):
    """The input data as a whole is unusable; nothing is written."""

SheetProblem dataclass

Bases: BaseProblem

A problem in a sheet-level string container.

Source code in src/xlsxfill/_problems.py 
29
30
31
32
33
34
@dataclass(frozen=True)
class SheetProblem(BaseProblem):
    """A problem in a sheet-level string container."""

    sheet: str
    part: Literal["sheet_name", "header_footer", "shape", "chart"]

XlsxfillError

Bases: Exception

Base class for all exceptions raised by xlsxfill.

Source code in src/xlsxfill/_exceptions.py 
1
2
class XlsxfillError(Exception):
    """Base class for all exceptions raised by xlsxfill."""

fill(template, data, output)

Merge a template xlsx with data and write the result.

Parameters:

Name Type Description Default
template str | Path | BinaryIO

The template xlsx.

 required
data Mapping[str, Value]

The data to merge into the template.

 required
output str | Path | BinaryIO

Where the resulting xlsx is written.

 required

Returns:

Type Description
list[Problem]

One problem per message embedded in the
list[Problem]

output.

Raises:

Type Description
DataError

data is unusable as a whole.
Source code in src/xlsxfill/_fill.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def fill(
    template: str | Path | BinaryIO,
    data: Mapping[str, Value],
    output: str | Path | BinaryIO,
) -> list[Problem]:
    """Merge a template xlsx with data and write the result.

    Args:
        template: The template xlsx.
        data: The data to merge into the template.
        output: Where the resulting xlsx is written.

    Returns:
        One problem per [message][xlsxfill.BaseProblem.message] embedded in the
        output.

    Raises:
        DataError: ``data`` is unusable as a whole.
    """
    validate(data)
    book = Excel.open(template)
    problems = Book(book, data).run()
    book.save(output)
    return problems