finviz-data 1.3.1__tar.gz

finviz_data-1.3.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: finviz-data
+Version: 1.3.1
+Summary: Simple package to get data from finviz.com
+Author-email: Dennis Iversen <dennis.iversen@gmail.com>
+Project-URL: Repository, https://github.com/diversen/finviz-data
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: beautifulsoup4<5,>=4.12
+Requires-Dist: curl-cffi<1,>=0.7
+
+# finviz-data
+
+A simple package for getting fundamental data from finviz.com for a single ticker.
+
+## Installation
+
+```bash
+uv add git+https://github.com/diversen/finviz-data
+```
+
+## Development
+
+```bash
+uv sync
+uv run python -m unittest discover
+```
+
+By default, the live Finviz test is skipped. To run the full test suite without
+skipping the live test, enable it with `FINVIZ_LIVE_TESTS=1`:
+
+```bash
+FINVIZ_LIVE_TESTS=1 uv run python -m unittest discover
+```
+
+The live test makes a real request to finviz.com and may still be skipped if
+Finviz temporarily rate limits your IP.
+
+## Usage
+
+```python
+
+from finviz_data import finviz_data
+
+# Get the html soup for a single ticker
+soup = finviz_data.get_soup('AAPL')
+
+# Get the fundamentals for a single ticker
+fundamentals = finviz_data.get_fundamentals(soup)
+
+# Get the fundamentals where all is formatted to float values where possible
+fundamentals = finviz_data.get_fundementals_float(soup)
+
+# Get basic company info, sector, ticker etc. 
+company_info = finviz_data.get_company_info(soup)
+```

finviz_data-1.3.1/README.md

@@ -0,0 +1,45 @@
+# finviz-data
+
+A simple package for getting fundamental data from finviz.com for a single ticker.
+
+## Installation
+
+```bash
+uv add git+https://github.com/diversen/finviz-data
+```
+
+## Development
+
+```bash
+uv sync
+uv run python -m unittest discover
+```
+
+By default, the live Finviz test is skipped. To run the full test suite without
+skipping the live test, enable it with `FINVIZ_LIVE_TESTS=1`:
+
+```bash
+FINVIZ_LIVE_TESTS=1 uv run python -m unittest discover
+```
+
+The live test makes a real request to finviz.com and may still be skipped if
+Finviz temporarily rate limits your IP.
+
+## Usage
+
+```python
+
+from finviz_data import finviz_data
+
+# Get the html soup for a single ticker
+soup = finviz_data.get_soup('AAPL')
+
+# Get the fundamentals for a single ticker
+fundamentals = finviz_data.get_fundamentals(soup)
+
+# Get the fundamentals where all is formatted to float values where possible
+fundamentals = finviz_data.get_fundementals_float(soup)
+
+# Get basic company info, sector, ticker etc. 
+company_info = finviz_data.get_company_info(soup)
+```

finviz_data-1.3.1/finviz_data/finviz_data.py

@@ -0,0 +1,223 @@
+from datetime import datetime
+
+from bs4 import BeautifulSoup
+from curl_cffi import requests
+
+
+class FinvizRequestError(Exception):
+    """Raised when Finviz returns an unsuccessful HTTP response."""
+
+
+def get_soup(ticker) -> BeautifulSoup:
+    url = f"https://finviz.com/stock?t={ticker}&p=d"
+    response = requests.get(url, impersonate="chrome")
+    status_code = getattr(response, "status_code", None)
+    if isinstance(status_code, int) and status_code >= 400:
+        raise FinvizRequestError(
+            f"Finviz request failed for ticker {ticker!r}: "
+            f"HTTP {status_code} ({url})"
+        )
+
+    html = response.text
+    soup = BeautifulSoup(html, "html.parser")
+    return soup
+
+
+def get_fundamentals(soup: BeautifulSoup) -> dict:
+    # Finviz may render the snapshot as one table or split it into several
+    # responsive columns, all with the same class.
+    tables = soup.find_all("table", {"class": "snapshot-table2"})
+
+    # Initialize a dictionary to store the key-value pairs
+    financial_data = {}
+
+    for table in tables:
+        # Iterate through all rows of the table
+        for row in table.find_all("tr"):
+            # Each cell in the row
+            cells = row.find_all("td")
+            # Step by two because the cells are key/value pairs.
+            for i in range(0, len(cells), 2):
+                key = cells[i].get_text().strip()
+                value = cells[i + 1].get_text().strip()
+                financial_data[key] = value
+
+    return financial_data
+
+
+def get_fundamentals_float(soup: BeautifulSoup) -> dict:
+    fundamentals = get_fundamentals(soup)
+    fundamentals_float = _convert_to_floats(fundamentals)
+
+    return fundamentals_float
+
+
+def get_company_info(soup: BeautifulSoup) -> dict:
+    base_info = {}
+
+    # Get ticker. Text ontent of quote-header_ticker-wrapper_ticker
+    ticker = soup.find("h1", class_="quote-header_ticker-wrapper_ticker").text
+    base_info["Ticker"] = ticker
+
+    # Get company name. Text content of h2.quote-header_ticker-wrapper_company a
+    company_name = (
+        soup.find("h2", class_="quote-header_ticker-wrapper_company").text
+    )
+    base_info["Company"] = company_name.strip()
+
+    categories = soup.find("div", class_="quote-header_categories")
+    if categories is None:
+        categories = soup.find("div", class_="quote-links")
+    links = categories.find_all("a") if categories else []
+
+    for link in links:
+        href = link.get("href", "")
+        if "f=sec_" in href:
+            base_info["Sector"] = link.text
+        elif "f=ind_" in href:
+            base_info["Industry"] = link.text
+        elif "f=geo_" in href:
+            base_info["Country"] = link.text
+        elif "f=exch_" in href:
+            base_info["Exchange"] = link.text
+
+    return base_info
+
+
+def _is_float_like(val: str) -> bool:
+    try:
+        float(val)
+        return True
+    except ValueError:
+        return False
+
+
+def _convert_value(value: str):
+    if value is None:
+        return None
+
+    value = value.strip()
+
+    if value in ("", "-"):
+        return None
+    elif value.endswith("%") and _is_float_like(value.strip("%")):
+        return float(value.strip("%")) / 100
+    elif value.endswith("M") and _is_float_like(value.strip("M")):
+        return float(value.strip("M")) * 1e6
+    elif value.endswith("B") and _is_float_like(value.strip("B")):
+        return float(value.strip("B")) * 1e9
+    elif value.endswith("T") and _is_float_like(value.strip("T")):
+        return float(value.strip("T")) * 1e12
+    elif _is_float_like(value.replace(",", "")):
+        return float(value.replace(",", ""))
+    else:
+        return value
+
+
+def _convert_date(value: str):
+    try:
+        return datetime.strptime(value, "%b %d, %Y").date().isoformat()
+    except ValueError:
+        return _convert_value(value)
+
+
+def _split_two_values(value: str, first_key: str, second_key: str) -> dict:
+    values = value.split()
+    if len(values) != 2:
+        return {first_key: _convert_value(value), second_key: None}
+
+    return {
+        first_key: _convert_value(values[0]),
+        second_key: _convert_value(values[1]),
+    }
+
+
+def _split_dividend(value: str, amount_key: str, yield_key: str) -> dict:
+    values = value.replace("(", "").replace(")", "").split()
+    if len(values) != 2:
+        return {amount_key: _convert_value(value), yield_key: None}
+
+    return {
+        amount_key: _convert_value(values[0]),
+        yield_key: _convert_value(values[1]),
+    }
+
+
+def _split_option_short(value: str) -> dict:
+    values = [item.strip() for item in value.split("/")]
+    if len(values) != 2:
+        return {"Optionable": _convert_value(value), "Shortable": None}
+
+    return {
+        "Optionable": values[0] == "Yes",
+        "Shortable": values[1] == "Yes",
+    }
+
+
+def _split_earnings(value: str) -> dict:
+    values = value.split()
+    if len(values) < 3:
+        return {"Earnings Date": _convert_value(value), "Earnings Time": None}
+
+    return {
+        "Earnings Date": " ".join(values[:-1]),
+        "Earnings Time": values[-1],
+    }
+
+
+def _convert_to_floats(data_dict: dict) -> dict:
+    """
+    Converts values in a dictionary to floats where applicable.
+    - Replaces single dash ('-') with None.
+    - Splits values representing a range (e.g., '10.86 - 19.08') into two separate keys.
+    - Converts values with '%' to proportionate floats.
+    - Converts values ending in 'M', 'B', or 'T' to their numeric equivalents in millions, billions, or trillions.
+    - Converts numeric strings with commas (e.g., '30,196,932') into floats.
+    """
+
+    compound_fields = {
+        "Volatility": lambda value: _split_two_values(
+            value, "Volatility Week", "Volatility Month"
+        ),
+        "52W High": lambda value: _split_two_values(
+            value, "52W High Price", "52W High Change"
+        ),
+        "52W Low": lambda value: _split_two_values(
+            value, "52W Low Price", "52W Low Change"
+        ),
+        "EPS past 3/5Y": lambda value: _split_two_values(
+            value, "EPS past 3Y", "EPS past 5Y"
+        ),
+        "Sales past 3/5Y": lambda value: _split_two_values(
+            value, "Sales past 3Y", "Sales past 5Y"
+        ),
+        "Dividend Gr. 3/5Y": lambda value: _split_two_values(
+            value, "Dividend Gr. 3Y", "Dividend Gr. 5Y"
+        ),
+        "EPS/Sales Surpr.": lambda value: _split_two_values(
+            value, "EPS Surprise", "Sales Surprise"
+        ),
+        "Dividend Est.": lambda value: _split_dividend(
+            value, "Dividend Est. Amount", "Dividend Est. Yield"
+        ),
+        "Dividend TTM": lambda value: _split_dividend(
+            value, "Dividend TTM Amount", "Dividend TTM Yield"
+        ),
+        "Option/Short": _split_option_short,
+        "Earnings": _split_earnings,
+    }
+
+    date_fields = {"IPO", "Dividend Ex-Date"}
+
+    new_data = {}
+    for key, value in data_dict.items():
+        value = value.strip() if isinstance(value, str) else value
+
+        if key in compound_fields:
+            new_data.update(compound_fields[key](value))
+        elif key in date_fields:
+            new_data[key] = _convert_date(value)
+        else:
+            new_data[key] = _convert_value(value)
+
+    return new_data

finviz_data-1.3.1/finviz_data.egg-info/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: finviz-data
+Version: 1.3.1
+Summary: Simple package to get data from finviz.com
+Author-email: Dennis Iversen <dennis.iversen@gmail.com>
+Project-URL: Repository, https://github.com/diversen/finviz-data
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: beautifulsoup4<5,>=4.12
+Requires-Dist: curl-cffi<1,>=0.7
+
+# finviz-data
+
+A simple package for getting fundamental data from finviz.com for a single ticker.
+
+## Installation
+
+```bash
+uv add git+https://github.com/diversen/finviz-data
+```
+
+## Development
+
+```bash
+uv sync
+uv run python -m unittest discover
+```
+
+By default, the live Finviz test is skipped. To run the full test suite without
+skipping the live test, enable it with `FINVIZ_LIVE_TESTS=1`:
+
+```bash
+FINVIZ_LIVE_TESTS=1 uv run python -m unittest discover
+```
+
+The live test makes a real request to finviz.com and may still be skipped if
+Finviz temporarily rate limits your IP.
+
+## Usage
+
+```python
+
+from finviz_data import finviz_data
+
+# Get the html soup for a single ticker
+soup = finviz_data.get_soup('AAPL')
+
+# Get the fundamentals for a single ticker
+fundamentals = finviz_data.get_fundamentals(soup)
+
+# Get the fundamentals where all is formatted to float values where possible
+fundamentals = finviz_data.get_fundementals_float(soup)
+
+# Get basic company info, sector, ticker etc. 
+company_info = finviz_data.get_company_info(soup)
+```

finviz_data-1.3.1/finviz_data.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+finviz_data/__init__.py
+finviz_data/finviz_data.py
+finviz_data.egg-info/PKG-INFO
+finviz_data.egg-info/SOURCES.txt
+finviz_data.egg-info/dependency_links.txt
+finviz_data.egg-info/requires.txt
+finviz_data.egg-info/top_level.txt
+tests/test_finviz_data.py

finviz_data-1.3.1/finviz_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

finviz_data-1.3.1/finviz_data.egg-info/requires.txt

@@ -0,0 +1,2 @@
+beautifulsoup4<5,>=4.12
+curl-cffi<1,>=0.7

finviz_data-1.3.1/finviz_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+finviz_data

finviz_data-1.3.1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "finviz-data"
+version = "1.3.1"
+description = "Simple package to get data from finviz.com"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Dennis Iversen", email = "dennis.iversen@gmail.com" },
+]
+dependencies = [
+    "beautifulsoup4>=4.12,<5",
+    "curl-cffi>=0.7,<1",
+]
+
+[project.urls]
+Repository = "https://github.com/diversen/finviz-data"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["finviz_data*"]

finviz_data-1.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

finviz_data-1.3.1/tests/test_finviz_data.py

@@ -0,0 +1,175 @@
+from finviz_data import finviz_data
+
+# import python unit test
+import os
+import unittest
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from bs4 import BeautifulSoup
+
+
+ticker = "AAPL"
+FIXTURE = Path(__file__).resolve().parents[1] / "finviz_example_latest.html"
+
+
+class TestFinvizData(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.html = FIXTURE.read_text(encoding="utf-8")
+        cls.soup = BeautifulSoup(cls.html, "html.parser")
+
+    def test_get_soup(self):
+        response = Mock(text=self.html, status_code=200)
+        with patch("finviz_data.finviz_data.requests.get", return_value=response) as get:
+            soup = finviz_data.get_soup(ticker)
+
+        get.assert_called_once_with(
+            "https://finviz.com/stock?t=AAPL&p=d",
+            impersonate="chrome",
+        )
+        self.assertIsNotNone(soup)
+        self.assertEqual(soup.find("h1").get_text(strip=True), ticker)
+
+    def test_get_soup_raises_for_http_error(self):
+        response = Mock(text="Not found", status_code=404)
+        with patch("finviz_data.finviz_data.requests.get", return_value=response):
+            with self.assertRaises(finviz_data.FinvizRequestError) as error:
+                finviz_data.get_soup("BYDN")
+
+        message = str(error.exception)
+        self.assertIn("BYDN", message)
+        self.assertIn("HTTP 404", message)
+        self.assertIn("https://finviz.com/stock?t=BYDN&p=d", message)
+
+    @unittest.skipUnless(
+        os.getenv("FINVIZ_LIVE_TESTS") == "1",
+        "set FINVIZ_LIVE_TESTS=1 to run live Finviz tests",
+    )
+    def test_get_soup_live(self):
+        soup = finviz_data.get_soup(ticker)
+        page_text = soup.get_text(" ", strip=True)
+
+        if "temporarily rate limited" in page_text:
+            self.skipTest("Finviz temporarily rate limited this IP")
+
+        self.assertIsNotNone(soup)
+        table = soup.find("table", class_="snapshot-table2")
+        self.assertIsNotNone(table, page_text[:500])
+
+        header = soup.find("h1", class_="quote-header_ticker-wrapper_ticker")
+        self.assertIsNotNone(header, page_text[:500])
+        self.assertEqual(header.get_text(strip=True), ticker)
+
+        fundamentals = finviz_data.get_fundamentals(soup)
+        self.assertIn("Market Cap", fundamentals)
+        self.assertIn("P/E", fundamentals)
+
+        company_info = finviz_data.get_company_info(soup)
+        self.assertEqual(company_info["Ticker"], ticker)
+        self.assertIn("Company", company_info)
+
+    @unittest.skipUnless(
+        os.getenv("FINVIZ_LIVE_TESTS") == "1",
+        "set FINVIZ_LIVE_TESTS=1 to run live Finviz tests",
+    )
+    def test_get_soup_live_raises_for_invalid_ticker(self):
+        with self.assertRaises(finviz_data.FinvizRequestError) as error:
+            finviz_data.get_soup("BYDN")
+
+        message = str(error.exception)
+        self.assertIn("BYDN", message)
+        self.assertIn("HTTP 404", message)
+        self.assertIn("https://finviz.com/stock?t=BYDN&p=d", message)
+
+    def test_get_fundamentals(self):
+        fundamentals = finviz_data.get_fundamentals(self.soup)
+        self.assertIsInstance(fundamentals, dict)
+        self.assertEqual(fundamentals["Market Cap"], "4183.77B")
+        self.assertEqual(fundamentals["P/E"], "34.46")
+        self.assertEqual(fundamentals["Volatility"], "3.31% 2.71%")
+
+    def test_get_company_info(self):
+        company_info = finviz_data.get_company_info(self.soup)
+        self.assertIsInstance(company_info, dict)
+
+        # check if company_info has all the keys
+        self.assertEqual(company_info["Ticker"], ticker)
+        self.assertEqual(company_info["Company"], "Apple Inc")
+        self.assertEqual(company_info["Sector"], "Technology")
+        self.assertEqual(company_info["Industry"], "Consumer Electronics")
+        self.assertEqual(company_info["Country"], "USA")
+        self.assertEqual(company_info["Exchange"], "NASD")
+        self.assertIn("Company", company_info)
+        self.assertIn("Sector", company_info)
+        self.assertIn("Industry", company_info)
+        self.assertIn("Country", company_info)
+        self.assertIn("Exchange", company_info)
+
+    def test_get_get_fundamentals_converted(self):
+        fundamentals_converted = finviz_data.get_fundamentals_float(self.soup)
+        self.assertIsInstance(fundamentals_converted, dict)
+        self.assertAlmostEqual(
+            fundamentals_converted["Market Cap"], 4183.77e9, delta=1
+        )
+        self.assertEqual(fundamentals_converted["P/E"], 34.46)
+        self.assertAlmostEqual(fundamentals_converted["Volatility Week"], 0.0331)
+        self.assertAlmostEqual(fundamentals_converted["Volatility Month"], 0.0271)
+        self.assertEqual(fundamentals_converted["52W High Price"], 317.4)
+        self.assertAlmostEqual(fundamentals_converted["52W High Change"], -0.1025)
+        self.assertEqual(fundamentals_converted["52W Low Price"], 199.26)
+        self.assertAlmostEqual(fundamentals_converted["52W Low Change"], 0.4296)
+        self.assertAlmostEqual(fundamentals_converted["EPS past 3Y"], 0.0689)
+        self.assertAlmostEqual(fundamentals_converted["EPS past 5Y"], 0.1791)
+        self.assertAlmostEqual(fundamentals_converted["Sales past 3Y"], 0.0181)
+        self.assertAlmostEqual(fundamentals_converted["Sales past 5Y"], 0.0871)
+        self.assertAlmostEqual(fundamentals_converted["Dividend Gr. 3Y"], 0.0426)
+        self.assertAlmostEqual(fundamentals_converted["Dividend Gr. 5Y"], 0.0498)
+        self.assertEqual(fundamentals_converted["Dividend Est. Amount"], 1.08)
+        self.assertAlmostEqual(fundamentals_converted["Dividend Est. Yield"], 0.0038)
+        self.assertEqual(fundamentals_converted["Dividend TTM Amount"], 1.05)
+        self.assertAlmostEqual(fundamentals_converted["Dividend TTM Yield"], 0.0037)
+        self.assertEqual(fundamentals_converted["Optionable"], True)
+        self.assertEqual(fundamentals_converted["Shortable"], True)
+        self.assertAlmostEqual(fundamentals_converted["EPS Surprise"], 0.033)
+        self.assertAlmostEqual(fundamentals_converted["Sales Surprise"], 0.0158)
+        self.assertEqual(fundamentals_converted["Earnings Date"], "Apr 30")
+        self.assertEqual(fundamentals_converted["Earnings Time"], "AMC")
+        self.assertEqual(fundamentals_converted["IPO"], "1980-12-12")
+        self.assertEqual(fundamentals_converted["Dividend Ex-Date"], "2026-05-11")
+        self.assertIsNone(fundamentals_converted["Trades"])
+
+        self.assertNotIn("Volatility", fundamentals_converted)
+        self.assertNotIn("52W High", fundamentals_converted)
+        self.assertNotIn("52W Low", fundamentals_converted)
+        self.assertNotIn("EPS past 3/5Y", fundamentals_converted)
+        self.assertNotIn("Sales past 3/5Y", fundamentals_converted)
+        self.assertNotIn("Dividend Gr. 3/5Y", fundamentals_converted)
+        self.assertNotIn("Dividend Est.", fundamentals_converted)
+        self.assertNotIn("Dividend TTM", fundamentals_converted)
+        self.assertNotIn("Option/Short", fundamentals_converted)
+        self.assertNotIn("EPS/Sales Surpr.", fundamentals_converted)
+        self.assertNotIn("Earnings", fundamentals_converted)
+
+    def test_convert_percentage(self):
+        value = "1.39%"
+        converted_value = finviz_data._convert_value(value)
+        self.assertEqual(converted_value, 0.0139)
+
+    def test_convert_million(self):
+        value = "1.39M"
+        converted_value = finviz_data._convert_value(value)
+        self.assertEqual(converted_value, 1390000)
+
+    def test_convert_negative_number(self):
+        value = "-1.39"
+        converted_value = finviz_data._convert_value(value)
+        self.assertEqual(converted_value, -1.39)
+
+    def test_convert_empty_value(self):
+        self.assertIsNone(finviz_data._convert_value(""))
+        self.assertIsNone(finviz_data._convert_value("-"))
+
+
+if __name__ == "__main__":
+    unittest.main()