shw-geocoder 0.1.0__tar.gz

shw_geocoder-0.1.0/LICENSE

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

shw_geocoder-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include shw_geocoder *.py

shw_geocoder-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: shw-geocoder
+Version: 0.1.0
+Summary: Geocoder client for SHSMI address_search API
+Author: zx
+License: MIT
+Keywords: geocoder,geocoding,address,shsmi,csv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# shw-geocoder
+
+A minimal PyPI package that wraps the SHSMI `address_search` geocoding API. **THIS PACKAGE IS SPECIFIC TO CERTAIN GEOCODING APIS AND IS NOT UNIVERSAL.**
+
+## Install
+
+```bash
+pip install shw-geocoder
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Python API
+
+```python
+from shw_geocoder import geocode
+
+result = geocode("your-address", "geocoder-url")
+print(result["data"][0]["pointX"], result["data"][0]["pointY"])
+```
+
+`geocode(address, base, result_count=3)` returns the raw JSON returned by the
+service. When the address cannot be resolved, the payload's `count` field is `0`
+and `data` is empty.
+
+## CLI
+
+The package exposes a `shw-geocoder` command.
+
+### Single address
+
+```bash
+shw-geocoder --base "geocoder-url" \
+             --address "your-address"
+```
+
+Prints `x, y, accuracy, poi, room_count` to stdout.
+
+### Batch (CSV in -> CSV out + log)
+
+```bash
+shw-geocoder --base "geocoder-url" \
+             --input  addrs.csv \
+             --address-column address \
+             --output out.csv \
+             --log    run.log
+```
+
+- `out.csv` keeps every original column from `addrs.csv` and appends five new
+  columns: `x, y, accuracy, poi, room_count`. Failed rows leave these blank.
+- `run.log` is a plain-text summary containing start/end time, elapsed seconds,
+  total / success / failed counts, and a breakdown by `accuracy` value.
+
+### Arguments
+
+| Flag              | Required | Description                                                  |
+|-------------------|----------|--------------------------------------------------------------|
+| `--base`          | yes      | Full URL of the address_search endpoint                      |
+| `--input`         | batch    | Input CSV path                                               |
+| `--address-column`| batch    | Column name in the input CSV that holds the address          |
+| `--output`        | batch    | Output CSV path                                              |
+| `--log`           | batch    | Log file path                                                |
+| `--encoding`      | no       | Input CSV encoding (e.g. `utf-8`, `gbk`, `gb18030`); default `utf-8` |
+| `--address`       | single   | Single address to geocode (printed to stdout)                |
+
+`--address` and the `--input` group are mutually exclusive.

shw_geocoder-0.1.0/README.md

@@ -0,0 +1,70 @@
+# shw-geocoder
+
+A minimal PyPI package that wraps the SHSMI `address_search` geocoding API. **THIS PACKAGE IS SPECIFIC TO CERTAIN GEOCODING APIS AND IS NOT UNIVERSAL.**
+
+## Install
+
+```bash
+pip install shw-geocoder
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Python API
+
+```python
+from shw_geocoder import geocode
+
+result = geocode("your-address", "geocoder-url")
+print(result["data"][0]["pointX"], result["data"][0]["pointY"])
+```
+
+`geocode(address, base, result_count=3)` returns the raw JSON returned by the
+service. When the address cannot be resolved, the payload's `count` field is `0`
+and `data` is empty.
+
+## CLI
+
+The package exposes a `shw-geocoder` command.
+
+### Single address
+
+```bash
+shw-geocoder --base "geocoder-url" \
+             --address "your-address"
+```
+
+Prints `x, y, accuracy, poi, room_count` to stdout.
+
+### Batch (CSV in -> CSV out + log)
+
+```bash
+shw-geocoder --base "geocoder-url" \
+             --input  addrs.csv \
+             --address-column address \
+             --output out.csv \
+             --log    run.log
+```
+
+- `out.csv` keeps every original column from `addrs.csv` and appends five new
+  columns: `x, y, accuracy, poi, room_count`. Failed rows leave these blank.
+- `run.log` is a plain-text summary containing start/end time, elapsed seconds,
+  total / success / failed counts, and a breakdown by `accuracy` value.
+
+### Arguments
+
+| Flag              | Required | Description                                                  |
+|-------------------|----------|--------------------------------------------------------------|
+| `--base`          | yes      | Full URL of the address_search endpoint                      |
+| `--input`         | batch    | Input CSV path                                               |
+| `--address-column`| batch    | Column name in the input CSV that holds the address          |
+| `--output`        | batch    | Output CSV path                                              |
+| `--log`           | batch    | Log file path                                                |
+| `--encoding`      | no       | Input CSV encoding (e.g. `utf-8`, `gbk`, `gb18030`); default `utf-8` |
+| `--address`       | single   | Single address to geocode (printed to stdout)                |
+
+`--address` and the `--input` group are mutually exclusive.

shw_geocoder-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shw-geocoder"
+version = "0.1.0"
+description = "Geocoder client for SHSMI address_search API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "zx" }]
+keywords = ["geocoder", "geocoding", "address", "shsmi", "csv"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Utilities",
+]
+dependencies = ["requests"]
+
+[project.scripts]
+shw-geocoder = "shw_geocoder.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["shw_geocoder*"]
+exclude = ["tests*"]

shw_geocoder-0.1.0/setup.cfg

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

shw_geocoder-0.1.0/shw_geocoder/__init__.py

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

shw_geocoder-0.1.0/shw_geocoder/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

shw_geocoder-0.1.0/shw_geocoder/cli.py

@@ -0,0 +1,175 @@
+"""Command-line entry point for shw-geocoder."""
+
+import argparse
+import csv
+import sys
+import time
+from collections import Counter
+from datetime import datetime
+
+from .geocoder import geocode
+
+NEW_COLUMNS = ["x", "y", "accuracy", "poi", "room_count"]
+
+
+def _extract(result: dict):
+    """Return (x, y, accuracy, poi, room_count) from an API response, or None."""
+    if not result or result.get("count", 0) <= 0:
+        return None
+    data = result.get("data") or []
+    if not data:
+        return None
+    d = data[0]
+    return (
+        d.get("pointX"),
+        d.get("pointY"),
+        d.get("resultAccuracy"),
+        d.get("poiString"),
+        d.get("roomCount"),
+    )
+
+
+def _progress(done: int, total: int):
+    if total <= 0:
+        return
+    pct = done * 100 // total
+    sys.stderr.write(f"\r[{done}/{total}] {pct}%")
+    sys.stderr.flush()
+    if done == total:
+        sys.stderr.write("\n")
+
+
+def _run_single(address: str, base: str) -> int:
+    try:
+        result = geocode(address, base)
+    except Exception as exc:  # noqa: BLE001
+        print(f"geocode failed: {exc}", file=sys.stderr)
+        return 1
+    fields = _extract(result)
+    if fields is None:
+        print("no result", file=sys.stderr)
+        return 1
+    print("x={}, y={}, accuracy={}, poi={}, room_count={}".format(*fields))
+    return 0
+
+
+def _run_batch(args) -> int:
+    start = datetime.now()
+    start_ts = time.time()
+
+    encoding = args.encoding
+    print(f"using encoding: {encoding}", file=sys.stderr)
+    try:
+        with open(args.input, newline="", encoding=encoding) as f:
+            reader = csv.DictReader(f)
+            fieldnames = list(reader.fieldnames or [])
+            rows = list(reader)
+    except UnicodeDecodeError as exc:
+        print(
+            f"error: failed to decode '{args.input}' as '{encoding}' ({exc}). "
+            f"The file's actual encoding does not match --encoding. "
+            f"Re-run with the correct --encoding (e.g. utf-8, gbk, gb18030).",
+            file=sys.stderr,
+        )
+        return 2
+
+    if args.address_column not in fieldnames:
+        print(
+            f"error: address column '{args.address_column}' not found in "
+            f"input CSV (columns: {fieldnames})",
+            file=sys.stderr,
+        )
+        return 2
+
+    total = len(rows)
+    success = 0
+    fail = 0
+    acc_counter = Counter()
+
+    out_fields = fieldnames + [c for c in NEW_COLUMNS if c not in fieldnames]
+
+    with open(args.output, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=out_fields)
+        writer.writeheader()
+        for i, row in enumerate(rows, 1):
+            address = row.get(args.address_column) or ""
+            try:
+                result = geocode(address, args.base)
+            except Exception:  # noqa: BLE001
+                result = None
+            fields = _extract(result)
+            if fields is None:
+                fail += 1
+                acc_counter["<nan>"] += 1
+            else:
+                success += 1
+                x, y, acc, poi, room = fields
+                row["x"] = x
+                row["y"] = y
+                row["accuracy"] = acc
+                row["poi"] = poi
+                row["room_count"] = room
+                acc_counter[str(acc)] += 1
+            writer.writerow(row)
+            _progress(i, total)
+
+    end = datetime.now()
+    elapsed = time.time() - start_ts
+    _write_log(args.log, start, end, elapsed, total, success, fail, acc_counter)
+    return 0
+
+
+def _write_log(path, start, end, elapsed, total, success, fail, acc_counter):
+    lines = [
+        "shw-geocoder run summary",
+        "========================",
+        f"Start:    {start.strftime('%Y-%m-%d %H:%M:%S')}",
+        f"End:      {end.strftime('%Y-%m-%d %H:%M:%S')}",
+        f"Elapsed:  {elapsed:.1f} s",
+        f"Total:    {total}",
+        f"Success:  {success}",
+        f"Failed:   {fail}",
+        "Accuracy breakdown:",
+    ]
+    for acc, cnt in sorted(acc_counter.items()):
+        lines.append(f"  {acc} : {cnt}")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="shw-geocoder", description=__doc__)
+    p.add_argument("--base", required=True, help="Full URL of the address_search endpoint")
+
+    group = p.add_mutually_exclusive_group(required=True)
+    group.add_argument("--input", help="Input CSV path (batch mode)")
+    group.add_argument("--address", help="Single address to geocode")
+
+    p.add_argument("--address-column", help="Column name holding the address in the input CSV")
+    p.add_argument("--encoding", default="utf-8", help="Input CSV encoding (e.g. utf-8, gbk, gb18030); default utf-8")
+    p.add_argument("--output", help="Output CSV path (batch mode)")
+    p.add_argument("--log", help="Log file path (batch mode)")
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.input:
+        missing = []
+        if not args.address_column:
+            missing.append("--address-column")
+        if not args.output:
+            missing.append("--output")
+        if not args.log:
+            missing.append("--log")
+        if missing:
+            print(f"error: batch mode requires {' '.join(missing)}", file=sys.stderr)
+            return 2
+        return _run_batch(args)
+
+    return _run_single(args.address, args.base)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shw_geocoder-0.1.0/shw_geocoder/geocoder.py

@@ -0,0 +1,30 @@
+"""Thin client around the SHSMI address_search endpoint."""
+
+import requests
+
+
+def geocode(address: str, base: str, result_count: int = 3, timeout: float = 10.0) -> dict:
+    """Geocode a single address.
+
+    Parameters
+    ----------
+    address:
+        The address text to search for.
+    base:
+        Full URL of the `address_search?parameters` endpoint.
+    result_count:
+        How many candidate results to request from the service.
+    timeout:
+        Per-request timeout in seconds.
+
+    Returns
+    -------
+    dict
+        The raw JSON payload returned by the service. When the address cannot
+        be resolved, the payload's ``count`` field is ``0`` and ``data`` is
+        empty.
+    """
+    params = {"search_word": address, "result_count": result_count}
+    resp = requests.get(base, params=params, timeout=timeout)
+    resp.raise_for_status()
+    return resp.json()

shw_geocoder-0.1.0/shw_geocoder.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: shw-geocoder
+Version: 0.1.0
+Summary: Geocoder client for SHSMI address_search API
+Author: zx
+License: MIT
+Keywords: geocoder,geocoding,address,shsmi,csv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# shw-geocoder
+
+A minimal PyPI package that wraps the SHSMI `address_search` geocoding API. **THIS PACKAGE IS SPECIFIC TO CERTAIN GEOCODING APIS AND IS NOT UNIVERSAL.**
+
+## Install
+
+```bash
+pip install shw-geocoder
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Python API
+
+```python
+from shw_geocoder import geocode
+
+result = geocode("your-address", "geocoder-url")
+print(result["data"][0]["pointX"], result["data"][0]["pointY"])
+```
+
+`geocode(address, base, result_count=3)` returns the raw JSON returned by the
+service. When the address cannot be resolved, the payload's `count` field is `0`
+and `data` is empty.
+
+## CLI
+
+The package exposes a `shw-geocoder` command.
+
+### Single address
+
+```bash
+shw-geocoder --base "geocoder-url" \
+             --address "your-address"
+```
+
+Prints `x, y, accuracy, poi, room_count` to stdout.
+
+### Batch (CSV in -> CSV out + log)
+
+```bash
+shw-geocoder --base "geocoder-url" \
+             --input  addrs.csv \
+             --address-column address \
+             --output out.csv \
+             --log    run.log
+```
+
+- `out.csv` keeps every original column from `addrs.csv` and appends five new
+  columns: `x, y, accuracy, poi, room_count`. Failed rows leave these blank.
+- `run.log` is a plain-text summary containing start/end time, elapsed seconds,
+  total / success / failed counts, and a breakdown by `accuracy` value.
+
+### Arguments
+
+| Flag              | Required | Description                                                  |
+|-------------------|----------|--------------------------------------------------------------|
+| `--base`          | yes      | Full URL of the address_search endpoint                      |
+| `--input`         | batch    | Input CSV path                                               |
+| `--address-column`| batch    | Column name in the input CSV that holds the address          |
+| `--output`        | batch    | Output CSV path                                              |
+| `--log`           | batch    | Log file path                                                |
+| `--encoding`      | no       | Input CSV encoding (e.g. `utf-8`, `gbk`, `gb18030`); default `utf-8` |
+| `--address`       | single   | Single address to geocode (printed to stdout)                |
+
+`--address` and the `--input` group are mutually exclusive.

shw_geocoder-0.1.0/shw_geocoder.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+shw_geocoder/__init__.py
+shw_geocoder/__main__.py
+shw_geocoder/cli.py
+shw_geocoder/geocoder.py
+shw_geocoder.egg-info/PKG-INFO
+shw_geocoder.egg-info/SOURCES.txt
+shw_geocoder.egg-info/dependency_links.txt
+shw_geocoder.egg-info/entry_points.txt
+shw_geocoder.egg-info/requires.txt
+shw_geocoder.egg-info/top_level.txt

shw_geocoder-0.1.0/shw_geocoder.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shw_geocoder-0.1.0/shw_geocoder.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shw-geocoder = shw_geocoder.cli:main

shw_geocoder-0.1.0/shw_geocoder.egg-info/requires.txt

@@ -0,0 +1 @@
+requests

shw_geocoder-0.1.0/shw_geocoder.egg-info/top_level.txt

@@ -0,0 +1 @@
+shw_geocoder