### Setup Development Environment with Pixi

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Installs the development environment and compiles the Rust extension using Pixi. This is the initial setup step for contributing to the project.

```bash
# Stage an authorized Bloomberg SDK locally under vendor/blpapi-sdk/ and let xbbg discover it
bash ./scripts/sdktool.sh               # macOS/Linux
# .\scripts\sdktool.ps1                # Windows PowerShell

# Install environment and compile the Rust extension
pixi install
pixi run install
```

--------------------------------

### Setup Development Environment for xbbg

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Commands to fork, clone the repository, and set up the development environment using pixi. This includes installing dependencies and running initial setup scripts.

```bash
git clone https://github.com/YOUR-USERNAME/xbbg.git
cd xbbg

pixi install && pixi run install

pixi run ci
```

--------------------------------

### Install @xbbg/core

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/packages/xbbg-core-darwin-arm64/README.md

Install the main wrapper package. Direct installation of the platform-specific package is only recommended for diagnostics or offline packaging.

```sh
npm install @xbbg/core
```

--------------------------------

### Verify xbbg Installation and SDK Info

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Quickly verify that xbbg is installed correctly and retrieve information about the detected Bloomberg SDK. This helps confirm setup.

```python
import xbbg

print(xbbg.__version__)
print(xbbg.get_sdk_info())
```

--------------------------------

### Install Dependencies and Build

Source: https://github.com/alpha-xone/xbbg/blob/main/CONTRIBUTING.md

Install project dependencies and build the project using pixi. This command ensures all necessary packages are installed and the project is compiled.

```bash
pixi install && pixi run install
```

--------------------------------

### Install SDK and Build Wheel

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Installs the SDK and builds the wheel package, including Rust extensions. Ensure the SDK is placed in the expected directory.

```bash
bash ./scripts/sdktool.sh
```

```powershell
.\scripts\sdktool.ps1
```

```bash
uv build
```

--------------------------------

### Install Dependencies and Run Benchmarks

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

Commands to install benchmark dependencies using 'uv' and then execute the benchmark suite. Requires Bloomberg terminal or BPIPE access.

```bash
# Install dependencies (from project root)
uv sync --group benchmark

# Run benchmarks (requires Bloomberg terminal/BPIPE access)
cd benchmarks
python run_all.py
```

--------------------------------

### Install Optional Conversion Backends

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Install optional backends for converting data to specific DataFrame types like PyArrow, Pandas, Polars, or DuckDB. Install them separately if needed.

```cmd
pip install xbbg[pyarrow] or pip install pyarrow
```

```cmd
pip install xbbg[pandas] or pip install pandas
```

```cmd
pip install xbbg[polars] or pip install polars
```

```cmd
pip install xbbg[duckdb] or pip install duckdb
```

--------------------------------

### Bloomberg Query Language (BQL) Example

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Demonstrates how to use Bloomberg Query Language (BQL) to retrieve data. Note that the 'for' clause must be outside the `get()` function.

```python
# Bloomberg Query Language (BQL)
# IMPORTANT: The 'for' clause must be OUTSIDE get(), not inside
# Correct: get(px_last) for('AAPL US Equity')
# Incorrect: get(px_last for('AAPL US Equity'))
# blp.bql("get(px_last) for('AAPL US Equity')")  # doctest: +SKIP
```

--------------------------------

### Install Benchmark Dependencies

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/benchmarks/README.md

Installs benchmark dependencies and competing packages for comparison using uv.

```bash
# Install benchmark dependencies (from project root)
uv sync --group benchmark

# Install competing packages for comparison
uv pip install xbbg==0.10.3  # Legacy version
uv pip install --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/ blpapi
uv pip install bbg-fetch
uv pip install pdblp
```

--------------------------------

### Install @xbbg/core Package

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/README.md

Install the core package using npm or bun. Optional dependencies are available for specific platforms.

```bash
npm install @xbbg/core
# or
bun add @xbbg/core
```

--------------------------------

### Get Local and Installed Package Version

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Check the version of the XBBG package locally using setuptools_scm or the installed package version.

```python
from setuptools_scm import get_version; print(get_version())
```

```python
import xbbg; print(xbbg.__version__)
```

--------------------------------

### Install xbbg Python Package

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Install the core xbbg Python package. This is the primary installation command for most users.

```cmd
pip install xbbg
```

--------------------------------

### Benchmark Configuration Example

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/benchmarks/README.md

Defines test data, benchmark settings, and packages to compare in `config.py`.

```python
# Test data configuration
TICKERS = ["IBM US Equity", "AAPL US Equity"]
FIELDS = ["PX_LAST", "VOLUME"]
DATE_RANGE = ("2025-01-02", "2025-01-06")

# Benchmark settings
ITERATIONS = 5  # Repetitions per test
WARMUP_ITERATIONS = 2  # Warm-up runs

# Packages to compare
PACKAGES = ["xbbg-rust", "xbbg-legacy", "blpapi", "bbg-fetch", "pdblp"]
```

--------------------------------

### List Installed SDK Versions (Bash)

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/blpapi-sys/vendor/blpapi-sdk/README.md

View all currently installed Bloomberg SDK versions using bash.

```bash
bash ./scripts/sdktool.sh --list
```

--------------------------------

### Dev Build Version Example

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Shows the format for development builds, which are automatically versioned based on untagged commits.

```plaintext
0.12.1.dev268+g84acdcf.d20260219
```

--------------------------------

### List Installed SDK Versions (PowerShell)

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/blpapi-sys/vendor/blpapi-sdk/README.md

View all currently installed Bloomberg SDK versions using PowerShell.

```powershell
.\scripts\sdktool.ps1 -List
```

--------------------------------

### BQL Options Query Example

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Example of a BQL query to calculate the sum of open interest for options, filtering by expiration date.

```python
# BQL Options query example - sum open interest
# blp.bql("get(sum(group(open_int))) for(filter(options('SPX Index'), expire_dt=='2025-11-21'))")  # doctest: +SKIP
```

--------------------------------

### Version Format Examples

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Illustrates the different formats for stable and pre-release versions of the xbbg package.

```plaintext
0.12.1        # Stable release
- 0.12.1b1      # Beta pre-release
- 0.12.1a1      # Alpha pre-release
- 0.12.1rc1     # Release candidate
```

--------------------------------

### Update CHANGELOG.md Example

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Provides a template for documenting changes in the CHANGELOG.md file before a release.

```markdown
## [Unreleased]

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description
```

--------------------------------

### Install Bloomberg Python Package

Source: https://github.com/alpha-xone/xbbg/blob/main/apps/xbbg-mcp/README.md

Installs the official Bloomberg Python package, which can help the xbbg-mcp wrapper locate the Bloomberg runtime automatically.

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

--------------------------------

### Install blpapi Python Package

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Install the official Bloomberg Python API package. This is often required for xbbg to auto-detect the SDK runtime.

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

--------------------------------

### Python Package Installation for CI

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/blpapi-sys/README.md

Install the official blpapi Python package for CI runtime and tests. Ensure its binary directory is added to the loader path.

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

--------------------------------

### Example of Good Release Notes

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Demonstrates effective release notes following best practices, including clear descriptions, issue linking, and categorization of changes.

```markdown
## [Unreleased]

### Added
- Native Arrow carrier with explicit `backend="native"`, `backend="pyarrow"` for real PyArrow tables, and a Narwhals default that preserves legacy PyArrow-backed behavior when PyArrow is installed (#173)
- Output format control with `Format` enum (long, semi_long, long_typed, long_metadata)
- `bta()` function for Bloomberg Technical Analysis (#175)
- `get_sdk_info()` as replacement for deprecated `getBlpapiVersion()`

### Changed
- All API functions now accept `backend` and `format` parameters
- Internal pipeline uses xbbg native Arrow tables with explicit optional conversion backends
- **BREAKING**: Deprecated `wide` output removed; use `semi_long` or pivot `long` results explicitly

### Deprecated
- `connect()` / `disconnect()` - engine auto-initializes in v1.0
- `getBlpapiVersion()` - use `get_sdk_info()` instead

### Fixed
- Empty DataFrame handling in helper functions with LONG format output (#180)
- Memory leak in streaming subscriptions (#182)
```

--------------------------------

### Install xbbg-mcp Latest

Source: https://github.com/alpha-xone/xbbg/blob/main/apps/xbbg-mcp/README.md

Installs the latest xbbg-mcp wrapper and binary pair for macOS arm64 and Linux amd64. Ensure you have the necessary Bloomberg SDK files.

```bash
curl -fsSL https://raw.githubusercontent.com/alpha-xone/xbbg/main/scripts/install-xbbg-mcp.sh | sh
```

--------------------------------

### Example Benchmark Output Report

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/benchmarks/README.md

Illustrates a markdown report format for benchmark results, showing latency, memory usage, and performance comparisons.

```text
┌─────────────────┬──────────┬─────────────┬──────────────┬──────────┐
│ Package         │ BDP (ms) │ BDH (ms)    │ Memory (MB)  │ Winner   │
├─────────────────┼──────────┼─────────────┼──────────────┼──────────┤
│ xbbg (Rust)     │  12 ✅   │  145 ✅     │  8.2 ✅      │ 🏆       │
│ xbbg (legacy)   │ 120      │ 1200        │ 45.1         │          │
│ blpapi          │  35      │  380        │ 22.3         │          │
│ bbg-fetch       │  95      │  920        │ 38.7         │          │
│ pdblp           │  85      │  890        │ 32.4         │          │
└─────────────────┴──────────┴─────────────┴──────────────┴──────────┘

Speedup vs legacy xbbg: 10.0x faster, 5.5x less memory
Speedup vs pdblp:       7.1x faster, 3.9x less memory
```

--------------------------------

### Example Benchmark Comparison in Markdown

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/benchmarks/results/README.md

An example of how benchmark results, specifically for BDP requests, might be presented in a markdown format. It highlights key metrics like Warm Mean and Memory usage, and calculates speedup.

```markdown
## BDP - Reference Data

| Package         | Warm Mean (ms) | Memory (MB) |
|-----------------|----------------|-------------|
| xbbg v1.0.0 ✅  |  12.3          |  8.2        |
| xbbg v0.10.3    | 120.7          | 45.1        |

**Speedup:** 9.8x faster, 5.5x less memory
```

--------------------------------

### Example Markdown for CHANGELOG.md

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Illustrates the standard format for the CHANGELOG.md file, including sections for Added, Changed, Deprecated, Removed, Fixed, and Security.

```markdown
## [Unreleased]

### Added
- New feature description (#PR_NUMBER)

### Changed
- Modified behavior description (#PR_NUMBER)

### Deprecated
- Feature that will be removed in future versions

### Removed
- Feature removed in this release

### Fixed
- Bug fix description (#ISSUE_NUMBER)

### Security
- Security fix description (CVE if applicable)
```

--------------------------------

### Install Specific xbbg-mcp Release

Source: https://github.com/alpha-xone/xbbg/blob/main/apps/xbbg-mcp/README.md

Installs a specific version of the xbbg-mcp wrapper and binary. Replace '1.0.0' with the desired version. Requires Bloomberg SDK.

```bash
curl -fsSL https://raw.githubusercontent.com/alpha-xone/xbbg/main/scripts/install-xbbg-mcp.sh | sh -s -- 1.0.0
```

--------------------------------

### Get Field Information using Convenience Wrapper

Source: https://context7.com/alpha-xone/xbbg/llms.txt

Uses a convenience wrapper to retrieve information for specified Bloomberg fields.

```python
# Convenience wrappers
df = xbbg.fieldInfo(["PX_LAST", "VOLUME"])
```

--------------------------------

### Utilities (Futures, Currency, etc.)

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Utilize functions for resolving futures contracts, getting active futures, performing currency conversions, and retrieving dividend history.

```python
# Resolve futures contract
contract = blp.fut_ticker('ES1 Index', '2024-01-15', freq='ME')  # → 'ESH24 Index'
```

```python
# Get active futures
active = blp.active_futures('ESA Index', '2024-01-15')
```

```python
# Currency conversion
hist_usd = blp.bdh('BMW GR Equity', 'PX_LAST', '2024-01-01', '2024-01-31')
hist_eur = blp.convert_ccy(hist_usd, ccy='EUR')
```

```python
# Dividend history
divs = blp.dividend('AAPL US Equity', start_date='2024-01-01', end_date='2024-12-31')
```

--------------------------------

### Search for Fields

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Provides an example of searching for fields related to a keyword. Use this to discover relevant field names for your data queries.

```python
# Search for fields
blp.fieldSearch('vwap')  # Find VWAP-related fields
```

--------------------------------

### Filter Market Data by Session

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Use the `session` parameter to retrieve data for specific trading sessions like 'am_open_30'. This example fetches data for the first 30 minutes of the morning session for a Japanese equity.

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

--------------------------------

### Fetch Reference, Historical, and Intraday Data with xbbg

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Demonstrates fetching different types of data using the xbbg library. Ensure you have the necessary Bloomberg API authorization and xbbg installed.

```python
from xbbg import blp

# Reference data
prices = blp.bdp(['AAPL US Equity', 'MSFT US Equity'], 'PX_LAST')

# Historical data
hist = blp.bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-12-31')

# Intraday bars with sub-minute precision
intraday = blp.bdib('TSLA US Equity', dt='2024-01-15', interval=10, intervalHasSeconds=True)
```

--------------------------------

### Date and Datetime Input Examples

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/README.md

Demonstrates using various date and datetime formats with bdh and bdtick functions. Supports JavaScript Date, ISO 8601 strings, Bloomberg-native strings, epoch milliseconds, and Luxon DateTime objects.

```typescript
import { bdh, bdtick } from '@xbbg/core';

await bdh('AAPL US Equity', 'PX_LAST', { start: new Date('2024-01-01'), end: '20240630' });
await bdtick('AAPL US Equity', new Date('2024-12-01T09:30Z'), Date.UTC(2024, 11, 1, 16, 0));
```

--------------------------------

### Get Bloomberg API Version

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Retrieves the installed version of the xbbg library.

```python
blp.__version__
```

--------------------------------

### Set Up Bloomberg SDK

Source: https://github.com/alpha-xone/xbbg/blob/main/CONTRIBUTING.md

Execute the SDK tool script to set up the Bloomberg C++ SDK. This script is essential for building the Rust backend and requires you to have your own Bloomberg SDK access.

```bash
bash ./scripts/sdktool.sh
```

```powershell
.\scripts\sdktool.ps1
```

--------------------------------

### Get xbbg Version

Source: https://github.com/alpha-xone/xbbg/blob/main/CONTRIBUTING.md

Check the installed version of the xbbg library. This is helpful for debugging and reporting issues.

```python
python -c "import xbbg; print(xbbg.__version__)"
```

--------------------------------

### Get Python Version

Source: https://github.com/alpha-xone/xbbg/blob/main/CONTRIBUTING.md

Retrieve the installed Python version. This information is useful when reporting issues or setting up the environment.

```bash
python --version
```

--------------------------------

### Get Dividend Data

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Fetches dividend information for a security starting from a specified year. Displays payment dates, amounts, and frequencies.

```python
blp.dividend('SPY US Equity', start_date='2019')
```

--------------------------------

### Intraday Bar Data Retrieval

Source: https://github.com/alpha-xone/xbbg/blob/main/apps/xbbg-cli/README.md

Get intraday bar data for a security at a specified interval. Requires security identifier, interval, start date, and optionally an end date.

```bash
xbbg bdib "AAPL US Equity" --interval 5 --start 2024-01-15
```

--------------------------------

### Get Current Stock Prices using xbbg

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Example of fetching the last traded price for specified equity tickers using the `bdp` function from the `blp` module. Requires an active Bloomberg terminal session.

```python
from xbbg import blp

# Get current stock prices
prices = blp.bdp(['AAPL US Equity', 'MSFT US Equity'], 'PX_LAST')
print(prices)
```

--------------------------------

### Run Subscription Replay Benchmark

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/README.md

Execute the subscription replay benchmark with various configurations. Use flags like `--path` to specify the measurement method and `--consume` to control output processing. `--warmup-iterations` can be used for untimed warmup.

```bash
npm run bench:subscription-replay -- --rows 100000 --iterations 3
```

```bash
npm run bench:subscription-replay -- --path arrow-decode-only --rows 100000 --iterations 3
```

```bash
npm run build:ts
npm run bench:subscription-replay -- --path subscription-wrapper --rows 100000 --iterations 3
```

```bash
npm run bench:subscription-replay -- --capture-live "XBTUSD Curncy" --capture-ms 10000 --out tmp/xbtusd-ticks.jsonl
```

```bash
npm run bench:subscription-replay -- --fixture tmp/xbtusd-ticks.jsonl --iterations 10 --warmup-iterations 1 --consume schema
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/alpha-xone/xbbg/blob/main/CONTRIBUTING.md

Clone the xbbg repository and change the directory to the project root. This is the initial step for setting up your development environment.

```bash
git clone https://github.com/alpha-xone/xbbg.git
cd xbbg
```

--------------------------------

### Configuration and Connection

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/README.md

Demonstrates how to configure the xbbg library and establish connections to Bloomberg data sources using different methods.

```APIDOC
## Configuration

### Description
Configure the xbbg library with connection details.

### Method
`xbbg.configure(options)`

### Parameters
- **options** (object) - Required - Configuration options.
  - **host** (string) - The host address.
  - **port** (number) - The port number.

## Connection

### Description
Establish a connection to Bloomberg data sources.

### Method
`xbbg.connect(options)`

### Parameters
- **options** (object) - Required - Connection options.
  - **servers** (array) - Optional - List of servers for failover.
    - **host** (string) - Server host.
    - **port** (number) - Server port.
  - **auth** (object) - Optional - Authentication details.
    - **method** (string) - Authentication method (e.g., 'userapp').
    - **appName** (string) - Application name.
  - **tls** (object) - Optional - TLS/SSL configuration.
    - **clientCredentials** (string) - Path to client credentials file.
    - **clientCredentialsPassword** (string) - Password for client credentials.
    - **trustMaterial** (string) - Path to trust material file.
  - **zfpRemote** (string) - Optional - ZFP remote endpoint identifier.
```

--------------------------------

### Crate Structure Overview

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/xbbg-sys/README.md

Illustrates the directory structure of the xbbg-sys crate, highlighting key files like Cargo.toml, build.rs, and src/lib.rs.

```text
xbbg-sys/
├── Cargo.toml      Live feature and optional dependency on blpapi-sys
├── build.rs        No-op build script; blpapi-sys owns binding generation
└── src/
    └── lib.rs      Feature gate and re-export of blpapi-sys
```

--------------------------------

### Build Project

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Command to build the project. This is typically done before publishing or for creating distributable artifacts.

```bash
pixi run build
```

--------------------------------

### Local Development Build Commands

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/README.md

Commands for building and testing the @xbbg/core package locally. This includes preferred methods for building the native addon and running tests.

```bash
# Preferred: build and copy js-xbbg/napi_xbbg.node into the package directory
npm --prefix js-xbbg run build

# Lower-level Rust build (useful while hacking on napi-xbbg itself)
cargo build -p napi-xbbg

# Stage the current platform package template with the built addon
npm --prefix js-xbbg run stage:native-package

# Run JS smoke test from js-xbbg/
npm test
```

--------------------------------

### Architecture Overview

Source: https://github.com/alpha-xone/xbbg/blob/main/bindings/dotnet-xbbg/README.md

Illustrates the architectural flow from the Rust engine to the C# wrappers and potential Excel add-in compatibility.

```text
xbbg-core + xbbg-async  (pure Rust engine)
         ↓
   dotnet-xbbg           (this crate — C-ABI exports)
         ↓
  XbbgSharp.dll          (NuGet package + C# wrappers)
```

--------------------------------

### Get Tick Data with Event Types

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Retrieve tick-by-tick data for a specified ticker and date, filtering for specific event types like 'TRADE'. Use `.head()` to get the first few entries.

```python
# Tick-by-tick data with event types and condition codes
blp.bdtick(ticker='XYZ US Equity', dt='2024-10-15', session='day', types=['TRADE']).head()
```

--------------------------------

### Get Market Hours with Reference Exchange

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Retrieve intraday bar data for a specific ticker, using a reference exchange ticker to determine market hours. Use `.tail()` to get the latest entries.

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

--------------------------------

### Run Benchmark Suite with Profile

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/xbbg-bench/README.md

Execute the benchmark suite with a specific profile (smoke, standard, stress). Profiles adjust the intensity and duration of tests, particularly live subscription collection.

```bash
BENCH_PROFILE=smoke cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

```bash
BENCH_PROFILE=standard cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

```bash
BENCH_PROFILE=stress cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Release Workflow Parameters

Source: https://github.com/alpha-xone/xbbg/blob/main/RELEASE_PROCESS.md

Illustrates how to configure the 'Bump Version and Create Release' workflow with different parameters for version increments and pre-release types.

```plaintext
- `0.12.1` → `0.13.0`: bump_type=`minor`, pre_release=`none`
- `0.12.1` → `0.12.2`: bump_type=`patch`, pre_release=`none`
- `0.12.1` → `0.12.2b1`: bump_type=`patch`, pre_release=`beta`, pre_number=`1`
```

--------------------------------

### Get ETF Holdings with BQL

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Retrieves a list of holdings for a given ETF. Requires the ETF ticker as input.

```python
blp.etf_holdings('SPY US Equity')
```

--------------------------------

### Get Parameters for a Specific Technical Analysis Study

Source: https://context7.com/alpha-xone/xbbg/llms.txt

Prints the default parameters for a specified technical analysis study, such as 'macd'.

```python
print(xbbg.ta_study_params("macd"))
```

--------------------------------

### Run Tests

Source: https://github.com/alpha-xone/xbbg/blob/main/CONTRIBUTING.md

Execute the project's test suite using pixi. This command verifies the integrity of your changes and ensures the project functions as expected.

```bash
pixi run test
```

--------------------------------

### Basic Usage with Different Backends

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Demonstrates fetching data using the default Narwhals DataFrame and explicitly specifying various backends like native, PyArrow, Pandas, Polars, DuckDB, and Narwhals.

```python
from xbbg import blp, Backend

# Default Narwhals DataFrame; PyArrow-backed when PyArrow is installed
df = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31")
print(df.columns, len(df))

# Explicit native carrier
table = blp.bdp("AAPL US Equity", "PX_LAST", backend="native")

# Optional conversions
table_pyarrow = blp.bdp("IBM US Equity", "PX_LAST", backend=Backend.PYARROW)
df_pandas = blp.bdp("MSFT US Equity", "PX_LAST", backend=Backend.PANDAS)
df_polars = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.POLARS)
duckdb_rel = blp.bdh("SPX Index", "PX_LAST", "2024-01-01", "2024-12-31", backend=Backend.DUCKDB)
nw_df = blp.bdp("AAPL US Equity", "PX_LAST", backend=Backend.NARWHALS)
```

--------------------------------

### Fetch Historical Data with Pandas Timestamp Input

Source: https://context7.com/alpha-xone/xbbg/llms.txt

Accepts pandas Timestamps for start and end dates. Ensure pandas is imported.

```python
import pandas as pd
import xbbg
df = xbbg.bdh(
    "AAPL US Equity",
    "PX_LAST",
    start_date=pd.Timestamp("2024-01-01"),
    end_date=pd.Timestamp("2024-12-31"),
)
```

--------------------------------

### Project Architecture Overview

Source: https://github.com/alpha-xone/xbbg/blob/main/bindings/napi-xbbg/README.md

Illustrates the layered architecture of the xbbg project, showing the progression from the pure Rust engine to the Node.js npm package.

```text
xbbg-core + xbbg-async  (pure Rust engine)
         ↓
    napi-xbbg            (this crate — thin N-API wrapper)
         ↓
     js-xbbg             (npm package + TS types)
```

--------------------------------

### Get Metadata for Specific Bloomberg Fields

Source: https://context7.com/alpha-xone/xbbg/llms.txt

Retrieves metadata for a list of specified Bloomberg fields. Returns a DataFrame with field details. Specify backend.

```python
import xbbg

# Get metadata for specific fields
df = xbbg.bflds(fields=["PX_LAST", "VOLUME", "PE_RATIO"], backend="pandas")
```

--------------------------------

### Generate blpapi-sys Bindings Locally

Source: https://github.com/alpha-xone/xbbg/blob/main/docker/README.md

Run the CI container to generate blpapi-sys bindings artifact locally. This requires mounting the current directory and setting environment variables for the SDK version and path.

```bash
mkdir -p target/ci-bindings

podman run --rm \
  -v "$PWD:/work" \
  -w /work \
  -e BLPAPI_BINDINGS_EXPORT_PATH=/work/target/ci-bindings/bindings.rs \
  xbbg-ci:local \
  bash -lc '
    BLPAPI_VERSION=${BLPAPI_VERSION:-3.26.2.1}
    bash ./scripts/sdktool.sh --version "$BLPAPI_VERSION" --no-set-active
    export BLPAPI_ROOT=/work/crates/blpapi-sys/vendor/blpapi-sdk/$BLPAPI_VERSION
    export LD_LIBRARY_PATH=/work/crates/blpapi-sys/vendor/blpapi-sdk/$BLPAPI_VERSION/Linux:$LD_LIBRARY_PATH
    cargo build -p blpapi-sys
  '
```

--------------------------------

### Get Bulk/Block Data (BDS)

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Retrieves bulk or block data for a security, such as 'All_Holders_Public_Filings'. Demonstrates data filtering and renaming for clarity. Caching is enabled.

```python
holders = blp.bds('AMZN US Equity', flds='All_Holders_Public_Filings', cache=True)
(holders.loc[:, ~holders.columns.str.contains(f'holder_id|portfolio_name|change|number|metro|percent_of_portfolio|source')]).rename(index=lambda tkr: tkr.replace(' Equity', ''), columns={'holder_name_': 'holder', 'position_': 'position', 'filing_date__': 'filing_dt', 'percent_outstanding': 'pct_out', 'insider_status_': 'insider'})).head()
```

--------------------------------

### Run BQL JSON Extraction Benchmark with Detail Mode

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/xbbg-bench/README.md

Execute the BQL JSON extraction benchmarks with the 'detail' profile mode. This provides more granular performance metrics for the BQL JSON parsing and Arrow materialization path.

```bash
BENCH_ONLY=bql_json BENCH_PROFILE_MODE=detail cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Get Reference Data (BDP)

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Fetches single point-in-time reference data for a given security and fields. Supports optional parameters like Eqy_Fund_Crncy.

```python
blp.bdp('AAPL US Equity', flds=['Security_Name', 'Last_Price'])
```

```python
blp.bdp('6758 JP Equity', flds='Crncy_Adj_Mkt_Cap', Eqy_Fund_Crncy='USD')
```

--------------------------------

### Retrieve End-of-Day Historical Data (BDH)

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Fetches historical end-of-day data for a single ticker and specified fields. Requires start and end dates.

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

--------------------------------

### Build xbbg CI Docker Image

Source: https://github.com/alpha-xone/xbbg/blob/main/docker/README.md

Build the Rust CI image locally using Podman. This command creates an OCI-compatible image tagged as 'xbbg-ci:local'.

```bash
podman build -f docker/ci/Dockerfile -t xbbg-ci:local .
```

--------------------------------

### Run Detailed Benchmark Profiling

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/xbbg-bench/README.md

Use this command to enable detailed profiling for benchmarks. Set `BENCH_PROFILE_MODE` to `detail` to record structured profiling data including phase timings and allocation counters. `BENCH_ONLY` can filter which benchmarks to run.

```bash
BENCH_PROFILE_MODE=detail BENCH_ONLY=synthetic_bdh \
  cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Fetch Intraday Bar Data with Pandas

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Fetches intraday bar data for multiple tickers and combines them into a pandas DataFrame. Requires pandas and xbbg to be installed.

```python
cur_dt = pd.Timestamp('today', tz='America/New_York').date()
recent = pd.bdate_range(end=cur_dt, periods=2, tz='America/New_York')
pre_dt = max(filter(lambda dd: dd < cur_dt, recent))

fx = blp.bdib('JPY Curncy', dt=pre_dt)
jp = pd.concat([
    blp.bdib(ticker, dt=pre_dt, session='day')
    for ticker in ['7974 JP Equity', '9984 JP Equity']
], axis=1)
jp.tail()
```

--------------------------------

### Build xbbg-mcp from Source

Source: https://github.com/alpha-xone/xbbg/blob/main/apps/xbbg-mcp/README.md

Builds the xbbg-mcp binary from source code. This process requires Rust and Cargo. The compiled binary will be in the target directory.

```bash
bash ./scripts/sdktool.sh
cargo build --release -p xbbg-mcp --locked
./scripts/xbbg-mcp
```

--------------------------------

### Live Streaming Market Data

Source: https://github.com/alpha-xone/xbbg/blob/main/js-xbbg/README.md

Subscribe to live market data streams for specified securities and fields. The example shows how to iterate over incoming ticks and log them.

```typescript
// Live streaming
const sub = await xbbg.blp.asubscribe(['AAPL US Equity'], ['LAST_PRICE', 'BID', 'ASK']);
for await (const tick of sub) {
  console.log(tick);
}
```

--------------------------------

### Run Default Benchmark Suite

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/xbbg-bench/README.md

Execute the main benchmark suite using Cargo. This command runs a comprehensive set of tests including live probes and cached replays.

```bash
cargo bench --package xbbg-bench --bench xbbg_benchmark_suite
```

--------------------------------

### Get Field Information

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Retrieves detailed information about specified fields, including data types and descriptions. This is helpful for understanding field properties before using them in requests.

```python
# Get field info
blp.fieldInfo(['PX_LAST', 'VOLUME'])  # See data types & descriptions
```

--------------------------------

### Get Trading Volume and Turnover

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Retrieve trading volume and turnover data for multiple tickers within a specified date range, with currency conversion to USD.

```python
# Trading volume & turnover (currency-adjusted, in millions)
blp.turnover(['ABC US Equity', 'DEF US Equity'], start_date='2024-01-01', end_date='2024-01-10', ccy='USD')
```

--------------------------------

### Discover Schema, Operations, and Generate IDE Stubs

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Explore Bloomberg service schemas and operations using `blp.bops()` and `list_operations()`. Generate IDE-friendly stubs for enhanced autocompletion.

```python
from xbbg import blp
from xbbg.schema import get_operation, list_operations

print(blp.bops())  # quick list for //blp/refdata
print(list_operations('//blp/instruments'))

hist_schema = get_operation('//blp/refdata', 'HistoricalDataRequest')
print(hist_schema.request.children[0].name)
```

--------------------------------

### Run Benchmarks

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/benchmarks/README.md

Executes all benchmarks or specific benchmark scripts.

```bash
# Run all benchmarks
python py-xbbg/benchmarks/run_all.py

# Run specific benchmark
python py-xbbg/benchmarks/bench_bdp.py
python py-xbbg/benchmarks/bench_bdh.py
python py-xbbg/benchmarks/bench_bdib.py
```

--------------------------------

### bdp() - Get current/reference data

Source: https://github.com/alpha-xone/xbbg/blob/main/README.md

Retrieves current or reference data for specified tickers and fields. Supports multiple tickers, Excel-style overrides, and ISIN/CUSIP/SEDOL identifiers.

```APIDOC
## bdp()

### Description
Get current/reference data for specified tickers and fields.

### Key Features
- Multiple tickers & fields
- Excel-style overrides
- ISIN/CUSIP/SEDOL support
```

--------------------------------

### Re-download and Re-extract SDK (Bash)

Source: https://github.com/alpha-xone/xbbg/blob/main/crates/blpapi-sys/vendor/blpapi-sdk/README.md

Force a re-download and re-extraction of a specific Bloomberg SDK version using bash.

```bash
bash ./scripts/sdktool.sh --version <version> --force
```

--------------------------------

### Get Earnings Data

Source: https://github.com/alpha-xone/xbbg/blob/main/py-xbbg/examples/xbbg_jupyter_examples.ipynb

Retrieves earnings data for a security, specifying the fiscal year and the number of periods to include. Shows segment-wise financial data and percentages.

```python
blp.earning('FB US Equity', Eqy_Fund_Year=2018, Number_Of_Periods=2)
```