finfetch 0.1.0__tar.gz

finfetch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Karanveer Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

finfetch-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: finfetch
+Version: 0.1.0
+Summary: Free financial data for Indian stocks — no API key needed.
+Author: Karanveer Singh
+License: MIT
+Project-URL: Homepage, https://github.com/karanveersingh/finfetch
+Project-URL: Issues, https://github.com/karanveersingh/finfetch/issues
+Keywords: finance,stocks,india,nse,bse,scraper,screener,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: beautifulsoup4>=4.11
+Requires-Dist: lxml>=4.9
+Requires-Dist: pandas>=1.5
+Requires-Dist: yfinance>=0.2.30
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# finfetch
+
+Free financial data for Indian stocks. No API key needed.
+
+`finfetch` scrapes publicly available data from Screener.in, Trendlyne, MoneyControl, and Yahoo Finance, returning clean **pandas DataFrames** with normalised column names and proper datetime indices.
+
+## Installation
+
+```bash
+pip install finfetch
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/karanveersingh/finfetch.git
+cd finfetch
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import finfetch as ff
+
+# Create a ticker object
+stock = ff.Ticker("RELIANCE")
+
+# Current price
+stock.price          # → 2845.50
+
+# Company info (dict)
+stock.info           # → {"symbol": "RELIANCE", "name": "Reliance Industries", "pe_ratio": 25.4, ...}
+
+# Price history (DataFrame)
+stock.history(period="1y")
+#             open     high      low    close     volume
+# 2024-01-02  2502.00  2535.00  2490.00  2520.00  8234567
+# 2024-01-03  2525.00  2560.00  2510.00  2545.00  7654321
+# ...
+
+# Annual income statement
+stock.financials
+#             revenue   cogs   gross_profit  operating_profit  net_profit  eps
+# 2024-03-31  612000.0  ...    ...           ...               60500.0     89.4
+# 2023-03-31  593500.0  ...    ...           ...               55100.0     81.5
+# ...
+
+# Other statements
+stock.balance_sheet
+stock.cashflow
+stock.ratios
+stock.quarterly_financials
+stock.shareholding
+```
+
+## Multiple Tickers
+
+```python
+tickers = ff.Tickers("RELIANCE TCS INFY")
+tickers["RELIANCE"].price
+tickers["TCS"].financials
+
+# Price history for all
+histories = tickers.history(period="6m")
+```
+
+## Convenience Functions
+
+```python
+# Quick price lookup
+ff.get_price("RELIANCE")   # → 2845.50
+
+# Search for tickers
+ff.search("Reliance")
+# [{"symbol": "RELIANCE", "name": "reliance industries", "score": 0.85}, ...]
+```
+
+## Features
+
+- **Lazy loading** — data is only fetched when you access a property
+- **Built-in caching** — results cached for 5 minutes (configurable)
+- **Multi-source fallback** — tries Screener.in → Trendlyne → MoneyControl → Yahoo Finance
+- **Retry with backoff** — handles rate limits and transient errors
+- **Clean output** — snake_case columns, DatetimeIndex, NaN for missing values
+- **No API keys** — pure web scraping of publicly available data
+
+## Configuration
+
+### Cache TTL
+
+```python
+stock = ff.Ticker("RELIANCE", cache_ttl=600)  # cache for 10 minutes
+stock.clear_cache()                            # manually invalidate
+```
+
+### Consolidated vs Standalone
+
+```python
+stock = ff.Ticker("RELIANCE", consolidated=False)  # standalone statements
+```
+
+### Screener.in Login (optional)
+
+Set environment variables for extended Screener.in data:
+
+```bash
+export SCREENER_EMAIL="your@email.com"
+export SCREENER_PASSWORD="yourpassword"
+```
+
+## Data Sources
+
+| Source | Sections | Auth Required |
+|---|---|---|
+| Screener.in | All financials, ratios, shareholding | Optional (login gives more history) |
+| Trendlyne | Income, balance sheet, cash flow, ratios | No |
+| MoneyControl | Income, balance sheet, cash flow, ratios | No |
+| Yahoo Finance | Income, balance sheet, cash flow, price | No |
+
+Sources are tried in the order listed above. If one fails, the next is tried automatically.
+
+## Output Format
+
+All financial DataFrames follow a consistent format:
+
+- **Index**: `DatetimeIndex` (fiscal period end dates)
+- **Columns**: `snake_case` field names (e.g., `revenue`, `net_profit`, `operating_profit`)
+- **Values**: `float64` in Crores (INR) for monetary fields
+- **Missing data**: `NaN` (never empty strings)
+
+## Error Handling
+
+```python
+from finfetch import TickerNotFoundError, DataUnavailableError
+
+try:
+    stock = ff.Ticker("INVALID")
+    data = stock.financials
+except DataUnavailableError as e:
+    print(f"No data: {e}")
+```
+
+## Building from Source
+
+```bash
+pip install build
+python -m build
+# Output: dist/finfetch-0.1.0-py3-none-any.whl
+```
+
+## License
+
+MIT

finfetch-0.1.0/README.md

@@ -0,0 +1,154 @@
+# finfetch
+
+Free financial data for Indian stocks. No API key needed.
+
+`finfetch` scrapes publicly available data from Screener.in, Trendlyne, MoneyControl, and Yahoo Finance, returning clean **pandas DataFrames** with normalised column names and proper datetime indices.
+
+## Installation
+
+```bash
+pip install finfetch
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/karanveersingh/finfetch.git
+cd finfetch
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import finfetch as ff
+
+# Create a ticker object
+stock = ff.Ticker("RELIANCE")
+
+# Current price
+stock.price          # → 2845.50
+
+# Company info (dict)
+stock.info           # → {"symbol": "RELIANCE", "name": "Reliance Industries", "pe_ratio": 25.4, ...}
+
+# Price history (DataFrame)
+stock.history(period="1y")
+#             open     high      low    close     volume
+# 2024-01-02  2502.00  2535.00  2490.00  2520.00  8234567
+# 2024-01-03  2525.00  2560.00  2510.00  2545.00  7654321
+# ...
+
+# Annual income statement
+stock.financials
+#             revenue   cogs   gross_profit  operating_profit  net_profit  eps
+# 2024-03-31  612000.0  ...    ...           ...               60500.0     89.4
+# 2023-03-31  593500.0  ...    ...           ...               55100.0     81.5
+# ...
+
+# Other statements
+stock.balance_sheet
+stock.cashflow
+stock.ratios
+stock.quarterly_financials
+stock.shareholding
+```
+
+## Multiple Tickers
+
+```python
+tickers = ff.Tickers("RELIANCE TCS INFY")
+tickers["RELIANCE"].price
+tickers["TCS"].financials
+
+# Price history for all
+histories = tickers.history(period="6m")
+```
+
+## Convenience Functions
+
+```python
+# Quick price lookup
+ff.get_price("RELIANCE")   # → 2845.50
+
+# Search for tickers
+ff.search("Reliance")
+# [{"symbol": "RELIANCE", "name": "reliance industries", "score": 0.85}, ...]
+```
+
+## Features
+
+- **Lazy loading** — data is only fetched when you access a property
+- **Built-in caching** — results cached for 5 minutes (configurable)
+- **Multi-source fallback** — tries Screener.in → Trendlyne → MoneyControl → Yahoo Finance
+- **Retry with backoff** — handles rate limits and transient errors
+- **Clean output** — snake_case columns, DatetimeIndex, NaN for missing values
+- **No API keys** — pure web scraping of publicly available data
+
+## Configuration
+
+### Cache TTL
+
+```python
+stock = ff.Ticker("RELIANCE", cache_ttl=600)  # cache for 10 minutes
+stock.clear_cache()                            # manually invalidate
+```
+
+### Consolidated vs Standalone
+
+```python
+stock = ff.Ticker("RELIANCE", consolidated=False)  # standalone statements
+```
+
+### Screener.in Login (optional)
+
+Set environment variables for extended Screener.in data:
+
+```bash
+export SCREENER_EMAIL="your@email.com"
+export SCREENER_PASSWORD="yourpassword"
+```
+
+## Data Sources
+
+| Source | Sections | Auth Required |
+|---|---|---|
+| Screener.in | All financials, ratios, shareholding | Optional (login gives more history) |
+| Trendlyne | Income, balance sheet, cash flow, ratios | No |
+| MoneyControl | Income, balance sheet, cash flow, ratios | No |
+| Yahoo Finance | Income, balance sheet, cash flow, price | No |
+
+Sources are tried in the order listed above. If one fails, the next is tried automatically.
+
+## Output Format
+
+All financial DataFrames follow a consistent format:
+
+- **Index**: `DatetimeIndex` (fiscal period end dates)
+- **Columns**: `snake_case` field names (e.g., `revenue`, `net_profit`, `operating_profit`)
+- **Values**: `float64` in Crores (INR) for monetary fields
+- **Missing data**: `NaN` (never empty strings)
+
+## Error Handling
+
+```python
+from finfetch import TickerNotFoundError, DataUnavailableError
+
+try:
+    stock = ff.Ticker("INVALID")
+    data = stock.financials
+except DataUnavailableError as e:
+    print(f"No data: {e}")
+```
+
+## Building from Source
+
+```bash
+pip install build
+python -m build
+# Output: dist/finfetch-0.1.0-py3-none-any.whl
+```
+
+## License
+
+MIT

finfetch-0.1.0/finfetch/__init__.py

@@ -0,0 +1,25 @@
+"""finfetch — Free financial data for Indian stocks. No API key needed."""
+
+from .core import Ticker, Tickers, get_price
+from .models import search
+from .exceptions import (
+    DataUnavailableError,
+    FinFetchError,
+    RateLimitError,
+    ScrapingError,
+    TickerNotFoundError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Ticker",
+    "Tickers",
+    "get_price",
+    "search",
+    # exceptions
+    "FinFetchError",
+    "TickerNotFoundError",
+    "DataUnavailableError",
+    "RateLimitError",
+    "ScrapingError",
+]