{ "markdown": "\n
\n\n

\n \n \"xbbg\n \n

\n\n[![CI](https://github.com/xbbg-org/xbbg/actions/workflows/ci-rust.yml/badge.svg)](https://github.com/xbbg-org/xbbg/actions/workflows/ci-rust.yml)\n[![PyPI version](https://img.shields.io/pypi/v/xbbg.svg)](https://pypi.org/project/xbbg/)\n[![Conda version](https://anaconda.org/conda-forge/xbbg/badges/version.svg)](https://anaconda.org/conda-forge/xbbg)\n[![npm version](https://img.shields.io/npm/v/%40xbbg%2Fcore.svg)](https://www.npmjs.com/package/@xbbg/core)\n[![Python versions](https://img.shields.io/pypi/pyversions/xbbg.svg)](https://pypi.org/project/xbbg/)\n[![PyPI downloads](https://pepy.tech/badge/xbbg)](https://pepy.tech/project/xbbg)\n[![npm downloads](https://img.shields.io/npm/dm/%40xbbg%2Fcore.svg)](https://www.npmjs.com/package/@xbbg/core)\n[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.gg/P34uMwgCjC)\n\n**Links:** [Documentation](https://xbbg.org/) · [Quickstart](#quickstart) · [Configuration](#configuration-and-engines) · [Examples notebook](py-xbbg/examples/xbbg_jupyter_examples.ipynb) · [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)\n\n
\n\n---\n\n\nLatest release: xbbg==1.4.11 (release: [notes](https://github.com/xbbg-org/xbbg/releases/tag/v1.4.11))\n\n\n> This `main` branch is the Rust-powered v1 release. For the legacy pure-Python line, use [`release/0.x`](https://github.com/xbbg-org/xbbg/tree/release/0.x).\n\n> **Important:** xbbg is an independent open-source project. It is not affiliated with, endorsed by, sponsored by, or approved by Bloomberg Finance L.P. or its affiliates. Bloomberg, Bloomberg Terminal, B-PIPE, BQL, and related names are trademarks or service marks of their respective owners. xbbg does not grant access to Bloomberg services, data, software, licenses, credentials, or entitlements; users must obtain and use those separately under their own Bloomberg agreements and applicable policies.\n\n## Contents\n\n- [What is xbbg?](#what-is-xbbg)\n- [Why xbbg?](#why-xbbg)\n- [Installation](#installation)\n- [Quickstart](#quickstart)\n- [JavaScript and Node](#javascript-and-node)\n- [Configuration and engines](#configuration-and-engines)\n- [Common API surface](#common-api-surface)\n- [Entitlement IDs](#entitlement-ids)\n- [Output backends](#output-backends)\n- [Async usage](#async-usage)\n- [Subscriptions: raw, tick mode, and all fields](#subscriptions-raw-tick-mode-and-all-fields)\n- [MCP server](#mcp-server)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n- [Project links](#project-links)\n\n## What is xbbg?\n\nxbbg is a Bloomberg client with Python as the primary surface and companion JavaScript/Node bindings, all backed by a shared Rust engine for request execution, response parsing, Arrow-shaped data movement, async workers, typed errors, and diagnostics.\n\nUse xbbg when you already have Bloomberg access and want higher-level helpers for common request patterns, plus an escape hatch for lower-level Bloomberg service requests.\n\nCore scope:\n\n- request helpers for BDP, BDS, BDH, intraday bars, ticks, BQL, BEQS, BSRCH, BQR, BTA, YAS, and related analytics\n- local Bloomberg Desktop API / DAPI by default\n- configuration for managed Bloomberg environments, including B-PIPE/SAPI, ZFP leased lines, TLS, failover hosts, SOCKS5, and SDK logging\n- sync and async Python APIs backed by the same engine\n- output as Narwhals, native xbbg Arrow carriers, PyArrow, pandas, Polars, DuckDB, and other optional Narwhals-backed libraries\n- JavaScript/Node bindings in [`js-xbbg`](js-xbbg/README.md)\n\n## Why xbbg?\n\nxbbg's project goal is direct: be the most complete, technically advanced, and performance-focused open-source Bloomberg client for Python workflows, while staying independent of Bloomberg and requiring users to bring their own authorized Bloomberg access.\n\nThe short version: if all you need is a tiny one-off `bdp()` wrapper, several packages can work. xbbg is built for the path where that notebook later grows into intraday data, BQL, streaming, B-PIPE/SAPI, ZFP, async services, typed errors, diagnostics, and non-pandas data pipelines.\n\n| Capability | xbbg | raw `blpapi` | pdblp / blp | bbg-fetch | polars-bloomberg |\n| --- | --- | --- | --- | --- | --- |\n| BDP/BDS/BDH helpers | yes | manual SDK code | yes | yes | partial |\n| Intraday bars and ticks | yes | manual SDK code | limited / no | no | partial |\n| Streaming subscriptions | yes | manual SDK code | no | no | no |\n| BQL, BEQS, BSRCH, BQR, YAS, BTA | broad helper coverage | manual SDK code | limited | limited | partial |\n| DAPI, SAPI/B-PIPE, ZFP, TLS, failover, SOCKS5 | configurable engine support | manual SDK code | limited | limited | limited |\n| Async worker pools and isolated subscription sessions | yes | application-owned | no | no | no |\n| Rust request/parsing engine with Arrow-shaped output | yes | no | no | no | no |\n| Output backends beyond pandas | Narwhals, native, PyArrow, pandas, Polars, DuckDB | application-owned | pandas-first | pandas-first | Polars-first |\n| Typed errors, diagnostics, field cache, testing helpers | yes | application-owned | limited | limited | limited |\n| Usable install footprint (Windows x64, Python 3.14) | xbbg 1.3.0 + narwhals 2.22.1, no `blpapi` = 16.933 MiB | blpapi 3.26.5.1 = 14.401 MiB | pdblp 0.1.8 + pandas 3.0.3 + numpy 2.4.6 + blpapi 3.26.5.1 = 129.344 MiB / blp 0.0.4 + pandas 3.0.3 + numpy 2.4.6 + blpapi 3.26.5.1 = 129.530 MiB | bbg-fetch 2.0.2 + pandas 3.0.3 + numpy 2.4.6 + blpapi 3.26.5.1 = 129.360 MiB | polars-bloomberg 0.6.0 + polars 1.41.2 + blpapi 3.26.5.1 = 197.296 MiB |\n\n## Installation\n\n```cmd\npip install xbbg\n```\n\nConda users can install the conda-forge build:\n\n```cmd\nconda install -c conda-forge xbbg\n```\n\n`blpapi` is **not** required as a Python dependency. xbbg only needs Bloomberg's shared runtime library\n(`blpapi3_64.dll` on Windows, `libblpapi3_64.so` on macOS/Linux), which can come from Bloomberg\nTerminal/DAPI, a managed Bloomberg C++ SDK install, or Bloomberg's official `blpapi` wheel. Installing\nthe wheel is just the easiest discovery path for many users:\n\n```cmd\npip install blpapi --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/\n```\n\nSupported Python versions: **3.10 through 3.14**.\n\nRequirements and notes:\n\n- You need an authorized Bloomberg environment: local Terminal/DAPI, SAPI/B-PIPE, or ZFP, depending on your setup.\n- If you build from source, stage the Bloomberg C++ SDK with `bash ./scripts/sdktool.sh` on macOS/Linux or `.\\\\scripts\\\\sdktool.ps1` on Windows PowerShell.\n- If you manage the SDK yourself, set `BLPAPI_ROOT` or use `xbbg.set_sdk_path(...)`.\n- On Windows Terminal installs, xbbg automatically probes DAPI runtime roots such as `C:\\blp\\DAPI` and `C:\\Program Files (x86)\\Bloomberg\\Blp\\DAPI` before requiring manual configuration.\n- Linux wheels are `manylinux_2_28` (x86_64): any distro with glibc ≥ 2.28 works — RHEL/Alma/Rocky 8+, Debian 10+, Ubuntu 20.04+, Amazon Linux 2023.\n- Optional dataframe conversions are installed separately: `xbbg[pyarrow]`, `xbbg[pandas]`, `xbbg[polars]`, or `xbbg[duckdb]`.\n\nVerify the install:\n\n```python\nimport xbbg\n\nprint(xbbg.__version__)\nprint(xbbg.get_sdk_info())\n```\n\n## Quickstart\n\n```python\nfrom xbbg import blp\n\n# Reference data\nprices = blp.bdp([\"AAPL US Equity\", \"MSFT US Equity\"], \"PX_LAST\")\n\n# Historical data\nhist = blp.bdh(\"SPX Index\", \"PX_LAST\", \"2024-01-01\", \"2024-12-31\")\n\n# Intraday bars\nbars = blp.bdib(\"TSLA US Equity\", dt=\"2024-01-15\", interval=5)\n```\n\nCommon request patterns:\n\n```python\nfrom xbbg import blp, ovr\n\n# Multiple fields\ninfo = blp.bdp(\"NVDA US Equity\", [\"Security_Name\", \"GICS_Sector_Name\", \"PX_LAST\"])\n\n# Bloomberg-style overrides\nvwap = blp.bdp(\"AAPL US Equity\", \"Eqy_Weighted_Avg_Px\", VWAP_Dt=\"20240115\")\nadj = blp.bdp(\"AAPL US Equity\", \"CRNCY_ADJ_PX_LAST\", overrides=ovr(EQY_FUND_CRNCY=\"EUR\"))\nper_sec = blp.bdp(\n [\"AAPL US Equity\", \"MSFT US Equity\"],\n \"CRNCY_ADJ_PX_LAST\",\n overrides=ovr(\n {\n \"EQY_FUND_CRNCY\": \"USD\",\n \"AAPL US Equity\": ovr(EQY_FUND_CRNCY=\"EUR\"),\n \"MSFT US Equity\": ovr(EQY_FUND_CRNCY=\"JPY\"),\n }\n ),\n)\n\n# Bulk data\nholders = blp.bds(\"AAPL US Equity\", \"DVD_Hist_All\", DVD_Start_Dt=\"20240101\")\n\n# BQL\nresult = blp.bql(\"get(px_last) for('AAPL US Equity')\")\n\n# Field lookup\nfields = blp.bflds(search_spec=\"vwap\")\n\n# Equity screening and constituents\nscreen = blp.beqs(screen=\"MyScreen\", asof=\"2024-01-01\")\nmembers = blp.index_members(\"SPX Index\", asof=\"2024-01-02\")\n\n# Workflow helpers\nactive = blp.active_futures(\"ESA Index\", \"2024-01-15\")\nsurface = blp.vol_surface(\"SPX Index\", start_date=\"2024-01-02\", end_date=\"2024-01-05\")\nresolved = blp.resolve_isins([\"US0378331005\", \"INVALIDISIN000\"])\n```\n\nETF NAV / iNAV workflows live in `xbbg.ext` and resolve Bloomberg's authoritative\n`ETF_NAV_TICKER` / `ETF_INAV_TICKER` relationships instead of guessing ticker suffixes:\n\n```python\nfrom xbbg import ext\n\n# Relationship discovery: QQQ US Equity -> QQQNV Index / QXV Index,\n# AT1 LN Equity -> null daily NAV / AT1IN Index (independently nullable)\nrel = ext.etf_nav_relationships([\"QQQ US Equity\", \"AT1 LN Equity\"])\n\n# Daily NAV/iNAV history: mapped Index targets price with PX_LAST; AT1's\n# missing daily NAV falls back to the fund's FUND_NET_ASSET_VAL — see the\n# nav_source_ticker / nav_source_field columns on every row\nhist = ext.etf_nav_history(\n [\"QQQ US Equity\", \"AT1 LN Equity\"],\n start_date=\"2026-06-01\",\n end_date=\"2026-07-01\",\n)\n\n# Real-time iNAV: validates every mapping first, then subscribes to the\n# resolved iNAV topics (here QXV Index) with LAST_PRICE by default\nsub = await ext.asubscribe_etf_inav(\"QQQ US Equity\")\nasync for table in sub:\n print(table.to_pylist())\n break\nawait sub.unsubscribe()\n```\n\nFor longer walkthroughs and example output shapes, use the [examples notebook](py-xbbg/examples/xbbg_jupyter_examples.ipynb) or [xbbg.org](https://xbbg.org/).\n\n## JavaScript and Node\n\nxbbg also ships supported Node bindings in [`@xbbg/core`](js-xbbg/README.md). The JS layer uses the same Rust engine through a native N-API addon, so Node can use the same Bloomberg connection modes and request surfaces as Python.\n\n```bash\nnpm install @xbbg/core\n# or\nbun add @xbbg/core\n```\n\nThe packages target Node.js 24+ server runtimes. Packaged native addons are provided for macOS arm64, Linux x64 (glibc 2.28+), and Windows x64. You still need Bloomberg access plus Bloomberg SDK runtime libraries on the target system.\n\n```ts\nimport * as xbbg from '@xbbg/core';\n\nxbbg.configure({ host: 'localhost', port: 8194 });\n\nconst hist = await xbbg.blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-12-31');\nconst ref = await xbbg.blp.abdp(['AAPL US Equity'], ['PX_LAST', 'SECURITY_NAME']);\n```\n\nSee [`js-xbbg/README.md`](js-xbbg/README.md) for platform packaging, runtime prerequisites, and the supported JavaScript API surface.\n\nFor LangChain and LangGraph agents, use the supported [`@xbbg/langgraph`](js-xbbg-langgraph/README.md) adapter. It exposes reusable server-side Bloomberg tools backed by `@xbbg/core` without making MCP, a chat app, or a browser integration the core path:\n\n```bash\nnpm install @xbbg/langgraph @xbbg/core @langchain/core\n```\n\n```ts\nimport { createAllBloombergTools, BLOOMBERG_TOOL_INSTRUCTIONS } from '@xbbg/langgraph';\n\nconst tools = createAllBloombergTools({ maxSecurities: 10, maxFields: 10 });\n```\n\nUse the existing [`apps/xbbg-mcp`](apps/xbbg-mcp/README.md) package only when you specifically need MCP.\n\n## Configuration and engines\n\nBy default, xbbg starts a Rust-backed engine and connects to local Bloomberg Desktop API / DAPI on `localhost:8194`. Configure the engine before the first request when you need a different transport, authentication mode, worker count, timeout policy, field cache, or logging behavior.\n\n```python\nfrom xbbg import blp, configure\n\n# Equivalent to the default local Terminal / DAPI path\nconfigure(host=\"localhost\", port=8194)\n\nprint(blp.bdp(\"AAPL US Equity\", \"PX_LAST\"))\n```\n\nCommon environments:\n\n| Environment | Use when | Configuration shape |\n| --- | --- | --- |\n| Desktop API / DAPI | Local Bloomberg Terminal session | no config, or `configure(host=\"localhost\", port=8194)` |\n| Direct server / SAPI | Firm-managed Bloomberg server | `configure(host=\"bpipe-host\", port=8194, auth_method=\"app\", app_name=\"...\")` |\n| B-PIPE | Enterprise Bloomberg feed infrastructure | direct host/failover config plus the auth/TLS settings your Bloomberg setup requires |\n| ZFP leased line | Bloomberg zero-footprint leased-line path | `configure(zfp_remote=\"8194\", tls_client_credentials=\"...\", tls_trust_material=\"...\")` |\n\nExample B-PIPE/SAPI-style configuration:\n\n```python\nfrom xbbg import configure\n\nconfigure(\n host=\"bpipe-host\",\n port=8194,\n auth_method=\"app\",\n app_name=\"my-app\",\n request_pool_size=4,\n # Opt-in sharding for wide multi-security BDP/BDH requests:\n # shard_requests=True,\n # shard_threshold=20,\n # shard_chunk_size=16,\n # shard_max_concurrent=4,\n subscription_pool_size=2,\n num_start_attempts=5,\n)\n```\n\nExample ZFP leased-line configuration:\n\n```python\nfrom xbbg import configure\n\nconfigure(\n zfp_remote=\"8194\",\n tls_client_credentials=\"/path/to/client.p12\",\n tls_client_credentials_password=\"\",\n tls_trust_material=\"/path/to/trust.pem\",\n)\n```\n\nThe engine uses separate worker pools for request/response calls and subscriptions:\n\n- request workers hold independent Bloomberg sessions and dispatch BDP/BDH/BDS/BQL-style calls across the pool\n- subscription sessions are isolated from request workers, so live streams do not share a single blocking session with batch requests\n- field validation, field-type caching, SDK logging, retry policy, keep-alive, slow-consumer thresholds, TLS, SOCKS5, and failover servers are configuration options rather than per-call ad hoc code\n\n`runtime_worker_threads` defaults to **2** (minimum **1**) and controls the engine's shared Tokio runtime, not the total process thread count. `subscription_pool_size` is the pre-warm count (default **1**, minimum **0**); `max_subscription_sessions` caps concurrent subscription sessions (default **32**, minimum **1**, and at least `subscription_pool_size`). Native subscription admission waits for capacity instead of allocating unbounded sessions. Node uses the corresponding `runtimeWorkerThreads`, `subscriptionPoolSize`, and `maxSubscriptionSessions` fields.\n\nUse `Engine(...)` when an application needs a scoped engine with its own connection settings instead of mutating global configuration.\n\nEngine shutdown closes subscription admission and signals both idle and checked-out sessions, waking pending operations so termination and errors can reach callers. Close subscriptions explicitly before releasing their engine; do not rely on interpreter teardown for application cleanup.\n\nField-cache snapshots are published atomically. On Windows this uses `FileRenameInfoEx` with POSIX rename semantics, requiring Windows 10 1607+ and a supporting filesystem. Existing readers can finish with the old snapshot while new opens see the complete replacement. Unsupported filesystems report persistence errors and retain the prior snapshot; there is no unsafe replacement fallback.\n\n## Common API surface\n\n| Area | Functions |\n| --- | --- |\n| Reference and bulk data | `bdp`, `bds`, `bflds`, `fieldInfo`, `fieldSearch`, `blkp`, `bport` |\n| Historical data | `bdh`, `dividend`, `earnings`, `turnover`, `dividend_yield` |\n| Intraday data | `bdib`, `bdtick` |\n| Query and screening | `bql`, `beqs`, `bsrch`, `bqr`, `bcurves`, `bgovts`, `etf_holdings`, `index_members` |\n| Analytics and utilities | `yas`, `bta`, `ta_studies`, `ta_study_params`, `convert_ccy`, `fut_ticker`, `active_futures`, `futures_curve`, `vol_surface`, `resolve_isins`, `issuer_isins`, `cdx_ticker`, `active_cdx` |\n| Real-time data | `subscribe`, `stream`, `vwap`, `mktbar`, `depth`, `chains` |\n| Generic requests | `request`, `Service`, `Operation`, `RequestParams`, `OutputMode` |\n| Schema and diagnostics | `bops`, `bschema`, `get_sdk_info`, `enable_sdk_logging`, `print_backend_status` |\n| Testing helpers | `xbbg.testing.create_mock_response`, `xbbg.testing.mock_engine` |\n\nMost sync helpers have async counterparts with an `a` prefix: `bdp` → `abdp`, `bdh` → `abdh`, `bdib` → `abdib`, `request` → `arequest`.\n\n## Entitlement IDs\n\nBloomberg can return entitlement IDs only for these four request operations. Opt in with `return_eids=True`:\n\n| Bloomberg operation | Python routes |\n| --- | --- |\n| `ReferenceDataRequest` | `blp.bdp`, `blp.bds` (BDS uses the reference-data operation) |\n| `HistoricalDataRequest` | `blp.bdh` |\n| `IntradayBarRequest` | `blp.bdib` |\n| `IntradayTickRequest` | `blp.bdtick` |\n\nFor example, request EIDs with intraday ticks and check them against the default `//blp/refdata` service:\n\n```python\nfrom xbbg import blp\n\nticks = blp.bdtick(\n \"AAPL US Equity\",\n \"2024-01-15T09:30:00\",\n \"2024-01-15T10:00:00\",\n return_eids=True,\n backend=\"native\",\n)\n\neid_data = ticks.eid_data or {}\neids = sorted({eid for security_eids in eid_data.values() for eid in security_eids})\nif eids:\n print(blp.check_entitlements(eids))\n```\n\nEID metadata remains available through the native `ArrowTable.eid_data` property, pandas `attrs[\"xbbg_eid_data\"]`, or PyArrow schema metadata under `xbbg.eid_data`. Polars and DuckDB do not provide a stable entitlement-metadata side channel; use the native, PyArrow, or pandas backend when EIDs are required.\n\nThis opt-in request metadata is separate from a subscription message's top-level `EID` field.\n\n## Output backends\n\nxbbg defaults to a Narwhals DataFrame. When PyArrow is installed, the Narwhals frame is backed by a real `pyarrow.Table`; otherwise xbbg falls back through available dataframe libraries and finally to its native Arrow carrier.\n\n```python\nfrom xbbg import Backend, blp\n\n# Default Narwhals output\nframe = blp.bdh(\"SPX Index\", \"PX_LAST\", \"2024-01-01\", \"2024-12-31\")\n\n# Explicit native xbbg Arrow carrier\ntable = blp.bdp(\"AAPL US Equity\", \"PX_LAST\", backend=\"native\")\n\n# Optional conversions\nas_pyarrow = blp.bdp(\"IBM US Equity\", \"PX_LAST\", backend=Backend.PYARROW)\nas_pandas = blp.bdp(\"MSFT US Equity\", \"PX_LAST\", backend=Backend.PANDAS)\nas_polars = blp.bdp(\"AAPL US Equity\", \"PX_LAST\", backend=Backend.POLARS)\nas_duckdb = blp.bdh(\"SPX Index\", \"PX_LAST\", \"2024-01-01\", \"2024-12-31\", backend=Backend.DUCKDB)\n```\n\nOutput shape is controlled with `format=`, including `long`, `long_typed`, `long_metadata`, and `semi_long`.\n\n- Native `ArrowTable`, `ArrowRecordBatch`, and `ArrowColumn` slices can retain their source allocations. Use `.compact()` when retaining a small result should release that backing storage: it returns an independent copy of the logical values with right-sized buffers, preserving schema, nulls, and physical batch/chunk boundaries. Native zero-column tables retain their row count.\n- Polars conversion preserves Arrow chunks rather than implicitly rechunking. The supported floor is **Polars >=0.20.4**; older supported versions use PyArrow when available or schema-aware per-batch materialization, while capsule-capable versions consume the native Arrow stream. Install `xbbg[polars]` to include the timezone data required on Windows.\n- `backend=\"polars_lazy\"` returns a Polars `LazyFrame`; `backend=\"narwhals_lazy\"` returns a genuine Narwhals lazy frame backed by Polars and requires Polars. Bloomberg retrieval and Arrow-to-Polars conversion have already happened: only subsequent local dataframe operations are deferred, with no Bloomberg query pushdown.\n- DuckDB results use isolated per-relation connections to one shared process-local in-memory database, not a new database per conversion. A retained relation keeps its connection and registered Arrow input alive; releasing one relation does not invalidate another. The shared database anchor is closed at process exit. If this backend was initialized before a fork, xbbg refuses inherited backend use or explicit close in the child; use multiprocessing `spawn` or fork before initializing the DuckDB backend.\n\n## Async usage\n\nUse async helpers directly in async applications:\n\n```python\nimport asyncio\nfrom xbbg import blp\n\nasync def main():\n aapl, msft = await asyncio.gather(\n blp.abdp(\"AAPL US Equity\", \"PX_LAST\"),\n blp.abdp(\"MSFT US Equity\", \"PX_LAST\"),\n )\n return aapl, msft\n\nresult = asyncio.run(main())\n```\n\nIn Jupyter, VS Code Interactive, and marimo, one-shot sync calls such as `blp.bdp(...)` and `blp.bdh(...)` use a notebook-only bridge when the notebook event loop is already running. Generic async applications such as FastAPI or ASGI services should still use the async APIs directly.\n\n## Subscriptions: raw, tick mode, and all fields\n\nUse `asubscribe()` when you need dynamic add/remove, explicit unsubscribe, raw Arrow batches, or subscription health diagnostics. Use `astream()` for the simple async iterator, or `stream()` for synchronous iteration.\n\n```python\nfrom xbbg import asubscribe\n\nsub = await asubscribe(\n [\"AAPL US Equity\"],\n [\"LAST_PRICE\", \"BID\", \"ASK\"],\n tick_mode=True,\n all_fields=True,\n conflate=True,\n)\n\nasync for tick in sub:\n print(tick) # dict ticks in tick_mode\n print(sub.stats) # messages_received, dropped_batches, data_loss_events, ...\n break\n\nawait sub.unsubscribe()\n```\n\n```python\nraw_sub = await asubscribe([\"AAPL US Equity\"], [\"LAST_PRICE\"], raw=True)\n\nasync for batch in raw_sub:\n print(batch.to_table()) # raw xbbg ArrowRecordBatch -> ArrowTable\n break\n\nawait raw_sub.unsubscribe()\n```\n\nKey behaviors:\n\n- `output` accepts exactly `record_batch`, `backend`, `dict`, or `tick` (case-insensitive); omitting it keeps whatever `raw` and `tick_mode` select\n- `raw=True` or `output=\"record_batch\"` yields raw xbbg `ArrowRecordBatch` values for max-performance consumers\n- `tick_mode=True`, `output=\"dict\"`, or `output=\"tick\"` returns native dict ticks and implies raw subscription mode\n- `output=\"backend\"` returns the configured backend output, the same as default iteration without `raw=True`\n- `all_fields=True` exposes all top-level scalar Bloomberg subscription fields\n- filtered mode keeps requested fields plus `MKTDATA_EVENT_TYPE` and `MKTDATA_EVENT_SUBTYPE`\n- `conflate=True` requests Bloomberg-conflated quote updates on `//blp/mktdata`; trades are still delivered as received\n- `sub.add(...)`, `sub.remove(...)`, `sub.status`, `sub.events`, `sub.failed_tickers`, and `sub.stats` expose runtime control and diagnostics\n- use `async with` on an acquired subscription or `try`/`finally` with `await sub.unsubscribe()` for deterministic cleanup; `unsubscribe(drain=True)` closes the subscription and returns remaining buffered native Arrow batches rather than discarding them\n\nPython `stream()` producers share one managed background event-loop thread, not a thread per stream. Each sync bridge has a bounded queue (`stream_capacity`, default **256**, minimum **1**) and asynchronously waits for consumer space; native overflow policy remains separate. Active sync producers are admitted per global/scoped engine up to `max_subscription_sessions`; excess producers raise `RuntimeError` rather than creating more tasks. Callbacks run on the consuming thread. Close the generator explicitly when stopping early: close cancels and waits for producer cleanup, and a cleanup timeout is reported while the producer remains tracked against its admission limit. In async applications use `astream()` directly and close it explicitly when retaining the generator after an early exit.\n\nIn Node, pass `{ allFields: true }` to `stream()` / `subscribe()` helpers for the same top-level field expansion. Default iteration yields scalar `Tick` objects; `sub.arrow()` constructs Arrow JS tables without IPC for supported schemas. Exposed mutable buffers are JS-owned snapshots: exclusive bounded allocations can be transferred, while shared/sliced/oversized storage is copied or canonicalized first. This is not a universal zero-copy Rust/JS boundary. Choose scalar or Arrow reads once per subscription; see the [Node lifecycle and benchmark contracts](js-xbbg/README.md).\n\n## MCP server\n\nThe repository also includes a local MCP server for coding-agent workflows. It wraps selected xbbg request/response operations and returns bounded JSON results with schema metadata.\n\nSee [`apps/xbbg-mcp/README.md`](apps/xbbg-mcp/README.md) for installation, supported environment variables, raw GitHub Release tar/zip assets, and the `xbbg-mcp-v.mcpb` local connector artifact. Official MCP Registry publication uses the generated `server.json` metadata after the matching GitHub Release contains the `.mcpb`; no MCP release asset includes Bloomberg SDK files or runtime components.\n\n## Troubleshooting\n\nEmpty results usually mean one of the inputs or entitlements is wrong rather than that the Python call failed:\n\n```python\nfrom xbbg import blp\n\n# Check security lookup and field discovery\nprint(blp.blkp(\"Apple\", yellowkey=\"eqty\"))\nprint(blp.fieldSearch(\"vwap\"))\n```\n\nConnection failures:\n\n- confirm Bloomberg Terminal is running and logged in for local DAPI usage\n- confirm the host, port, auth method, TLS files, and entitlements for SAPI/B-PIPE/ZFP environments\n- run `print(xbbg.get_sdk_info())` to see how the SDK/runtime was detected\n- enable SDK logging before the first session when debugging low-level connection problems\n\nTimeouts and large responses:\n\n- increase per-request timeout where appropriate\n- split large historical/tick requests into smaller date ranges\n- enable opt-in sharding for wide multi-security `bdp`/`bdh` requests with `shard_requests=True`\n- tune `request_pool_size`, `subscription_pool_size`, queue sizes, and keep-alive settings for managed infrastructure\n\nWhen reporting issues, include:\n\n1. xbbg version: `import xbbg; print(xbbg.__version__)`\n2. Python version and operating system\n3. Bloomberg connection mode: DAPI, SAPI/B-PIPE, ZFP, or other\n4. minimal code to reproduce\n5. full traceback or error message\n\n## Development\n\nSet up the development environment with [pixi](https://pixi.sh/):\n\n```bash\n# Stage an authorized Bloomberg SDK locally under vendor/blpapi-sdk/\nbash ./scripts/sdktool.sh # macOS/Linux\n# .\\scripts\\sdktool.ps1 # Windows PowerShell\n\n# Install the environment and compile the Rust extension\npixi install\npixi run install\n```\n\nCommon checks:\n\n```bash\npixi run test\npixi run lint\npixi run ci\n```\n\nFor non-live tests, use `xbbg.testing`:\n\n```python\nfrom xbbg import blp\nfrom xbbg.testing import create_mock_response, mock_engine\n\nresponse = create_mock_response(\n service=\"//blp/refdata\",\n operation=\"ReferenceDataRequest\",\n data={\"AAPL US Equity\": {\"PX_LAST\": 101.23}},\n)\n\nwith mock_engine([response]):\n df = blp.bdp(\"AAPL US Equity\", \"PX_LAST\")\n```\n\nPublishing is handled through GitHub Actions and PyPI Trusted Publishing.\n\n## Project links\n\n- Documentation: [xbbg.org](https://xbbg.org/)\n- JavaScript/Node bindings: [js-xbbg/README.md](js-xbbg/README.md)\n- LangChain/LangGraph tools: [js-xbbg-langgraph/README.md](js-xbbg-langgraph/README.md)\n- PyPI: [pypi.org/project/xbbg](https://pypi.org/project/xbbg/)\n- Source: [github.com/xbbg-org/xbbg](https://github.com/xbbg-org/xbbg)\n- Issues: [GitHub Issues](https://github.com/xbbg-org/xbbg/issues)\n- Discord: [Join the community](https://discord.gg/P34uMwgCjC)\n- Changelog: [CHANGELOG.md](CHANGELOG.md)\n- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)\n- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n- Security: [SECURITY.md](SECURITY.md)\n- License: [LICENSE](LICENSE)\n\n## Citation\n\nIf you use xbbg in research or published work, please cite:\n\n```bibtex\n@software{xbbg,\n author = {{xbbg contributors}},\n title = {{xbbg}: Independent client for Bloomberg-connected data workflows},\n year = {2026},\n publisher = {GitHub},\n url = {https://github.com/xbbg-org/xbbg},\n version = {1.3.0}\n}\n```\n", "bytes": 28243, "sha": "a2e5152c9eb6648bef2ac3713c367687ef8274bfd364f54e43761d681cd37841", "repo_slug": "xbbg-org/xbbg", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_xbbg_org_xbbg_mcp_7c215695/readme" }