Saltar a contenido

🔌 Asset Providers (Developer)

This section provides the technical deep-dive for each asset pricing provider in LibreFolio. For the end-user perspective, see the User Manual — Providers.

📦 Providers at a Glance

Provider Code Features get_asset_url params_schema Identifier Types Test Level
Yahoo Finance yfinance History, Search, Metadata ✅ — TICKER, ISIN Beta
JustETF justetf History, Search, Metadata ✅ ✅ ISIN Beta
Borsa Italiana borsa_italiana History, Search, Metadata, URL resolution ✅ ✅ ISIN Beta
CSS Scraper css_scraper Current Value ✅ ✅ URL Beta
Scheduled Investment scheduled_investment History (Calc), Events — ✅ AUTO_GENERATED Beta
Mock Provider mockprov History, Search — — TICKER, ISIN Alpha

🔑 Feature Key

  • 📈 History: Can fetch historical OHLC data.
  • 🔎 Search: Supports searching for assets by name/ticker. Detected via test_search_query is not None.
  • 📋 Metadata: Can fetch asset details (sector, description, identifiers) via fetch_asset_metadata().
  • 💰 Current Value: Can fetch the latest real-time price.
  • 📊 Events: Can produce asset events, returned with the history in FAHistoricalData.events — dividends and splits (Yahoo Finance), dividends (JustETF), interest and settlements (Scheduled Investment). There is no supports_events flag.
  • 🔗 get_asset_url: Generates a link to the provider's page for this asset (e.g., Yahoo Finance quote page).
  • 🧩 params_schema: Exposes a form schema for the frontend to render dynamic configuration fields.
  • 🧪 Probe: All providers support POST /assets/provider/probe for dry-run testing (current_price, history, metadata operations).

📝 Notes

  • CSS Scraper get_asset_url returns the identifier itself (which is the URL to scrape).
  • Scheduled Investment uses AUTO_GENERATED identifier type — no external identifier needed.
  • Mock Provider (mockprov) is only registered when LIBREFOLIO_TEST_MODE is enabled.

📈 Yahoo Finance (yfinance)

The primary market data provider — fetches stock, ETF, crypto, and index prices using the yfinance library.

  • Features: History, Search, Metadata, Current Value
  • Identifier types: TICKER, ISIN
  • Key details: ticker.info for current price (no history() or fast_info), core search-query cache (15 min TTL), currency caching (24h), single-sector metadata (no geographic split)
  • 📖 Technical Details →
  • 📖 User Guide →

🔍 JustETF (justetf)

Specialized ETF provider — fetches data from justetf.com including sector and geographic distributions.

  • Features: History, Search, Metadata, Current Value (gettex live in EUR, daily latestQuote otherwise)
  • Identifier types: ISIN
  • Key details: Cached ETF list for instant search, Gettex WebSocket for real-time quotes, geographic/sector distributions, pre-warm at startup
  • 📖 Technical Details →
  • 📖 User Guide →

🇮🇹 Borsa Italiana (borsa_italiana)

Italian market data provider — fetches stocks, bonds (BTP), and ETFs listed on Borsa Italiana using the borsa-italiana-scraping library.

  • Features: History, Search, Metadata, Current Value
  • Identifier types: ISIN
  • Provider params: Optional language ("en" / "it"), codice_fondo for mutual funds, mic / platform for market routing; the page url is stored automatically
  • URL resolution: resolvable_url_domains = ["borsaitaliana.it"]; resolve_url(url) returns the canonical IT + EN result set for fund/detail pages, then search flattens and de-dupes by (identifier, language)
  • Key details: Full OHLCV history for listed instruments, dual-language search with flag emojis, fund NAV pricing by internal codice_fondo (not ISIN), current fund NAV only when NAV date is today, fund history as one NAV point at its real date, identifier_other stored as a JSON list for alternative technical identifiers
  • 📖 Technical Details →

🌐 CSS Scraper (css_scraper)

A versatile provider that can extract a current price from any public webpage using a CSS selector. Useful for tracking assets from niche sources without an API.

  • Features: Current Value only (no historical data)
  • Identifier type: URL
  • Key config: current_css_selector, currency, decimal_format
  • 📖 Technical Details →
  • 📖 User Guide →

📅 Scheduled Investment (scheduled_investment)

A synthetic, deterministic provider that calculates asset value based on a predefined interest schedule. No external calls, no DB access — pure math.

  • Features: Calculated History, Auto-generated Events (💵 INTEREST, 🏁 MATURITY_SETTLEMENT)
  • Identifier type: AUTO_GENERATED
  • Key config: initial_value, schedule[], day_count, interest_type, late_interest
  • 📖 Technical Details →
  • 📖 User Guide →