report-toolkit 0.1.0__tar.gz

report_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heladio Lopes
+
+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.

report_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: report-toolkit
+Version: 0.1.0
+Summary: Compose analytical reports in Python and render them as HTML
+Author: Heladio Lopes
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mistune<4,>=3
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == "pandas"
+Provides-Extra: altair
+Requires-Dist: altair>=5; extra == "altair"
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib>=3.7; extra == "matplotlib"
+Provides-Extra: plotly
+Requires-Dist: plotly>=5; extra == "plotly"
+Provides-Extra: templates
+Requires-Dist: PyYAML<7,>=6; extra == "templates"
+Provides-Extra: all
+Requires-Dist: pandas>=2; extra == "all"
+Requires-Dist: altair>=5; extra == "all"
+Requires-Dist: matplotlib>=3.7; extra == "all"
+Requires-Dist: plotly>=5; extra == "all"
+Requires-Dist: PyYAML<7,>=6; extra == "all"
+Provides-Extra: offline
+Requires-Dist: altair>=5; extra == "offline"
+Requires-Dist: vl-convert-python>=1; extra == "offline"
+Dynamic: license-file
+
+# report-toolkit
+
+Build analytical reports in Python or Markdown templates and export styled HTML
+with tables, charts, sections, and column layouts.
+
+## Install
+
+Install the package:
+
+```bash
+pip install report-toolkit
+```
+
+From a checkout:
+
+```bash
+uv sync
+```
+
+For tables, charts, and YAML template metadata, use `uv sync --extra all`.
+Individual extras are `pandas`, `altair`, `matplotlib`, `plotly`, and `templates`;
+`offline` additionally supports embedding Altair's JavaScript.
+
+## Quick start
+
+```python
+from report_toolkit import Report
+
+report = Report('Sales review', author='Report author')
+report.heading(1, 'Summary')
+report.markdown('Revenue **increased** this month.')
+report.unordered(['Review the results', 'Plan the next month'])
+report.write('sales.html', toc=True)
+```
+
+Open `sales.html` in a browser.
+
+## Documentation
+
+Start with [Getting Started](docs/getting-started.md), use
+[Common Tasks](docs/common-tasks.md) for recipes, and consult the
+[API Reference](docs/api-reference.md) for signatures and constraints.
+
+## Two equivalent examples
+
+[Python composition](examples/sales_report.py) and
+[Markdown templates](examples/template_report.py), using
+[monthly_sales.md](examples/monthly_sales.md), generate the same sales report.
+They demonstrate shared text, list, table, chart, and layout capabilities.
+
+```bash
+uv run --extra all python examples/sales_report.py
+uv run --extra all python examples/template_report.py
+```
+
+Each prints its report tree and output path. Open `examples/sales_report.html`
+and `examples/template_report.html` in a browser. Altair and Plotly charts
+require network access for their JavaScript. Raw HTML is covered in the
+[recipes](docs/common-tasks.md#insert-trusted-html), since templates escape it.
+
+## Themes
+
+Export with `style={'mode': 'dark'}`, or use `style={'mode': 'auto'}` to follow
+the reader's system appearance. Choose `slate`, `azure`, `parchment`, or `ember`
+with `style={'palette': 'parchment'}`. The default preserves the previous light
+appearance. Define reusable `Style`, `Theme`, and `Palette` objects;
+see [Themes](docs/themes.md) for customization and migration from `theme=`, and the
+[theme gallery](examples/theme_gallery.py).
+
+## Development
+
+```bash
+uv run --extra all pytest
+uv run --extra all make test
+uv run ruff check .
+uv run ruff format --check .
+uv run make build
+```
+
+`make test` and pytest both run the unittest-compatible suite, including the
+example integration test. Optional integration tests skip when dependencies are absent.
+Version tags run tests, Ruff lint, and a format check before the release workflow
+builds and publishes to PyPI.
+
+Theming code lives in `src/report_toolkit/themes/`: structural defaults belong in
+`theme.py`, color values in `palette.py`, and configuration normalization in
+`style.py`. Edit `src/report_toolkit/resources/report.css` for static report CSS;
+HTML-specific scoping and dynamic style generation live in the writer. CSS is
+packaged with the library and embedded in exported HTML. After changing resources
+or package-data settings, run `make build` and verify the built distributions.
+
+Artifact layout is configurable per item:
+
+```python
+report.add(table, center=True)
+report.add(chart, width='full', expand='always')
+report.write('report.html', pretty=True)  # Compact markup is the default.
+```
+
+Tables and charts use native width by default. Oversized artifacts offer an
+centered expanded view with zoom controls and a Close icon. Zoom is available
+only in the expanded preview.
+See [artifact options](docs/api-reference.md#analytical-artifacts) for details.

report_toolkit-0.1.0/README.md

@@ -0,0 +1,103 @@
+# report-toolkit
+
+Build analytical reports in Python or Markdown templates and export styled HTML
+with tables, charts, sections, and column layouts.
+
+## Install
+
+Install the package:
+
+```bash
+pip install report-toolkit
+```
+
+From a checkout:
+
+```bash
+uv sync
+```
+
+For tables, charts, and YAML template metadata, use `uv sync --extra all`.
+Individual extras are `pandas`, `altair`, `matplotlib`, `plotly`, and `templates`;
+`offline` additionally supports embedding Altair's JavaScript.
+
+## Quick start
+
+```python
+from report_toolkit import Report
+
+report = Report('Sales review', author='Report author')
+report.heading(1, 'Summary')
+report.markdown('Revenue **increased** this month.')
+report.unordered(['Review the results', 'Plan the next month'])
+report.write('sales.html', toc=True)
+```
+
+Open `sales.html` in a browser.
+
+## Documentation
+
+Start with [Getting Started](docs/getting-started.md), use
+[Common Tasks](docs/common-tasks.md) for recipes, and consult the
+[API Reference](docs/api-reference.md) for signatures and constraints.
+
+## Two equivalent examples
+
+[Python composition](examples/sales_report.py) and
+[Markdown templates](examples/template_report.py), using
+[monthly_sales.md](examples/monthly_sales.md), generate the same sales report.
+They demonstrate shared text, list, table, chart, and layout capabilities.
+
+```bash
+uv run --extra all python examples/sales_report.py
+uv run --extra all python examples/template_report.py
+```
+
+Each prints its report tree and output path. Open `examples/sales_report.html`
+and `examples/template_report.html` in a browser. Altair and Plotly charts
+require network access for their JavaScript. Raw HTML is covered in the
+[recipes](docs/common-tasks.md#insert-trusted-html), since templates escape it.
+
+## Themes
+
+Export with `style={'mode': 'dark'}`, or use `style={'mode': 'auto'}` to follow
+the reader's system appearance. Choose `slate`, `azure`, `parchment`, or `ember`
+with `style={'palette': 'parchment'}`. The default preserves the previous light
+appearance. Define reusable `Style`, `Theme`, and `Palette` objects;
+see [Themes](docs/themes.md) for customization and migration from `theme=`, and the
+[theme gallery](examples/theme_gallery.py).
+
+## Development
+
+```bash
+uv run --extra all pytest
+uv run --extra all make test
+uv run ruff check .
+uv run ruff format --check .
+uv run make build
+```
+
+`make test` and pytest both run the unittest-compatible suite, including the
+example integration test. Optional integration tests skip when dependencies are absent.
+Version tags run tests, Ruff lint, and a format check before the release workflow
+builds and publishes to PyPI.
+
+Theming code lives in `src/report_toolkit/themes/`: structural defaults belong in
+`theme.py`, color values in `palette.py`, and configuration normalization in
+`style.py`. Edit `src/report_toolkit/resources/report.css` for static report CSS;
+HTML-specific scoping and dynamic style generation live in the writer. CSS is
+packaged with the library and embedded in exported HTML. After changing resources
+or package-data settings, run `make build` and verify the built distributions.
+
+Artifact layout is configurable per item:
+
+```python
+report.add(table, center=True)
+report.add(chart, width='full', expand='always')
+report.write('report.html', pretty=True)  # Compact markup is the default.
+```
+
+Tables and charts use native width by default. Oversized artifacts offer an
+centered expanded view with zoom controls and a Close icon. Zoom is available
+only in the expanded preview.
+See [artifact options](docs/api-reference.md#analytical-artifacts) for details.

report_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "report-toolkit"
+version = "0.1.0"
+description = "Compose analytical reports in Python and render them as HTML"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Heladio Lopes"}]
+dependencies = ["mistune>=3,<4"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=2"]
+altair = ["altair>=5"]
+matplotlib = ["matplotlib>=3.7"]
+plotly = ["plotly>=5"]
+templates = ["PyYAML>=6,<7"]
+all = ["pandas>=2", "altair>=5", "matplotlib>=3.7", "plotly>=5", "PyYAML>=6,<7"]
+offline = ["altair>=5", "vl-convert-python>=1"]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.9", "build>=1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+report_toolkit = ["resources/*.css", "resources/*.js"]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["E402"]
+"**/{tests,docs,tools}/*" = ["E402"]
+

report_toolkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

report_toolkit-0.1.0/src/report_toolkit/__init__.py

@@ -0,0 +1,44 @@
+"""Compose analytical reports and render them as HTML."""
+
+from ._template import TemplateError
+from .adapters import Adapter, AdapterRegistry, RenderedArtifact, default_registry
+from .composer import Report
+from .model import (
+    Artifact,
+    Columns,
+    Container,
+    Document,
+    List,
+    Markdown,
+    Node,
+    Panel,
+    RawHTML,
+    Section,
+)
+from .themes import Palette, Style, Theme, get_palette, get_theme
+from .writer import HTMLWriter
+
+__all__ = [
+    'Adapter',
+    'AdapterRegistry',
+    'Artifact',
+    'Columns',
+    'Container',
+    'Document',
+    'HTMLWriter',
+    'List',
+    'Markdown',
+    'Node',
+    'Palette',
+    'Panel',
+    'RawHTML',
+    'RenderedArtifact',
+    'Report',
+    'Section',
+    'Style',
+    'TemplateError',
+    'Theme',
+    'default_registry',
+    'get_palette',
+    'get_theme',
+]