Python functions

This document describes the design of the Python functions forming the CLI and supporting non-CLI layer and tracks implementation status.

We use symbols to indicate the status of implementation (see table below). For planned or in-progress work, we might include signatures, docstrings, and pseudocode to clarify the design. Once the interface is implemented, these are replaced by links to the reference documentation.

A table showing the symbols used to indicate the status of interface components, along with their descriptions.
Status	Description
	Interface that has been implemented.
	Interface that is currently being worked on.
	Interface that is planned, but isn’t being worked on currently.

Overview

The Python interface is split into CLI functions (the CLI interface) and non-CLI functions (the underlying implementation) to:

Separate functions exposed via the CLI from those usable as a standalone Python library.
Apply functional programming practices to non-CLI functions, confining side effects and other non-functional practices to the CLI functions.
Test non-CLI functions with unit tests and CLI functions with integration tests.
Keep CLI functions small by building them from non-CLI functions.

Python CLI functions

The Python CLI functions are the direct equivalents of the CLI commands described on the CLI design page: build() and view(). Both functions read datapackage.json into a Python dictionary, check it with check-datapackage, and pass this dictionary as input to the non-CLI functions that produce the output.

`build()`

build() takes the parameters source, style, template_dir, output_dir, and verbose. See build() for details.

The internal flow of build() is shown in the diagram below.

flowchart TD
    source:::input --> parse_source{{"parse_source()"}} --> path
    style_cfg[style]:::input --> Config
    template_dir_cfg[template_dir]:::input --> Config
    path --> read_properties{{"read_properties()"}} --> properties
    properties & Config --> build_sections{{"build_sections()"}} --> output["list[BuiltSection]"]
    output --> write_sections{{"write_sections()"}}
    output_dir:::input --> Config
    Config --> write_sections
    write_sections --> files["list[Path]"]
    files --> cli_message{{"cli_message()"}} --> stdout
    verbose:::input --> cli_message

    classDef input fill:#FFF

Figure 1: Diagram of the internal flow of functions and objects in the build() CLI function.

`view()`

view() takes the same parameters as build(): source and style. Unlike build(), view()’s style parameter only accepts built-in one-page styles (the terminal displays a single page) and ignores custom styles and the configuration file. For details about the parameters, see view().

The internal flow of view() is shown in the diagram below.

flowchart TD
    source:::input --> parse_source{{"parse_source()"}} --> path
    style_cfg[style]:::input --> Config
    path --> read_properties{{"read_properties()"}} --> properties
    properties & Config --> build_sections{{"build_sections()"}} --> output["list[BuiltSection]"]
    output --> pretty_print{{"pretty_print()"}}

    classDef input fill:#FFF

Figure 2: Diagram of the internal flow of functions and objects in the view() CLI function.