yfin-cli 0.1.1__py3-none-any.whl

src/commands/screen.py

@@ -0,0 +1,260 @@
+import yfinance as yf
+import typer
+import json
+from ..decorators import command
+from ..typer import (
+    ScreenFilterTypeOptional,
+    ScreenPredefinedQueryTypeOptional,
+    ScreenJsonQueryTypeOptional,
+    OffsetType,
+    default_offset,
+    LimitType,
+    default_limit,
+    ScreenQueryFieldType,
+    ScreenSortOrderType,
+    default_sort_order,
+)
+from ..utils import is_number, count_specified
+
+VALID_FIELDS_DICT = yf.const.EQUITY_SCREENER_FIELDS
+VALID_VALUES_DICT = yf.const.EQUITY_SCREENER_EQ_MAP
+VALID_FIELDS = set().union(*VALID_FIELDS_DICT.values())
+VALID_REGIONS = set(VALID_VALUES_DICT.get("region"))
+VALID_EXCHANGES = set().union(*VALID_VALUES_DICT.get("exchange").values())
+VALID_SECTORS = set(VALID_VALUES_DICT.get("sector"))
+VALID_INDUSTRIES = set().union(*VALID_VALUES_DICT.get("industry").values())
+VALID_PEER_GROUPS = set(VALID_VALUES_DICT.get("peer_group"))
+PREDEFINED_QUERIES = set(yf.PREDEFINED_SCREENER_QUERIES.keys())
+VALID_OPERATORS = {
+    "eq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "btwn",
+    "is-in",
+}
+
+
+@command
+def screen_query_fields():
+    """Get a list of all valid fields for screening."""
+    return [{"field": f} for f in sorted(list(VALID_FIELDS))]
+
+
+@command
+def screen_query_values(field: ScreenQueryFieldType):
+    """Get a list of all valid values for a field."""
+    if field == "region":
+        values = list(VALID_REGIONS)
+    elif field == "exchange":
+        values = list(VALID_EXCHANGES)
+    elif field == "sector":
+        values = list(VALID_SECTORS)
+    elif field == "industry":
+        values = list(VALID_INDUSTRIES)
+    elif field == "peer_group":
+        values = list(VALID_PEER_GROUPS)
+    else:
+        validate_field(field)
+        values = None
+
+    if values is None:
+        return None
+
+    return [{"value": v} for v in sorted(values)]
+
+
+@command
+def screen_predefined_queries():
+    """Get a list of all valid predefined queries."""
+    return [{"query": q} for q in sorted(list(PREDEFINED_QUERIES))]
+
+
+def validate_field(field: str):
+    """
+    Validate the field.
+    """
+    if field not in VALID_FIELDS:
+        raise typer.BadParameter(
+            f"Invalid field: '{field}'. Valid fields can be found using `yfin screen-query-fields`."
+        )
+
+
+def parse_value(field: str, value: str) -> str | float:
+    """
+    Validate the value against the field, then return it into the correct type.
+    """
+    if field in VALID_FIELDS_DICT.get("eq_fields"):
+        # fields in `eq_fields` should operate with fixed values
+        if field not in ["region", "exchange", "sector", "industry", "peer_group"]:
+            # This should never happen
+            raise ValueError(f"Invalid field '{field}' for eq_fields")
+
+        if field == "region" and value not in VALID_REGIONS:
+            raise typer.BadParameter(
+                f"Invalid value: '{value}' for 'region' field. Valid values can be found using `yfin screen-query-values --field region`."
+            )
+        elif field == "exchange" and value not in VALID_EXCHANGES:
+            raise typer.BadParameter(
+                f"Invalid value: '{value}' for 'exchange' field. Valid values can be found using `yfin screen-query-values --field exchange`."
+            )
+        elif field == "sector" and value not in VALID_SECTORS:
+            raise typer.BadParameter(
+                f"Invalid value: '{value}' for 'sector' field. Valid values can be found using `yfin screen-query-values --field sector`."
+            )
+        elif field == "industry" and value not in VALID_INDUSTRIES:
+            raise typer.BadParameter(
+                f"Invalid value: '{value}' for 'industry' field. Valid values can be found using `yfin screen-query-values --field industry`."
+            )
+        elif field == "peer_group" and value not in VALID_PEER_GROUPS:
+            raise typer.BadParameter(
+                f"Invalid value: '{value}' for 'peer_group' field. Valid values can be found using `yfin screen-query-values --field peer_group`."
+            )
+        return value
+
+    # Remaining fields are numeric
+    if not is_number(value):
+        raise typer.BadParameter(
+            f"Invalid value: '{value}' for '{field}' field. Expected a number."
+        )
+    return float(value)
+
+
+def parse_filter(filter_str: str) -> yf.EquityQuery:
+    """
+    Parse a filter string like '<field> <operator> <value>' into an EquityQuery.
+    Example: 'sector eq Technology' -> EquityQuery('eq', ['sector', 'Technology'])
+    """
+    parts = filter_str.strip().split(maxsplit=2)
+    if len(parts) != 3:
+        raise typer.BadParameter(
+            f"Invalid filter format: '{filter_str}'. Expected '<field> <operator> <value>'."
+        )
+
+    field, operator, value = (parts[0].lower(), parts[1].lower(), parts[2])
+
+    validate_field(field)
+
+    if operator not in VALID_OPERATORS:
+        raise typer.BadParameter(
+            f"Invalid operator: '{operator}'. Use one of {', '.join(sorted(list(VALID_OPERATORS)))}"
+        )
+
+    if operator in ["is-in", "btwn"]:
+        # comma-separated values
+        values = [parse_value(field, v.strip()) for v in value.split(",")]
+        if operator == "btwn" and len(values) != 2:
+            raise typer.BadParameter(
+                f"Invalid value: '{value}' for '{field}' field. Expected exactly two values."
+            )
+    else:
+        values = [parse_value(field, value)]
+
+    return yf.EquityQuery(operator, [field] + values)
+
+
+def parse_json_query(json_query: str) -> yf.EquityQuery:
+    """
+    Parse a JSON query into an EquityQuery.
+    """
+    try:
+        query_node = json.loads(json_query)
+    except json.JSONDecodeError:
+        raise typer.BadParameter(f"Invalid JSON query: '{json_query}'.")
+
+    def _build_query(node):
+        if isinstance(node, str):
+            return parse_filter(node)
+
+        if isinstance(node, dict):
+            operator = node.get("operator")
+            queries = node.get("queries")
+            if operator is None:
+                raise typer.BadParameter("Invalid query, 'operator' is required.")
+
+            if queries is None:
+                raise typer.BadParameter("Invalid query, 'queries' is required.")
+
+            if operator not in ["and", "or"]:
+                raise typer.BadParameter(
+                    "Invalid query, 'operator' must be either 'and' or 'or'."
+                )
+
+            if not isinstance(queries, list) or len(queries) == 0:
+                raise typer.BadParameter(
+                    "Invalid query, 'queries' must be a non-empty list."
+                )
+            operands = [_build_query(q) for q in queries]
+
+            # yfinance does not support single operand queries
+            if len(operands) == 1:
+                return operands[0]
+
+            return yf.EquityQuery(operator, operands)
+
+        raise typer.BadParameter(
+            f"Invalid query, unexpected type: {type(node).__name__}"
+        )
+
+    return _build_query(query_node)
+
+
+@command
+def screen(
+    filters: ScreenFilterTypeOptional = None,
+    predefined: ScreenPredefinedQueryTypeOptional = None,
+    json_query: ScreenJsonQueryTypeOptional = None,
+    offset: OffsetType = default_offset,
+    limit: LimitType = default_limit,
+    sort_field: ScreenQueryFieldType = None,
+    sort_order: ScreenSortOrderType = default_sort_order,
+):
+    """
+    Run a stock screener.
+
+    Supports predefined queries, simple filters (implicitly ANDed), or complex JSON queries.
+    Options --predefined, --filter, and --json-query are mutually exclusive.
+    """
+    specified_count = count_specified(filters, predefined, json_query)
+    if specified_count != 1:
+        raise typer.BadParameter(
+            "Exactly one of --filter, --predefined, or --json-query must be specified."
+        )
+
+    if predefined:
+        if predefined not in PREDEFINED_QUERIES:
+            raise typer.BadParameter(
+                f"Invalid predefined query: '{predefined}'. Valid predefined queries can be found using `yfin screen-predefined-queries`."
+            )
+        final_query = predefined
+    elif filters:
+        queries = [parse_filter(f) for f in filters]
+        final_query = (
+            queries[0] if len(queries) == 1 else yf.EquityQuery("and", queries)
+        )
+    else:
+        final_query = parse_json_query(json_query)
+
+    if sort_field:
+        validate_field(sort_field)
+
+    # yfinance docs say that size is only for custom queries, count is only for predefined queries
+    if predefined:
+        response = yf.screen(
+            final_query,
+            offset=offset,
+            count=limit,
+            sortField=sort_field,
+            sortAsc=sort_order == "asc",
+        )
+    else:
+        response = yf.screen(
+            final_query,
+            offset=offset,
+            size=limit,
+            sortField=sort_field,
+            sortAsc=sort_order == "asc",
+        )
+
+    return response["quotes"]

src/commands/sector.py

@@ -0,0 +1,66 @@
+import yfinance as yf
+from ..typer import SectorKeyType
+from ..decorators import command
+from ..utils import data_frame_to_list
+
+
+@command
+def sector_keys():
+    """
+    Get all available sector keys.
+    """
+    return [{"key": k} for k in yf.const.SECTOR_INDUSTY_MAPPING_LC.keys()]
+
+
+@command
+def sector_industries(key: SectorKeyType):
+    """
+    Get the industries within a sector.
+    """
+    return data_frame_to_list(yf.Sector(key).industries)
+
+
+@command
+def sector_overview(key: SectorKeyType):
+    """
+    Get the overview information of the domain entity.
+    """
+    return yf.Sector(key).overview
+
+
+@command
+def sector_research_reports(key: SectorKeyType):
+    """
+    Get research reports related to the domain entity.
+    """
+    return yf.Sector(key).research_reports
+
+
+@command
+def sector_top_companies(key: SectorKeyType):
+    """
+    Get the top companies within the domain entity.
+    """
+    return data_frame_to_list(yf.Sector(key).top_companies)
+
+
+@command
+def sector_top_etfs(key: SectorKeyType):
+    """
+    Get the top ETFs for the sector.
+    """
+    return [
+        {"symbol": symbol, "name": name}
+        for symbol, name in yf.Sector(key).top_etfs.items()
+    ]
+
+
+@command
+def sector_top_mutual_funds(key: SectorKeyType):
+    """
+    Get the top mutual funds for the sector.
+    """
+    return [
+        {"symbol": symbol, "name": name}
+        for symbol, name in yf.Sector(key).top_mutual_funds.items()
+    ]

src/commands/stock.py

@@ -0,0 +1,108 @@
+import yfinance as yf
+import typer
+from ..typer import (
+    TickerType,
+    IntervalType,
+    default_interval,
+    StartDateTypeOptional,
+    EndDateTypeOptional,
+    PeriodTypeOptional,
+    PeriodType,
+    default_period,
+    NewsTabType,
+    default_news_tab,
+    CountType,
+    default_count,
+)
+from ..decorators import command
+from ..utils import count_specified, compact, data_frame_to_list, series_to_list
+
+
+@command
+def history(
+    ticker: TickerType,
+    interval: IntervalType = default_interval,
+    period: PeriodTypeOptional = None,
+    start: StartDateTypeOptional = None,
+    end: EndDateTypeOptional = None,
+):
+    """
+    Get historical market data for a stock ticker.
+
+    Note: period, start, and end - at most 2 of these can be specified together.
+    """
+    specified_count = count_specified(period, start, end)
+    if specified_count > 2:
+        raise typer.BadParameter(
+            "At most 2 of --period, --start, --end can be specified together."
+        )
+
+    if specified_count == 0:
+        period = "1mo"
+
+    kwargs = compact(
+        interval=interval,
+        period=period,
+        start=start,
+        end=end,
+    )
+
+    stock = yf.Ticker(ticker)
+    data_frame = stock.history(**kwargs)
+    return data_frame_to_list(data_frame)
+
+
+@command
+def dividends(
+    ticker: TickerType,
+    period: PeriodType = default_period,
+):
+    """
+    Get dividends for a stock ticker.
+    """
+    stock = yf.Ticker(ticker)
+    series = stock.get_dividends(period=period)
+    return series_to_list(series)
+
+
+@command
+def fast_info(
+    ticker: TickerType,
+):
+    """
+    Get fast info (15 min delayed) summary for a stock ticker.
+
+    Returns key metrics like price, market cap, volume, and 52-week range.
+    """
+    stock = yf.Ticker(ticker)
+    fast_info = stock.get_fast_info()
+    if fast_info is None:
+        return None
+    fast_info_dict = dict(fast_info)  # fast_info is a dict-like object
+    return fast_info_dict
+
+
+@command
+def news(
+    ticker: TickerType,
+    count: CountType = default_count,
+    tab: NewsTabType = default_news_tab,
+):
+    """
+    Get news for a stock ticker.
+    """
+    stock = yf.Ticker(ticker)
+    news_list = stock.get_news(count, tab)
+    processed_news_list = []
+    for article in news_list:
+        content = article.get("content") or {}
+        processed_news_list.append(
+            {
+                "Date": content.get("pubDate"),
+                "Title": content.get("title"),
+                "Summary": content.get("summary"),
+                "URL": (content.get("canonicalUrl") or {}).get("url"),
+                "Source": (content.get("provider") or {}).get("displayName"),
+            }
+        )
+    return processed_news_list

src/decorators.py

@@ -0,0 +1,33 @@
+import typer
+import click
+from functools import wraps
+from .writer import WriterFactory
+from .utils import console_print_error, console_print_warning
+
+
+def command(func):
+    """Decorator to handle standard errors and output writing in CLI commands."""
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            data = func(*args, **kwargs)
+
+            if data is None:
+                console_print_warning("No data found")
+                raise typer.Exit(code=1)
+
+            if not isinstance(data, (dict, list)):
+                raise ValueError(f"Unsupported data type: {type(data).__name__}")
+
+            ctx = click.get_current_context()
+            output_type = ctx.obj.get("output")
+            writer = WriterFactory.get_writer(output_type)
+            writer.write(data)
+        except (typer.Exit, typer.Abort, typer.BadParameter):
+            raise
+        except Exception as e:
+            console_print_error(f"Unexpected error: {e}")
+            raise typer.Exit(code=1)
+
+    return wrapper

src/typer.py

@@ -0,0 +1,223 @@
+import typer
+from typing import Annotated
+from .utils import (
+    get_today_date_string,
+    validate_date_string,
+    validate_value_in_list,
+)
+
+TickerType = Annotated[
+    str,
+    typer.Argument(
+        help="Stock ticker symbol (e.g., TSLA, AAPL)", callback=lambda x: x.upper()
+    ),
+]
+
+VALID_OUTPUT_TYPES = ["json", "table"]
+
+default_output = VALID_OUTPUT_TYPES[0]
+
+OutputType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(VALID_OUTPUT_TYPES),
+        help=f"Output format ({', '.join(VALID_OUTPUT_TYPES)})",
+    ),
+]
+
+default_frequency = "yearly"
+
+FrequencyType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(["yearly", "quarterly"]),
+        help="Frequency of the data (yearly, quarterly)",
+    ),
+]
+
+ExtendedFrequencyType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(["yearly", "quarterly", "trailing"]),
+        help="Frequency of the data (yearly, quarterly, trailing)",
+    ),
+]
+
+StartDateType = Annotated[
+    str,
+    typer.Option(
+        default_factory=get_today_date_string,
+        callback=validate_date_string,
+        help="Start date (YYYY-MM-DD), default today",
+    ),
+]
+
+StartDateTypeOptional = Annotated[
+    str | None,
+    typer.Option(
+        callback=lambda x: validate_date_string(x) if x else None,
+        help="Start date (YYYY-MM-DD)",
+    ),
+]
+
+EndDateType = Annotated[
+    str | None,
+    typer.Option(
+        callback=lambda x: validate_date_string(x) if x else None,
+        help="End date (YYYY-MM-DD), default 7 days from start",
+    ),
+]
+
+EndDateTypeOptional = Annotated[
+    str | None,
+    typer.Option(
+        callback=lambda x: validate_date_string(x) if x else None,
+        help="End date (YYYY-MM-DD)",
+    ),
+]
+
+VALID_PERIODS = ["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"]
+
+default_period = VALID_PERIODS[-1]  # max
+
+
+PeriodType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(VALID_PERIODS),
+        help=f"Data period {', '.join(VALID_PERIODS)}",
+    ),
+]
+
+PeriodTypeOptional = Annotated[
+    str | None,
+    typer.Option(
+        callback=lambda x: validate_value_in_list(VALID_PERIODS)(x) if x else None,
+        help=f"Data period {', '.join(VALID_PERIODS)}",
+    ),
+]
+
+default_limit = 12
+
+LimitType = Annotated[
+    int,
+    typer.Option(
+        help="Maximum number of results to show",
+    ),
+]
+
+default_offset = 0
+
+OffsetType = Annotated[
+    int,
+    typer.Option(
+        help="Offset of the results",
+    ),
+]
+
+default_market_cap = 0
+
+MarketCapType = Annotated[
+    int,
+    typer.Option(
+        help="Market cap of the company",
+    ),
+]
+
+VALID_INTERVALS = [
+    "1m",
+    "2m",
+    "5m",
+    "15m",
+    "30m",
+    "60m",
+    "90m",
+    "1h",
+    "1d",
+    "5d",
+    "1wk",
+    "1mo",
+    "3mo",
+]
+
+default_interval = VALID_INTERVALS[8]  # "1d"
+
+IntervalType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(VALID_INTERVALS),
+        help=f"Data interval ({', '.join(VALID_INTERVALS)})",
+    ),
+]
+
+default_count = 10
+
+CountType = Annotated[
+    int,
+    typer.Option(
+        help="Number of results to show",
+    ),
+]
+
+default_news_tab = "all"
+
+NewsTabType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(["all", "news", "press releases"]),
+        help="Tab of the news (all, news, press releases)",
+    ),
+]
+
+SectorKeyType = Annotated[
+    str,
+    typer.Argument(
+        help="A valid sector key, can be found using `yfin sector-keys`",
+    ),
+]
+
+IndustryKeyType = Annotated[
+    str,
+    typer.Argument(
+        help="A valid industry key, can be found using `yfin sector-industries <sector-key>`",
+    ),
+]
+
+ScreenFilterTypeOptional = Annotated[
+    list[str] | None,
+    typer.Option(
+        "--filter",  # parameter name is plural
+        help="Filter in '<field> <operator> <value>' format (e.g., 'sector eq Technology')",
+    ),
+]
+
+ScreenPredefinedQueryTypeOptional = Annotated[
+    str | None,
+    typer.Option(
+        help="Predefined query, can be found using `yfin screen-predefined-queries`",
+    ),
+]
+
+ScreenJsonQueryTypeOptional = Annotated[
+    str | None,
+    typer.Option(
+        help="Complex query in JSON format: {'operator': 'and|or', 'queries': [<filter1>, <filter2>, <json_query>, ...]}.",
+    ),
+]
+
+ScreenQueryFieldType = Annotated[
+    str | None,
+    typer.Option(
+        help="Query field, can be found using `yfin screen-query-fields`",
+    ),
+]
+
+default_sort_order = "desc"
+
+ScreenSortOrderType = Annotated[
+    str,
+    typer.Option(
+        callback=validate_value_in_list(["asc", "desc"]),
+        help="Sort order, can be 'asc' or 'desc'",
+    ),
+]