Metadata-Version: 2.5
Name: otb-cbso-webservice-pyclient
Version: 2.3.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.

## 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.
