Usage

The main workflow exports a BusinessObjects document to a parquet file in four steps, driven by a YAML file. The matching scripts are in the examples/ directory.

Each script accepts --env (suffix read from .env, default qualif) and --help.

Step 1: Describe the document parameters

Lists the parameters a document accepts: their id (used as a key under filters: in the YAML), their type and the allowed values.

python examples/01_describe_document.py 123456 --env prod

examples/01_describe_document.py

#!/usr/bin/env python3
"""Step 1: list the parameters a BusinessObjects document accepts.

The output gives the parameter ids used as keys under ``filters:`` in the YAML
config, the dataprovider names, and the allowed LOV values.

Usage::

    python examples/01_describe_document.py DOC_ID --env qualif
"""

import argparse
import json

from boapi import describe_document_parameters


def main():
    parser = argparse.ArgumentParser(description="Describe a BO document parameters")
    parser.add_argument("doc_id", help="BusinessObjects document id")
    parser.add_argument("--env", default="qualif",
                        help="Environment suffix read from .env (default: qualif)")
    args = parser.parse_args()

    infos = describe_document_parameters(args.doc_id, env=args.env)
    print(json.dumps(infos, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

Step 2: Generate the YAML file

Produces a ready-to-edit config skeleton: filters pre-filled by parameter id (with the name as a comment), and, with --with-columns, the document column names (read from the dataprovider dictionary, without fetching data).

python examples/02_generate_config.py 123456 --env prod --with-columns \
    -o config/s_lieuprel.yaml

examples/02_generate_config.py

#!/usr/bin/env python3
"""Step 2: generate a YAML export config from a document.

Reads the document parameters and writes a ready-to-edit YAML config. Filters
are pre-filled with placeholders, keyed by parameter id, with the parameter
name as a comment. With --with-columns, the document column names are appended
as commented entries.

Usage::

    python examples/02_generate_config.py 123456 --env qualif
    python examples/02_generate_config.py 123456 --env qualif -o config/s_lieuprel.yaml
    python examples/02_generate_config.py 123456 --env qualif --with-columns
"""

import argparse

from boapi import generate_export_config


def main():
    parser = argparse.ArgumentParser(description="Generate a YAML export config from a BO document")
    parser.add_argument("doc_id", help="BusinessObjects document id")
    parser.add_argument("--env", default="qualif",
                        help="Environment suffix read from .env (default: qualif)")
    parser.add_argument("-o", "--out", default=None,
                        help="Write the YAML to this file (default: print to stdout)")
    parser.add_argument("--output", default=None,
                        help="Value written under the YAML 'output' key (data file path)")
    parser.add_argument("--chunk-size", type=int, default=10000,
                        help="Value written under the YAML 'chunk_size' key")
    parser.add_argument("--date-format", default="%d/%m/%Y",
                        help="Value written under the YAML 'date_format' key")
    parser.add_argument("--with-columns", action="store_true",
                        help="List the document column names from the dataprovider dictionary")
    args = parser.parse_args()

    yaml_text = generate_export_config(
        args.doc_id,
        env=args.env,
        output=args.output,
        chunk_size=args.chunk_size,
        date_format=args.date_format,
        with_columns=args.with_columns,
    )

    if args.out:
        with open(args.out, "w", encoding="utf-8") as f:
            f.write(yaml_text)
        print(f"Config written -> {args.out}")
    else:
        print(yaml_text)


if __name__ == "__main__":
    main()

Step 3: Refresh and export

Applies the YAML filters (BO refresh), retrieves the data and writes the output. The output directory is created automatically. Column typing is applied to .parquet and .json outputs (.csv is written raw).

python examples/03_export_from_config.py config/s_lieuprel.yaml --env prod

examples/03_export_from_config.py

#!/usr/bin/env python3
"""Step 2: refresh the document with the YAML filters and export it.

The YAML config drives the document id, the BO filters and the output column
typing. See examples/s_lieuprel.yaml for the schema.

Usage::

    python examples/02_export_from_config.py examples/s_lieuprel.yaml --env qualif
    python examples/02_export_from_config.py config.yaml --env prod --output out/data.parquet
"""

import argparse

from boapi import export_from_config


def main():
    parser = argparse.ArgumentParser(description="Export a BO document from a YAML config")
    parser.add_argument("config", help="Path to the YAML export config")
    parser.add_argument("--env", default="qualif",
                        help="Environment suffix read from .env (default: qualif)")
    parser.add_argument("--output", default=None,
                        help="Override the output path defined in the YAML")
    args = parser.parse_args()

    path = export_from_config(args.config, env=args.env, output=args.output)
    print(f"Export done -> {path}")


if __name__ == "__main__":
    main()

Step 4: Check the parquet

Prints the shape, dtypes and a preview of the produced file.

python examples/04_check_parquet.py out/s_lieuprel.parquet

examples/04_check_parquet.py

#!/usr/bin/env python3
"""Step 3: inspect the exported parquet (shape, dtypes, preview).

Usage::

    python examples/03_check_parquet.py out/s_lieuprel.parquet
"""

import argparse

import pandas as pd


def main():
    parser = argparse.ArgumentParser(description="Inspect an exported parquet file")
    parser.add_argument("path", help="Path to the parquet file")
    parser.add_argument("--rows", type=int, default=5, help="Preview rows (default: 5)")
    args = parser.parse_args()

    df = pd.read_parquet(args.path)
    print(f"Shape: {df.shape}")
    print("\nDtypes:")
    print(df.dtypes)
    print(f"\nHead ({args.rows} rows):")
    print(df.head(args.rows))


if __name__ == "__main__":
    main()