rsplot 0.3.0__tar.gz → 0.3.1.dev3__tar.gz

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/.gitignore

@@ -280,7 +280,4 @@ tags
 logs/
 .vscode/
 .claude
-docs/
 tests/
-skills/
-tools/

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: rsplot
-Version: 0.3.0
+Version: 0.3.1.dev3
 Summary: CLI tool for plotting Remote Sensing data, designed for Agent.
 Project-URL: Repository, https://git.lug.ustc.edu.cn/yaoyhu/rsplot
 Project-URL: GitHub, https://github.com/yaoyhu/rsplot
@@ -247,6 +247,19 @@ uv add rsplot
 uv run rsplot --help
 ```
 
+### Development releases
+
+Every push to `main` publishes a PEP 440 development release such as
+`0.3.1.dev4`. Stable installs continue to ignore these releases. To follow the
+latest development build, opt in once:
+
+```bash
+uv tool install rsplot --prerelease allow
+uv tool upgrade rsplot
+```
+
+The prerelease setting is retained by later `uv tool upgrade` commands.
+
 For local development:
 
 ```bash
@@ -284,6 +297,12 @@ era5 = "/path/to/era5"
 forecast = "/path/to/forecast"
 reconstruct = "/path/to/reconstruct"
 
+# Optional lower-level boundary override for a direct-administered city.
+# [subdivision_overrides."中山市"]
+# path = "/path/to/中山市镇街界线.shp"
+# name_field = "镇街名称"
+# level = "township"
+
 # Optional satellite basemap key. Leave commented unless you have a real key.
 # [tianditu]
 # api_key = "your-real-key"
@@ -316,6 +335,11 @@ Command-line directory options, such as `--data-dir`, take precedence for the
 command being run. If no TianDiTu API key is configured, use `--basemap none`
 to avoid requesting satellite tiles.
 
+City subdivision overrides replace the county layer only for the configured
+city. Their source CRS is converted to the CRS of the standard city boundary.
+This lets direct-administered towns or streets appear in maps and spatial
+summaries, and makes qualified inputs such as `中山/板芙` resolvable.
+
 ## Usage
 
 The examples below assume data paths are configured and readable.
@@ -415,3 +439,39 @@ output resolution, regional statistics, administrative summaries, and hotspots.
 ## License
 
 This project is distributed under the license in `LICENSE`.
+
+## Publishing
+
+The package version is derived from Git by `hatch-vcs`; do not add a static
+`project.version` or make version-bump commits. The latest `vX.Y.Z` tag is the
+stable version. Commits after it build as the next patch development series:
+
+```text
+v0.3.0           -> 0.3.0
+first commit     -> 0.3.1.dev1
+second commit    -> 0.3.1.dev2
+v0.3.1           -> 0.3.1
+```
+
+GitHub Actions publishes every `main` push through the `pypi-dev` environment
+and every `v*` tag through `pypi`. Configure two PyPI Trusted Publishers with
+the same owner, repository, and workflow, differing only by environment:
+
+```text
+Owner: yaoyhu
+Repository: rsplot
+Workflow: publish.yml
+Environment: pypi-dev
+Environment: pypi
+```
+
+Leave `pypi-dev` automatic for continuous development uploads. Protect the
+`pypi` GitHub environment with required reviewers so stable releases need an
+explicit approval.
+
+To make a stable release after the desired commit is on GitHub:
+
+```bash
+git tag -a v0.3.1 -m v0.3.1
+git push github v0.3.1
+```

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/README.md

@@ -20,6 +20,19 @@ uv add rsplot
 uv run rsplot --help
 ```
 
+### Development releases
+
+Every push to `main` publishes a PEP 440 development release such as
+`0.3.1.dev4`. Stable installs continue to ignore these releases. To follow the
+latest development build, opt in once:
+
+```bash
+uv tool install rsplot --prerelease allow
+uv tool upgrade rsplot
+```
+
+The prerelease setting is retained by later `uv tool upgrade` commands.
+
 For local development:
 
 ```bash
@@ -57,6 +70,12 @@ era5 = "/path/to/era5"
 forecast = "/path/to/forecast"
 reconstruct = "/path/to/reconstruct"
 
+# Optional lower-level boundary override for a direct-administered city.
+# [subdivision_overrides."中山市"]
+# path = "/path/to/中山市镇街界线.shp"
+# name_field = "镇街名称"
+# level = "township"
+
 # Optional satellite basemap key. Leave commented unless you have a real key.
 # [tianditu]
 # api_key = "your-real-key"
@@ -89,6 +108,11 @@ Command-line directory options, such as `--data-dir`, take precedence for the
 command being run. If no TianDiTu API key is configured, use `--basemap none`
 to avoid requesting satellite tiles.
 
+City subdivision overrides replace the county layer only for the configured
+city. Their source CRS is converted to the CRS of the standard city boundary.
+This lets direct-administered towns or streets appear in maps and spatial
+summaries, and makes qualified inputs such as `中山/板芙` resolvable.
+
 ## Usage
 
 The examples below assume data paths are configured and readable.
@@ -188,3 +212,39 @@ output resolution, regional statistics, administrative summaries, and hotspots.
 ## License
 
 This project is distributed under the license in `LICENSE`.
+
+## Publishing
+
+The package version is derived from Git by `hatch-vcs`; do not add a static
+`project.version` or make version-bump commits. The latest `vX.Y.Z` tag is the
+stable version. Commits after it build as the next patch development series:
+
+```text
+v0.3.0           -> 0.3.0
+first commit     -> 0.3.1.dev1
+second commit    -> 0.3.1.dev2
+v0.3.1           -> 0.3.1
+```
+
+GitHub Actions publishes every `main` push through the `pypi-dev` environment
+and every `v*` tag through `pypi`. Configure two PyPI Trusted Publishers with
+the same owner, repository, and workflow, differing only by environment:
+
+```text
+Owner: yaoyhu
+Repository: rsplot
+Workflow: publish.yml
+Environment: pypi-dev
+Environment: pypi
+```
+
+Leave `pypi-dev` automatic for continuous development uploads. Protect the
+`pypi` GitHub environment with required reviewers so stable releases need an
+explicit approval.
+
+To make a stable release after the desired commit is on GitHub:
+
+```bash
+git tag -a v0.3.1 -m v0.3.1
+git push github v0.3.1
+```

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rsplot"
-version = "0.3.0"
+dynamic = ["version"]
 description = "CLI tool for plotting Remote Sensing data, designed for Agent."
 authors = [
     { name = "Yaoyao Hu", email = "yaoyhu@mail.ustc.edu.cn" },
@@ -37,9 +37,16 @@ GitHub = "https://github.com/yaoyhu/rsplot"
 rsplot = "rsplot.__main__:app"
 
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "hatch-vcs>=0.5,<0.6"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+version_scheme = "guess-next-dev"
+local_scheme = "no-local-version"
+
 [tool.hatch.build.targets.sdist]
 only-include = ["src/rsplot"]
 
@@ -58,9 +65,3 @@ ignore = ["E501", "RUF001", "RUF002"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-
-[dependency-groups]
-dev = [
-    "pytest>=9.1.1",
-    "ruff>=0.15.21",
-]

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/src/rsplot/config.py

@@ -62,6 +62,15 @@ class LevelParams:
     zoom: int  # TianDiTu tile zoom level
 
 
+@dataclass(frozen=True)
+class SubdivisionSource:
+    """External boundary source replacing a city's county-level layer."""
+
+    path: str
+    name_field: str = "name"
+    level: str = "township"
+
+
 LEVEL_DEFAULTS: dict[str, LevelParams] = {
     "country": LevelParams(
         res=0.1,
@@ -166,6 +175,9 @@ class AppConfig:
     hcho_cmap_file: str | None = DEFAULT_HCHO_CMAP_FILE
     tianditu_key: str | None = DEFAULT_TIANDITU_KEY
     config_files: list[str] = field(default_factory=list)
+    subdivision_overrides: dict[str, SubdivisionSource] = field(
+        default_factory=dict
+    )
 
     # plotting defaults
     dpi: int = 300
@@ -269,6 +281,39 @@ class AppConfig:
         for name, provinces in kr.items():
             self.key_regions[name] = provinces
 
+        overrides = data.get("subdivision_overrides", {})
+        if not isinstance(overrides, dict):
+            raise ValueError("[subdivision_overrides] 必须是 TOML 表。")
+        for parent, raw_source in overrides.items():
+            if isinstance(raw_source, str):
+                source = SubdivisionSource(path=_normalize_path(raw_source))
+            elif isinstance(raw_source, dict):
+                path = raw_source.get("path")
+                if not path:
+                    raise ValueError(
+                        f"subdivision_overrides.{parent} 缺少 path。"
+                    )
+                name_field = str(raw_source.get("name_field", "name")).strip()
+                level = str(raw_source.get("level", "township")).strip()
+                if not name_field:
+                    raise ValueError(
+                        f"subdivision_overrides.{parent}.name_field 不能为空。"
+                    )
+                if not level:
+                    raise ValueError(
+                        f"subdivision_overrides.{parent}.level 不能为空。"
+                    )
+                source = SubdivisionSource(
+                    path=_normalize_path(path),
+                    name_field=name_field,
+                    level=level,
+                )
+            else:
+                raise ValueError(
+                    f"subdivision_overrides.{parent} 必须是路径或 TOML 表。"
+                )
+            self.subdivision_overrides[str(parent)] = source
+
 
 def _config_paths() -> list[Path]:
     """Return config files to load in priority order."""

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/src/rsplot/geo/boundaries.py

@@ -15,7 +15,12 @@ import geopandas as gpd
 import pandas as pd
 from shapely.ops import unary_union
 
-from rsplot.config import LEVEL_DEFAULTS, AppConfig, LevelParams
+from rsplot.config import (
+    LEVEL_DEFAULTS,
+    AppConfig,
+    LevelParams,
+    SubdivisionSource,
+)
 
 if TYPE_CHECKING:
     from shapely.geometry.base import BaseGeometry
@@ -23,7 +28,7 @@ if TYPE_CHECKING:
 
 # Suffixes to strip for fuzzy matching
 _SUFFIXES = re.compile(
-    r"(省|市|区|县|自治区|自治州|自治县|地区|盟|林区|特别行政区)$"
+    r"(特别行政区|自治区|自治州|自治县|街道|地区|林区|省|市|区|县|盟|镇|乡)$"
 )
 
 NAME_FIELD = "name"
@@ -51,6 +56,8 @@ class RegionInfo:
         None  # finer sub-divisions (counties in province view)
     )
     sub_name_field: str = NAME_FIELD
+    administrative_level: str | None = None
+    subdivision_level: str | None = None
 
 
 def _strip_suffix(name: str) -> str:
@@ -67,7 +74,7 @@ def _fuzzy_match(
         return exact
 
     # with common suffixes appended
-    for suffix in ["省", "市", "区", "县", "自治区"]:
+    for suffix in ["省", "市", "区", "县", "自治区", "镇", "乡", "街道"]:
         padded = candidates[candidates[NAME_FIELD] == query + suffix]
         if len(padded) > 0:
             return padded
@@ -99,6 +106,55 @@ def _load_county(geojson_dir: str) -> gpd.GeoDataFrame:
     return gpd.read_file(f"{geojson_dir}/中国_县.geojson")
 
 
+@lru_cache(maxsize=16)
+def _load_subdivision_source(
+    path: str,
+    name_field: str,
+    target_crs: str,
+) -> gpd.GeoDataFrame:
+    """Load and normalize a configured city subdivision boundary file."""
+    try:
+        source = gpd.read_file(path)
+    except Exception as exc:
+        raise ValueError(f"无法读取下级行政区边界文件 '{path}': {exc}") from exc
+
+    if name_field not in source.columns:
+        available = ", ".join(str(column) for column in source.columns)
+        raise ValueError(
+            f"下级行政区边界文件 '{path}' 缺少名称字段 "
+            f"'{name_field}'。可用字段: {available}"
+        )
+    if source.crs is None:
+        raise ValueError(f"下级行政区边界文件 '{path}' 缺少坐标系信息。")
+
+    try:
+        source = source.to_crs(target_crs)
+    except Exception as exc:
+        raise ValueError(
+            f"下级行政区边界文件 '{path}' 无法转换到 {target_crs}: {exc}"
+        ) from exc
+
+    normalized = source[[name_field, "geometry"]].rename(
+        columns={name_field: NAME_FIELD}
+    )
+    normalized[NAME_FIELD] = normalized[NAME_FIELD].astype("string").str.strip()
+    normalized = normalized[
+        normalized[NAME_FIELD].notna()
+        & normalized[NAME_FIELD].ne("")
+        & normalized.geometry.notna()
+        & ~normalized.geometry.is_empty
+    ].copy()
+    if len(normalized) == 0:
+        raise ValueError(f"下级行政区边界文件 '{path}' 没有可用要素。")
+    invalid = ~normalized.geometry.is_valid
+    if invalid.any():
+        raise ValueError(
+            f"下级行政区边界文件 '{path}' 包含 "
+            f"{int(invalid.sum())} 个无效几何。"
+        )
+    return normalized
+
+
 def load_province_boundaries(geojson_dir: str) -> gpd.GeoDataFrame:
     """Return the cached province boundary dataset."""
     return _load_province(geojson_dir)
@@ -114,6 +170,49 @@ def load_county_boundaries(geojson_dir: str) -> gpd.GeoDataFrame:
     return _load_county(geojson_dir)
 
 
+def _find_subdivision_source(
+    city_name: str,
+    cfg: AppConfig,
+) -> SubdivisionSource | None:
+    """Match a configured override by canonical or suffix-free city name."""
+    if city_name in cfg.subdivision_overrides:
+        return cfg.subdivision_overrides[city_name]
+    stripped = _strip_suffix(city_name)
+    for configured_name, source in cfg.subdivision_overrides.items():
+        if _strip_suffix(configured_name) == stripped:
+            return source
+    return None
+
+
+def _city_subdivisions(
+    city_name: str,
+    city_geometry: BaseGeometry,
+    city_crs: object,
+    cfg: AppConfig,
+) -> tuple[gpd.GeoDataFrame, str] | None:
+    """Return a configured city-specific subdivision layer when present."""
+    source = _find_subdivision_source(city_name, cfg)
+    if source is None:
+        return None
+    if city_crs is None:
+        raise ValueError("城市边界数据缺少坐标系，无法加载下级行政区覆盖。")
+
+    subdivisions = _load_subdivision_source(
+        source.path,
+        source.name_field,
+        str(city_crs),
+    )
+    subdivisions = subdivisions[
+        subdivisions.geometry.intersects(city_geometry.buffer(0.01))
+    ].copy()
+    if len(subdivisions) == 0:
+        raise ValueError(
+            f"为 {city_name} 配置的边界文件与城市边界没有空间交集: "
+            f"{source.path}"
+        )
+    return subdivisions, source.level
+
+
 # ---------------------------------------------------------------------------
 # Core resolver
 # ---------------------------------------------------------------------------
@@ -142,6 +241,7 @@ def _resolve_country(
 
 def _resolve_qualified_county(
     name: str,
+    cfg: AppConfig,
     cities: gpd.GeoDataFrame,
     counties: gpd.GeoDataFrame,
 ) -> RegionInfo | None:
@@ -151,16 +251,27 @@ def _resolve_qualified_county(
     city_match = _fuzzy_match(city_name, cities)
     if city_match is None:
         raise ValueError(f"无法识别城市 '{city_name}'。")
+    canonical_city_name = city_match.iloc[0][NAME_FIELD]
     city_geometry = unary_union(city_match.geometry)
-    sub_counties = counties[
-        counties.geometry.within(city_geometry.buffer(0.01))
-    ]
+    configured = _city_subdivisions(
+        canonical_city_name,
+        city_geometry,
+        cities.crs,
+        cfg,
+    )
+    if configured is None:
+        sub_counties = counties[
+            counties.geometry.within(city_geometry.buffer(0.01))
+        ]
+        administrative_level = "county"
+    else:
+        sub_counties, administrative_level = configured
     county_match = _fuzzy_match(county_name, sub_counties)
     if county_match is None:
         available = ", ".join(sub_counties[NAME_FIELD].tolist())
         raise ValueError(
-            f"在 {city_match.iloc[0][NAME_FIELD]} 下未找到 '{county_name}'。"
-            f"\n可用县区: {available}"
+            f"在 {canonical_city_name} 下未找到 '{county_name}'。"
+            f"\n可用下级行政区: {available}"
         )
     return _build_info(
         name=county_match.iloc[0][NAME_FIELD],
@@ -168,6 +279,7 @@ def _resolve_qualified_county(
         geometry=unary_union(county_match.geometry),
         main_gdf=county_match,
         sub_gdf=None,
+        administrative_level=administrative_level,
     )
 
 
@@ -241,20 +353,30 @@ def _resolve_province(
 
 def _resolve_city(
     name: str,
+    cfg: AppConfig,
     cities: gpd.GeoDataFrame,
     counties: gpd.GeoDataFrame,
 ) -> RegionInfo | None:
     match = _fuzzy_match(name, cities)
     if match is None:
         return None
+    city_name = match.iloc[0][NAME_FIELD]
     geometry = unary_union(match.geometry)
-    sub_counties = counties[counties.geometry.within(geometry.buffer(0.01))]
+    configured = _city_subdivisions(city_name, geometry, cities.crs, cfg)
+    if configured is None:
+        sub_counties = counties[
+            counties.geometry.within(geometry.buffer(0.01))
+        ]
+        subdivision_level = None
+    else:
+        sub_counties, subdivision_level = configured
     return _build_info(
-        name=match.iloc[0][NAME_FIELD],
+        name=city_name,
         level="city",
         geometry=geometry,
         main_gdf=match,
         sub_gdf=sub_counties,
+        subdivision_level=subdivision_level,
     )
 
 
@@ -277,7 +399,12 @@ def resolve_region(
     if "/" in name:
         cities = load_city_boundaries(geojson_dir)
         counties = load_county_boundaries(geojson_dir)
-        qualified_county = _resolve_qualified_county(name, cities, counties)
+        qualified_county = _resolve_qualified_county(
+            name,
+            cfg,
+            cities,
+            counties,
+        )
         if qualified_county is not None:
             return qualified_county
 
@@ -299,13 +426,14 @@ def resolve_region(
     if level_override is None or level_override == "city":
         cities = load_city_boundaries(geojson_dir)
         counties = load_county_boundaries(geojson_dir)
-        city = _resolve_city(name, cities, counties)
+        city = _resolve_city(name, cfg, cities, counties)
         if city is not None:
             return city
 
     if level_override == "county":
         raise ValueError(
-            "县/区级别需要指定所属城市，格式: 城市/县区，如 合肥/蜀山、成都/高新"
+            "县区/镇街级别需要指定所属城市，格式: 城市/下级行政区，"
+            "如 合肥/蜀山、中山/板芙"
         )
 
     raise ValueError(
@@ -321,6 +449,8 @@ def _build_info(
     main_gdf: gpd.GeoDataFrame | None,
     sub_gdf: gpd.GeoDataFrame | None,
     detail_gdf: gpd.GeoDataFrame | None = None,
+    administrative_level: str | None = None,
+    subdivision_level: str | None = None,
 ) -> RegionInfo:
     bounds = geometry.bounds  # (minx, miny, maxx, maxy)
     params = LEVEL_DEFAULTS[level]
@@ -339,4 +469,6 @@ def _build_info(
         main_boundary_gdf=main_gdf,
         sub_boundary_gdf=sub_gdf,
         detail_boundary_gdf=detail_gdf,
+        administrative_level=administrative_level,
+        subdivision_level=subdivision_level,
     )

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/src/rsplot/result_builders/common.py

@@ -16,11 +16,16 @@ if TYPE_CHECKING:
 
 def serialize_region(region: RegionInfo) -> dict[str, Any]:
     """Serialize a region identically across every result type."""
-    return {
+    result = {
         "name": region.name,
         "level": region.level,
         "extent": [round(value, 3) for value in region.extent],
     }
+    if region.administrative_level not in (None, region.level):
+        result["administrative_level"] = region.administrative_level
+    if region.subdivision_level is not None:
+        result["subdivision_level"] = region.subdivision_level
+    return result
 
 
 def grid_per_admin_stats(

{rsplot-0.3.0 → rsplot-0.3.1.dev3}/src/rsplot/result_builders/station.py

@@ -57,6 +57,8 @@ def aqi_distribution(values: np.ndarray) -> dict[str, int]:
 
 
 def station_admin_level(region: RegionInfo) -> str | None:
+    if region.subdivision_level is not None:
+        return region.subdivision_level
     if region.level == "country":
         return "province"
     if region.level == "key_region":