taigeotrans 0.1.0__tar.gz

taigeotrans-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chien-Hsun Chang & TaiGeotrans Contributors
+
+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.

taigeotrans-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: taigeotrans
+Version: 0.1.0
+Summary: Taiwan Geospatial Transformer - 台灣地址與座標轉換工具
+Author: TaiGeotrans Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KageRyo/TaiGeotrans
+Project-URL: Repository, https://github.com/KageRyo/TaiGeotrans
+Project-URL: Issues, https://github.com/KageRyo/TaiGeotrans/issues
+Keywords: taiwan,geospatial,coordinate,transform,TWD97,WGS84,geocoding
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyproj>=3.6.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: geocoding
+Requires-Dist: httpx>=0.27.0; extra == "geocoding"
+Provides-Extra: dataframe
+Requires-Dist: pandas>=2.0.0; extra == "dataframe"
+Provides-Extra: progress
+Requires-Dist: tqdm>=4.66.0; extra == "progress"
+Provides-Extra: cli
+Requires-Dist: httpx>=0.27.0; extra == "cli"
+Requires-Dist: pandas>=2.0.0; extra == "cli"
+Requires-Dist: python-dotenv>=1.0.0; extra == "cli"
+Requires-Dist: rich>=13.0.0; extra == "cli"
+Requires-Dist: tqdm>=4.66.0; extra == "cli"
+Requires-Dist: typer>=0.12.0; extra == "cli"
+Provides-Extra: all
+Requires-Dist: httpx>=0.27.0; extra == "all"
+Requires-Dist: pandas>=2.0.0; extra == "all"
+Requires-Dist: python-dotenv>=1.0.0; extra == "all"
+Requires-Dist: rich>=13.0.0; extra == "all"
+Requires-Dist: tqdm>=4.66.0; extra == "all"
+Requires-Dist: typer>=0.12.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Dynamic: license-file
+
+# TaiGeotrans
+
+[![CI](https://github.com/KageRyo/TaiGeotrans/actions/workflows/ci.yml/badge.svg)](https://github.com/KageRyo/TaiGeotrans/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/taigeotrans?logo=pypi&logoColor=white)](https://pypi.org/project/taigeotrans/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+TaiGeotrans 是一個台灣地址與座標轉換工具，支援：
+
+- WGS84（EPSG:4326）與 TWD97（EPSG:3826）雙向轉換
+- 透過 TGOS 將台灣地址轉成座標
+- 批量處理、pandas DataFrame 與 GeoJSON
+- 命令列操作
+
+## 安裝
+
+只使用座標轉換時：
+
+```bash
+python -m pip install taigeotrans
+```
+
+需要地址定位、DataFrame 或 CLI 時，再安裝對應功能：
+
+```bash
+python -m pip install "taigeotrans[geocoding]"
+python -m pip install "taigeotrans[dataframe]"
+python -m pip install "taigeotrans[cli]"
+```
+
+也可以一次安裝全部功能：
+
+```bash
+python -m pip install "taigeotrans[all]"
+```
+
+## Python API
+
+```python
+from taigeotrans import TaiGeotrans
+
+tg = TaiGeotrans()
+
+# WGS84 -> TWD97
+result = tg.transform_lonlat(121.5654, 25.0330)
+print(result.twd97_x, result.twd97_y)
+
+# TWD97 -> WGS84
+result = tg.transform_twd97(303891.54, 2773226.67)
+print(result.wgs84_lon, result.wgs84_lat)
+```
+
+### 地址定位
+
+地址定位使用 TGOS，需要 AppID 與 APIKey。請先在 TGOS 申請這兩項資料，
+再透過環境變數提供：
+
+```bash
+export TGOS_APP_ID="your-app-id"
+export TGOS_API_KEY="your-api-key"
+```
+
+或直接傳給 `TaiGeotrans`：
+
+```python
+tg = TaiGeotrans(
+    tgos_app_id="your-app-id",
+    tgos_api_key="your-api-key",
+)
+result = tg.geocode("臺北市中山區松江路469巷4號")
+print(result.matched_address, result.twd97_x, result.twd97_y)
+```
+
+Python API 不會自動讀取 `.env`。CLI 會讀取目前工作目錄的 `.env`，可以複製
+`.env.example` 作為範本；實際 key 不要提交到 Git。
+
+### 批量處理
+
+```python
+addresses = ["嘉義縣民雄鄉中樂路55號", "臺北市信義區市府路1號"]
+coords = [(120.4278, 23.5521), (121.5654, 25.0330)]
+
+address_results = tg.batch_geocode(addresses, show_progress=False)
+coordinate_results = tg.batch_transform_lonlat(coords, show_progress=False)
+df = tg.batch_transform_lonlat_to_dataframe(coords, show_progress=False)
+```
+
+DataFrame 方法需要 `taigeotrans[dataframe]`。進度列使用 `tqdm`；沒有安裝時，
+批量方法仍可執行，只是不顯示進度列。
+
+## CLI
+
+```bash
+python -m pip install "taigeotrans[cli]"
+
+taigeotrans transform 121.5654 25.0330
+taigeotrans transform 121.5654 25.0330 --format json
+taigeotrans geocode "臺北市信義區市府路1號"
+taigeotrans batch-geocode addresses.txt -o results.csv
+taigeotrans batch-transform coords.csv -o results.csv
+```
+
+`addresses.txt` 每行一個地址；`coords.csv` 需要包含 `lon,lat` 欄位。執行
+`taigeotrans --help` 查看完整指令。
+
+## 結果
+
+每個操作都回傳 `GeocodeResult`，包含輸入值、WGS84/TWD97 座標、來源與狀態。
+狀態可能是 `success`、`out_of_bounds`、`invalid` 或 `failed`。
+
+## 開發
+
+```bash
+python -m pip install -e ".[dev,all]"
+python -m pytest
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m mypy src
+python -m build
+python -m twine check dist/*
+```
+
+CI 會測試 Python 3.11–3.13。推送 `vMAJOR.MINOR.PATCH` tag 後，release workflow
+會建置套件、發佈到 PyPI，並建立 GitHub Release。
+
+## 授權
+
+MIT License，請參考 [LICENSE](LICENSE)。

taigeotrans-0.1.0/README.md

@@ -0,0 +1,128 @@
+# TaiGeotrans
+
+[![CI](https://github.com/KageRyo/TaiGeotrans/actions/workflows/ci.yml/badge.svg)](https://github.com/KageRyo/TaiGeotrans/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/taigeotrans?logo=pypi&logoColor=white)](https://pypi.org/project/taigeotrans/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+TaiGeotrans 是一個台灣地址與座標轉換工具，支援：
+
+- WGS84（EPSG:4326）與 TWD97（EPSG:3826）雙向轉換
+- 透過 TGOS 將台灣地址轉成座標
+- 批量處理、pandas DataFrame 與 GeoJSON
+- 命令列操作
+
+## 安裝
+
+只使用座標轉換時：
+
+```bash
+python -m pip install taigeotrans
+```
+
+需要地址定位、DataFrame 或 CLI 時，再安裝對應功能：
+
+```bash
+python -m pip install "taigeotrans[geocoding]"
+python -m pip install "taigeotrans[dataframe]"
+python -m pip install "taigeotrans[cli]"
+```
+
+也可以一次安裝全部功能：
+
+```bash
+python -m pip install "taigeotrans[all]"
+```
+
+## Python API
+
+```python
+from taigeotrans import TaiGeotrans
+
+tg = TaiGeotrans()
+
+# WGS84 -> TWD97
+result = tg.transform_lonlat(121.5654, 25.0330)
+print(result.twd97_x, result.twd97_y)
+
+# TWD97 -> WGS84
+result = tg.transform_twd97(303891.54, 2773226.67)
+print(result.wgs84_lon, result.wgs84_lat)
+```
+
+### 地址定位
+
+地址定位使用 TGOS，需要 AppID 與 APIKey。請先在 TGOS 申請這兩項資料，
+再透過環境變數提供：
+
+```bash
+export TGOS_APP_ID="your-app-id"
+export TGOS_API_KEY="your-api-key"
+```
+
+或直接傳給 `TaiGeotrans`：
+
+```python
+tg = TaiGeotrans(
+    tgos_app_id="your-app-id",
+    tgos_api_key="your-api-key",
+)
+result = tg.geocode("臺北市中山區松江路469巷4號")
+print(result.matched_address, result.twd97_x, result.twd97_y)
+```
+
+Python API 不會自動讀取 `.env`。CLI 會讀取目前工作目錄的 `.env`，可以複製
+`.env.example` 作為範本；實際 key 不要提交到 Git。
+
+### 批量處理
+
+```python
+addresses = ["嘉義縣民雄鄉中樂路55號", "臺北市信義區市府路1號"]
+coords = [(120.4278, 23.5521), (121.5654, 25.0330)]
+
+address_results = tg.batch_geocode(addresses, show_progress=False)
+coordinate_results = tg.batch_transform_lonlat(coords, show_progress=False)
+df = tg.batch_transform_lonlat_to_dataframe(coords, show_progress=False)
+```
+
+DataFrame 方法需要 `taigeotrans[dataframe]`。進度列使用 `tqdm`；沒有安裝時，
+批量方法仍可執行，只是不顯示進度列。
+
+## CLI
+
+```bash
+python -m pip install "taigeotrans[cli]"
+
+taigeotrans transform 121.5654 25.0330
+taigeotrans transform 121.5654 25.0330 --format json
+taigeotrans geocode "臺北市信義區市府路1號"
+taigeotrans batch-geocode addresses.txt -o results.csv
+taigeotrans batch-transform coords.csv -o results.csv
+```
+
+`addresses.txt` 每行一個地址；`coords.csv` 需要包含 `lon,lat` 欄位。執行
+`taigeotrans --help` 查看完整指令。
+
+## 結果
+
+每個操作都回傳 `GeocodeResult`，包含輸入值、WGS84/TWD97 座標、來源與狀態。
+狀態可能是 `success`、`out_of_bounds`、`invalid` 或 `failed`。
+
+## 開發
+
+```bash
+python -m pip install -e ".[dev,all]"
+python -m pytest
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m mypy src
+python -m build
+python -m twine check dist/*
+```
+
+CI 會測試 Python 3.11–3.13。推送 `vMAJOR.MINOR.PATCH` tag 後，release workflow
+會建置套件、發佈到 PyPI，並建立 GitHub Release。
+
+## 授權
+
+MIT License，請參考 [LICENSE](LICENSE)。

taigeotrans-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "taigeotrans"
+version = "0.1.0"
+description = "Taiwan Geospatial Transformer - 台灣地址與座標轉換工具"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "TaiGeotrans Contributors"}
+]
+keywords = ["taiwan", "geospatial", "coordinate", "transform", "TWD97", "WGS84", "geocoding"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyproj>=3.6.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+geocoding = [
+    "httpx>=0.27.0",
+]
+dataframe = [
+    "pandas>=2.0.0",
+]
+progress = [
+    "tqdm>=4.66.0",
+]
+cli = [
+    "httpx>=0.27.0",
+    "pandas>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.0.0",
+    "tqdm>=4.66.0",
+    "typer>=0.12.0",
+]
+all = [
+    "httpx>=0.27.0",
+    "pandas>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "rich>=13.0.0",
+    "tqdm>=4.66.0",
+    "typer>=0.12.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+]
+
+[project.scripts]
+taigeotrans = "taigeotrans.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/KageRyo/TaiGeotrans"
+Repository = "https://github.com/KageRyo/TaiGeotrans"
+Issues = "https://github.com/KageRyo/TaiGeotrans/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+taigeotrans = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.11"
+plugins = ["pydantic.mypy"]
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --cov=taigeotrans --cov-report=term-missing"

taigeotrans-0.1.0/setup.cfg

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

taigeotrans-0.1.0/src/taigeotrans/__init__.py

@@ -0,0 +1,13 @@
+"""
+TaiGeotrans - Taiwan Geospatial Transformer
+台灣地址與座標轉換工具
+
+基於內政地理資訊圖資雲整合服務平台 (TGOS) 實現的輕量級地址、
+經緯度 (WGS84:EPSG:4326) 及 TWD97 (EPSG:3826) 轉換器。
+"""
+
+from taigeotrans.core import TaiGeotrans
+from taigeotrans.models import GeocodeResult, TransformStatus
+
+__version__ = "0.1.0"
+__all__ = ["TaiGeotrans", "GeocodeResult", "TransformStatus"]

taigeotrans-0.1.0/src/taigeotrans/_cli_app.py

@@ -0,0 +1,182 @@
+"""Typer implementation for the optional TaiGeotrans CLI extra."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pandas as pd
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from taigeotrans.core import TaiGeotrans
+from taigeotrans.models import GeocodeResult, TransformStatus
+
+app = typer.Typer(
+    name="taigeotrans",
+    help="TaiGeotrans - Taiwan address and coordinate transformation tool",
+    add_completion=False,
+)
+console = Console()
+
+
+@app.command()
+def geocode(
+    address: str = typer.Argument(..., help="Taiwan address to geocode"),
+    output_format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format: table, json, csv",
+    ),
+) -> None:
+    """Geocode a Taiwan address to TWD97 coordinates."""
+    result = TaiGeotrans().geocode(address)
+    _print_single_result(result, output_format)
+
+
+@app.command()
+def batch_geocode(
+    input_file: Path = typer.Argument(..., help="Input file with one address per line"),
+    output_file: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path",
+    ),
+    output_format: str = typer.Option(
+        "csv",
+        "--format",
+        "-f",
+        help="Output format: csv, json, geojson",
+    ),
+) -> None:
+    """Geocode multiple Taiwan addresses."""
+    if not input_file.exists():
+        raise typer.BadParameter(f"File not found: {input_file}")
+
+    addresses = [
+        line.strip() for line in input_file.read_text(encoding="utf-8").splitlines() if line.strip()
+    ]
+    if not addresses:
+        console.print("[yellow]No valid addresses in file[/yellow]")
+        return
+
+    converter = TaiGeotrans()
+    results = converter.batch_geocode(addresses, show_progress=True)
+    _save_batch_results(results, output_file, output_format, converter)
+
+
+@app.command()
+def transform(
+    lon: float = typer.Argument(..., help="WGS84 longitude"),
+    lat: float = typer.Argument(..., help="WGS84 latitude"),
+    output_format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format: table, json, csv",
+    ),
+) -> None:
+    """Transform WGS84 coordinates to TWD97."""
+    result = TaiGeotrans().transform_lonlat(lon, lat)
+    _print_single_result(result, output_format)
+
+
+@app.command()
+def batch_transform(
+    input_file: Path = typer.Argument(..., help="CSV file with lon and lat columns"),
+    output_file: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file path",
+    ),
+    output_format: str = typer.Option(
+        "csv",
+        "--format",
+        "-f",
+        help="Output format: csv, json, geojson",
+    ),
+) -> None:
+    """Transform multiple WGS84 coordinate pairs."""
+    if not input_file.exists():
+        raise typer.BadParameter(f"File not found: {input_file}")
+
+    df = pd.read_csv(input_file)
+    if "lon" not in df.columns or "lat" not in df.columns:
+        raise typer.BadParameter("CSV file must contain 'lon' and 'lat' columns")
+
+    coords = [(row.lon, row.lat) for row in df.itertuples(index=False)]
+    converter = TaiGeotrans()
+    results = converter.batch_transform_lonlat(coords, show_progress=True)
+    _save_batch_results(results, output_file, output_format, converter)
+
+
+@app.command()
+def version() -> None:
+    """Display version information."""
+    from taigeotrans import __version__
+
+    console.print(f"TaiGeotrans version {__version__}")
+
+
+def _print_single_result(result: GeocodeResult, output_format: str) -> None:
+    if output_format == "json":
+        console.print_json(json.dumps(result.to_dict(), ensure_ascii=False, indent=2))
+    elif output_format == "csv":
+        frame = pd.DataFrame([result.to_dict()])
+        console.print(frame.to_csv(index=False))
+    elif output_format == "table":
+        table = Table(title="Transformation Result")
+        for key, value in result.to_dict().items():
+            table.add_row(key, str(value))
+        console.print(table)
+        _print_status(result)
+    else:
+        raise typer.BadParameter(f"Unsupported output format: {output_format}")
+
+
+def _print_status(result: GeocodeResult) -> None:
+    if result.status == TransformStatus.SUCCESS:
+        console.print("[green]Success[/green]")
+    elif result.status == TransformStatus.OUT_OF_BOUNDS:
+        console.print("[yellow]Warning: coordinates are outside Taiwan mainland bounds[/yellow]")
+    else:
+        console.print(f"[red]Failed: {result.error_message}[/red]")
+
+
+def _save_batch_results(
+    results: list[GeocodeResult],
+    output_file: Path | None,
+    output_format: str,
+    converter: TaiGeotrans,
+) -> None:
+    if output_file is None:
+        for result in results[:10]:
+            console.print_json(json.dumps(result.to_dict(), ensure_ascii=False))
+        return
+
+    if output_format == "json":
+        output_file.write_text(
+            json.dumps([result.to_dict() for result in results], ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    elif output_format == "geojson":
+        output_file.write_text(
+            json.dumps(
+                converter.to_geojson(results, filter_failed=False), ensure_ascii=False, indent=2
+            ),
+            encoding="utf-8",
+        )
+    elif output_format == "csv":
+        pd.DataFrame([result.to_dict() for result in results]).to_csv(
+            output_file,
+            index=False,
+            encoding="utf-8-sig",
+        )
+    else:
+        raise typer.BadParameter(f"Unsupported output format: {output_format}")
+
+    console.print(f"[green]Saved to {output_file} ({output_format})[/green]")

taigeotrans-0.1.0/src/taigeotrans/cli.py

@@ -0,0 +1,36 @@
+"""Command-line entry point with an actionable optional-dependency error."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> int:
+    """Run the Typer CLI and return a process exit code."""
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv()
+        from taigeotrans._cli_app import app
+    except ImportError as exc:
+        print(
+            "The CLI requires optional dependencies. Install them with "
+            "`python -m pip install 'taigeotrans[cli]'`.",
+            file=sys.stderr,
+        )
+        print(f"Missing dependency: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        app()
+    except KeyboardInterrupt:
+        print("\nInterrupted", file=sys.stderr)
+        return 130
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())