Metadata-Version: 2.4
Name: xbbg
Version: 0.7.10
Summary: Intuitive Bloomberg data API
Author-email: Alpha x1 <alpha.xone@outlook.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/alpha-xone/xbbg
Project-URL: Documentation, https://xbbg.readthedocs.io/
Project-URL: Source, https://github.com/alpha-xone/xbbg
Project-URL: Issues, https://github.com/alpha-xone/xbbg/issues
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas>=2.3.3
Requires-Dist: pandas-market-calendars>=5.1.3
Requires-Dist: pyarrow>=22.0.0
Requires-Dist: pytest>=8.4.2
Requires-Dist: pytz>=2025.2
Requires-Dist: ruamel.yaml>=0.18.16
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: codecov; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.3.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
Requires-Dist: sphinx-llms-txt>=0.7.0; extra == "docs"
Dynamic: license-file

# xbbg

![xbbg](https://raw.githubusercontent.com/alpha-xone/xbbg/main/docs/xbbg.png)

An intuitive Bloomberg API for Python

[![PyPI version](https://img.shields.io/pypi/v/xbbg.svg)](https://pypi.org/project/xbbg/)
[![Python versions](https://img.shields.io/pypi/pyversions/xbbg.svg)](https://pypi.org/project/xbbg/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/xbbg)](https://pypistats.org/packages/xbbg)
[![Gitter](https://badges.gitter.im/xbbg/community.svg)](https://gitter.im/xbbg/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)

[![Coffee](https://www.buymeacoffee.com/assets/img/custom_images/purple_img.png)](https://www.buymeacoffee.com/Lntx29Oof)

<!-- xbbg:latest-release-start -->
Latest release: xbbg==0.7.10 (release: [notes](https://github.com/alpha-xone/xbbg/releases/tag/xbbg%3D%3D0.7.10))
<!-- xbbg:latest-release-end -->

## Features

Below are main features. See [Jupyter notebook examples](https://colab.research.google.com/drive/1YVVS5AiJAQGGEECmOFAb7DNQZMOHdXLR).

- Excel compatible inputs
- Straightforward intraday bar requests
- Subscriptions

## Requirements

- Bloomberg C++ SDK version 3.12.1 or higher:

  - Visit [Bloomberg API Library](https://www.bloomberg.com/professional/support/api-library/) and download C++ Supported Release

  - In the `bin` folder of downloaded zip file, copy `blpapi3_32.dll` and `blpapi3_64.dll` to Bloomberg `BLPAPI_ROOT` folder (usually `blp/DAPI`)

- Bloomberg official Python API:

```cmd
pip install blpapi --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/
```

- `numpy`, `pandas`, `ruamel.yaml` and `pyarrow`

## Installation

```cmd
pip install xbbg
```

Supported Python versions: 3.10 – 3.14 (universal wheel).

## Quickstart

```python
from xbbg import blp

# Reference data (BDP)
ref = blp.bdp(tickers='AAPL US Equity', flds=['Security_Name', 'GICS_Sector_Name'])
print(ref)

# Historical data (BDH)
hist = blp.bdh('SPX Index', ['high', 'low', 'last_price'], '2021-01-01', '2021-01-05')
print(hist.tail())
```

## Development

- Create venv and install deps from lock:

```cmd
uv venv .venv
.\.venv\Scripts\Activate.ps1
uv sync --locked --extra dev --extra test
```

- Add a dependency:

```cmd
uv add <package>
```

- Run tasks:

```cmd
uv run ruff check xbbg
uv run pytest --doctest-modules --cov -v xbbg
```

- Build (for maintainers):

```cmd
uv run python -m build
```

Publishing is handled via GitHub Actions using PyPI Trusted Publishing (OIDC).

## Docs (optional)

```cmd
uv sync --locked --extra docs
uv run sphinx-build -b html docs docs/_build/html
```

## Contributing

- Issues and feature requests: please open an issue on the repository.
- Pull requests welcome. Run lint and tests locally:

```cmd
uv sync --locked --extra dev --extra test
uv run ruff check xbbg
uv run pytest --doctest-modules -q
```

## Links

- [PyPI](https://pypi.org/project/xbbg/)
- [Documentation](https://xbbg.readthedocs.io/)
- [Source](https://github.com/alpha-xone/xbbg)
- Security policy: see `SECURITY.md`

## What's New

<!-- xbbg:changelog-start -->
_0.7.10_ - see release: [notes](https://github.com/alpha-xone/xbbg/releases/tag/xbbg%3D%3D0.7.10)

What's Changed

- Migrate to uv + PEP 621; modernize CI and blpapi index by @kaijensen55 in #124

New Contributors

- @kaijensen55 made their first contribution in #124

Full Changelog: v0.7.9...xbbg==0.7.10
<!-- xbbg:changelog-end -->

_0.7.7a2_ - Custom `config` and etc. for reference exchange (author `hceh`)

_0.7.6a2_ - Use `blp.connect` for alternative Bloomberg connection (author `anxl2008`)

_0.7.2_ - Use `async` for live data feeds

_0.7.0_ - `bdh` preserves columns orders (both tickers and flds).
`timeout` argument is available for all queries - `bdtick` usually takes longer to respond -
can use `timeout=1000` for example if keep getting empty DataFrame.

_0.6.6_ - Add flexibility to use reference exchange as market hour definition
(so that it's not necessary to add `.yml` for new tickers, provided that the exchange was defined
in `/xbbg/markets/exch.yml`). See example of `bdib` below for more details.

_0.6.0_ - Speed improvements and tick data availablity

_0.5.0_ - Rewritten library to add subscription, BEQS, simplify interface and remove dependency of `pdblp`

_0.1.22_ - Remove PyYAML dependency due to security vulnerability

_0.1.17_ - Add `adjust` argument in `bdh` for easier dividend / split adjustments

## Tutorial

```python
In [1]: from xbbg import blp
```

### Basics

- ``BDP`` example:

```python
In [2]: blp.bdp(tickers='NVDA US Equity', flds=['Security_Name', 'GICS_Sector_Name'])
```

```pydocstring
Out[2]:
               security_name        gics_sector_name
NVDA US Equity   NVIDIA Corp  Information Technology
```

- ``BDP`` with overrides:

```python
In [3]: blp.bdp('AAPL US Equity', 'Eqy_Weighted_Avg_Px', VWAP_Dt='20181224')
```

```pydocstring
Out[3]:
                eqy_weighted_avg_px
AAPL US Equity               148.75
```

- ``BDH`` example:

```python
In [4]: blp.bdh(
   ...:     tickers='SPX Index', flds=['high', 'low', 'last_price'],
   ...:     start_date='2018-10-10', end_date='2018-10-20',
   ...: )
```

```pydocstring
Out[4]:
           SPX Index
                high      low last_price
2018-10-10  2,874.02 2,784.86   2,785.68
2018-10-11  2,795.14 2,710.51   2,728.37
2018-10-12  2,775.77 2,729.44   2,767.13
2018-10-15  2,775.99 2,749.03   2,750.79
2018-10-16  2,813.46 2,766.91   2,809.92
2018-10-17  2,816.94 2,781.81   2,809.21
2018-10-18  2,806.04 2,755.18   2,768.78
2018-10-19  2,797.77 2,760.27   2,767.78
```

- ``BDH`` example with Excel compatible inputs:

```python
In [5]: blp.bdh(
   ...:     tickers='SHCOMP Index', flds=['high', 'low', 'last_price'],
   ...:     start_date='2018-09-26', end_date='2018-10-20',
   ...:     Per='W', Fill='P', Days='A',
   ...: )
```

```pydocstring
Out[5]:
           SHCOMP Index
                   high      low last_price
2018-09-28     2,827.34 2,771.16   2,821.35
2018-10-05     2,827.34 2,771.16   2,821.35
2018-10-12     2,771.94 2,536.66   2,606.91
2018-10-19     2,611.97 2,449.20   2,550.47
```

- ``BDH`` without adjustment for dividends and splits:

```python
In [6]: blp.bdh(
   ...:     'AAPL US Equity', 'px_last', '20140605', '20140610',
   ...:     CshAdjNormal=False, CshAdjAbnormal=False, CapChg=False
   ...: )
```

```pydocstring
Out[6]:
           AAPL US Equity
                  px_last
2014-06-05         647.35
2014-06-06         645.57
2014-06-09          93.70
2014-06-10          94.25
```

- ``BDH`` adjusted for dividends and splits:

```python
In [7]: blp.bdh(
   ...:     'AAPL US Equity', 'px_last', '20140605', '20140610',
   ...:     CshAdjNormal=True, CshAdjAbnormal=True, CapChg=True
   ...: )
```

```pydocstring
Out[7]:
           AAPL US Equity
                  px_last
2014-06-05          85.45
2014-06-06          85.22
2014-06-09          86.58
2014-06-10          87.09
```

- ``BDS`` example:

```python
In [8]: blp.bds('AAPL US Equity', 'DVD_Hist_All', DVD_Start_Dt='20180101', DVD_End_Dt='20180531')
```

```pydocstring
Out[8]:
               declared_date     ex_date record_date payable_date  dividend_amount dividend_frequency dividend_type
AAPL US Equity    2018-05-01  2018-05-11  2018-05-14   2018-05-17             0.73            Quarter  Regular Cash
AAPL US Equity    2018-02-01  2018-02-09  2018-02-12   2018-02-15             0.63            Quarter  Regular Cash
```

- Intraday bars ``BDIB`` example:

```python
In [9]: blp.bdib(ticker='BHP AU Equity', dt='2018-10-17').tail()
```

```pydocstring
Out[9]:
                          BHP AU Equity
                                   open  high   low close   volume num_trds
2018-10-17 15:56:00+11:00         33.62 33.65 33.62 33.64    16660      126
2018-10-17 15:57:00+11:00         33.65 33.65 33.63 33.64    13875      156
2018-10-17 15:58:00+11:00         33.64 33.65 33.62 33.63    16244      159
2018-10-17 15:59:00+11:00         33.63 33.63 33.61 33.62    16507      167
2018-10-17 16:10:00+11:00         33.66 33.66 33.66 33.66  1115523      216
```

Above example works because 1) `AU` in equity ticker is mapped to `EquityAustralia` in
`markets/assets.yml`, and 2) `EquityAustralia` is defined in `markets/exch.yml`.
To add new mappings, define `BBG_ROOT` in sys path and add `assets.yml` and
`exch.yml` under `BBG_ROOT/markets`.

_New in 0.6.6_ - if exchange is defined in `/xbbg/markets/exch.yml`, can use
`ref` to look for relevant exchange market hours. Both `ref='ES1 Index'` and
`ref='CME'` work for this example:

```python
In [10]: blp.bdib(ticker='ESM0 Index', dt='2020-03-20', ref='ES1 Index').tail()
```

```pydocstring
out[10]:
                          ESM0 Index
                                open     high      low    close volume num_trds        value
2020-03-20 16:55:00-04:00   2,260.75 2,262.25 2,260.50 2,262.00    412      157   931,767.00
2020-03-20 16:56:00-04:00   2,262.25 2,267.00 2,261.50 2,266.75    812      209 1,838,823.50
2020-03-20 16:57:00-04:00   2,266.75 2,270.00 2,264.50 2,269.00   1136      340 2,576,590.25
2020-03-20 16:58:00-04:00   2,269.25 2,269.50 2,261.25 2,265.75   1077      408 2,439,276.00
2020-03-20 16:59:00-04:00   2,265.25 2,272.00 2,265.00 2,266.50   1271      378 2,882,978.25
```

- Intraday bars within market session:

```python
In [11]: blp.bdib(ticker='7974 JT Equity', dt='2018-10-17', session='am_open_30').tail()
```

```pydocstring
Out[11]:
                          7974 JT Equity
                                    open      high       low     close volume num_trds
2018-10-17 09:27:00+09:00      39,970.00 40,020.00 39,970.00 39,990.00  10800       44
2018-10-17 09:28:00+09:00      39,990.00 40,020.00 39,980.00 39,980.00   6300       33
2018-10-17 09:29:00+09:00      39,970.00 40,000.00 39,960.00 39,970.00   3300       21
2018-10-17 09:30:00+09:00      39,960.00 40,010.00 39,950.00 40,000.00   3100       19
2018-10-17 09:31:00+09:00      39,990.00 40,000.00 39,980.00 39,990.00   2000       15
```

- Corporate earnings:

```python
In [12]: blp.earning('AMD US Equity', by='Geo', Eqy_Fund_Year=2017, Number_Of_Periods=1)
```

```pydocstring
Out[12]:
                 level    fy2017  fy2017_pct
Asia-Pacific      1.00  3,540.00       66.43
    China         2.00  1,747.00       49.35
    Japan         2.00  1,242.00       35.08
    Singapore     2.00    551.00       15.56
United States     1.00  1,364.00       25.60
Europe            1.00    263.00        4.94
Other Countries   1.00    162.00        3.04
```

- Dividends:

```python
In [13]: blp.dividend(['C US Equity', 'MS US Equity'], start_date='2018-01-01', end_date='2018-05-01')
```

```pydocstring
Out[13]:
                dec_date     ex_date    rec_date    pay_date  dvd_amt dvd_freq      dvd_type
C US Equity   2018-01-18  2018-02-02  2018-02-05  2018-02-23     0.32  Quarter  Regular Cash
MS US Equity  2018-04-18  2018-04-27  2018-04-30  2018-05-15     0.25  Quarter  Regular Cash
MS US Equity  2018-01-18  2018-01-30  2018-01-31  2018-02-15     0.25  Quarter  Regular Cash
```

-----

_New in 0.1.17_ - Dividend adjustment can be simplified to one parameter `adjust`:

- ``BDH`` without adjustment for dividends and splits:

```python
In [14]: blp.bdh('AAPL US Equity', 'px_last', '20140606', '20140609', adjust='-')
```

```pydocstring
Out[14]:
           AAPL US Equity
                  px_last
2014-06-06         645.57
2014-06-09          93.70
```

- ``BDH`` adjusted for dividends and splits:

```python
In [15]: blp.bdh('AAPL US Equity', 'px_last', '20140606', '20140609', adjust='all')
```

```pydocstring
Out[15]:
           AAPL US Equity
                  px_last
2014-06-06          85.22
2014-06-09          86.58
```

### Data Storage

If `BBG_ROOT` is provided in `os.environ`, data can be saved locally.
By default, local storage is preferred than Bloomberg for all queries.

Noted that local data usage must be compliant with Bloomberg Datafeed Addendum
(full description in `DAPI<GO>`):

> To access Bloomberg data via the API (and use that data in Microsoft Excel),
> your company must sign the 'Datafeed Addendum' to the Bloomberg Agreement.
> This legally binding contract describes the terms and conditions of your use
> of the data and information available via the API (the "Data").
> The most fundamental requirement regarding your use of Data is that it cannot
> leave the local PC you use to access the BLOOMBERG PROFESSIONAL service.

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=alpha-xone/xbbg&type=Date)](https://star-history.com/#alpha-xone/xbbg&Date)

|                |                                                                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Docs           | [![Documentation Status](https://readthedocs.org/projects/xbbg/badge/?version=latest)](https://xbbg.readthedocs.io/)                                                             |
| Build          | [![Actions Status](https://github.com/alpha-xone/xbbg/workflows/Auto%20CI/badge.svg)](https://github.com/alpha-xone/xbbg/actions)                                                |
| Coverage       | [![codecov](https://codecov.io/gh/alpha-xone/xbbg/branch/main/graph/badge.svg)](https://codecov.io/gh/alpha-xone/xbbg)                                                           |
| Quality        | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/daec9f52ba344e3ea116c15f1fc6d541)](https://www.codacy.com/gh/alpha-xone/xbbg/)                                       |
|                | [![CodeFactor](https://www.codefactor.io/repository/github/alpha-xone/xbbg/badge)](https://www.codefactor.io/repository/github/alpha-xone/xbbg)                                  |
|                | [![codebeat badge](https://codebeat.co/badges/eef1f14d-72eb-445a-af53-12d3565385ec)](https://codebeat.co/projects/github-com-alpha-xone-xbbg-main)                               |
| License        | [![GitHub license](https://img.shields.io/github/license/alpha-xone/xbbg.svg)](https://github.com/alpha-xone/xbbg/blob/main/LICENSE)                                             |
