silverpoint 0.11.0__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.
Files changed (75) hide show
  1. silverpoint-0.11.0/.gitignore +230 -0
  2. silverpoint-0.11.0/CHANGELOG.md +16 -0
  3. silverpoint-0.11.0/LICENSE +21 -0
  4. silverpoint-0.11.0/PKG-INFO +151 -0
  5. silverpoint-0.11.0/README.md +128 -0
  6. silverpoint-0.11.0/pyproject.toml +69 -0
  7. silverpoint-0.11.0/scripts/conformance.mjs +18 -0
  8. silverpoint-0.11.0/scripts/make_builders.py +199 -0
  9. silverpoint-0.11.0/scripts/vendor.py +168 -0
  10. silverpoint-0.11.0/src/silverpoint/__init__.py +44 -0
  11. silverpoint-0.11.0/src/silverpoint/_builders.py +3543 -0
  12. silverpoint-0.11.0/src/silverpoint/_builders.pyi +1566 -0
  13. silverpoint-0.11.0/src/silverpoint/_catalog.py +37 -0
  14. silverpoint-0.11.0/src/silverpoint/_closest.py +28 -0
  15. silverpoint-0.11.0/src/silverpoint/_vendor/OFL.txt +93 -0
  16. silverpoint-0.11.0/src/silverpoint/_vendor/conformance.json +705 -0
  17. silverpoint-0.11.0/src/silverpoint/_vendor/host-catalog.json +28819 -0
  18. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/bar-chart.document.html +1 -0
  19. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/bar-chart.fragment.html +1 -0
  20. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/bar-chart.interactive.html +1 -0
  21. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/cases.json +11 -0
  22. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/gauge-arc.document.html +1 -0
  23. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/gauge-arc.fragment.html +1 -0
  24. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/gauge-arc.interactive.html +1 -0
  25. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/heatmap-chart.document.html +1 -0
  26. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/heatmap-chart.fragment.html +1 -0
  27. silverpoint-0.11.0/src/silverpoint/_vendor/html-goldens/heatmap-chart.interactive.html +1 -0
  28. silverpoint-0.11.0/src/silverpoint/_vendor/integrity.json +6 -0
  29. silverpoint-0.11.0/src/silverpoint/_vendor/silverpoint-embed.full.js +3 -0
  30. silverpoint-0.11.0/src/silverpoint/_vendor/silverpoint-embed.full.mjs +3 -0
  31. silverpoint-0.11.0/src/silverpoint/_vendor/tables/errors.json +10 -0
  32. silverpoint-0.11.0/src/silverpoint/_vendor/tables/pivot-dimensions.json +7 -0
  33. silverpoint-0.11.0/src/silverpoint/_vendor/tables/pivot-matrix.json +7 -0
  34. silverpoint-0.11.0/src/silverpoint/_vendor/tables/rows.json +22 -0
  35. silverpoint-0.11.0/src/silverpoint/_vendor/tables/scalar.json +12 -0
  36. silverpoint-0.11.0/src/silverpoint/chart.py +133 -0
  37. silverpoint-0.11.0/src/silverpoint/contrib/__init__.py +1 -0
  38. silverpoint-0.11.0/src/silverpoint/contrib/_markup.py +27 -0
  39. silverpoint-0.11.0/src/silverpoint/contrib/django/__init__.py +11 -0
  40. silverpoint-0.11.0/src/silverpoint/contrib/django/apps.py +9 -0
  41. silverpoint-0.11.0/src/silverpoint/contrib/django/static/silverpoint/silverpoint-embed.full.js +3 -0
  42. silverpoint-0.11.0/src/silverpoint/contrib/django/templatetags/__init__.py +0 -0
  43. silverpoint-0.11.0/src/silverpoint/contrib/django/templatetags/silverpoint.py +21 -0
  44. silverpoint-0.11.0/src/silverpoint/contrib/flask.py +58 -0
  45. silverpoint-0.11.0/src/silverpoint/data.py +126 -0
  46. silverpoint-0.11.0/src/silverpoint/errors.py +22 -0
  47. silverpoint-0.11.0/src/silverpoint/html.py +110 -0
  48. silverpoint-0.11.0/src/silverpoint/notebook.py +77 -0
  49. silverpoint-0.11.0/src/silverpoint/reshape.py +61 -0
  50. silverpoint-0.11.0/src/silverpoint/spec.py +196 -0
  51. silverpoint-0.11.0/src/silverpoint/svg.py +64 -0
  52. silverpoint-0.11.0/tests/conftest.py +21 -0
  53. silverpoint-0.11.0/tests/fixtures/hostile/ampersand-entities.json +6 -0
  54. silverpoint-0.11.0/tests/fixtures/hostile/attribute-break-in-id-label.json +7 -0
  55. silverpoint-0.11.0/tests/fixtures/hostile/comment-open-in-badge.json +7 -0
  56. silverpoint-0.11.0/tests/fixtures/hostile/hostile-palette.json +6 -0
  57. silverpoint-0.11.0/tests/fixtures/hostile/img-onerror-in-data.json +13 -0
  58. silverpoint-0.11.0/tests/fixtures/hostile/javascript-url-in-footer.json +6 -0
  59. silverpoint-0.11.0/tests/fixtures/hostile/line-separators.json +6 -0
  60. silverpoint-0.11.0/tests/fixtures/hostile/script-close-in-title.json +6 -0
  61. silverpoint-0.11.0/tests/fixtures/hostile/svg-onload-column.json +12 -0
  62. silverpoint-0.11.0/tests/fixtures/hostile/unicode-names.json +12 -0
  63. silverpoint-0.11.0/tests/fixtures/hostile-expected.json +12 -0
  64. silverpoint-0.11.0/tests/test_browser.py +141 -0
  65. silverpoint-0.11.0/tests/test_builders.py +58 -0
  66. silverpoint-0.11.0/tests/test_data.py +164 -0
  67. silverpoint-0.11.0/tests/test_django.py +36 -0
  68. silverpoint-0.11.0/tests/test_examples.py +86 -0
  69. silverpoint-0.11.0/tests/test_flask.py +50 -0
  70. silverpoint-0.11.0/tests/test_html.py +98 -0
  71. silverpoint-0.11.0/tests/test_notebook.py +62 -0
  72. silverpoint-0.11.0/tests/test_spark.py +52 -0
  73. silverpoint-0.11.0/tests/test_spec.py +152 -0
  74. silverpoint-0.11.0/tests/test_svg.py +33 -0
  75. silverpoint-0.11.0/tests/test_vendor.py +93 -0
@@ -0,0 +1,230 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ .idea/
10
+
11
+
12
+ # Distribution / packaging
13
+ .Python
14
+ build/
15
+ develop-eggs/
16
+ dist/
17
+ downloads/
18
+ eggs/
19
+ .eggs/
20
+ lib/
21
+ lib64/
22
+ parts/
23
+ sdist/
24
+ var/
25
+ wheels/
26
+ share/python-wheels/
27
+ *.egg-info/
28
+ .installed.cfg
29
+ *.egg
30
+ MANIFEST
31
+
32
+ # PyInstaller
33
+ # Usually these files are written by a python script from a template
34
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
35
+ *.manifest
36
+ *.spec
37
+
38
+ # Installer logs
39
+ pip-log.txt
40
+ pip-delete-this-directory.txt
41
+
42
+ # Unit test / coverage reports
43
+ htmlcov/
44
+ .tox/
45
+ .nox/
46
+ .coverage
47
+ .coverage.*
48
+ .cache
49
+ nosetests.xml
50
+ coverage.xml
51
+ *.cover
52
+ *.py.cover
53
+ *.lcov
54
+ .hypothesis/
55
+ .pytest_cache/
56
+ cover/
57
+
58
+ # Translations
59
+ *.mo
60
+ *.pot
61
+
62
+ # Django stuff:
63
+ *.log
64
+ local_settings.py
65
+ db.sqlite3
66
+ db.sqlite3-journal
67
+
68
+ # Flask stuff:
69
+ instance/
70
+ .webassets-cache
71
+
72
+ # Scrapy stuff:
73
+ .scrapy
74
+
75
+ # Sphinx documentation
76
+ docs/_build/
77
+
78
+ # PyBuilder
79
+ .pybuilder/
80
+ target/
81
+
82
+ # Jupyter Notebook
83
+ .ipynb_checkpoints
84
+
85
+ # IPython
86
+ profile_default/
87
+ ipython_config.py
88
+
89
+ # pyenv
90
+ # For a library or package, you might want to ignore these files since the code is
91
+ # intended to run in multiple environments; otherwise, check them in:
92
+ # .python-version
93
+
94
+ # pipenv
95
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
96
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
97
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
98
+ # install all needed dependencies.
99
+ # Pipfile.lock
100
+
101
+ # uv
102
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
103
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
104
+ # commonly ignored for libraries.
105
+ # uv.lock
106
+
107
+ # poetry
108
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
109
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
110
+ # commonly ignored for libraries.
111
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
112
+ # poetry.lock
113
+ # poetry.toml
114
+
115
+ # pdm
116
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
117
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
118
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
119
+ # pdm.lock
120
+ # pdm.toml
121
+ .pdm-python
122
+ .pdm-build/
123
+
124
+ # pixi
125
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
126
+ # pixi.lock
127
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
128
+ # in the .venv directory. It is recommended not to include this directory in version control.
129
+ .pixi/*
130
+ !.pixi/config.toml
131
+
132
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
133
+ __pypackages__/
134
+
135
+ # Celery stuff
136
+ celerybeat-schedule*
137
+ celerybeat.pid
138
+
139
+ # Redis
140
+ *.rdb
141
+ *.aof
142
+ *.pid
143
+
144
+ # RabbitMQ
145
+ mnesia/
146
+ rabbitmq/
147
+ rabbitmq-data/
148
+
149
+ # ActiveMQ
150
+ activemq-data/
151
+
152
+ # SageMath parsed files
153
+ *.sage.py
154
+
155
+ # Environments
156
+ .env
157
+ .envrc
158
+ .venv
159
+ env/
160
+ venv/
161
+ ENV/
162
+ env.bak/
163
+ venv.bak/
164
+
165
+ # Conda environments
166
+ conda-meta/
167
+
168
+ # Spyder project settings
169
+ .spyderproject
170
+ .spyproject
171
+
172
+ # Rope project settings
173
+ .ropeproject
174
+
175
+ # mkdocs/Zensical documentation
176
+ /site
177
+
178
+ # mypy
179
+ .mypy_cache/
180
+ .dmypy.json
181
+ dmypy.json
182
+
183
+ # Pyre type checker
184
+ .pyre/
185
+
186
+ # pytype static type analyzer
187
+ .pytype/
188
+
189
+ # Cython debug symbols
190
+ cython_debug/
191
+
192
+ # PyCharm
193
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
194
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
195
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
196
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
197
+ # .idea/
198
+
199
+ # Abstra
200
+ # Abstra is an AI-powered process automation framework.
201
+ # Ignore directories containing user credentials, local state, and settings.
202
+ # Learn more at https://abstra.io/docs
203
+ .abstra/
204
+
205
+ # Visual Studio Code
206
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
207
+ # can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
208
+ # and can be added to the global gitignore or merged into this file. However, if you prefer, you
209
+ # could uncomment the following to ignore the entire vscode folder
210
+ # .vscode/
211
+ # Temporary file for partial code execution
212
+ tempCodeRunnerFile.py
213
+
214
+ # Ruff stuff:
215
+ .ruff_cache/
216
+
217
+ # PyPI configuration file
218
+ .pypirc
219
+
220
+ # Marimo
221
+ marimo/_static/
222
+ marimo/_lsp/
223
+ __marimo__/
224
+
225
+ # Streamlit
226
+ .streamlit/secrets.toml
227
+
228
+ # silverpoint
229
+ examples/**/out/
230
+ .idea/
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ ## 0.11.0 (unreleased)
4
+
5
+ First release, vendoring `@silverpoint/embed` 0.11.0 from the hosts kit attached to silverpoint's
6
+ `v0.11.0` release (built test-first against 0.10.1's local build, which carries the same API).
7
+
8
+ - `Chart`, one builder per bindable chart, `SpecError` with "did you mean".
9
+ - `to_html` (server-drawn in Node or client-drawn), `to_svg`, notebook frames, `notebook.enable()`.
10
+ - `silverpoint.contrib.flask` and `silverpoint.contrib.django`, CSP-safe.
11
+ - Databricks (delta-001): Spark and pandas-on-Spark DataFrames and Spark `Row`s as data, read
12
+ through `limit` up to `SPARK_ROW_LIMIT` (10,000); `notebook.enable()` warns there; an example
13
+ notebook in Databricks source format.
14
+ - `scripts/vendor.py`, `scripts/make_builders.py`, `scripts/conformance.mjs`. `vendor.py X.Y.Z`
15
+ verifies the kit before the version is moved; `--check` then requires `pyproject.toml` and
16
+ `silverpoint.__version__` to mirror it (PY-DD-01).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ernesto Crespo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,151 @@
1
+ Metadata-Version: 2.5
2
+ Name: silverpoint
3
+ Version: 0.11.0
4
+ Summary: silverpoint charts from Python: notebooks, Flask, Django and static HTML, drawn by the library's own standalone script.
5
+ Project-URL: Homepage, https://github.com/ecrespo/silverpoint-python
6
+ Project-URL: Library, https://github.com/ecrespo/silverpoint
7
+ Author-email: Ernesto Crespo <ecrespo@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ License-File: src/silverpoint/_vendor/OFL.txt
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Framework :: Django
13
+ Classifier: Framework :: Flask
14
+ Classifier: Framework :: Jupyter
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Scientific/Engineering :: Visualization
17
+ Requires-Python: >=3.10
18
+ Provides-Extra: django
19
+ Requires-Dist: django>=4.2; extra == 'django'
20
+ Provides-Extra: flask
21
+ Requires-Dist: flask>=2.3; extra == 'flask'
22
+ Description-Content-Type: text/markdown
23
+
24
+ # silverpoint
25
+
26
+ silverpoint charts from Python — in notebooks, Flask, Django and static HTML. No picture is made in
27
+ Python: the package builds a chart spec and the markup that carries it, and the library's own
28
+ standalone script (`@silverpoint/embed`, vendored version for version) draws it.
29
+
30
+ ```sh
31
+ pip install silverpoint # no dependencies
32
+ pip install "silverpoint[flask]" # or [django]
33
+ ```
34
+
35
+ `silverpoint` X.Y.Z vendors `@silverpoint/embed` X.Y.Z (`silverpoint.SILVERPOINT_VERSION`).
36
+
37
+ ## A chart
38
+
39
+ ```python
40
+ import pandas as pd
41
+ import silverpoint
42
+
43
+ df = pd.DataFrame({"team": ["A", "B", "C"], "wins": [12, 9, 15]})
44
+ chart = silverpoint.bar_chart(df, x="team", value="wins", orientation="rows", title="Wins")
45
+
46
+ chart.spec # the ChartSpec, a dict
47
+ chart.to_html() # a complete, self-contained page (the script inlined; no network)
48
+ chart.to_svg() # the library's renderToSVG bytes (needs Node 20+ on PATH)
49
+ ```
50
+
51
+ There is one builder per chart a table can feed — `silverpoint.line_chart`, `heatmap_chart`,
52
+ `sankey_chart`, … — with one keyword per role (a column name) and per option, generated from the
53
+ host catalog. `silverpoint.Chart("bar-chart", df, roles={...}, options={...})` is the same thing by
54
+ name, and `silverpoint.catalog` is the catalog itself. Data can be rows, a mapping of columns, a pandas
55
+ or polars DataFrame or a pyarrow Table; dates become ISO strings and NaN/NaT become `None`.
56
+
57
+ A role, column, option or value the catalog does not know raises `SpecError` naming the closest valid
58
+ names, before any HTML is written.
59
+
60
+ ## Jupyter, JupyterLab, VS Code
61
+
62
+ A chart as a cell's value draws itself: each one is a sandboxed `<iframe srcdoc>` holding the inline
63
+ page, so it needs no trusted notebook. `silverpoint.notebook.enable()` shows the script once and writes
64
+ later charts as `<silverpoint-chart>` elements, for front ends that run scripts in outputs.
65
+
66
+ ## Databricks
67
+
68
+ A Spark DataFrame goes straight into a builder, and a chart as a cell's value draws itself:
69
+
70
+ ```python
71
+ from pyspark.sql import functions as F
72
+
73
+ import silverpoint
74
+
75
+ by_hour = (
76
+ spark.read.table("samples.nyctaxi.trips")
77
+ .groupBy(F.hour("tpep_pickup_datetime").alias("hour"))
78
+ .agg(F.count("*").alias("trips"))
79
+ .orderBy("hour")
80
+ )
81
+ silverpoint.line_chart(by_hour, x="hour", value="trips", title="Trips per pickup hour")
82
+ ```
83
+
84
+ `displayHTML(chart.to_html(render="client"))` draws a chart anywhere in a cell, so one cell can draw
85
+ several. pandas-on-Spark DataFrames and the `Row`s of `collect()` work too.
86
+
87
+ - **Rows.** At most `silverpoint.data.SPARK_ROW_LIMIT` (10,000) rows are read, through `limit`, so a
88
+ large table never reaches the driver; a bigger DataFrame raises `ValueError`. Aggregate in Spark
89
+ first.
90
+ - **Size.** Each chart carries its own copy of the script (about 0.5 MB; 1.1 MB with 10,000 rows).
91
+ One cell's output may be 10 MB by default on Runtime 17+ (`%set_cell_max_output_size_in_mb`
92
+ sets 1–20 MB), and a notebook keeps about fifteen charts before Databricks stops saving its
93
+ revision snapshots (10 MB).
94
+ - `silverpoint.notebook.enable()` has no effect there: each output is its own frame.
95
+
96
+ [`examples/notebooks/databricks.py`](examples/notebooks/databricks.py) is a notebook to import
97
+ (Databricks source format) that runs on `samples.nyctaxi.trips`.
98
+
99
+ ## Flask
100
+
101
+ ```python
102
+ from silverpoint.contrib.flask import Silverpoint
103
+
104
+ Silverpoint(app) # serves the script at /_silverpoint/, immutable, with its integrity
105
+ ```
106
+
107
+ ```jinja
108
+ <head>{{ silverpoint_script() }}</head>
109
+ <body>{{ silverpoint_chart(chart) }}</body>
110
+ ```
111
+
112
+ ## Django
113
+
114
+ Add `"silverpoint.contrib.django"` to `INSTALLED_APPS` (with `django.contrib.staticfiles`), then:
115
+
116
+ ```django
117
+ {% load silverpoint %}
118
+ <head>{% silverpoint_script %}</head>
119
+ <body>{% silverpoint_chart chart %}</body>
120
+ ```
121
+
122
+ The Flask and Django markup has no inline script or style: it renders under
123
+ `Content-Security-Policy: script-src 'self'; style-src 'self'`.
124
+
125
+ ## HTML
126
+
127
+ `to_html(full_document=True, script="inline", render="auto")`:
128
+
129
+ - `script`: `"inline"` (the vendored file in the page), `"none"` (the page loads it) or a URL your
130
+ application serves. A CDN URL is never written.
131
+ - `render`: `"server"` draws the chart in Node with the library's `renderToHTML` (byte-identical to
132
+ its goldens; the script then adopts it); `"client"` writes only the spec and the script draws it;
133
+ `"auto"` picks `server` when Node is on PATH.
134
+
135
+ `silverpoint.static_path()` is the folder holding `silverpoint-embed.full.js`, for any framework.
136
+
137
+ ## Development
138
+
139
+ ```sh
140
+ uv sync
141
+ uv run pytest # browser tests: uv run playwright install chromium
142
+ uv run ruff check . && uv run ruff format --check .
143
+ uv run python scripts/vendor.py --check # the vendored files against integrity.json
144
+ uv run python scripts/make_builders.py --check # the generated builders are current
145
+ node scripts/conformance.mjs # the library's conformance kit, in Node
146
+ ```
147
+
148
+ A new silverpoint version: `uv run python scripts/vendor.py X.Y.Z` (the release's hosts kit), then
149
+ `uv run python scripts/make_builders.py`, and set `version` in `pyproject.toml` to X.Y.Z.
150
+
151
+ Licence: MIT. The vendored script embeds EB Garamond (SIL OFL 1.1, `_vendor/OFL.txt`).
@@ -0,0 +1,128 @@
1
+ # silverpoint
2
+
3
+ silverpoint charts from Python — in notebooks, Flask, Django and static HTML. No picture is made in
4
+ Python: the package builds a chart spec and the markup that carries it, and the library's own
5
+ standalone script (`@silverpoint/embed`, vendored version for version) draws it.
6
+
7
+ ```sh
8
+ pip install silverpoint # no dependencies
9
+ pip install "silverpoint[flask]" # or [django]
10
+ ```
11
+
12
+ `silverpoint` X.Y.Z vendors `@silverpoint/embed` X.Y.Z (`silverpoint.SILVERPOINT_VERSION`).
13
+
14
+ ## A chart
15
+
16
+ ```python
17
+ import pandas as pd
18
+ import silverpoint
19
+
20
+ df = pd.DataFrame({"team": ["A", "B", "C"], "wins": [12, 9, 15]})
21
+ chart = silverpoint.bar_chart(df, x="team", value="wins", orientation="rows", title="Wins")
22
+
23
+ chart.spec # the ChartSpec, a dict
24
+ chart.to_html() # a complete, self-contained page (the script inlined; no network)
25
+ chart.to_svg() # the library's renderToSVG bytes (needs Node 20+ on PATH)
26
+ ```
27
+
28
+ There is one builder per chart a table can feed — `silverpoint.line_chart`, `heatmap_chart`,
29
+ `sankey_chart`, … — with one keyword per role (a column name) and per option, generated from the
30
+ host catalog. `silverpoint.Chart("bar-chart", df, roles={...}, options={...})` is the same thing by
31
+ name, and `silverpoint.catalog` is the catalog itself. Data can be rows, a mapping of columns, a pandas
32
+ or polars DataFrame or a pyarrow Table; dates become ISO strings and NaN/NaT become `None`.
33
+
34
+ A role, column, option or value the catalog does not know raises `SpecError` naming the closest valid
35
+ names, before any HTML is written.
36
+
37
+ ## Jupyter, JupyterLab, VS Code
38
+
39
+ A chart as a cell's value draws itself: each one is a sandboxed `<iframe srcdoc>` holding the inline
40
+ page, so it needs no trusted notebook. `silverpoint.notebook.enable()` shows the script once and writes
41
+ later charts as `<silverpoint-chart>` elements, for front ends that run scripts in outputs.
42
+
43
+ ## Databricks
44
+
45
+ A Spark DataFrame goes straight into a builder, and a chart as a cell's value draws itself:
46
+
47
+ ```python
48
+ from pyspark.sql import functions as F
49
+
50
+ import silverpoint
51
+
52
+ by_hour = (
53
+ spark.read.table("samples.nyctaxi.trips")
54
+ .groupBy(F.hour("tpep_pickup_datetime").alias("hour"))
55
+ .agg(F.count("*").alias("trips"))
56
+ .orderBy("hour")
57
+ )
58
+ silverpoint.line_chart(by_hour, x="hour", value="trips", title="Trips per pickup hour")
59
+ ```
60
+
61
+ `displayHTML(chart.to_html(render="client"))` draws a chart anywhere in a cell, so one cell can draw
62
+ several. pandas-on-Spark DataFrames and the `Row`s of `collect()` work too.
63
+
64
+ - **Rows.** At most `silverpoint.data.SPARK_ROW_LIMIT` (10,000) rows are read, through `limit`, so a
65
+ large table never reaches the driver; a bigger DataFrame raises `ValueError`. Aggregate in Spark
66
+ first.
67
+ - **Size.** Each chart carries its own copy of the script (about 0.5 MB; 1.1 MB with 10,000 rows).
68
+ One cell's output may be 10 MB by default on Runtime 17+ (`%set_cell_max_output_size_in_mb`
69
+ sets 1–20 MB), and a notebook keeps about fifteen charts before Databricks stops saving its
70
+ revision snapshots (10 MB).
71
+ - `silverpoint.notebook.enable()` has no effect there: each output is its own frame.
72
+
73
+ [`examples/notebooks/databricks.py`](examples/notebooks/databricks.py) is a notebook to import
74
+ (Databricks source format) that runs on `samples.nyctaxi.trips`.
75
+
76
+ ## Flask
77
+
78
+ ```python
79
+ from silverpoint.contrib.flask import Silverpoint
80
+
81
+ Silverpoint(app) # serves the script at /_silverpoint/, immutable, with its integrity
82
+ ```
83
+
84
+ ```jinja
85
+ <head>{{ silverpoint_script() }}</head>
86
+ <body>{{ silverpoint_chart(chart) }}</body>
87
+ ```
88
+
89
+ ## Django
90
+
91
+ Add `"silverpoint.contrib.django"` to `INSTALLED_APPS` (with `django.contrib.staticfiles`), then:
92
+
93
+ ```django
94
+ {% load silverpoint %}
95
+ <head>{% silverpoint_script %}</head>
96
+ <body>{% silverpoint_chart chart %}</body>
97
+ ```
98
+
99
+ The Flask and Django markup has no inline script or style: it renders under
100
+ `Content-Security-Policy: script-src 'self'; style-src 'self'`.
101
+
102
+ ## HTML
103
+
104
+ `to_html(full_document=True, script="inline", render="auto")`:
105
+
106
+ - `script`: `"inline"` (the vendored file in the page), `"none"` (the page loads it) or a URL your
107
+ application serves. A CDN URL is never written.
108
+ - `render`: `"server"` draws the chart in Node with the library's `renderToHTML` (byte-identical to
109
+ its goldens; the script then adopts it); `"client"` writes only the spec and the script draws it;
110
+ `"auto"` picks `server` when Node is on PATH.
111
+
112
+ `silverpoint.static_path()` is the folder holding `silverpoint-embed.full.js`, for any framework.
113
+
114
+ ## Development
115
+
116
+ ```sh
117
+ uv sync
118
+ uv run pytest # browser tests: uv run playwright install chromium
119
+ uv run ruff check . && uv run ruff format --check .
120
+ uv run python scripts/vendor.py --check # the vendored files against integrity.json
121
+ uv run python scripts/make_builders.py --check # the generated builders are current
122
+ node scripts/conformance.mjs # the library's conformance kit, in Node
123
+ ```
124
+
125
+ A new silverpoint version: `uv run python scripts/vendor.py X.Y.Z` (the release's hosts kit), then
126
+ `uv run python scripts/make_builders.py`, and set `version` in `pyproject.toml` to X.Y.Z.
127
+
128
+ Licence: MIT. The vendored script embeds EB Garamond (SIL OFL 1.1, `_vendor/OFL.txt`).
@@ -0,0 +1,69 @@
1
+ [project]
2
+ name = "silverpoint"
3
+ version = "0.11.0"
4
+ description = "silverpoint charts from Python: notebooks, Flask, Django and static HTML, drawn by the library's own standalone script."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE", "src/silverpoint/_vendor/OFL.txt"]
8
+ authors = [{ name = "Ernesto Crespo", email = "ecrespo@gmail.com" }]
9
+ requires-python = ">=3.10"
10
+ dependencies = []
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Framework :: Django",
14
+ "Framework :: Flask",
15
+ "Framework :: Jupyter",
16
+ "Programming Language :: Python :: 3",
17
+ "Topic :: Scientific/Engineering :: Visualization",
18
+ ]
19
+
20
+ [project.optional-dependencies]
21
+ flask = ["flask>=2.3"]
22
+ django = ["django>=4.2"]
23
+
24
+ [project.urls]
25
+ Homepage = "https://github.com/ecrespo/silverpoint-python"
26
+ Library = "https://github.com/ecrespo/silverpoint"
27
+
28
+ [dependency-groups]
29
+ dev = [
30
+ "pytest>=8",
31
+ "ruff>=0.8",
32
+ "pandas>=2",
33
+ "polars>=1",
34
+ "pyarrow>=15",
35
+ "flask>=2.3",
36
+ "django>=4.2",
37
+ "playwright>=1.49",
38
+ ]
39
+ # delta-001: Spark inputs and the Databricks example, tested against a local Spark session (needs Java 17+).
40
+ spark = [
41
+ "pyspark>=3.5",
42
+ ]
43
+
44
+ [build-system]
45
+ requires = ["hatchling>=1.26"]
46
+ build-backend = "hatchling.build"
47
+
48
+ [tool.hatch.build.targets.wheel]
49
+ packages = ["src/silverpoint"]
50
+
51
+ [tool.hatch.build.targets.sdist]
52
+ include = ["src/silverpoint", "scripts", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
53
+
54
+ [tool.ruff]
55
+ line-length = 110
56
+ target-version = "py310"
57
+ extend-exclude = ["src/silverpoint/_vendor", "src/silverpoint/_builders.py", "src/silverpoint/_builders.pyi"] # generated
58
+
59
+ [tool.ruff.lint]
60
+ select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
61
+ ignore = ["RUF001", "RUF002", "RUF003", "E501"] # the formatter owns line length
62
+
63
+ [tool.pytest.ini_options]
64
+ testpaths = ["tests"]
65
+ addopts = "-ra"
66
+ markers = ["node: needs Node 20+ on PATH", "browser: needs Playwright Chromium"]
67
+
68
+ [tool.ruff.lint.isort]
69
+ known-first-party = ["silverpoint"]
@@ -0,0 +1,18 @@
1
+ // The conformance kit (silverpoint REQ-666) against the vendored module build, in Node (PY-REQ-015).
2
+ // The cases are the pinned `conformance.json`; exit code 1 on any failure.
3
+ import { readFileSync } from 'node:fs';
4
+ import { fileURLToPath } from 'node:url';
5
+
6
+ const vendor = new URL('../src/silverpoint/_vendor/', import.meta.url);
7
+ const sp = await import(new URL('silverpoint-embed.full.mjs', vendor).href);
8
+ const cases = JSON.parse(readFileSync(fileURLToPath(new URL('conformance.json', vendor)), 'utf8'));
9
+
10
+ const result = await sp.conformance((spec) => {
11
+ const out = sp.renderToSVG(spec);
12
+ if (!out.ok) throw new Error(sp.specErrorMessage ? sp.specErrorMessage(out.error) : JSON.stringify(out.error));
13
+ return out.value.svg;
14
+ }, undefined, cases);
15
+
16
+ console.log(`conformance ${cases.version}: ${result.passed} passed, ${result.failed.length} failed`);
17
+ for (const f of result.failed) console.log(` ${f.name}: expected ${f.expected}, got ${f.actual}`);
18
+ process.exit(result.failed.length === 0 && cases.version === sp.version ? 0 : 1);