Metadata-Version: 2.5
Name: otb-cbso-webservice-pyclient
Version: 2.4.0
Summary: Download annual account data from the Belgian National Bank's Central Balance Sheet Office webservices
Project-URL: Homepage, https://github.com/openthebox/cbso-webservice-pyclient
Project-URL: Issues, https://github.com/openthebox/cbso-webservice-pyclient/issues
Project-URL: Changelog, https://github.com/openthebox/cbso-webservice-pyclient/releases
Author: openthebox
License: Proprietary
Keywords: annual accounts,belgium,cbso,nbb,xbrl
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fsspec>=2024.6
Requires-Dist: urllib3>=2.0
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: s3
Requires-Dist: s3fs>=2024.6; extra == 's3'
Description-Content-Type: text/markdown

# otb-cbso-webservice-pyclient

Download Belgian annual accounts from the National Bank's Central Balance Sheet Office (CBSO).
Use the Python package or the `cbso-fetch` command.

The package downloads authentic and improved accounts to a local directory or S3.
It can also validate saved files, repair missing files, and collect consolidated accounts.
All operations run sequentially.
Individual authentic PDF and XBRL downloads try the production public website after subscription HTTP 404 responses.

## Installation

Use Python 3.10 or later.
Install from [PyPI](https://pypi.org/project/otb-cbso-webservice-pyclient/).

```console
pip install otb-cbso-webservice-pyclient
```

Install the S3 extra for S3 destinations.

```console
pip install 'otb-cbso-webservice-pyclient[s3]'
```

## Subscription keys

Set the keys for the services you need.

| Environment variable         | Service                                           |
| ---------------------------- | ------------------------------------------------- |
| `CBSO_KEY_AUTHENTIC`         | Individual authentic references and account files |
| `CBSO_KEY_EXTRACTS`          | Daily authentic batches                           |
| `CBSO_KEY_AUTHENTIC_ARCHIVE` | Authentic archive batches                         |
| `CBSO_KEY_IMPROVED`          | Individual improved files and daily batches       |
| `CBSO_KEY_IMPROVED_ARCHIVE`  | Improved archive batches                          |

Validation and consolidated filtering need no CBSO keys.
See [Configuration](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/configuration.md) for subscriptions, S3 access, and environments.

## Basic use

Fetch authentic and improved filings for an enterprise:

```console
export CBSO_KEY_AUTHENTIC='your-authentic-subscription-key'
export CBSO_KEY_IMPROVED='your-improved-subscription-key'
cbso-fetch download-enterprise BE0203.201.340 --destination ./data
```

The destination can also be an S3 prefix, such as `s3://my-bucket/cbso`.
Production is the default environment. Use `--env test` for UAT2 downloads and repairs.

## Commands

| Command                                                                                                                                            | Purpose                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [download](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#download-batches)                                     | Download batches for selected past dates       |
| [download-enterprise](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#download-filings-by-enterprise)            | Download filings for enterprise numbers        |
| [download-reference](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#download-filings-by-reference)              | Download authentic filings by reference number |
| [validate](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#validate-saved-files)                                 | Check authentic files against saved references |
| [validate-improved](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#validate-improved-files)                     | Check improved JSON and expected OCR files     |
| [repair](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#repair-authentic-files)                                 | Resolve references and restore authentic files |
| [repair-improved](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#repair-improved-files)                         | Resolve references and restore improved JSON   |
| [download-pdf-only-accounts](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#download-pdfs-for-pdf-only-filings) | Download missing PDFs for PDF-only filings     |
| [filter-consolidated-accounts](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md#filter-consolidated-accounts)     | Collect references and move consolidated PDFs  |

Use `cbso-fetch --help` to list commands.
Use `cbso-fetch COMMAND --help` for command options.

## Documentation

- [Configuration](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/configuration.md): subscriptions, environments, S3 access, and logging.
- [Commands](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/commands.md): examples, formats, validation, repair, and dry runs.
- [Python package](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/python.md): library operations and client ownership.
- [Storage and reports](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/docs/storage-and-reports.md): file layout, repeated runs, and results.
- [Contributing](https://github.com/openthebox/cbso-webservice-pyclient/blob/main/CONTRIBUTING.md): development setup, checks, and releases.

## Licence

Proprietary. © openthebox.
