Development and Deployment

Relevant source files

• .github/labeler.yml
• .github/platform-drafter.yml
• .github/release-drafter.yml
• .github/workflows/README.md
• .pre-commit-config.yaml

This page provides guidance for developers contributing to the OpenBB Platform. It covers the development environment setup, code quality standards, testing practices, building custom extensions, and the CI/CD pipeline for distribution. This documentation assumes familiarity with Python package management and the OpenBB architecture described in Architecture.

For information about installation and usage of OpenBB, see Installation and Setup. For creating data providers specifically, see Provider Architecture.

---

Development Environment Setup

Local Development Installation

The OpenBB Platform uses a specialized development installation script that converts PyPI version constraints to local path dependencies with editable mode enabled. This allows developers to make changes across multiple packages simultaneously without reinstalling.

Key Script: openbb_platform/dev_install.py

The dev_install.py script performs the following operations:

1. Dependency Rewriting: Converts version-pinned dependencies in openbb_platform/pyproject.toml to local path dependencies with develop = true
2. Lock File Removal: Deletes poetry.lock files to force fresh dependency resolution
3. Editable Installation: Installs all local packages in editable mode using poetry install

Development Dependency Transformation Example

The script transforms dependencies from versioned constraints to local paths:

Original (PyPI)	Development (Local Path)
openbb-core = "^1.5.8"	openbb-core = { path = "./core", develop = true }
openbb-yfinance = "^1.5.2"	openbb-yfinance = { path = "./providers/yfinance", develop = true }
openbb-economy = "^1.5.1"	openbb-economy = { path = "./extensions/economy", develop = true }

Sources: openbb_platform/dev_install.py1-194 openbb_platform/pyproject.toml1-119

---

Poetry Workspace Configuration

The OpenBB Platform is organized as a Poetry monorepo with 50+ independent packages. Each package maintains its own pyproject.toml and poetry.lock file.

Package Hierarchy:

• Root Package (openbb_platform/pyproject.toml): Aggregator that depends on core, API, providers, and extensions
• Core Package (openbb_platform/core/pyproject.toml): Foundation with router, command runner, provider abstractions
• Provider Packages: 25+ data source integrations (yfinance, fmp, fred, etc.)
• Extension Packages: Domain-specific APIs (economy, equity, etf, etc.)
• DevTools Package (openbb_platform/extensions/devtools/pyproject.toml): Development dependencies and tools
• CLI Package (cli/pyproject.toml): Command-line interface

Sources: openbb_platform/pyproject.toml1-119 openbb_platform/core/pyproject.toml1-36 openbb_platform/providers/yfinance/pyproject.toml1-21 openbb_platform/dev_install.py1-194

---

Virtual Environment Setup

The development workflow uses separate virtual environments for the platform and CLI:

Platform Environment:

CLI Environment (optional, for CLI development):

The dev_install.py script automatically handles Poetry installation and dependency resolution across all packages.

Sources: openbb_platform/dev_install.py1-194 README.md113-149

---

Code Quality and Testing

Pre-Commit Hooks

The repository enforces code quality through Git pre-commit hooks configured in .pre-commit-config.yaml These hooks run automatically before each commit.

Linter Configuration:

Tool	Version	Purpose	Configuration
check-yaml	v5.0.0	YAML syntax validation	.pre-commit-config.yaml2-6
end-of-file-fixer	v5.0.0	Ensure files end with newline	.pre-commit-config.yaml7-8
trailing-whitespace	v5.0.0	Remove trailing whitespace	.pre-commit-config.yaml9-10
check-merge-conflict	v5.0.0	Detect merge conflict markers	.pre-commit-config.yaml11
detect-private-key	v5.0.0	Prevent key leakage	.pre-commit-config.yaml12
black	v25.1.0	Code formatter	.pre-commit-config.yaml13-16
ruff	v0.12.12	Fast Python linter	.pre-commit-config.yaml17-20
pydocstyle	v6.3.0	Docstring style checker	.pre-commit-config.yaml21-32
codespell	v2.4.1	Spell checker	.pre-commit-config.yaml33-44
mypy	v1.15.0	Static type checker	.pre-commit-config.yaml45-57
nbstripout	v0.8.1	Strip notebook output	.pre-commit-config.yaml58-62
pylint	system	Code analyzer	.pre-commit-config.yaml65-69
check-generated-files	local	Prevent generated file commits	.pre-commit-config.yaml70-82
detect-secrets	v1.5.0	Secret scanner	.pre-commit-config.yaml83-94

Key Hook Details:

• check-yaml excludes construct.yaml file
• end-of-file-fixer and trailing-whitespace exclude css, markdown, text, and svg files
• Pydocstyle runs only on files matching '^(openbb_platform/|cli/).*\.py$' and excludes test files, using configuration from ruff.toml
• Codespell ignores words in .codespell.ignore and skips test files, generated files, and various binary formats
• Mypy includes type stubs for requests, setuptools, python-dateutil, and pytz, excludes test files
• nbstripout strips output cells from Jupyter notebooks before committing
• check-generated-files prevents committing auto-generated files in openbb_platform/core/openbb/package/ (only __init__.py is allowed)
• detect-secrets uses baseline file .secrets.baseline and excludes cassettes, recorded files, API documentation, and charting assets

Sources: .pre-commit-config.yaml1-95

---

Testing Framework

The OpenBB Platform uses pytest with several plugins for comprehensive testing.

Test Execution:

The devtools package (openbb_platform/extensions/devtools/pyproject.toml1-37) includes all testing dependencies:

• pytest (≥8.4.1): Core test framework
• pytest-recorder (≥0.6.3): Records HTTP interactions to VCR cassettes for deterministic testing
• pytest-asyncio (^0.23.2): Enables async/await test functions
• pytest-order (^1.3.0): Controls test execution order
• pytest-cov (^4.1.0): Generates code coverage reports

VCR Cassette Testing:

The YFinance provider demonstrates VCR testing patterns in openbb_platform/providers/yfinance/tests/test_yfinance_fetchers.py1-435:

Test File Naming Conventions:

• Unit tests: test_<module_name>.py
• Integration tests: test_<provider_name>_fetchers.py
• Exclude pattern in pre-commit: tests/.*\.py|openbb_platform/test_.*\.py

Sources: openbb_platform/extensions/devtools/pyproject.toml10-32 openbb_platform/providers/yfinance/tests/test_yfinance_fetchers.py1-435 .pre-commit-config.yaml21-32

---

Developer Tools Package

The openbb-devtools package (openbb_platform/extensions/devtools/pyproject.toml) consolidates all development dependencies:

Linting and Formatting:

• ruff (^0.13): Fast linter and formatter
• pylint (^3.3): Code analyzer
• mypy (^1.12.1): Static type checker
• pydocstyle (^6.3.0): Docstring conventions
• black (^25.1.0): Opinionated code formatter

Security and Quality:

• bandit (^1.7.5): Security issue scanner
• codespell (^2.2.5): Spell checker

Testing:

• pytest (≥8.4.1) + plugins listed above
• ipykernel (^6.30.1): Jupyter notebook testing support

Build Tools:

• poetry (≥2.1.3): Dependency management
• pre-commit (^3.5.0): Git hook manager
• tox (^4.11.3): Multi-environment testing

Type Stubs:

• types-python-dateutil (^2.8.19.14)
• types-toml (^0.10.8.7)

Installing openbb-devtools provides all tools needed for development:

Sources: openbb_platform/extensions/devtools/pyproject.toml1-37

---

Creating Extensions

Extension Types

The OpenBB Platform supports three extension types, each with different registration mechanisms:

Extension Type	Entry Point	Purpose	Example
Provider	openbb_provider_extension	Data source integration	openbb-yfinance
Router	openbb_core_extension	Domain-specific API routes	openbb-economy
OBBject	openbb_obbject_extension	Output post-processing	openbb-charting

Plugin Registration in pyproject.toml:

Sources: openbb_platform/providers/yfinance/pyproject.toml19-21

---

Creating a Custom Provider

A provider implements the fetcher pattern to retrieve data from external APIs.

YFinance Provider Example (openbb_platform/providers/yfinance/openbb_yfinance/__init__.py1-87):

Fetcher Implementation Structure:

1. Query Parameters: Extend StandardModelQueryParams with provider-specific filters
2. Data Schema: Extend StandardModelData with provider-specific fields
3. Fetcher Class: Implement Fetcher[QueryParams, Data] with three methods:
   • transform_query(): Normalize and validate input parameters
   • aextract_data(): Fetch data from external API (async)
   • transform_data(): Parse and validate response into Data schema

Example from YFinance Equity Screener (openbb_platform/providers/yfinance/openbb_yfinance/models/equity_screener.py1-264):

The screener demonstrates advanced query transformation with custom filters for market cap, sector, industry, and country. It maps user-friendly filter names to Yahoo Finance's internal query syntax.

Sources: openbb_platform/providers/yfinance/openbb_yfinance/__init__.py1-87 openbb_platform/providers/yfinance/openbb_yfinance/models/equity_screener.py1-264 openbb_platform/providers/yfinance/pyproject.toml1-21

---

Helper Utilities for Providers

Providers often include utility modules for data transformations and API-specific logic.

YFinance Helpers (openbb_platform/providers/yfinance/openbb_yfinance/utils/helpers.py1-418):

Reference Data (openbb_platform/providers/yfinance/openbb_yfinance/utils/references.py1-1470):

The references module defines:

• Supported time intervals: INTERVALS = Literal["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1W", "1M", "1Q"]
• Index symbols: INDICES dict mapping 200+ index codes to Yahoo Finance tickers
• Screener fields: SCREENER_FIELDS list of available data columns
• Country codes, exchange names, sector/industry mappings

Sources: openbb_platform/providers/yfinance/openbb_yfinance/utils/helpers.py1-418 openbb_platform/providers/yfinance/openbb_yfinance/utils/references.py1-1470

---

Creating Router Extensions

Router extensions add domain-specific endpoints to the OpenBB API by defining command routes.

Router Extension Structure:

Example Router Definition:

Router extensions define commands using the @router.command() decorator, which automatically generates API endpoints, Python methods, and CLI commands. The model parameter links commands to standard data models that providers implement.

Key Router Components:

1. Router Instance: Created with Router(prefix="/<domain>")
2. Command Decorators: @router.command() with model parameter specifying standard model name
3. Function Signatures: Parameter names and types define the API contract
4. Return Type: Always OBBject containing standardized data

Plugin Registration:

Sources: openbb_platform/pyproject.toml35-46

---

CI/CD and Distribution

Branch Naming Convention

The OpenBB Platform follows GitFlow naming conventions enforced by GitHub Actions workflows. The branch name check workflow validates branch names before allowing pull requests to be merged.

Branch Naming Convention: GitFlow Branch Naming and Pull Request Workflow

Branch Naming Rules:

Target Branch	Allowed Source Branches	Pattern	Example
develop	Feature, bugfix, hotfix	^(feature|hotfix|bugfix)/.*	feature/new-fetcher
main	Hotfix, release	^(hotfix|release)/.*	release/4.6.0 or hotfix/critical-fix

Workflow Steps:

1. Extract branch names: Uses jq to parse source and target branch names from pull request event
2. Show output: Prints branch names to console for debugging
3. Check develop PRs: If target is develop, validates source branch matches feature/bugfix/hotfix pattern
4. Check main PRs: If target is main, validates source branch is either hotfix or release branch
5. Exit status: Returns exit code 1 if validation fails, blocking the merge

Sources: .github/workflows/README.md9-32 .github/labeler.yml12-19

---

Automated Pull Request Labeling

Pull requests are automatically labeled based on file paths and branch names using the actions/labeler action.

Auto-Labeling Configuration

Labeling Rules (.github/labeler.yml1-28):

Label	Condition	Description
platform	Files match openbb_platform/.*	Changes to Platform codebase
v4	Files match openbb_platform/.*	Platform v4 changes
enhancement	Branch matches ^feature/.*	New feature development
bug	Branch matches ^hotfix/.* or ^bugfix/.*	Bug fixes
excel	Files match website/content/excel/.*	Excel add-in documentation
breaking_change	Files match openbb_platform/core/openbb_core/provider/standard_models/.*	Breaking API changes

The labeler uses version: 2 with appendOnly: true, meaning labels are never removed automatically, only added.

Sources: .github/labeler.yml1-28 .github/workflows/README.md86-88

---

GitHub Actions Workflows

The OpenBB Platform uses GitHub Actions for comprehensive testing and deployment automation.

CI/CD Workflow Architecture

Workflow Summary:

Workflow	Trigger	Purpose	Key Actions
General Linting	PR events (opened, synchronize, edited) Push to feature/hotfix/release branches	Code quality validation	bandit (security), black (formatting), codespell (spelling), ruff (linting), pylint (analysis), mypy (types), pydocstyle (docstrings)
Unit Test Platform	PR and push events	Test openbb_platform/ directory	pytest on providers, extensions, core
Unit Test CLI	PR and push events	Test cli/ directory	pytest on CLI codebase
Integration Test Platform (API)	PR and push events	Test openbb-api functionality	API endpoint integration tests
Markdown Link Check	PR and push events	Validate markdown links	Docker container avtodev/markdown-lint
Pull Request Labels	PR events	Auto-label PRs	Apply labels based on files/branches
Branch Name Check	PR events to develop/main	Enforce GitFlow naming	Regex validation of branch names
Release Drafter	Manual dispatch	Generate draft releases	Categorize changes, thank contributors
Deploy to Test PyPI	Push to release/* branches	Test package distribution	Build and publish to test.pypi.org
Deploy to PyPI	Push to main branch	Production distribution	Build and publish to pypi.org
Deploy to PyPI - Nightly	Schedule: Daily at UTC+0	Daily pre-release builds	Version as <version>.dev<YYYYMMDD>
Deploy to GitHub Pages	Push to main/release branches	Documentation deployment	Build and publish docs

Sources: .github/workflows/README.md1-101

---

Release Drafting and Changelog Generation

Release notes are automatically generated using the release-drafter action, which categorizes changes by label and acknowledges contributors.

Release Drafter Template Structure

Release Drafter Configuration (.github/release-drafter.yml1-49):

Change Template Format:

- <PR Title> @<Author> (#<PR Number>)

Excluded Contributors: Core team members are excluded from the contributors section to highlight community contributions:

• jmaslek, DidierRLopes, deeleeramone, hjoaquim, jose-donato, luqmanbello, montezdesousa, tehcoderer, colin99d, piiq, andrewkenreich, IgorWounds, minhhoang1023

Platform-Specific Drafter (.github/platform-drafter.yml1-49):

The platform drafter includes an additional filter include-labels: ['platform', 'v4'] to only include platform-related changes in platform-specific release notes.

Sources: .github/release-drafter.yml1-49 .github/platform-drafter.yml1-49

---

PyPI Distribution Pipeline

The OpenBB Platform publishes packages to PyPI through three deployment pathways: Test PyPI validation, production releases, and nightly builds.

PyPI Deployment Architecture

Deployment Workflows:

1. Deploy to Test PyPI (.github/workflows/README.md43-58):

• Trigger: Push to release/* branches
• Purpose: Validate package builds before production release
• Concurrency: Group ${{ github.workflow }}-${{ github.ref }} with cancel-in-progress: true
• Steps:
  1. Setup Python environment
  2. Install pypa/build package
  3. Build binary wheel and source tarball using python -m build
  4. Publish to Test PyPI using pypa/gh-action-pypi-publish@release/v1
• Authentication: Uses secret TEST_PYPI_API_TOKEN

2. Deploy to PyPI (.github/workflows/README.md43-58):

• Trigger: Push to main branch
• Purpose: Production package distribution
• Same steps as Test PyPI, but publishes to production PyPI
• Authentication: Uses secret PYPI_API_TOKEN

3. Deploy to PyPI - Nightly (.github/workflows/README.md33-42):

• Trigger: GitHub Actions schedule event at UTC+0 daily
• Purpose: Provide latest development builds with date-based versioning
• Version Format: <currentVersion>.dev<YYYYMMDD> (e.g., 4.6.0.dev20240315)
• Steps:
  1. Update pyproject.toml with nightly version string
  2. Install pypa/build
  3. Build distribution files
  4. Publish to production PyPI
• Installation: Users can install nightly builds with pip install openbb==X.Y.Z.devYYYYMMDD

Concurrency Control: Both Test PyPI and PyPI workflows use concurrency groups to prevent simultaneous deployments, canceling in-progress jobs when new pushes occur.

Sources: .github/workflows/README.md33-58

---

Package Distribution Hierarchy

The OpenBB Platform publishes packages to PyPI with the following modular hierarchy:

Package Dependency Architecture

Installation Methods:

Version Management:

All packages follow semantic versioning with synchronized releases. The core framework version (1.5.8) is maintained across core, most providers, and extensions to ensure compatibility. Nightly builds append .devYYYYMMDD to version strings.

Package Metadata:

Each package's pyproject.toml includes:

• name: Package identifier (e.g., openbb-yfinance)
• version: Semantic version (e.g., 1.5.2)
• description: Human-readable description
• authors: ["OpenBB Team <[email protected]>"]
• license: "AGPL-3.0-only"
• python: Version constraint (e.g., ">=3.10,<3.14")

Sources: openbb_platform/pyproject.toml1-119 openbb_platform/core/pyproject.toml1-36 openbb_platform/providers/yfinance/pyproject.toml1-21 .github/workflows/README.md33-42

---

Contribution Workflow

The standard contribution workflow follows these steps:

Contribution Guidelines:

1. Check Existing Issues: Before creating a new issue, search existing issues to avoid duplicates
2. Issue Templates:
   • Bug Report
   • Feature Request
   • Improvement Suggestion
3. Development Documentation: Detailed contributor guide at docs.openbb.co/python/developer
4. Community Support: Active discussions on Discord

Code Standards Enforcement:

• All commits must pass pre-commit hooks (black, ruff, pylint, mypy)
• Test coverage required for new features
• Docstrings required following Google style (checked by pydocstyle)
• No secrets or generated files in commits

Sources: README.md131-150 .pre-commit-config.yaml1-95