python.qmd

---
title: Python functions
---

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

{{< include /docs/includes/_design-status.qmd >}}

## 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](cli.qmd): `build()` and `view()`.
Both functions read `datapackage.json` into a `Properties` type, check
it with
[`check-datapackage`](https://check-datapackage.seedcase-project.org),
and pass it as input to the non-CLI functions that produce the output.

This `Properties` class is used instead of a dictionary for a few
reasons:

- Provides a clear and structured way of representing the properties of
  a Data Package with defined attributes and types.
- Allows for better type checking of the properties to ensure the
  properties are in the expected format.
- Provides a clearer and documented interface for accessing the
  properties.
- Includes better integrated documentation of the properties via
  developer tools and IDEs.

<!-- TODO: Unhide if implementing a class based approach. -->

::: content-hidden

- Allows for the use of dataclass features, such as default values and
  immutability.
- Makes it easier to extend the properties to accommodate version
  updates of the Data Package specification, by creating new versions of
  the `PackageProperties` class.

:::

### {{< var done >}} `build()`

`build()` takes the parameters `source`, `style`, `template_dir`,
`output_dir`, and `verbose`. See [`build()`](/docs/reference/build.qmd)
for details.

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

```{mermaid}
%%| label: fig-python-build-flow
%%| fig-cap: "Diagram of the internal flow of functions and objects in the `build()` CLI function."
flowchart TD
    source:::input --> parse_source{{"parse_source()"}} --> Address
    style_cfg[style]:::input --> Config
    template_dir_cfg[template_dir]:::input --> Config
    Address --> 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
```

### {{< var done >}} `view()`

`view()` takes a `source` and a display `mode`. Unlike `build()`,
`view()` does not use styles, custom templates, output files, or the
configuration file. The metadata is shown in an interactive TUI by
default, or printed to stdout when `mode="stdout"`. For details about
the parameters, see [`view()`](/docs/reference/view.qmd).

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

```{mermaid}
%%| label: fig-python-view-flow
%%| fig-cap: "Diagram of the internal flow of functions and objects in the `view()` CLI function."
flowchart TD
    source:::input --> parse_source{{"parse_source()"}} --> address
    mode[mode]:::input
    address --> read_properties{{"read_properties()"}} --> properties
    properties & mode --> output{{"TUI or stdout"}}

    classDef input fill:#FFF
```