provsql-studio 1.0.0__tar.gz

provsql_studio-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Pierre Senellart
+
+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.

provsql_studio-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: provsql-studio
+Version: 1.0.0
+Summary: Web UI for ProvSQL: provenance inspection, circuit visualisation, and on-the-fly semiring evaluation.
+Author-email: Pierre Senellart <pierre@senellart.com>
+License-Expression: MIT
+Project-URL: Homepage, https://provsql.org
+Project-URL: Documentation, https://provsql.org/docs/user/studio.html
+Project-URL: Source, https://github.com/PierreSenellart/provsql
+Project-URL: Issues, https://github.com/PierreSenellart/provsql/issues
+Project-URL: Changelog, https://github.com/PierreSenellart/provsql/releases?q=tag%3Astudio-v
+Keywords: postgresql,probabilistic-database,provenance,provenance-tracking,provsql,web-ui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=3.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: sqlparse>=0.4
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-flask>=1.3; extra == "test"
+Requires-Dist: playwright>=1.40; extra == "test"
+Requires-Dist: pytest-playwright>=0.4; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# ProvSQL Studio
+
+[![CI](https://github.com/PierreSenellart/provsql/actions/workflows/studio.yml/badge.svg?branch=master)](https://github.com/PierreSenellart/provsql/actions/workflows/studio.yml)
+[![PyPI](https://img.shields.io/pypi/v/provsql-studio?style=flat)](https://pypi.org/project/provsql-studio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Web UI for [ProvSQL](https://provsql.org/): provenance inspection, circuit
+visualisation, and on-the-fly semiring evaluation.
+
+ProvSQL is a PostgreSQL extension that adds (m-)semiring provenance and
+uncertainty management to PostgreSQL, transparently rewriting queries to
+track provenance as circuit tokens. ProvSQL Studio is a small Flask app
+that lets you point a browser at a ProvSQL-enabled database and inspect
+that provenance interactively, without writing the query-wrapping
+boilerplate by hand.
+
+Website: **<https://provsql.org/>** – Documentation: **<https://provsql.org/docs/user/studio.html>**
+
+## Inspection modes
+
+Two complementary modes share the same UI (query box, result table,
+sidebar):
+
+* **Where mode** highlights the source cells that contributed to each
+  output value. Hover a result cell and the contributing cells of the
+  underlying provenance-tracked relations light up in the sidebar. The
+  query is wrapped automatically with `provsql.where_provenance`, so no
+  explicit `where_provenance(...)` call is needed.
+
+* **Circuit mode** renders the provenance DAG behind a result's UUID
+  or aggregate token. Click a UUID cell to load its DAG, hover to
+  highlight a subtree, click to pin a node and open the inspector.
+  Frontiers expand on demand so deep circuits stay readable. An
+  evaluation strip targets the pinned node (or the root) and runs
+  provenance evaluation in various semirings, probability computation
+  through various methods, or PROV-XML export, with the result
+  rendered inline.
+
+A schema panel and a configuration panel round out the UI; see the
+documentation for the full feature reference.
+
+## Install
+
+```sh
+pip install provsql-studio
+```
+
+Requires Python 3.10+ and a PostgreSQL database with the ProvSQL
+extension installed (see the
+[extension installation guide](https://provsql.org/docs/user/getting-provsql.html)).
+Studio 1.0.x targets ProvSQL extension 1.4.0 or newer; the startup
+check refuses to launch against an older extension unless
+`--ignore-version` is passed.
+
+## Connecting
+
+Launch Studio with a DSN:
+
+```sh
+provsql-studio --dsn postgresql://user@localhost:5432/mydb
+```
+
+Without `--dsn`, libpq's standard environment variables (`PGDATABASE`,
+`PGSERVICE`, `DATABASE_URL`…) are honoured. If neither is set,
+Studio connects to the `postgres` maintenance database and offers an
+in-page database picker.
+
+The browser reaches the UI at `http://127.0.0.1:8000/`. Override the
+bind address and port with `--host` and `--port`. Per-request size
+caps, statement timeout, and search path are tunable on the CLI
+(`--max-circuit-nodes`, `--max-sidebar-rows`, `--max-result-rows`,
+`--statement-timeout`, `--search-path`) and through the Config panel;
+the panel persists its settings to
+`~/.config/provsql-studio/config.json`.
+
+## Documentation
+
+The full Studio user guide, including screenshots, the configuration
+reference, the compatibility matrix, and worked examples, lives at:
+
+<https://provsql.org/docs/user/studio.html>
+
+For the underlying ProvSQL SQL API (`add_provenance`,
+`create_provenance_mapping`, `view_circuit`, `provenance_evaluate`,
+and the rest), see <https://provsql.org/docs/>.
+
+## License
+
+MIT: see [LICENSE](LICENSE).
+
+## Contact
+
+<https://github.com/PierreSenellart/provsql>
+
+Pierre Senellart <pierre@senellart.com>
+
+Bug reports and feature requests are preferably sent through the
+*Issues* feature of GitHub.

provsql_studio-1.0.0/README.md

@@ -0,0 +1,98 @@
+# ProvSQL Studio
+
+[![CI](https://github.com/PierreSenellart/provsql/actions/workflows/studio.yml/badge.svg?branch=master)](https://github.com/PierreSenellart/provsql/actions/workflows/studio.yml)
+[![PyPI](https://img.shields.io/pypi/v/provsql-studio?style=flat)](https://pypi.org/project/provsql-studio/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Web UI for [ProvSQL](https://provsql.org/): provenance inspection, circuit
+visualisation, and on-the-fly semiring evaluation.
+
+ProvSQL is a PostgreSQL extension that adds (m-)semiring provenance and
+uncertainty management to PostgreSQL, transparently rewriting queries to
+track provenance as circuit tokens. ProvSQL Studio is a small Flask app
+that lets you point a browser at a ProvSQL-enabled database and inspect
+that provenance interactively, without writing the query-wrapping
+boilerplate by hand.
+
+Website: **<https://provsql.org/>** – Documentation: **<https://provsql.org/docs/user/studio.html>**
+
+## Inspection modes
+
+Two complementary modes share the same UI (query box, result table,
+sidebar):
+
+* **Where mode** highlights the source cells that contributed to each
+  output value. Hover a result cell and the contributing cells of the
+  underlying provenance-tracked relations light up in the sidebar. The
+  query is wrapped automatically with `provsql.where_provenance`, so no
+  explicit `where_provenance(...)` call is needed.
+
+* **Circuit mode** renders the provenance DAG behind a result's UUID
+  or aggregate token. Click a UUID cell to load its DAG, hover to
+  highlight a subtree, click to pin a node and open the inspector.
+  Frontiers expand on demand so deep circuits stay readable. An
+  evaluation strip targets the pinned node (or the root) and runs
+  provenance evaluation in various semirings, probability computation
+  through various methods, or PROV-XML export, with the result
+  rendered inline.
+
+A schema panel and a configuration panel round out the UI; see the
+documentation for the full feature reference.
+
+## Install
+
+```sh
+pip install provsql-studio
+```
+
+Requires Python 3.10+ and a PostgreSQL database with the ProvSQL
+extension installed (see the
+[extension installation guide](https://provsql.org/docs/user/getting-provsql.html)).
+Studio 1.0.x targets ProvSQL extension 1.4.0 or newer; the startup
+check refuses to launch against an older extension unless
+`--ignore-version` is passed.
+
+## Connecting
+
+Launch Studio with a DSN:
+
+```sh
+provsql-studio --dsn postgresql://user@localhost:5432/mydb
+```
+
+Without `--dsn`, libpq's standard environment variables (`PGDATABASE`,
+`PGSERVICE`, `DATABASE_URL`…) are honoured. If neither is set,
+Studio connects to the `postgres` maintenance database and offers an
+in-page database picker.
+
+The browser reaches the UI at `http://127.0.0.1:8000/`. Override the
+bind address and port with `--host` and `--port`. Per-request size
+caps, statement timeout, and search path are tunable on the CLI
+(`--max-circuit-nodes`, `--max-sidebar-rows`, `--max-result-rows`,
+`--statement-timeout`, `--search-path`) and through the Config panel;
+the panel persists its settings to
+`~/.config/provsql-studio/config.json`.
+
+## Documentation
+
+The full Studio user guide, including screenshots, the configuration
+reference, the compatibility matrix, and worked examples, lives at:
+
+<https://provsql.org/docs/user/studio.html>
+
+For the underlying ProvSQL SQL API (`add_provenance`,
+`create_provenance_mapping`, `view_circuit`, `provenance_evaluate`,
+and the rest), see <https://provsql.org/docs/>.
+
+## License
+
+MIT: see [LICENSE](LICENSE).
+
+## Contact
+
+<https://github.com/PierreSenellart/provsql>
+
+Pierre Senellart <pierre@senellart.com>
+
+Bug reports and feature requests are preferably sent through the
+*Issues* feature of GitHub.

provsql_studio-1.0.0/provsql_studio/__init__.py

@@ -0,0 +1,2 @@
+"""ProvSQL Studio: web UI for the ProvSQL PostgreSQL extension."""
+__version__ = "1.0.0"

provsql_studio-1.0.0/provsql_studio/__main__.py

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