pyautark 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,231 @@
1
+ .venv*
2
+ ._*
3
+ *._*
4
+ .DS_Store
5
+
6
+ node_modules/
7
+ dist/
8
+ test-results/
9
+ playwright-report/
10
+ npm-debug.log*
11
+
12
+ # Byte-compiled / optimized / DLL files
13
+ __pycache__/
14
+ *.py[codz]
15
+ *$py.class
16
+
17
+ # C extensions
18
+ *.so
19
+
20
+ # Distribution / packaging
21
+ .Python
22
+ build/
23
+ develop-eggs/
24
+ dist/
25
+ downloads/
26
+ eggs/
27
+ .eggs/
28
+ lib/
29
+ lib64/
30
+ parts/
31
+ sdist/
32
+ var/
33
+ wheels/
34
+ share/python-wheels/
35
+ *.egg-info/
36
+ .installed.cfg
37
+ *.egg
38
+ MANIFEST
39
+
40
+ # PyInstaller
41
+ # Usually these files are written by a python script from a template
42
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
43
+ *.manifest
44
+ *.spec
45
+
46
+ # Installer logs
47
+ pip-log.txt
48
+ pip-delete-this-directory.txt
49
+
50
+ # Unit test / coverage reports
51
+ htmlcov/
52
+ .tox/
53
+ .nox/
54
+ .coverage
55
+ .coverage.*
56
+ .cache
57
+ nosetests.xml
58
+ coverage.xml
59
+ *.cover
60
+ *.py.cover
61
+ .hypothesis/
62
+ .pytest_cache/
63
+ cover/
64
+
65
+ # Translations
66
+ *.mo
67
+ *.pot
68
+
69
+ # Django stuff:
70
+ *.log
71
+ local_settings.py
72
+ db.sqlite3
73
+ db.sqlite3-journal
74
+
75
+ # Flask stuff:
76
+ instance/
77
+ .webassets-cache
78
+
79
+ # Scrapy stuff:
80
+ .scrapy
81
+
82
+ # Sphinx documentation
83
+ docs/_build/
84
+
85
+ # PyBuilder
86
+ .pybuilder/
87
+ target/
88
+
89
+ # Jupyter Notebook
90
+ .ipynb_checkpoints
91
+
92
+ # IPython
93
+ profile_default/
94
+ ipython_config.py
95
+
96
+ # pyenv
97
+ # For a library or package, you might want to ignore these files since the code is
98
+ # intended to run in multiple environments; otherwise, check them in:
99
+ # .python-version
100
+
101
+ # pipenv
102
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
103
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
104
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
105
+ # install all needed dependencies.
106
+ # Pipfile.lock
107
+
108
+ # UV
109
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
110
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
111
+ # commonly ignored for libraries.
112
+ # uv.lock
113
+
114
+ # poetry
115
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
116
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
117
+ # commonly ignored for libraries.
118
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
119
+ # poetry.lock
120
+ # poetry.toml
121
+
122
+ # pdm
123
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
124
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
125
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
126
+ # pdm.lock
127
+ # pdm.toml
128
+ .pdm-python
129
+ .pdm-build/
130
+
131
+ # pixi
132
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
133
+ # pixi.lock
134
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
135
+ # in the .venv directory. It is recommended not to include this directory in version control.
136
+ .pixi
137
+
138
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
139
+ __pypackages__/
140
+
141
+ # Celery stuff
142
+ celerybeat-schedule
143
+ celerybeat.pid
144
+
145
+ # Redis
146
+ *.rdb
147
+ *.aof
148
+ *.pid
149
+
150
+ # RabbitMQ
151
+ mnesia/
152
+ rabbitmq/
153
+ rabbitmq-data/
154
+
155
+ # ActiveMQ
156
+ activemq-data/
157
+
158
+ # SageMath parsed files
159
+ *.sage.py
160
+
161
+ # Environments
162
+ .env
163
+ .envrc
164
+ .venv
165
+ env/
166
+ venv/
167
+ ENV/
168
+ env.bak/
169
+ venv.bak/
170
+
171
+ # Spyder project settings
172
+ .spyderproject
173
+ .spyproject
174
+
175
+ # Rope project settings
176
+ .ropeproject
177
+
178
+ # mkdocs documentation
179
+ /site
180
+
181
+ # mypy
182
+ .mypy_cache/
183
+ .dmypy.json
184
+ dmypy.json
185
+
186
+ # Pyre type checker
187
+ .pyre/
188
+
189
+ # pytype static type analyzer
190
+ .pytype/
191
+
192
+ # Cython debug symbols
193
+ cython_debug/
194
+
195
+ # PyCharm
196
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
197
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
198
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
199
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
200
+ # .idea/
201
+
202
+ # Abstra
203
+ # Abstra is an AI-powered process automation framework.
204
+ # Ignore directories containing user credentials, local state, and settings.
205
+ # Learn more at https://abstra.io/docs
206
+ .abstra/
207
+
208
+ # Visual Studio Code
209
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
210
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
211
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
212
+ # you could uncomment the following to ignore the entire vscode folder
213
+ # .vscode/
214
+ # Temporary file for partial code execution
215
+ tempCodeRunnerFile.py
216
+
217
+ # Ruff stuff:
218
+ .ruff_cache/
219
+
220
+ # PyPI configuration file
221
+ .pypirc
222
+
223
+ # Marimo
224
+ marimo/_static/
225
+ marimo/_lsp/
226
+ __marimo__/
227
+
228
+ # Streamlit
229
+ .streamlit/secrets.toml
230
+ tests/.specs/
231
+ tests/results/
@@ -0,0 +1,269 @@
1
+ Metadata-Version: 2.5
2
+ Name: pyautark
3
+ Version: 0.1.0a1
4
+ Summary: Declarative Python API for urban visual analytics (maps, plots, spatial joins) rendered with WebGPU and DuckDB-WASM
5
+ Project-URL: Homepage, https://github.com/urban-toolkit/pyautark
6
+ Project-URL: Repository, https://github.com/urban-toolkit/pyautark
7
+ Project-URL: Issues, https://github.com/urban-toolkit/pyautark/issues
8
+ Author: Urban Toolkit
9
+ License: MIT
10
+ Keywords: declarative,duckdb,gis,jupyter,maps,urban,visualization,webgpu
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Framework :: Jupyter
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Scientific/Engineering :: GIS
20
+ Classifier: Topic :: Scientific/Engineering :: Visualization
21
+ Requires-Python: >=3.10
22
+ Provides-Extra: desktop
23
+ Requires-Dist: pywebview>=5.0; extra == 'desktop'
24
+ Provides-Extra: dev
25
+ Requires-Dist: anywidget>=0.9; extra == 'dev'
26
+ Requires-Dist: jsonschema>=4.0; extra == 'dev'
27
+ Requires-Dist: mypy>=1.8; extra == 'dev'
28
+ Requires-Dist: nbclient>=0.7; extra == 'dev'
29
+ Requires-Dist: nbformat>=5.0; extra == 'dev'
30
+ Requires-Dist: pywebview>=5.0; extra == 'dev'
31
+ Provides-Extra: test
32
+ Requires-Dist: jsonschema>=4.0; extra == 'test'
33
+ Provides-Extra: validation
34
+ Requires-Dist: jsonschema>=4.0; extra == 'validation'
35
+ Provides-Extra: widget
36
+ Requires-Dist: anywidget>=0.9; extra == 'widget'
37
+ Description-Content-Type: text/markdown
38
+
39
+ # Autark Python API
40
+
41
+ Declarative Python API for creating urban visual analytics views. You describe the data, the tables derived from it, the maps and the plots with Python objects. Each object writes its part of an **UrbanSpec**, the JSON specification of [autk-grammar](https://github.com/urban-toolkit/autk-grammar), and a bundled browser runtime runs that spec with the Autark modules.
42
+
43
+ ## Quick Example
44
+
45
+ ```python
46
+ import pyautark as ak
47
+
48
+ # Load GeoJSON data
49
+ neighborhoods = ak.GeoJSON(
50
+ "neighborhoods",
51
+ url="/data/neighborhoods.geojson",
52
+ coordinate_format="EPSG:4326",
53
+ )
54
+
55
+ # Create a map with styled layers
56
+ spec = ak.Spec(
57
+ metadata=ak.Metadata(title="Neighborhood Map"),
58
+ data=[neighborhoods],
59
+ views=[
60
+ ak.Map(
61
+ camera=ak.Camera(zoom=12),
62
+ layers=[
63
+ ak.Layer(neighborhoods)
64
+ .style(color="#3498db", opacity=0.7)
65
+ ]
66
+ )
67
+ ]
68
+ )
69
+
70
+ # The UrbanSpec, as plain Python
71
+ spec.to_dict()
72
+
73
+ # Export
74
+ spec.save_json("spec.json")
75
+ spec.save_html("map.html")
76
+
77
+ # Validate against schema/urbanspec.json (requires pyautark[validation])
78
+ spec.validate()
79
+
80
+ # Display in Jupyter without any local server (requires pyautark[widget])
81
+ spec.widget()
82
+
83
+ # Open the same bundled runtime in a native window from a Python script
84
+ # (requires: pip install -e ".[desktop]")
85
+ spec.window(height="760px")
86
+ ```
87
+
88
+ ## Features
89
+
90
+ - **Declarative specs** - Python objects that serialize as an UrbanSpec, which the browser bundle runs as it is
91
+ - **Data sources** - `GeoJSON`, `CSV` and `JSON` (latitude/longitude or WKT geometry), `OSM` (a place or a `bbox`, from Overpass or a PBF extract) and `GeoTIFF`
92
+ - **Spatial operations** - `SpatialJoin` and `Heatmap`
93
+ - **Compute transforms** - `Compute.gpgpu` (a WGSL function per feature) and `Compute.render` (render-based analysis such as sky exposure)
94
+ - **Interactive visualizations** - `Map`; plots (`Histogram`, `Barchart`, `Scatterplot`, `Table`, `ParallelCoordinates`, `Heatmatrix`, `EventSeries`, `Timeseries`); and linked selections
95
+ - **Jupyter integration** - bundled anywidget rendering
96
+ - **Script window display** - Open the bundled runtime in a native window via pywebview
97
+ - **Selections back in Python** - observe `widget.selections` for brushes
98
+ - **pandas/GeoPandas input** - `GeoJSON.from_dataframe()` / `from_geopandas()`
99
+ - **Standalone HTML export** - No Python runtime required
100
+
101
+ ## Installation
102
+
103
+ **Note:** Not yet published to PyPI. Install from source:
104
+
105
+ ```bash
106
+ cd autark/python
107
+ pip install -e .
108
+ pip install -e ".[validation]" # Optional: JSON Schema validation
109
+ pip install -e ".[widget]" # Optional: zero-server Jupyter widget (anywidget)
110
+ ```
111
+
112
+ Package builds use Hatch and `hatch-jupyter-builder` to run
113
+ `npm run build:widget` in `autk-runtime` and include
114
+ `autark/static/autark-widget.js` automatically.
115
+
116
+ ### Displaying specs in Jupyter
117
+
118
+ `spec.widget()` renders with the runtime bundled inside the Python package. No local server needed; works in Jupyter, JupyterLab, VS Code, and Colab. DuckDB sidecar assets are packaged next to the widget bundle and used when the host exposes sibling files. Data sources must use absolute URLs or inline `values` (in JupyterLab started from a folder, `/files/<path>` URLs also work).
119
+
120
+ Plot selections sync back to the kernel, keyed by plot id (the name of the plot's selection):
121
+
122
+ ```python
123
+ brush = ak.interval("latitude_brush")
124
+ w = spec.widget()
125
+ w # display; brush the plot, then:
126
+ w.selections # {'latitude_brush': [0, 2]}
127
+ w.observe(lambda change: print(change["new"]), names="selections")
128
+ ```
129
+
130
+ DataFrames can be passed directly as inline data:
131
+
132
+ ```python
133
+ trees = ak.GeoJSON.from_dataframe("trees", df, latitude="lat", longitude="lon")
134
+ neighborhoods = ak.GeoJSON.from_geopandas("neighborhoods", gdf) # reprojects to EPSG:4326
135
+ ```
136
+
137
+ A notebook kernel keeps the widget bundle it loaded. After rebuilding the bundle, restart the kernel and reload the page.
138
+
139
+ ## Names and rules
140
+
141
+ Python keeps its own words, and each builder writes the UrbanSpec fields:
142
+
143
+ | Python | UrbanSpec |
144
+ |---|---|
145
+ | a source's `name` | `outputTableName` |
146
+ | a source's `url` / `values` | `geojsonFileUrl` / `geojsonObject` (`csvFileUrl`, `csvObject`, `jsonFileUrl`, ...) |
147
+ | `ak.latlng(lat, lon)`, `ak.wkt(col)` | `geometryColumns` |
148
+ | `OSM(area=..., layers=[...])`, `OSM(bbox=...)` | `queryArea`, `autoLoadLayers` |
149
+ | a layer's source (name or object) | `dataRef` |
150
+ | `Layer(id=...)` | `title` |
151
+ | `.encode(color=ak.field(path, scale))` | `getFnv`, `isColorMap`, `colorMapInterpolator`, ... |
152
+ | `.style(color, opacity, strokeColor, width, size)` | `color`, `opacity`, `stroke`, `width`, `pointSize` |
153
+ | `SpatialJoin(root, join)` | a `join` entry of `data`: `dataRef`, `joinDataRef` |
154
+ | `Heatmap(source, output)` | a `heatmap` entry of `data`: `joinDataRef`, `outputTableName` |
155
+ | `Compute.gpgpu(source, variable_mapping, wgsl_body, result_field)` | an entry of `compute`: `dataRef`, `attributes`, `wgslFunction`, `outputColumnName` |
156
+ | `Compute.render(output, ...)` | a `compute` entry with `type: 'render'` |
157
+ | `Map(name=...)`, `Camera` | `map` with `id`, `camera` |
158
+ | `Histogram`, `Barchart`, `Scatterplot`, `Table`, `ParallelCoordinates`, `Heatmatrix`, `EventSeries`, `Timeseries` | `plot` with `mark` `bar`, `scatter`, `table`, `parallel-coordinates`, `heatmatrix`, `linechart` and the matching `transform` |
159
+ | `Link(selection, target)` | `links[]`: the plot that owns the selection, the map and layer that draw `target` |
160
+
161
+ Rules worth knowing:
162
+
163
+ - **The first source sets the workspace.** Autark cuts every later source to the extent of the first one, so a table that lies outside it comes out empty. Put the source that covers the area of interest first.
164
+ - **Workspaces keep areas apart.** `workspace="name"` on a source, a join, a heatmap, a compute pass, a map or a plot puts it in a named workspace, with its own extent; the entries without one share the default workspace. Two areas that must not clip each other go in two workspaces, and each workspace may hold a table of the same name (see `examples/python/osm_layers_workspaces.py`).
165
+ - **A table is drawn from its geometry** (points, lines or polygons); a layer does not say. A collection that mixes types goes in as one source per type.
166
+ - **A plot with a selection takes the selection's name as its id**, which is also the key of `widget.selections`. A link points to a layer by its `id`, and an unnamed map gets `map1`, `map2`, ... when a link needs it.
167
+ - **Joins and heatmaps run before compute passes.** A `SpatialJoin` or `Heatmap` that reads a table a compute pass wrote is refused.
168
+ - **`Compute.gpgpu` without `output` adds its result to the source table** (`properties.compute.<name>`); with `output`, it makes a new table and leaves the source as it was. `Compute.render` always makes a new table.
169
+ - **Links highlight.** Other actions are refused.
170
+ - **Give plots in a grid a `width` and `height`** (pixels) so they fit their cells.
171
+ - **What the grammar has no field for is reported with a `UserWarning` and left out**, for example `strokeWidth`, or sizing or opacity driven by a field.
172
+ - `metadata` (title, ...) is for the page that shows the spec and is not serialized.
173
+
174
+ ## Example styles
175
+
176
+ Examples come in two flavors. Both build the same `Spec`; they differ in what
177
+ the script does when run from the command line.
178
+
179
+ **Style A (default) — terse `spec.window()`.** The spec is built at module
180
+ scope and `spec.window()` opens a native window when the script is run. Best
181
+ for small didactic examples; the spec is also importable from a REPL or
182
+ notebook.
183
+
184
+ ```python
185
+ import pyautark as ak
186
+
187
+ spec = ak.Spec(
188
+ data=[ak.OSM("osm", geocode_area="New York", area="Financial District",
189
+ layers=["roads", "buildings"])],
190
+ views=[ak.Map(layers=[ak.Layer("osm_roads"),
191
+ ak.Layer("osm_buildings")])],
192
+ )
193
+
194
+ if __name__ == "__main__":
195
+ spec.window(height="760px")
196
+ ```
197
+
198
+ **Style B — CLI flags via `ak.cli(spec)`.** Use this when the example should
199
+ also be runnable from CI to regenerate JSON, validate against the schema, or
200
+ emit standalone HTML without needing the `desktop` extra installed.
201
+
202
+ ```python
203
+ import pyautark as ak
204
+
205
+ spec = ak.Spec(...) # same builder
206
+
207
+ if __name__ == "__main__":
208
+ ak.cli(spec)
209
+ ```
210
+
211
+ Resulting CLI:
212
+
213
+ ```bash
214
+ python ex.py # opens a window (same as Style A)
215
+ python ex.py --output spec.json # write the UrbanSpec as JSON
216
+ python ex.py --html out.html # write standalone HTML
217
+ python ex.py --validate # validate against schema/urbanspec.json
218
+ python ex.py --json # print JSON to stdout
219
+ python ex.py --height 800px # override window/HTML height
220
+ ```
221
+
222
+ Action flags suppress the window. `--validate` can be combined with `--output`
223
+ or `--html`.
224
+
225
+ ## Documentation
226
+
227
+ - **[examples/](../examples/)** - Working examples
228
+ - [simple_geojson_map.py](../examples/python/simple_geojson_map.py) - Basic map
229
+ - [csv_points_map.py](../examples/python/csv_points_map.py) - CSV points + histogram
230
+ - [spatial_join.py](../examples/python/spatial_join.py) - Spatial join workflow
231
+ - [geopandas_workflow.py](../examples/python/geopandas_workflow.py) - GeoPandas workflow
232
+ - [specs/](../examples/specs/) - the same kind of views as UrbanSpec JSON files
233
+ - The **pyautark tutorial** (https://github.com/ctsilva/pyautark-tutorial): six notebooks, from data formats to GPU computing
234
+ - The UrbanSpec itself: [autk-grammar](https://github.com/urban-toolkit/autk-grammar)
235
+
236
+ ## Design
237
+
238
+ The Autark Python API follows the Vega-Lite/Altair pattern:
239
+
240
+ 1. Python authors **structured specifications**
241
+ 2. Specifications **serialize to an UrbanSpec** (JSON)
242
+ 3. The browser bundle **runs the UrbanSpec with `AutkGrammar`** (autk-db, autk-compute, autk-map, autk-plot)
243
+ 4. All rendering/compute happens in **WebGPU/DuckDB-WASM**
244
+
245
+ Benefits:
246
+ - Shareable as JSON or HTML
247
+ - Jupyter-friendly
248
+ - LLM/agent-friendly
249
+ - No Python runtime needed for visualization
250
+ - One specification and one engine: the UrbanSpec runs in any autk-grammar host
251
+
252
+ ## Testing
253
+
254
+ ```bash
255
+ # Run Python tests
256
+ python -m unittest discover -s tests
257
+
258
+ # Type check (pip install -e ".[dev]")
259
+ python -m mypy
260
+
261
+ # Validate examples
262
+ python ../examples/python/simple_geojson_map.py --validate
263
+ python ../examples/python/csv_points_map.py --validate
264
+ python ../examples/python/spatial_join.py --validate
265
+ ```
266
+
267
+ ## License
268
+
269
+ MIT License