Skip to content

go-yfinance v1.2.0 Development Progress

Last Updated: 2026-02-19

Overview

Implementation of full Screener module parity with Python yfinance v1.2.0, including client-side query validation, FundQuery support, IS-IN operator, and all predefined screener queries.

Branch Structure

main
 └── feature/screener-parity     ← ✅ Completed and merged

Changes from Python yfinance v1.1.0 → v1.2.0

Python yfinance v1.2.0 added exchange codes to EQUITY_SCREENER_EQ_MAP and expanded FUND_SCREENER_EQ_MAP. During analysis, we discovered the Go screener module had fundamental feature gaps from v1.1.0 — missing query validation, FundQuery support, IS-IN operator, and predefined screener queries. This release addresses all gaps to achieve full Python parity.

Implementation Summary

New Files (3)

File Description
pkg/models/screener_const.go All validation maps ported from Python const.py
pkg/models/screener_query.go EquityQuery, FundQuery with ScreenerQueryBuilder interface
pkg/screener/predefined.go 15 predefined screener queries (9 equity + 6 fund)

Modified Files (3)

File Changes
pkg/models/screener.go IS-IN operator, fund fields, UserID/UserIDType params
pkg/screener/screener.go ScreenerQueryBuilder interface, dynamic quoteType, offset workaround
docs/API.md Full documentation update for all screener changes

Feature Details

1. Screener Constants and Validation Maps

Ported from Python const.py to pkg/models/screener_const.go:

Map Contents
SectorIndustryMapping 11 sectors with complete industry lists
EquityScreenerExchangeMap 57 regions with exchange codes
FundScreenerExchangeMap 56 regions with exchange codes
EquityScreenerSectors 11 sector names
EquityScreenerPeerGroups 74 peer group names
EquityScreenerFields 12 categories, ~91 field names
FundScreenerFields 2 categories, 9 field names

2. Query Validation (EquityQuery / FundQuery)

Implemented in pkg/models/screener_query.go:

  • ScreenerQueryBuilder interface: ToDict() and QuoteType() methods
  • Client-side validation: Field names, EQ values (exchange, region, sector, industry), numeric types for GT/LT/GTE/LTE/BTWN
  • IS-IN operator: Expands to OR-of-EQ (e.g., is-in ["exchange", "NMS", "NYQ"] → or [eq("exchange","NMS"), eq("exchange","NYQ")])
  • Type preservation: IS-IN expansion maintains EquityQuery/FundQuery identity

3. FundQuery Support

  • NewFundQuery(operator string, operands []any) (*FundQuery, error) — validates against fund-specific fields
  • QuoteType() returns "MUTUALFUND" (vs "EQUITY" for EquityQuery)
  • Fund-specific ScreenerQuote fields: FundNetAssets, CategoryName, PerformanceRatingOverall, RiskRatingOverall, InitialInvestment, AnnualReturnNavY1CategoryRank

4. Predefined Screener Queries

All 15 predefined screeners from Python PREDEFINED_SCREENER_QUERIES:

Equity (9):

Screener Sort Field Sort
aggressive_small_caps eodvolume DESC
day_gainers percentchange DESC
day_losers percentchange ASC
growth_technology_stocks eodvolume DESC
most_actives dayvolume DESC
most_shorted_stocks short_percentage_of_shares_outstanding.value DESC
small_cap_gainers eodvolume DESC
undervalued_growth_stocks eodvolume DESC
undervalued_large_caps eodvolume DESC

Fund (6):

Screener Sort Field Sort
conservative_foreign_funds fundnetassets DESC
high_yield_bond fundnetassets DESC
portfolio_anchors fundnetassets DESC
solid_large_growth_funds fundnetassets DESC
solid_midcap_growth_funds fundnetassets DESC
top_mutual_funds percentchange DESC

5. Screen() and ScreenWithQuery() Enhancements

  • Count validation: Returns error when count > 250 (Yahoo API limit)
  • Offset workaround: When offset > 0, switches from GET predefined endpoint to POST custom endpoint (Yahoo's GET ignores offset)
  • Dynamic quoteType: Automatically determined from query type
  • Sort params: Forwarded to GET predefined endpoint
  • UserID/UserIDType: Added to POST request body

Test Coverage

Test Cases
TestNewEquityQuery AND query construction, ToDict serialization
TestNewFundQuery FundQuery construction, QuoteType verification
TestISINExpansion IS-IN → OR-of-EQ expansion
TestQueryValidation 11 cases (valid/invalid fields, operators, values)
TestFundQueryValidation 4 cases (exchange, category, performance rating)
TestQueryOperators All 9 operator constants
TestPredefinedScreenerQueries 15 screeners, type checks
TestPredefinedScreenerToDicts Serialization without panic
TestScreenWithQueryNilQuery Nil query error handling
TestScreenWithQueryCountLimit Count > 250 rejection
TestHelperFunctions getString, getFloat, getInt, getInt64

Commits

Hash Message
02cc12f feat(models): add screener query validation and fund support for Python v1.2.0 parity
89c27ef feat(screener): add predefined queries, offset workaround, and dynamic quoteType
5f9db60 test(screener): comprehensive tests for query validation, fund support, and predefined screeners
5b0c371 docs: update API.md for screener v1.2.0 parity changes

Verification

Check Result
go test ./... (17 packages) ✅ All PASS
golangci-lint run ./... ✅ 0 issues
go vet ./... ✅ Clean

Change History

Date Description
2026-02-18 Branch created, analysis of Python v1.2.0 changes
2026-02-18 Full screener parity implementation (constants, validation, queries)
2026-02-18 Tests, documentation, lint fixes completed
2026-02-19 Merged to main, deployed to GitHub Pages