API reference

Package

Python client for the SAP BusinessObjects Web Intelligence API (EFS).

Standalone functions (`boapi.api`)

Functions to query a BusinessObjects document and export it to a file.

Credentials are read from .env. The output format is taken from the file extension (.parquet, .csv, .json).

boapi.api.describe_document_parameters(doc_id: str, env: str | None = None) → Dict[str, List[Dict]][source]

Describe the filter parameters of a document.

Connects using .env credentials. Returns the parameters per dataprovider.

Parameters:

doc_id (str) – Document identifier
env (Optional[str]) – Optional environment suffix for .env

Returns:

Mapping of dataprovider name to a list of parameter descriptors (name, id, type, cardinality, mandatory, values)

Return type:

Dict[str, List[Dict]]

boapi.api.generate_export_config(doc_id: str, env: str | None = None, output: str | None = None, chunk_size: int = 10000, date_format: str = '%d/%m/%Y', with_columns: bool = False) → str[source]

Build a YAML export config skeleton for a document.

Reads the document parameters and returns YAML text ready to be saved. Filters are keyed by parameter id, with the parameter name kept as a comment and a placeholder value. DateTime parameters get a placeholder ISO value. When with_columns is set, the column names declared by the document dataproviders are appended as commented entries so that unlisted columns stay under pandas inference.

Parameters:

doc_id (str) – Document identifier
env (Optional[str]) – Optional environment suffix for .env
output (Optional[str]) – Output path written under the output key, optional
chunk_size (int) – Value written under the chunk_size key
date_format (str) – Value written under the date_format key
with_columns (bool) – List the document column names from the dataprovider dictionary (no data fetch)

Returns:

YAML configuration text

Return type:

str

boapi.api.export_document(doc_id: str, output: str, params: Dict[str, Any] | None = None, env: str | None = None, refresh: bool | None = None, **kwargs) → str[source]

Query a document and export it to a file.

Connects using .env credentials. Refreshes the document when params is given. The output format is taken from the output extension (.parquet, .csv, .json).

Parameters:

doc_id (str) – Document identifier
output (str) – Output file path; its extension selects the format
params (Optional[Dict[str, Any]]) – Filter parameters as {name: value}; triggers a refresh
env (Optional[str]) – Optional environment suffix for .env
refresh (Optional[bool]) – Force (True) or disable (False) the refresh; when None, refresh only if params is provided
kwargs – Options forwarded to the export (e.g. chunk_size, date_format)

Returns:

Path of the created file

Return type:

str

boapi.api.export_from_config(config_path, env: str | None = None, output: str | None = None, **kwargs) → str[source]

Export a document from a YAML configuration file.

Reads the doc_id, filters and column typing from the YAML, refreshes the document when filters are present, then exports it. Column typing applies to .parquet and .json outputs.

Parameters:

config_path – Path to the YAML configuration file
env (Optional[str]) – Environment name for .env and doc_id resolution
output (Optional[str]) – Output file path; overrides the YAML output
kwargs – Extra arguments forwarded to the export

Returns:

Path of the created file

Return type:

str

Raises:

ValueError – If no output path is provided

YAML configuration (`boapi.config`)

YAML export configuration for a BusinessObjects document.

A single YAML file describes the document id, the BO filters and the output column typing for one export. The file is loaded into a plain dictionary used by boapi.api.export_from_config().

Schema:

doc_id:                 # scalar, or a mapping by environment
  dev: 123456
  prod: 123456
output: out.parquet     # optional, output file path
chunk_size: 10000       # optional, rows per chunk for Parquet
dataprovider: s_lieuprel # optional, dataprovider targeted by the filters
date_format: "%d/%m/%Y" # optional, default format for datetime columns
filters:                # optional, BO parameters by parameter id
  '0': ['2026-04-24']
  '1': ['2026-05-01']
  '2': [AURA, IDFR]
columns:                # optional, typing and renaming
  id_lieu_prel: str     # shorthand: type only
  lat: {type: float}
  date_prel: {rename: date_prelevement, type: datetime, format: "%d/%m/%Y"}

boapi.config.load_export_config(config_path, env: str | None = None) → Dict[str, Any][source]

Load a YAML export configuration.

Parameters:

config_path – Path to the YAML file
env (Optional[str]) – Environment name used to resolve doc_id when defined per env

Returns:

Configuration with keys doc_id, output, chunk_size, dataprovider, date_format, filters, column_mapping

Return type:

Dict[str, Any]

Raises:

FileNotFoundError – If the file does not exist

`.env` credentials (`boapi.credentials`)

BusinessObjects connection settings loaded from .env files.

boapi.credentials.load_bo_config(env: str | None = None) → Dict[str, str | None][source]

Load BusinessObjects connection settings from .env files.

Values are read from ~/.env then the local .env, the latter taking precedence. Expected variables: BO_BASE_URL, BO_USER, BO_PASSWORD and optionally BO_AUTH_TYPE (default secEnterprise). When env is given, the suffixed variant (e.g. BO_BASE_URL_PROD) is used if present, otherwise the unsuffixed variable.

Parameters:: env (Optional[str]) – Optional environment suffix (e.g. ‘dev’, ‘prod’)
Returns:: Mapping with keys base_url, user, password, auth_type
Return type:: Dict[str, Optional[str]]

Low-level client (`boapi.client`)

Main client for the BusinessObjects Web Intelligence API.

Defines the BOAPIClient class, the entry point for API operations with session handling.

class boapi.client.BOAPIClient(base_url: str, user: str, auth_type: str = 'secEnterprise')[source]

Bases: object

Client for the BusinessObjects Web Intelligence API.

Handles connection and authentication, and delegates operations to the managers. Implements the context manager protocol to close the session on exit.

Variables:

cache – Cache manager
reports – Reports manager
dataproviders – Dataproviders manager
refresh – Refresh manager
export – Export manager

Example:

with BOAPIClient(base_url, "user") as client:
    if client.connect():
        df = client.get_dataframe("123456")

connect(password: str = None) → bool[source]

Open the connection to the BusinessObjects API.

Parameters:: password (str) – Password, prompted interactively if None
Returns:: True if the connection succeeds
Return type:: bool

disconnect()[source]: Close the session and release resources.

get_headers(accept: str = 'application/json', use_quotes: bool = True) → dict[source]

Build the HTTP headers with authentication.

The token may be wrapped in quotes depending on the endpoint. The raylight API requires use_quotes=False.

Parameters:

accept (str) – Accepted content type
use_quotes (bool) – Wrap the token in quotes if True

Returns:

HTTP headers dictionary

Return type:

dict

Raises:

ConnectionError – If not connected

get_dataframe(doc_id: str, separator: str = None, use_cache: bool = True, debug: bool = False, **kwargs)[source]

Retrieve the data of a document as a DataFrame.

Delegates to the export manager.

Parameters:

doc_id (str) – Document identifier
separator (str) – CSV separator, auto-detected if None
use_cache (bool) – Enable caching
debug (bool) – Enable debug mode
kwargs – Extra arguments (date_format, apply_mapping, etc.)

Returns:

A pandas DataFrame

Return type:

pd.DataFrame

save_to_parquet(doc_id: str, output_path: str, use_cache: bool = True, **kwargs)[source]

Save the data to Parquet format.

Parameters:

doc_id (str) – Document identifier
output_path (str) – Output file path
use_cache (bool) – Enable caching
kwargs – Arguments for to_parquet and export (chunk_size, date_format)

Returns:

Path of the created file

Return type:

str

save_to_csv(doc_id: str, output_path: str, use_cache: bool = True)[source]

Save the data to CSV format.

Parameters:

doc_id (str) – Document identifier
output_path (str) – Output file path
use_cache (bool) – Enable caching

Returns:

Path of the created file

Return type:

str

save_to_json(doc_id: str, output_path: str, use_cache: bool = True, orient: str = 'records', **kwargs)[source]

Save the data to JSON format.

Parameters:

doc_id (str) – Document identifier
output_path (str) – Output file path
use_cache (bool) – Enable caching
orient (str) – JSON format
kwargs – Extra arguments (date_format, etc.)

Returns:

Path of the created file

Return type:

str

list_reports(doc_id: str, show_details: bool = True)[source]

List the reports of a document.

Parameters:

doc_id (str) – Document identifier
show_details (bool) – Enable detail output

Returns:

List of reports

Return type:

list

list_dataproviders(doc_id: str, show_details: bool = True)[source]

List the dataproviders of a document.

Parameters:

doc_id (str) – Document identifier
show_details (bool) – Enable detail output

Returns:

List of dataproviders

Return type:

list

describe_parameters(doc_id: str)[source]

Describe the filter parameters of a document, grouped by dataprovider.

Delegates to the dataproviders manager.

Parameters:: doc_id (str) – Document identifier
Returns:: Mapping of dataprovider name to a list of parameter descriptors with keys name, id, type, cardinality, mandatory, values
Return type:: dict

refresh_document(doc_id: str, dataprovider_names=None, refresh_all: bool = False, verbose: bool = True, parameters=None)[source]

Refresh the dataproviders of a document.

Parameters:

doc_id (str) – Document identifier
dataprovider_names (list) – Names of the dataproviders to refresh
refresh_all (bool) – Refresh all if True
verbose (bool) – Enable detail output
parameters (dict) – Per-dataprovider parameters

Returns:

Results with success, failed, skipped

Return type:

dict

inspect_document(doc_id: str)[source]

Print all the information of a document.

Parameters:: doc_id (str) – Document identifier

Managers

BusinessObjects dataprovider management.

A dataprovider is the data source feeding a Web Intelligence document. It holds a query with its dimensions, measures and parameters.

class boapi.dataproviders.DataProvidersManager(client: BOAPIClient)[source]

Bases: object

Manager for the dataproviders of a document.

Dataproviders represent the data sources with their queries, dimensions, measures and filter parameters.

get_dataproviders(doc_id: str) → List[Dict][source]

Return the list of dataproviders of a document.

Parameters:: doc_id (str) – Document identifier
Returns:: List of dataproviders with id, name, rowCount
Return type:: List[Dict]
Raises:: Exception – If the API returns an error other than 404

get_dataprovider_detail(doc_id: str, dp_id: str) → Dict[source]

Return the full details of a dataprovider.

Parameters:

doc_id (str) – Document identifier
dp_id (str) – Dataprovider identifier

Returns:

Full dataprovider structure

Return type:

Dict

Raises:

Exception – If the API returns an error

list_dataproviders(doc_id: str, show_details: bool = True, show_parameters: bool = False) → List[Dict][source]

Print the list of dataproviders of a document.

Parameters:

doc_id (str) – Document identifier
show_details (bool) – Enable detail output
show_parameters (bool) – Enable parameter output

Returns:

List of dataproviders

Return type:

List[Dict]

get_dataprovider_parameters(doc_id: str, dp_id: str) → List[Dict][source]

Return the parameters of a dataprovider.

Parameters:

doc_id (str) – Document identifier
dp_id (str) – Dataprovider identifier

Returns:

List of parameters with their metadata

Return type:

List[Dict]

build_lov_map(doc_id: str, dp_id: str) → Dict[str, Dict[str, str]][source]

Build a mapping from LOV values to their identifiers.

LOV (List of Values) parameters require a mapping between text values and their internal identifiers.

Parameters:

doc_id (str) – Document identifier
dp_id (str) – Dataprovider identifier

Returns:

Mapping {param_id: {value: lov_id}}

Return type:

Dict[str, Dict[str, str]]

Example:

{"2": {"IDFR": "67", "AURA": "59"}}

describe_parameters(doc_id: str) → Dict[str, List[Dict]][source]

Describe the filter parameters of a document, grouped by dataprovider.

For each dataprovider, returns its parameters with their metadata: name, internal identifier, type, cardinality, mandatory flag and, for LOV (List of Values) parameters, the list of allowed values.

Parameters:: doc_id (str) – Document identifier
Returns:: Mapping of dataprovider name to a list of parameter descriptors with keys name, id, type, cardinality, mandatory, values
Return type:: Dict[str, List[Dict]]

analyze_dataprovider(doc_id: str, dp_id: str, save_json: bool = False) → Dict[source]

Run a detailed analysis of a dataprovider.

Prints the dimensions, measures and parameters. Optionally saves the full structure to JSON.

Parameters:

doc_id (str) – Document identifier
dp_id (str) – Dataprovider identifier
save_json (bool) – Enable JSON saving

Returns:

Detailed dataprovider structure

Return type:

Dict

Export of BusinessObjects data to Parquet, CSV or JSON, with chunked processing for large volumes.

class boapi.export.ExportManager(client: BOAPIClient)[source]

Bases: object

Manager for data exports.

Exports data to a pandas DataFrame, CSV, Parquet or JSON with column mapping and automatic typing.

get_csv_from_zip(zip_content: bytes) → str[source]

Extract the CSV content from an in-memory ZIP archive.

Parameters:: zip_content (bytes) – Binary content of the ZIP file
Returns:: CSV file content
Return type:: str
Raises:: Exception – If no CSV file is found

get_raw_data(doc_id: str, use_cache: bool = True) → str[source]

Retrieve the raw data as CSV.

Downloads the data from the API and keeps it in memory. Automatically extracts from a ZIP archive when needed.

Parameters:

doc_id (str) – Document identifier
use_cache (bool) – Enable cache usage

Returns:

CSV content

Return type:

str

Raises:

Exception – If the download fails

get_dataframe(doc_id: str, separator: str = None, use_cache: bool = True, debug: bool = False, apply_mapping: bool = True, mapping_file: str | None = None, date_format: str | None = None) → pandas.DataFrame[source]

Retrieve the data and convert it to a DataFrame.

Downloads the data, auto-detects the CSV separator and applies the column mapping with typing.

Parameters:

doc_id (str) – Document identifier
separator (str) – CSV separator, auto-detected if None
use_cache (bool) – Enable cache usage
debug (bool) – Enable debug output
apply_mapping (bool) – Enable column mapping and typing
mapping_file (Optional[str]) – Path to the mapping file, optional
date_format (Optional[str]) – Date format used for datetime columns, optional

Returns:

DataFrame with the data

Return type:

pd.DataFrame

Raises:

Exception – If CSV parsing fails

save_to_parquet(doc_id: str, output_path: str, use_cache: bool = True, apply_mapping: bool = True, mapping_file: str | None = None, chunk_size: int | None = None, date_format: str | None = None, **kwargs) → str[source]

Save the data to Parquet format.

Converts and saves the data with compression. If chunk_size is given, processes the data in batches to optimize memory usage.

Parameters:

doc_id (str) – Document identifier
output_path (str) – Output file path
use_cache (bool) – Enable cache usage
apply_mapping (bool) – Enable column mapping
mapping_file (Optional[str]) – Path to the mapping file, optional
chunk_size (Optional[int]) – Chunk size for batch processing
date_format (Optional[str]) – Date format used for datetime columns, optional
kwargs – Extra arguments for to_parquet

Returns:

Path of the created file

Return type:

str

save_to_csv(doc_id: str, output_path: str, use_cache: bool = True) → str[source]

Save the data to CSV format.

Parameters:

doc_id (str) – Document identifier
output_path (str) – Output file path
use_cache (bool) – Enable cache usage

Returns:

Path of the created file

Return type:

str

save_to_json(doc_id: str, output_path: str, use_cache: bool = True, apply_mapping: bool = True, mapping_file: str | None = None, date_format: str | None = None, orient: str = 'records') → str[source]

Save the data to JSON format.

Parameters:

doc_id (str) – Document identifier
output_path (str) – Output file path
use_cache (bool) – Enable cache usage
apply_mapping (bool) – Enable column mapping
mapping_file (Optional[str]) – Path to the mapping file, optional
date_format (Optional[str]) – Date format used for datetime columns, optional
orient (str) – JSON format (records, split, index, columns, values, table)

Returns:

Path of the created file

Return type:

str

Refresh of BusinessObjects dataproviders by re-running their queries with the applied parameters and filters.

class boapi.refresh.RefreshManager(client: BOAPIClient)[source]

Bases: object

Manager for dataprovider refresh.

Re-runs dataprovider queries with applied filter parameters.

refresh_dataprovider(doc_id: str, dp_id: str, parameters: Dict | None = None)[source]

Refresh a dataprovider with optional parameters.

Re-runs the dataprovider query applying the given filter parameters. LOV parameters are handled automatically.

Parameters:

doc_id (str) – Document identifier
dp_id (str) – Dataprovider identifier
parameters (Optional[Dict]) – Filter parameters as {“param_id”: [“value1”, “value2”]}

Raises:

Exception – If the refresh fails

refresh_document(doc_id: str, dataprovider_names: List[str] | None = None, refresh_all: bool = False, verbose: bool = True, parameters: Dict[str, Dict] | None = None) → Dict[source]

Refresh the dataproviders of a document.

Refreshes all dataproviders or a selection, applying per-dataprovider parameters.

Parameters:

doc_id (str) – Document identifier
dataprovider_names (Optional[List[str]]) – Names of the dataproviders to refresh
refresh_all (bool) – Refresh all dataproviders if True
verbose (bool) – Enable detail output
parameters (Optional[Dict[str, Dict]]) – Per-dataprovider parameters as {“DP_NAME”: {“param_id”: [“value”]}}

Returns:

Dictionary with success, failed and skipped lists

Return type:

Dict

Report enumeration and metadata for Web Intelligence documents.

class boapi.reports.ReportsManager(client: BOAPIClient)[source]

Bases: object

Manager for the reports of a BusinessObjects document.

Reports correspond to the views and tables configured in Web Intelligence documents.

get_reports(doc_id: str) → List[Dict][source]

Return the list of reports of a document.

Parameters:: doc_id (str) – Document identifier
Returns:: List of reports, each report being a dictionary
Return type:: List[Dict]
Raises:: Exception – If the API returns an error other than 404

list_reports(doc_id: str, show_details: bool = True) → List[Dict][source]

Print the list of reports of a document.

Parameters:

doc_id (str) – Document identifier
show_details (bool) – Enable detail output

Returns:

List of reports

Return type:

List[Dict]

In-memory cache for raw CSV data, to avoid repeated downloads.

class boapi.cache.CacheManager[source]

Bases: object

In-memory cache for CSV data.

The cache stores raw data to avoid querying the API several times for the same document.

get(key: str) → str | None[source]

Return a value from the cache.

Parameters:: key (str) – Data identifier (usually doc_id)
Returns:: Stored value, or None if absent
Return type:: Optional[str]

set(key: str, value: str)[source]

Store a value in the cache.

Parameters:

key (str) – Data identifier
value (str) – Content to store (usually CSV)

has(key: str) → bool[source]

Return whether a key is present in the cache.

Parameters:: key (str) – Identifier to check
Returns:: True if the key exists
Return type:: bool

delete(key: str)[source]

Remove an entry from the cache.

Parameters:: key (str) – Identifier to remove

clear()[source]: Clear the whole cache.

size() → int[source]

Return the number of entries in the cache.

Returns:: Number of cached items
Return type:: int

Utilities (`boapi.utils`)

Formatting, validation and type-conversion helpers for the export pipeline.

boapi.utils.format_size(size_bytes: int) → str[source]

Format a size in bytes for human-readable display.

Parameters:: size_bytes (int) – Size in bytes
Returns:: Formatted size (e.g. “1.5 MB”, “234 KB”)
Return type:: str

Example:

>>> format_size(1536)
"1.50 KB"
>>> format_size(1048576)
"1.00 MB"

boapi.utils.validate_doc_id(doc_id: str) → bool[source]

Validate a BusinessObjects document identifier.

Parameters:: doc_id (str) – Identifier to validate
Returns:: True if the identifier is valid
Return type:: bool

Example:

>>> validate_doc_id("123456")
True
>>> validate_doc_id("")
False

boapi.utils.parse_bo_error(response_data: dict) → str[source]

Extract and format an error message from the API.

Parameters:: response_data (dict) – JSON data of the error response
Returns:: Formatted error message
Return type:: str

Example:

>>> error = {"error_code": "ERR_WIS_30270", "message": "Invalid session"}
>>> parse_bo_error(error)
"BO error ERR_WIS_30270: Invalid session"

boapi.utils.truncate_string(text: str, max_length: int = 100, suffix: str = '...') → str[source]

Truncate a string if it exceeds the maximum length.

Parameters:

text (str) – Text to truncate
max_length (int) – Maximum length including the suffix
suffix (str) – Suffix appended on truncation

Returns:

Truncated text if needed

Return type:

str

Example:

>>> truncate_string("A very long text", max_length=10)
"A very ..."

boapi.utils.load_column_mapping(mapping_file=None) → dict[source]

Load the column mapping configuration.

Accepts a path to a JSON file or an already-built mapping dictionary.

Parameters:: mapping_file – Path to the JSON file, a mapping dict, or None to use column_mapping.json
Returns:: Mapping configuration dictionary
Return type:: dict

Example:

>>> mapping = load_column_mapping()
>>> mapping['Code INSEE']['normalized_name']
'insee_code'

boapi.utils.get_dtype_dict(mapping_file: str | None = None) → dict[source]

Build a dtype dictionary for pd.read_csv().

Forces columns that must preserve their format (codes with leading zeros, categories, booleans, dates, integers) to load as str. Floats are left to pandas to handle decimal=’,’ and thousands=’ ‘.

The final conversion to the target type is done by apply_column_mapping().

Parameters:: mapping_file (Optional[str]) – Path to the mapping file, optional
Returns:: Mapping {original_column_name: pandas_dtype}
Return type:: dict

Example:

>>> dtype_dict = get_dtype_dict()
>>> dtype_dict['Code Postal']
str
>>> dtype_dict['Code INSEE']
str

boapi.utils.apply_column_mapping(df: pandas.DataFrame, mapping_file=None, date_format: str | None = None) → pandas.DataFrame[source]

Apply the column mapping and type conversions.

Renames columns according to normalized_name and converts types according to python_type. A per-column date_format overrides the global one. Columns absent from the mapping are left unchanged.

Parameters:

df (pd.DataFrame) – DataFrame to transform
mapping_file – Path to the mapping file, a mapping dict, or None
date_format (Optional[str]) – Default date format for datetime columns, optional

Returns:

DataFrame with renamed and typed columns

Return type:

pd.DataFrame

Example:

>>> df = pd.DataFrame({'Code INSEE': ['01234', '56789']})
>>> df_mapped = apply_column_mapping(df)
>>> 'insee_code' in df_mapped.columns
True

API reference

Package

Standalone functions (boapi.api)

YAML configuration (boapi.config)

.env credentials (boapi.credentials)

Low-level client (boapi.client)

Managers

Utilities (boapi.utils)

Standalone functions (`boapi.api`)

YAML configuration (`boapi.config`)

`.env` credentials (`boapi.credentials`)

Low-level client (`boapi.client`)

Utilities (`boapi.utils`)