Metadata-Version: 2.5
Name: spatialharness
Version: 0.2.0
Summary: A lightweight plugin-based toolkit for GIS and urban science: core does plugin management and data contracts only, all functionality ships as plugins.
Project-URL: Homepage, https://github.com/GIStudio/SpatialUtils
Project-URL: Issues, https://github.com/GIStudio/SpatialUtils/issues
Author-email: Shiqi Wang <qtec@outlook.com>
License: MIT License
        
        Copyright (c) 2026 GIStudio / Shiqi Wang
        
        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.
License-File: LICENSE
Keywords: GIS,accessibility,plugin,street-view,urban-science
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.8
Provides-Extra: access
Requires-Dist: spatialaccessibility; extra == 'access'
Provides-Extra: all
Requires-Dist: spatialaccessibility; extra == 'all'
Requires-Dist: streetsolartrack; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Provides-Extra: street
Requires-Dist: streetsolartrack; extra == 'street'
Description-Content-Type: text/markdown

# SpatialHarness

**插件式的 GIS / 城市科学工具库** —— 轻量核心只做两件事：**插件管理**与**数据契约**；所有功能由插件提供，现有库不重写、以适配器方式接入。

> 核心理念：像 pytest 收集测试、napari 收集插件一样收集城市科学工具。
> 核心零第三方依赖（纯标准库），数据契约通过 duck-typing 校验，不强制 pandas/geopandas。

## 安装

```bash
pip install spatialharness                # 核心
pip install spatialharness[access]        # + SpatialAccessibility 适配器后端
pip install spatialharness[street]        # + StreetSolarTrack 适配器后端
pip install spatialharness[all]           # 全部后端
```

## 快速开始

### Python API

```python
from spatialharness import PluginManager

mgr = PluginManager()
print(mgr.list_plugins())
# {'spatial_accessibility': ..., 'street_solar': ...}

# 街景元数据（包装 StreetSolarTrack，不改变原库用法）
result = mgr.run("street_solar", folder="data/street_views", report=True)
result["metadata"].head()

# 空间可达性（包装 SpatialAccessibility 0.0.13）
result = mgr.run("spatial_accessibility", od_matrix_df, AccModel="Gravity", beta=1)
result["accessibility"].head()
```

### CLI

```bash
spatialharness list                                   # 列出插件
spatialharness show street_solar                      # 查看数据契约
spatialharness run street_solar --param folder=./photos --param report=true
```

### 管理插件

```python
mgr.disable("street_solar")   # 禁用
mgr.enable("street_solar")    # 启用
mgr.source_of("street_solar") # 来源: builtin / entrypoint:xxx / local:path
```

## AI 互操作（MCP）

```bash
spatialharness mcp
```

以 **MCP stdio 服务器**运行：全部已启用插件（含输入/输出契约）自动生成工具清单，
AI 客户端（Claude Code / Codex / DeepSeek Harness 等）可直接调用。零依赖实现
（newline-delimited JSON-RPC）。数据支持 list[记录] 与 GeoJSON
FeatureCollection 输入，GeoDataFrame 结果自动输出为 GeoJSON——与
[SpatialHarness Web 工作台](https://github.com/GIStudio/SpatialHarness)（npm
`spatial-harness`）的数据格式原生对齐，AI 可编排两端："Python 算可达性 → Web
端分级设色出图"。

## 本地 HTTP 桥（供 Web 工作台调用）

```bash
spatialharness serve                 # 默认 http://127.0.0.1:8765
```

| 端点 | 说明 |
|---|---|
| `GET /health` | 存活检查（含版本） |
| `GET /plugins` | 插件 manifest 列表（含输入/输出契约） |
| `POST /run/<plugin>` | `{"data": <JSON>, "params": {...}}` → 插件结果 |

响应带 CORS 头，`localhost:5173` 开发服与线上页均可直连；数据转换规则同上。
姊妹项目 [SpatialHarness Web 工作台](https://github.com/GIStudio/SpatialHarness)
的"Python 分析"面板即通过此桥调用本包插件。

## 架构

```
┌─────────────────────────────────────────────┐
│  接口层   Python API  ·  CLI                 │
├─────────────────────────────────────────────┤
│  核心层   PluginManager · Plugin 协议        │
│           数据契约 (duck-typing 校验)         │
│           —— 纯标准库，零第三方依赖 ——         │
├──────────┬──────────────┬───────────────────┤
│ 插件层    │ builtin 适配器│ entry points 插件 │ 本地 plugins/ 目录
│          │ (包装现有库)  │ (第三方 pip 包)    │ (实验性脚本)
└──────────┴──────────────┴───────────────────┘
```

## 数据契约

插件声明输入/输出契约，核心在运行前后校验（duck-typing，不强制依赖）：

| 类型            | 判定                                        |
|-----------------|---------------------------------------------|
| `table`         | 有 `columns` + `iloc`（pandas DataFrame 满足）|
| `geodataframe`  | table 且有 `geometry`（geopandas）           |
| `series`        | 有 `iloc` 无 `columns`                       |
| `path`          | `str` / `os.PathLike`                        |
| `any`           | 不检查                                       |

## 编写插件

### 方式一：类（推荐）

```python
from spatialharness.core.plugin import Plugin

class MyPlugin(Plugin):
    name = "my_tool"
    version = "0.1.0"
    category = "analysis"
    input_contract = {"data": "table"}
    output_contract = {"result": "table"}

    def run(self, data=None, **params):
        ...  # 调用你的算法
        return {"result": df}
```

### 方式二：包装现成函数

```python
from spatialharness.core import plugin_from_function
plugin = plugin_from_function(my_func, name="my_tool",
                              input_contract={"data": "table"})
mgr.register(plugin)
```

### 发布为可安装插件（entry points）

在你的 `pyproject.toml` 里：

```toml
[project.entry-points."spatialharness.plugins"]
my-tool = "my_package.plugin:MyPlugin"
```

`pip install` 后即被所有 SpatialHarness 用户自动发现。

### 本地即插即用

把 `*.py` 丢进 `~/.spatialharness/plugins/` 或项目下 `plugins/` 目录即可，
参见本仓库 [`plugins/hello_demo.py`](plugins/hello_demo.py)。

## 插件流水线（pipeline）

```python
mgr.run_pipeline([
    {"plugin": "street_solar", "params": {"folder": "photos"}},
    {"plugin": "spatial_accessibility", "input_key": "metadata"},
])
```

每个步骤的输出自动作为下一步输入；`input_key` 可从上一步结果字典中选键。

## 内置适配器（现有库不重写）

| 插件名                 | 包装的库              | 后端安装                |
|------------------------|------------------------|-------------------------|
| `spatial_accessibility`| SpatialAccessibility 0.0.13 | `pip install spatialharness[access]` |
| `street_solar`         | StreetSolarTrack 0.0.10     | `pip install spatialharness[street]` |

后端库缺失时，插件在 `run()` 时才报错并给出 pip 提示（懒导入，核心保持轻量）。

## 开发

```bash
git clone https://github.com/GIStudio/SpatialHarness.git
cd SpatialHarness
pip install -e .[dev]
pytest
```

## Handoff / 交接说明

> 面向后续维护者（人或 AI 会话）的现状速览。最后更新：2026-09-05。

### 命名沿革（重要，避免混淆）

- **仓库名** `SpatialHarness`（github.com/GIStudio/SpatialHarness），**包名** `spatialharness`——两者有意不同。
- 原包名 `spatialutils` 被 PyPI 以"与既有 `spatial-utils` 过于相似"为由拒绝，2026-09-05 全局重命名：导入包、CLI 命令、entry-points 组（`spatialharness.plugins`）、本地插件目录（`~/.spatialharness/plugins/`）。
- `SpatialAccessibility` 与 `StreetSolarTrack` 是**独立发布的第三方风格库**，本库只做适配器包装，不改动它们。

### 当前状态（v0.1.0，已发布 PyPI）

- 核心（纯标准库零依赖）：PluginManager（entry points + 本地目录双发现、启停）、Plugin 协议、duck-typing 数据契约、`run_pipeline` 链式调用。
- 内置适配器：`spatial_accessibility`（SpatialAccessibility 0.0.13）、`street_solar`（StreetSolarTrack 0.0.10），后端懒导入，缺失时 `run()` 才报错并给 pip 提示。
- 三个包均已在 PyPI：spatialharness 0.1.0 / SpatialAccessibility 0.0.13 / StreetSolarTrack 0.0.10。
- 测试：24 个，`pytest` 全过（Windows / Python 3.12 验证）。

### 代码地图

| 路径 | 职责 |
|---|---|
| `src/spatialharness/core/plugin.py` | Plugin 基类与协议、PluginInfo、`plugin_from_function` |
| `src/spatialharness/core/manager.py` | 发现 / 注册 / 启停 / `run` / `run_pipeline` |
| `src/spatialharness/core/contracts.py` | 契约类型判定（duck-typing）与校验 |
| `src/spatialharness/core/errors.py` | 异常体系 |
| `src/spatialharness/adapters/` | 两个内置适配器，汇总于 `BUILTIN_ADAPTERS` |
| `src/spatialharness/cli.py` | CLI：list / show / run / enable / disable |
| `plugins/hello_demo.py` | 本地即插即用示例插件 |
| `tests/` | 24 个测试（manager / contracts / cli / adapters） |

### 如何扩展

- **新内置适配器**：在 `adapters/` 加 Plugin 子类并注册进 `BUILTIN_ADAPTERS`（参考 `street_solar.py`）。
- **第三方插件**：独立 Python 包，在自己的 `pyproject.toml` 声明 `[project.entry-points."spatialharness.plugins"]`。
- **实验性插件**：`*.py` 丢进 `~/.spatialharness/plugins/` 或项目 `plugins/` 目录。

### 发布流程

1. 同步版本号：`pyproject.toml` 的 `version` 与 `VERSION` 文件。
2. `python -m build` 产出 `dist/`，`python -m twine check dist/*` 校验。
3. `python -m twine upload dist/*`（凭据由维护者自行配置，勿写入仓库）。
4. git 打 tag 并推送。

### 已知边界 / 下一步

- 尚无 CI（建议：push 时跑 pytest + build 冒烟，参考 GIStudioNote 的 Actions 配置）。
- 契约只校验数据形态，不做数值范围 / CRS 一致性校验。
- `hello` 插件仅作演示，发布正式版前可移入 examples。
- 远期：CitySense 分析流程固化为 perception 类插件；接入 ZenSVI 街景下载能力。

## License

MIT © GIStudio / Shiqi Wang
