pyjpx-etf 0.2.0__tar.gz

pyjpx_etf-0.2.0/.claude/CLAUDE.md

@@ -0,0 +1,103 @@
+# pyjpx-etf
+
+A clean, beginner-friendly Python library for fetching JPX ETF portfolio composition (PCF) data.
+
+## Quick Start Commands
+
+```bash
+# Setup
+uv sync
+
+# Run unit tests
+uv run pytest tests/unit/ -v
+
+# Run integration tests (hits live endpoints, requires JST business hours)
+uv run pytest tests/integration/ --integration -v
+
+# Format & lint
+uv run ruff format .
+uv run ruff check .
+
+# Serve docs
+uv run mkdocs serve
+
+# Build docs (strict)
+uv run mkdocs build --strict
+```
+
+## Architecture
+
+```
+src/pyjpx_etf/
+├── __init__.py        # Public API: ETF class, config, exceptions, models
+├── etf.py             # ETF class (main entry, lazy-loaded) + _resolve_japanese_names()
+├── models.py          # ETFInfo, Holding frozen dataclasses
+├── config.py          # Provider URLs, timeout, delay, lang (mutable singleton, lang validated)
+├── exceptions.py      # PyJPXETFError → ETFNotFoundError, FetchError, ParseError
+├── cli.py             # CLI entry point: `etf <code|alias> [--en] [-a]`, aliases (topix, 225, sox, fang, jpsox1, jpsox2)
+└── _internal/
+    ├── fetcher.py     # I/O only: HTTP GET → raw CSV text (provider fallback)
+    ├── parser.py      # Pure parse: CSV text → models (no I/O)
+    ├── master.py      # JPX master list: fetch XLS (_fetch_master_xls) + parse (_parse_master_xls), 2-tier cache
+    └── fees.py        # JPX ETF fees (信託報酬): fetch HTML (_fetch_fee_html) + parse (_parse_fee_html), 2-tier cache
+```
+
+### Key Design Patterns
+
+- **Fetch/Parse split**: `_internal/fetcher.py` does HTTP only, `_internal/parser.py` does CSV parsing only. `_internal/master.py` and `_internal/fees.py` also follow this split.
+- **Lazy loading**: ETF data fetched on first `.info` or `.holdings` access
+- **Provider fallback**: Try ICE first, then Solactive. CSV content validated (rejects HTML 200s)
+- **Error precedence**: ETFNotFoundError only if *all* providers return 404; any server/network error → FetchError
+- **Name resolution**: Extracted to `_resolve_japanese_names()` in `etf.py` — keeps `_load()` focused on fetch+parse
+- **Config validation**: `config.lang` only accepts `"ja"` or `"en"`, raises `ValueError` otherwise
+
+## Data Sources
+
+| Provider | URL Pattern | Covers |
+|---|---|---|
+| ICE Data Services | `https://inav.ice.com/pcf-download/{code}.csv` | Majority of TSE ETFs |
+| Solactive AG | `https://www.solactive.com/downloads/etfservices/tse-pcf/single/{code}.csv` | Global X Japan ETFs |
+
+- Available 7:50–23:55 JST on business days
+- ICE returns HTML (not 404) outside hours and for unknown codes — fetcher handles this
+- Solactive CSVs use `\r\n` line endings — parser normalizes this
+
+### Verified ETF Codes
+
+| Code | Name | Provider |
+|---|---|---|
+| 1306 | TOPIX ETF | ICE |
+| 1321 | Nikkei 225 ETF | ICE |
+| 1348 | MAXIS TOPIX ETF | ICE |
+| 2564 | Global X MSCI SuperDividend Japan ETF | Solactive |
+| 2627 | Global X E-Commerce Japan ETF | Solactive |
+| 2644 | Global X Japan Semiconductor ETF | Solactive |
+| 2243 | Global X US Tech Top 20 ETF | Solactive |
+| 200A | 日経半導体株 ETF | ICE |
+| 316A | iShares 日経半導体株 ETF | ICE |
+
+## API
+
+```python
+import pyjpx_etf as etf
+
+e = etf.ETF("1306")
+e.info                     # ETFInfo dataclass
+e.info.name                # "TOPIX ETF"
+e.info.to_dict()           # dict of all fields
+e.nav                      # total fund NAV in yen (int)
+e.fee                      # 0.06 (trust fee %, or None)
+e.holdings                 # list[Holding]
+e.to_dataframe()           # pd.DataFrame with weights
+
+etf.config.timeout = 60
+etf.config.request_delay = 0.5
+```
+
+## Dependencies
+
+- `requests>=2.32` — HTTP
+- `pandas>=2.0` — DataFrame output
+- `xlrd>=2.0` — required by `pd.read_excel` for JPX master `.xls` files
+- `lxml>=5.0` — required by `pd.read_html` for JPX ETF fee page
+- No Pydantic, no async

pyjpx_etf-0.2.0/.claude/settings.local.json

@@ -0,0 +1,33 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(tasks-init)",
+      "Bash(uv sync 2>&1)",
+      "Bash(uv run pytest tests/unit/ -v --tb=short 2>&1)",
+      "Bash(uv run pytest --tb=short 2>&1)",
+      "Bash(uv run mkdocs build --strict 2>&1)",
+      "Bash(uv run ruff check --select F401,F841 2>&1)",
+      "Bash(uv run pytest --tb=short -v 2>&1)",
+      "Bash(uv run python -c \"\nimport requests\n\n# Try Solactive first \\(Global X Japan\\)\nurl = 'https://www.solactive.com/downloads/etfservices/tse-pcf/single/2644.csv'\nr = requests.get\\(url, timeout=30\\)\nprint\\(f'Solactive status: {r.status_code}'\\)\nif r.status_code == 200:\n    print\\('--- First 30 lines ---'\\)\n    for i, line in enumerate\\(r.text.split\\('\\\\n'\\)[:30]\\):\n        print\\(f'{i:3}: {repr\\(line\\)}'\\)\nelse:\n    # Try ICE\n    url2 = 'https://inav.ice.com/pcf-download/2644.csv'\n    r2 = requests.get\\(url2, timeout=30\\)\n    print\\(f'ICE status: {r2.status_code}'\\)\n    if r2.status_code == 200:\n        print\\('--- First 30 lines ---'\\)\n        for i, line in enumerate\\(r2.text.split\\('\\\\n'\\)[:30]\\):\n            print\\(f'{i:3}: {repr\\(line\\)}'\\)\n\")",
+      "Bash(uv run python -c \"\nimport requests\nurl = 'https://www.solactive.com/downloads/etfservices/tse-pcf/single/2644.csv'\nr = requests.get\\(url, timeout=30\\)\ntext = r.text\n# Show exact bytes around blank line\nidx = text.find\\('20260227'\\)\nsnippet = text[idx:idx+50]\nprint\\('Bytes around section break:', repr\\(snippet\\)\\)\n\n# Try the normalize\nnorm = text.replace\\('\\\\r\\\\n', '\\\\n'\\).strip\\(\\)\nsections = norm.split\\('\\\\n\\\\n'\\)\nprint\\(f'Sections after normalize: {len\\(sections\\)}'\\)\nif len\\(sections\\) >= 2:\n    print\\(f'Section 1 lines: {sections[0].count\\(chr\\(10\\)\\)+1}'\\)\n    print\\(f'Section 2 lines: {sections[1].count\\(chr\\(10\\)\\)+1}'\\)\n\")",
+      "Bash(uv run python -c \"import pyjpx_etf._internal.parser; print\\(pyjpx_etf._internal.parser.__file__\\)\")",
+      "Bash(uv run python -c \"\nimport inspect, pyjpx_etf._internal.parser as p\nsrc = inspect.getsource\\(p.parse_pcf\\)\nprint\\(src[:300]\\)\n\")",
+      "Bash(find /Users/soshimizutani/dev/pyjpx-etf/src -name \"*.pyc\" -delete && uv run pytest tests/unit/ --tb=short -v 2>&1)",
+      "Bash(find /Users/soshimizutani/dev/pyjpx-etf -name \"*.pyc\" -not -path '*/.venv/*' -delete && uv run pytest tests/integration/ --integration --tb=short -v 2>&1)",
+      "Skill(audit)",
+      "Bash(uv run mkdocs gh-deploy --strict)",
+      "Bash(uv run pytest tests/unit/ --tb=short 2>&1)",
+      "Bash(uv run etf 1306 2>&1)",
+      "Bash(uv run python -c \"\nfrom pyjpx_etf._internal.fetcher import fetch_pcf\ncsv = fetch_pcf\\('1306'\\)\n# Show header rows and first few data lines\nlines = csv.replace\\('\\\\r\\\\n', '\\\\n'\\).strip\\(\\).split\\('\\\\n'\\)\nfor line in lines[:3]:\n    print\\(line\\)\nprint\\('...'\\)\nsections = csv.replace\\('\\\\r\\\\n', '\\\\n'\\).strip\\(\\).split\\('\\\\n\\\\n'\\)\nholdings_lines = sections[1].split\\('\\\\n'\\)\nfor line in holdings_lines[:5]:\n    print\\(line\\)\n\" 2>&1)",
+      "Bash(uv run etf 1306 --en 2>&1)",
+      "Bash(uv run pytest tests/unit/test_master.py -v --tb=short 2>&1)",
+      "Bash(uv run pytest tests/unit/test_etf.py -v --tb=short 2>&1)",
+      "WebSearch",
+      "Bash(uv run pytest tests/unit/ -v 2>&1)",
+      "Bash(uv run etf 2042)",
+      "Bash(uv run pytest tests/unit/ --tb=short -q)",
+      "Bash(uv run ruff check --select F401,F841 src/)",
+      "WebFetch(domain:api.github.com)"
+    ]
+  }
+}

pyjpx_etf-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyjpx_etf-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+
+# MkDocs build output
+site/

pyjpx_etf-0.2.0/LICENSE

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

pyjpx_etf-0.2.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: pyjpx-etf
+Version: 0.2.0
+Summary: A clean, beginner-friendly Python library for fetching JPX ETF portfolio composition (PCF) data.
+Project-URL: Homepage, https://github.com/obichan117/pyjpx-etf
+Project-URL: Documentation, https://obichan117.github.io/pyjpx-etf
+Project-URL: Repository, https://github.com/obichan117/pyjpx-etf
+Author: obichan117
+License-Expression: MIT
+License-File: LICENSE
+Keywords: etf,finance,japan,jpx,pcf,portfolio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+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
+Requires-Python: >=3.10
+Requires-Dist: lxml>=5.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.32
+Requires-Dist: xlrd>=2.0
+Description-Content-Type: text/markdown
+
+# pyjpx-etf
+
+A clean, beginner-friendly Python library for fetching JPX ETF portfolio composition (PCF) data.
+
+## Installation
+
+```bash
+pip install pyjpx-etf
+```
+
+## Quick Start
+
+```python
+import pyjpx_etf as etf
+
+e = etf.ETF("1306")
+print(e.info.name)       # "TOPIX連動型上場投資信託"
+print(e.nav)             # total fund NAV in yen
+print(e.fee)             # trust fee (%) e.g. 0.06
+print(e.holdings[:3])
+# [Holding(code='7203', name='トヨタ自動車', ...),
+#  Holding(code='8306', name='三菱UFJフィナンシャル・グループ', ...),
+#  Holding(code='6758', name='ソニーグループ', ...)]
+```
+
+## CLI
+
+```
+$ etf 1306
+
+1306 — TOPIX連動型上場投資信託 (2026-02-27)
+Nav: 5170億  信託報酬: 0.06%
+
+ Code   Name                                Weight
+─────  ──────────────────────────────────  ──────
+ 7203   トヨタ自動車                          3.7%
+ 8306   三菱ＵＦＪフィナンシャル・グループ    3.3%
+ 6501   日立製作所                            2.4%
+ ...
+```
+
+### Aliases
+
+Use shorthand aliases instead of codes:
+
+| Alias | Code | ETF |
+|-------|------|-----|
+| `etf topix` | 1306 | TOPIX連動型上場投資信託 |
+| `etf 225` | 1321 | 日経225連動型上場投資信託 |
+| `etf core30` | 1311 | TOPIX Core30連動型上場投資信託 |
+| `etf div50` | 1489 | 日経平均高配当株50指数連動型ETF |
+| `etf div70` | 1577 | 野村日本株高配当70連動型ETF |
+| `etf div100` | 1698 | 上場インデックスファンド日本高配当 |
+| `etf pbr` | 2080 | PBR1倍割れ解消推進ETF |
+| `etf fang` | 2243 | Global X US Tech Top 20 ETF |
+| `etf sox` | 2644 | Global X 半導体関連-日本株式 ETF |
+| `etf jpsox1` | 200A | 日経半導体株 ETF |
+| `etf jpsox2` | 316A | iShares 日経半導体株 ETF |
+
+### Options
+
+```
+$ etf sox --en         # English names
+$ etf topix -a         # all holdings (not just top 10)
+$ etf 1306 -a --en     # combine options
+```
+
+## Language Setting
+
+Names default to Japanese. Switch to English via config or CLI flag:
+
+```python
+import pyjpx_etf as etf
+
+# English names
+etf.config.lang = "en"
+e = etf.ETF("1306")
+print(e.info.name)  # "TOPIX ETF"
+```
+
+## Configuration
+
+```python
+import pyjpx_etf as etf
+
+etf.config.timeout = 60
+etf.config.request_delay = 0.5
+etf.config.lang = "en"  # "ja" (default) or "en"
+```
+
+## Documentation
+
+[Full documentation](https://obichan117.github.io/pyjpx-etf)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obichan117/pyjpx-etf/blob/main/examples/quickstart.ipynb)

pyjpx_etf-0.2.0/README.md

@@ -0,0 +1,95 @@
+# pyjpx-etf
+
+A clean, beginner-friendly Python library for fetching JPX ETF portfolio composition (PCF) data.
+
+## Installation
+
+```bash
+pip install pyjpx-etf
+```
+
+## Quick Start
+
+```python
+import pyjpx_etf as etf
+
+e = etf.ETF("1306")
+print(e.info.name)       # "TOPIX連動型上場投資信託"
+print(e.nav)             # total fund NAV in yen
+print(e.fee)             # trust fee (%) e.g. 0.06
+print(e.holdings[:3])
+# [Holding(code='7203', name='トヨタ自動車', ...),
+#  Holding(code='8306', name='三菱UFJフィナンシャル・グループ', ...),
+#  Holding(code='6758', name='ソニーグループ', ...)]
+```
+
+## CLI
+
+```
+$ etf 1306
+
+1306 — TOPIX連動型上場投資信託 (2026-02-27)
+Nav: 5170億  信託報酬: 0.06%
+
+ Code   Name                                Weight
+─────  ──────────────────────────────────  ──────
+ 7203   トヨタ自動車                          3.7%
+ 8306   三菱ＵＦＪフィナンシャル・グループ    3.3%
+ 6501   日立製作所                            2.4%
+ ...
+```
+
+### Aliases
+
+Use shorthand aliases instead of codes:
+
+| Alias | Code | ETF |
+|-------|------|-----|
+| `etf topix` | 1306 | TOPIX連動型上場投資信託 |
+| `etf 225` | 1321 | 日経225連動型上場投資信託 |
+| `etf core30` | 1311 | TOPIX Core30連動型上場投資信託 |
+| `etf div50` | 1489 | 日経平均高配当株50指数連動型ETF |
+| `etf div70` | 1577 | 野村日本株高配当70連動型ETF |
+| `etf div100` | 1698 | 上場インデックスファンド日本高配当 |
+| `etf pbr` | 2080 | PBR1倍割れ解消推進ETF |
+| `etf fang` | 2243 | Global X US Tech Top 20 ETF |
+| `etf sox` | 2644 | Global X 半導体関連-日本株式 ETF |
+| `etf jpsox1` | 200A | 日経半導体株 ETF |
+| `etf jpsox2` | 316A | iShares 日経半導体株 ETF |
+
+### Options
+
+```
+$ etf sox --en         # English names
+$ etf topix -a         # all holdings (not just top 10)
+$ etf 1306 -a --en     # combine options
+```
+
+## Language Setting
+
+Names default to Japanese. Switch to English via config or CLI flag:
+
+```python
+import pyjpx_etf as etf
+
+# English names
+etf.config.lang = "en"
+e = etf.ETF("1306")
+print(e.info.name)  # "TOPIX ETF"
+```
+
+## Configuration
+
+```python
+import pyjpx_etf as etf
+
+etf.config.timeout = 60
+etf.config.request_delay = 0.5
+etf.config.lang = "en"  # "ja" (default) or "en"
+```
+
+## Documentation
+
+[Full documentation](https://obichan117.github.io/pyjpx-etf)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obichan117/pyjpx-etf/blob/main/examples/quickstart.ipynb)

pyjpx_etf-0.2.0/docs/api/config.md

@@ -0,0 +1,7 @@
+# Config
+
+::: pyjpx_etf.config
+    options:
+      show_root_heading: true
+
+::: pyjpx_etf.config.Config

pyjpx_etf-0.2.0/docs/api/etf.md

@@ -0,0 +1,3 @@
+# ETF
+
+::: pyjpx_etf.ETF

pyjpx_etf-0.2.0/docs/api/exceptions.md

@@ -0,0 +1,9 @@
+# Exceptions
+
+::: pyjpx_etf.PyJPXETFError
+
+::: pyjpx_etf.ETFNotFoundError
+
+::: pyjpx_etf.FetchError
+
+::: pyjpx_etf.ParseError

pyjpx_etf-0.2.0/docs/getting-started.md

@@ -0,0 +1,68 @@
+# Getting Started
+
+## Installation
+
+```bash
+pip install pyjpx-etf
+```
+
+## Basic Usage
+
+```python
+import pyjpx_etf as etf
+
+e = etf.ETF("1306")
+
+# ETF metadata (Japanese names by default)
+print(e.info.name)              # "TOPIX連動型上場投資信託"
+print(e.info.cash_component)    # 496973797639.0
+print(e.info.shares_outstanding)  # 8133974978
+print(e.info.date)              # datetime.date(2026, 2, 27)
+
+# Holdings
+for h in e.holdings[:3]:
+    print(f"{h.name}: {h.weight:.2%}")
+# トヨタ自動車: 3.80%
+# 三菱UFJフィナンシャル・グループ: 2.50%
+# ソニーグループ: 2.30%
+
+# Full DataFrame
+df = e.to_dataframe()
+```
+
+### Language
+
+Names default to Japanese (`config.lang = "ja"`). Switch to English:
+
+```python
+etf.config.lang = "en"
+e = etf.ETF("1306")
+print(e.info.name)  # "TOPIX ETF"
+```
+
+The CLI uses `--en` for English:
+
+```
+$ etf 1306 --en
+```
+
+### Configuration
+
+```python
+import pyjpx_etf as etf
+
+etf.config.timeout = 60        # HTTP timeout in seconds
+etf.config.request_delay = 0.5  # Delay between provider retries
+etf.config.lang = "en"          # "ja" (default) or "en"
+```
+
+## Data Sources
+
+pyjpx-etf fetches PCF (Portfolio Composition File) CSVs from:
+
+| Provider | Covers |
+|---|---|
+| ICE Data Services | Majority of TSE ETFs |
+| Solactive AG | Global X Japan ETFs |
+
+Data is updated daily on business days, available 7:50–23:55 JST.

pyjpx_etf-0.2.0/docs/guide/etf.md

@@ -0,0 +1,96 @@
+# ETF Data
+
+## The ETF Class
+
+The `ETF` class is the main entry point. It lazily fetches data on first access.
+
+```python
+import pyjpx_etf as etf
+
+e = etf.ETF("1306")
+```
+
+### ETF Info
+
+Access metadata via the `info` property. Names are Japanese by default:
+
+```python
+e.info.code               # "1306"
+e.info.name               # "TOPIX連動型上場投資信託"
+e.info.cash_component     # Fund cash component
+e.info.shares_outstanding # Shares outstanding
+e.info.date               # Fund date as datetime.date
+
+# Convert to dict
+dict_info = e.info.to_dict()
+```
+
+### Holdings
+
+Access constituent holdings:
+
+```python
+for h in e.holdings[:3]:
+    print(f"{h.code} {h.name}: {h.weight:.2%}")
+# 7203 トヨタ自動車: 3.80%
+# 8306 三菱UFJフィナンシャル・グループ: 2.50%
+# 6758 ソニーグループ: 2.30%
+```
+
+Each `Holding` has: `code`, `name`, `isin`, `exchange`, `currency`, `shares`, `price`, `weight`.
+
+### NAV
+
+Total fund net asset value (cash + holdings market value) in yen:
+
+```python
+e.nav  # 515997003139 (in yen)
+```
+
+### Fee (信託報酬)
+
+Trust fee (信託報酬) from the JPX ETF list page. Independent of PCF data:
+
+```python
+e.fee  # 0.06 (means 0.06%)
+```
+
+Returns `None` if the fee is unavailable for the given ETF code.
+
+### DataFrame Output
+
+```python
+df = e.to_dataframe()
+# Columns: code, name, isin, exchange, currency, shares, price, weight
+```
+
+### Language
+
+Set `config.lang` before creating an `ETF` instance:
+
+```python
+import pyjpx_etf as etf
+
+# Japanese (default)
+e = etf.ETF("1306")
+e.info.name  # "TOPIX連動型上場投資信託"
+
+# English
+etf.config.lang = "en"
+e = etf.ETF("1306")
+e.info.name  # "TOPIX ETF"
+```
+
+## Error Handling
+
+```python
+from pyjpx_etf import ETFNotFoundError, FetchError, ParseError
+
+try:
+    e = etf.ETF("9999")
+    _ = e.info
+except ETFNotFoundError:
+    print("ETF not found")
+except FetchError:
+    print("Network error")
+```

pyjpx_etf-0.2.0/docs/index.md

@@ -0,0 +1,60 @@
+# pyjpx-etf
+
+A clean, beginner-friendly Python library for fetching JPX ETF portfolio composition (PCF) data.
+
+## Features
+
+- **Simple API** — yfinance-style `ETF("1306")` interface
+- **Japanese names by default** — powered by the JPX master list
+- **No authentication** — uses free, public PCF CSV endpoints
+- **Lightweight** — just `requests`, `pandas`, and `xlrd`
+- **Auto provider detection** — tries ICE Data Services, then Solactive
+
+## Quick Example
+
+```python
+import pyjpx_etf as etf
+
+e = etf.ETF("1306")
+print(e.info.name)  # "TOPIX連動型上場投資信託"
+print(e.top())
+```
+
+```
+   code          name    weight
+0  7203      トヨタ自動車     3.8
+1  8306  三菱UFJフィナンシャル・グループ  2.5
+2  6758    ソニーグループ     2.3
+...
+```
+
+### CLI
+
+```
+$ etf 1306
+
+1306 — ＮＥＸＴ　ＦＵＮＤＳ　ＴＯＰＩＸ連動型上場投信 (2026-02-27)
+
+ Code   Name                                Weight
+─────  ──────────────────────────────────  ──────
+ 7203   トヨタ自動車                          3.7%
+ 8306   三菱ＵＦＪフィナンシャル・グループ    3.3%
+ 6501   日立製作所                            2.4%
+ 8316   三井住友フィナンシャルグループ        2.3%
+ 6758   ソニーグループ                        2.1%
+ 8058   三菱商事                              2.0%
+ 8411   みずほフィナンシャルグループ          1.8%
+ 8035   東京エレクトロン                      1.7%
+ 7011   三菱重工業                            1.7%
+ 6857   アドバンテスト                        1.6%
+```
+
+Use `--en` for English names: `etf 1306 --en`
+
+## Installation
+
+```bash
+pip install pyjpx-etf
+```
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obichan117/pyjpx-etf/blob/main/examples/quickstart.ipynb)