indexes 0.1.0__tar.gz

indexes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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.

indexes-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: indexes
+Version: 0.1.0
+Summary: A lightweight utility to scrape and retrieve financial index constituents, starting with the S&P 500.
+Author: Fernando Zuniga
+License: MIT
+Project-URL: Homepage, https://github.com/fzunigam/indexes
+Project-URL: Bug Tracker, https://github.com/fzunigam/indexes/issues
+Keywords: finance,sp500,stock-market,scraping,indexes
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Dynamic: license-file
+
+# Indexes
+
+A lightweight, professional Python utility to scrape and retrieve financial index constituents, starting with the S&P 500.
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/indexes.svg)](https://pypi.org/project/indexes/)
+[![Python versions](https://img.shields.io/pypi/pyversions/indexes.svg)](https://pypi.org/project/indexes/)
+
+## About
+
+`indexes` provides a simple, cached interface to access up-to-date data for major financial indexes. It currently supports fetching S&P 500 constituents directly from reliable public sources, providing essential metadata like sector, sub-industry, and CIK.
+
+## Features
+
+- **Simple API**: Get index data in one function call.
+- **Flexible Output**: Choose between list or dictionary formats.
+- **Selective Fields**: Retrieve only the data you need (symbol, name, sector, etc.).
+- **Automatic Caching**: Minimizes network requests during the same session.
+- **Lightweight**: Minimal dependencies (`requests`, `beautifulsoup4`).
+
+## Installation
+
+```bash
+pip install indexes
+```
+
+### Requirements
+
+- Python >= 3.8
+- `requests`
+- `beautifulsoup4`
+
+## Usage
+
+```python
+from financial_indexes import get_sp500
+
+# Get all S&P 500 symbols as a list
+symbols = get_sp500()
+print(f"Total symbols: {len(symbols)}")
+
+# Get detailed info for all companies as a dictionary keyed by symbol
+sp500_details = get_sp500(
+    return_type='dict', 
+    fields=['name', 'sector', 'sub_industry']
+)
+print(sp500_details['AAPL'])
+# Output: {'name': 'Apple Inc.', 'sector': 'Information Technology', 'sub_industry': 'Technology Hardware, Storage & Peripherals'}
+
+# Get specific fields as a list of dictionaries
+data = get_sp500(return_type='list', fields=['name', 'sector'])
+```
+
+## Documentation
+
+### `get_sp500(return_type='list', fields=None)`
+
+Returns constituents of the S&P 500 index.
+
+- **`return_type`** (str): `'list'` (default) or `'dict'`.
+- **`fields`** (list, optional): List of fields to include. Defaults to `['symbol']`.
+    - Supported fields: `symbol`, `name`, `sector`, `sub_industry`, `date_added`, `cik`, `founded`.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/financial-indexes.git
+   cd financial-indexes
+   ```
+2. Create and activate a virtual environment.
+3. Install dependencies:
+   ```bash
+   pip install -e .
+   ```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+`financial-indexes` is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.

indexes-0.1.0/README.md

@@ -0,0 +1,89 @@
+# Indexes
+
+A lightweight, professional Python utility to scrape and retrieve financial index constituents, starting with the S&P 500.
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/indexes.svg)](https://pypi.org/project/indexes/)
+[![Python versions](https://img.shields.io/pypi/pyversions/indexes.svg)](https://pypi.org/project/indexes/)
+
+## About
+
+`indexes` provides a simple, cached interface to access up-to-date data for major financial indexes. It currently supports fetching S&P 500 constituents directly from reliable public sources, providing essential metadata like sector, sub-industry, and CIK.
+
+## Features
+
+- **Simple API**: Get index data in one function call.
+- **Flexible Output**: Choose between list or dictionary formats.
+- **Selective Fields**: Retrieve only the data you need (symbol, name, sector, etc.).
+- **Automatic Caching**: Minimizes network requests during the same session.
+- **Lightweight**: Minimal dependencies (`requests`, `beautifulsoup4`).
+
+## Installation
+
+```bash
+pip install indexes
+```
+
+### Requirements
+
+- Python >= 3.8
+- `requests`
+- `beautifulsoup4`
+
+## Usage
+
+```python
+from financial_indexes import get_sp500
+
+# Get all S&P 500 symbols as a list
+symbols = get_sp500()
+print(f"Total symbols: {len(symbols)}")
+
+# Get detailed info for all companies as a dictionary keyed by symbol
+sp500_details = get_sp500(
+    return_type='dict', 
+    fields=['name', 'sector', 'sub_industry']
+)
+print(sp500_details['AAPL'])
+# Output: {'name': 'Apple Inc.', 'sector': 'Information Technology', 'sub_industry': 'Technology Hardware, Storage & Peripherals'}
+
+# Get specific fields as a list of dictionaries
+data = get_sp500(return_type='list', fields=['name', 'sector'])
+```
+
+## Documentation
+
+### `get_sp500(return_type='list', fields=None)`
+
+Returns constituents of the S&P 500 index.
+
+- **`return_type`** (str): `'list'` (default) or `'dict'`.
+- **`fields`** (list, optional): List of fields to include. Defaults to `['symbol']`.
+    - Supported fields: `symbol`, `name`, `sector`, `sub_industry`, `date_added`, `cik`, `founded`.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/financial-indexes.git
+   cd financial-indexes
+   ```
+2. Create and activate a virtual environment.
+3. Install dependencies:
+   ```bash
+   pip install -e .
+   ```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+`financial-indexes` is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.

indexes-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "indexes"
+version = "0.1.0"
+description = "A lightweight utility to scrape and retrieve financial index constituents, starting with the S&P 500."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+authors = [
+    {name = "Fernando Zuniga"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+    "Intended Audience :: Developers",
+]
+keywords = ["finance", "sp500", "stock-market", "scraping", "indexes"]
+dependencies = [
+    "requests",
+    "beautifulsoup4",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/fzunigam/indexes"
+"Bug Tracker" = "https://github.com/fzunigam/indexes/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

indexes-0.1.0/setup.cfg

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

indexes-0.1.0/src/financial_indexes/__init__.py

@@ -0,0 +1,4 @@
+from .api import get_sp500
+
+__version__ = "0.1.0"
+__all__ = ["get_sp500"]

indexes-0.1.0/src/financial_indexes/api.py

@@ -0,0 +1,32 @@
+from .scraper import fetch_and_parse_sp500
+
+SUPPORTED_FIELDS = {'symbol', 'name', 'sector', 'sub_industry', 'date_added', 'cik', 'founded'}
+_CACHE = {}
+
+def get_sp500(return_type='list', fields=None):
+    if return_type not in ('list', 'dict'):
+        raise ValueError("Invalid return_type. Must be 'list' or 'dict'.")
+    if fields is None:
+        fields = ['symbol']
+    for field in fields:
+        if field not in SUPPORTED_FIELDS:
+            raise ValueError(f"Unsupported field: {field}")
+            
+    if 'sp500' not in _CACHE:
+        _CACHE['sp500'] = fetch_and_parse_sp500()
+        
+    data = _CACHE['sp500']
+    
+    if return_type == 'dict':
+        return {
+            row['symbol']: {k: v for k, v in row.items() if k in fields}
+            for row in data
+        }
+    
+    if return_type == 'list':
+        if len(fields) == 1 and fields[0] == 'symbol':
+            return [row['symbol'] for row in data]
+        return [
+            {k: v for k, v in row.items() if k in fields or k == 'symbol'}
+            for row in data
+        ]

indexes-0.1.0/src/financial_indexes/scraper.py

@@ -0,0 +1,26 @@
+import requests
+from bs4 import BeautifulSoup
+
+URL = "https://en.wikipedia.org/wiki/List_of_S%26P_500_companies"
+
+def fetch_and_parse_sp500():
+    headers = {'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'}
+    response = requests.get(URL, headers=headers)
+    response.raise_for_status()
+    soup = BeautifulSoup(response.text, 'html.parser')
+    table = soup.find('table', {'id': 'constituents'})
+    
+    results = []
+    for row in table.find_all('tr')[1:]:
+        cols = row.find_all(['td', 'th'])
+        if len(cols) >= 8:
+            results.append({
+                'symbol': cols[0].text.strip(),
+                'name': cols[1].text.strip(),
+                'sector': cols[3].text.strip(),
+                'sub_industry': cols[4].text.strip(),
+                'date_added': cols[6].text.strip(),
+                'cik': cols[7].text.strip(),
+                'founded': cols[8].text.strip() if len(cols) > 8 else ''
+            })
+    return results

indexes-0.1.0/src/indexes.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: indexes
+Version: 0.1.0
+Summary: A lightweight utility to scrape and retrieve financial index constituents, starting with the S&P 500.
+Author: Fernando Zuniga
+License: MIT
+Project-URL: Homepage, https://github.com/fzunigam/indexes
+Project-URL: Bug Tracker, https://github.com/fzunigam/indexes/issues
+Keywords: finance,sp500,stock-market,scraping,indexes
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: beautifulsoup4
+Dynamic: license-file
+
+# Indexes
+
+A lightweight, professional Python utility to scrape and retrieve financial index constituents, starting with the S&P 500.
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/indexes.svg)](https://pypi.org/project/indexes/)
+[![Python versions](https://img.shields.io/pypi/pyversions/indexes.svg)](https://pypi.org/project/indexes/)
+
+## About
+
+`indexes` provides a simple, cached interface to access up-to-date data for major financial indexes. It currently supports fetching S&P 500 constituents directly from reliable public sources, providing essential metadata like sector, sub-industry, and CIK.
+
+## Features
+
+- **Simple API**: Get index data in one function call.
+- **Flexible Output**: Choose between list or dictionary formats.
+- **Selective Fields**: Retrieve only the data you need (symbol, name, sector, etc.).
+- **Automatic Caching**: Minimizes network requests during the same session.
+- **Lightweight**: Minimal dependencies (`requests`, `beautifulsoup4`).
+
+## Installation
+
+```bash
+pip install indexes
+```
+
+### Requirements
+
+- Python >= 3.8
+- `requests`
+- `beautifulsoup4`
+
+## Usage
+
+```python
+from financial_indexes import get_sp500
+
+# Get all S&P 500 symbols as a list
+symbols = get_sp500()
+print(f"Total symbols: {len(symbols)}")
+
+# Get detailed info for all companies as a dictionary keyed by symbol
+sp500_details = get_sp500(
+    return_type='dict', 
+    fields=['name', 'sector', 'sub_industry']
+)
+print(sp500_details['AAPL'])
+# Output: {'name': 'Apple Inc.', 'sector': 'Information Technology', 'sub_industry': 'Technology Hardware, Storage & Peripherals'}
+
+# Get specific fields as a list of dictionaries
+data = get_sp500(return_type='list', fields=['name', 'sector'])
+```
+
+## Documentation
+
+### `get_sp500(return_type='list', fields=None)`
+
+Returns constituents of the S&P 500 index.
+
+- **`return_type`** (str): `'list'` (default) or `'dict'`.
+- **`fields`** (list, optional): List of fields to include. Defaults to `['symbol']`.
+    - Supported fields: `symbol`, `name`, `sector`, `sub_industry`, `date_added`, `cik`, `founded`.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+### Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/yourusername/financial-indexes.git
+   cd financial-indexes
+   ```
+2. Create and activate a virtual environment.
+3. Install dependencies:
+   ```bash
+   pip install -e .
+   ```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## License
+
+`financial-indexes` is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.

indexes-0.1.0/src/indexes.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/financial_indexes/__init__.py
+src/financial_indexes/api.py
+src/financial_indexes/scraper.py
+src/indexes.egg-info/PKG-INFO
+src/indexes.egg-info/SOURCES.txt
+src/indexes.egg-info/dependency_links.txt
+src/indexes.egg-info/requires.txt
+src/indexes.egg-info/top_level.txt
+tests/test_api.py
+tests/test_scraper.py
+tests/test_setup.py

indexes-0.1.0/src/indexes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

indexes-0.1.0/src/indexes.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests
+beautifulsoup4

indexes-0.1.0/src/indexes.egg-info/top_level.txt

@@ -0,0 +1 @@
+financial_indexes

indexes-0.1.0/tests/test_api.py

@@ -0,0 +1,20 @@
+import pytest
+from financial_indexes.api import get_sp500
+
+def test_invalid_return_type():
+    with pytest.raises(ValueError, match="Invalid return_type"):
+        get_sp500(return_type='tuple')
+
+def test_invalid_fields():
+    with pytest.raises(ValueError, match="Unsupported field"):
+        get_sp500(fields=['symbol', 'fake_field'])
+
+def test_get_sp500_list():
+    res = get_sp500(return_type='list', fields=['symbol'])
+    assert len(res) > 400
+    assert isinstance(res[0], str)
+
+def test_get_sp500_dict():
+    res = get_sp500(return_type='dict', fields=['name'])
+    assert 'AAPL' in res
+    assert 'name' in res['AAPL']

indexes-0.1.0/tests/test_scraper.py

@@ -0,0 +1,8 @@
+from financial_indexes.scraper import fetch_and_parse_sp500
+
+def test_scraper_returns_data():
+    # Note: in real implementation, mock requests.get, but for this basic setup we test structure
+    data = fetch_and_parse_sp500()
+    assert isinstance(data, list)
+    assert len(data) > 0
+    assert 'symbol' in data[0]

indexes-0.1.0/tests/test_setup.py

@@ -0,0 +1,4 @@
+import financial_indexes
+
+def test_package_imports():
+    assert financial_indexes.__version__ == "0.1.0"