caxton 0.1.0__tar.gz

caxton-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Byte-compiled files and caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# Environments
+.venv/
+venv/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Documentation
+site/
+.cache/
+
+# Coverage
+.coverage
+coverage/
+coverage.xml
+htmlcov/
+
+# IDE and operating system files
+.idea/
+.vscode/
+.DS_Store
+
+backend/stations.sqlite3
+**/output/**

caxton-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+<!-- towncrier release notes start -->
+
+## [0.1.0] - 2026-08-19
+
+### Features
+
+- Add public spreadsheet API with data-source ingestion, semantic types, references, validation, styles, formulas,
+  streaming, and direct XLSX output ([#2](https://github.com/dzhalaevd/caxton/issues/2))
+- Add declarative spreadsheet blocks: `title`, `spacer`, `image`, `chart` and the `stack` flow container.
+  A sheet now places its blocks sequentially without manual `start_row` arithmetic, explicit `anchor` stays
+  available as a layout escape hatch, overlapping placed blocks are rejected during validation, and the
+  XlsxWriter backend lowers titles, images and the supported chart
+  kinds. ([#3](https://github.com/dzhalaevd/caxton/issues/3))
+- Add grouped reports and pivot matrices with flexible aggregates, typed keys,
+  and single-pass buffering. Enforce XLSX bounds and avoid dense sparse
+  materialization. ([#4](https://github.com/dzhalaevd/caxton/issues/4))
+- Add a format-independent template specification and a dedicated XLSX template
+  route with named-range table targets, styled block repetition, OpenPyXL hooks,
+  and pivot package post-processing. ([#5](https://github.com/dzhalaevd/caxton/issues/5))
+
+### Documentation
+
+- Added a MkDocs documentation site with a Material theme and a mkdocstrings API
+  reference, a `docs` dependency group, `docs` and `docs-serve` tox environments, and a
+  GitHub Pages deployment workflow that builds with `--strict`. ([#6](https://github.com/dzhalaevd/caxton/issues/6))

caxton-0.1.0/LICENSE

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

caxton-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: caxton
+Version: 0.1.0
+Summary: A declarative way to describe files in Python
+Project-URL: Homepage, https://github.com/dzhalaevd/caxton
+Project-URL: Repository, https://github.com/dzhalaevd/caxton
+Project-URL: Issues, https://github.com/dzhalaevd/caxton/issues
+Author: David Dzhalaev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: declarative,files,validation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: openpyxl<4.0,>=3.1.5
+Requires-Dist: xlsxwriter<4.0,>=3.2.9
+Provides-Extra: hypothesis
+Requires-Dist: hypothesis<7.0,>=6.165; extra == 'hypothesis'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Caxton
+
+**Declarative document generation for Python**
+
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stars][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+
+</div>
+
+---
+
+| 🏗️ This project is currently under development and is **not ready for production use**. |
+|------------------------------------------------------------------------------------------|
+
+## :mag: About
+
+Declarative Python library for describing and generating documents
+from application data. Users define the document structure and semantics, while
+renderers handle output formats and backend-specific details.
+
+## :alembic: Built With
+
+![Python][python-shield]
+![Excel][excel-shield]
+![uv][uv-shield]
+![wps][wemake-shield]
+
+## Quick start
+
+```python
+from caxton import render, sheet, spreadsheet, table, text, write
+
+rows = [{"name": "Ada Lovelace"}, {"name": "Grace Hopper"}]
+
+report = spreadsheet(
+    sheet(
+        "People",
+        table(
+            rows,
+            text("name").titled("Name"),
+        ),
+    ),
+)
+
+result = render(report)
+
+write(report, "people.xlsx")
+```
+
+More examples are available in the [example projects](example).
+
+## :books: Documentation
+
+Full documentation is at [dzhalaevd.github.io/caxton](https://dzhalaevd.github.io/caxton/).
+
+## :scroll: Licensing
+
+- The project is licensed under the [MIT](LICENSE)
+
+<div align="center">
+
+### Works on Open-Source
+
+If you find this project interesting, consider giving it a ⭐
+
+</div>
+
+
+[contributors-shield]: https://img.shields.io/github/contributors/dzhalaevd/caxton.svg?style=for-the-badge
+
+[contributors-url]: https://github.com/dzhalaevd/caxton/graphs/contributors
+
+[forks-shield]: https://img.shields.io/github/forks/dzhalaevd/caxton.svg?style=for-the-badge
+
+[forks-url]: https://github.com/dzhalaevd/caxton/network/members
+
+[stars-shield]: https://img.shields.io/github/stars/dzhalaevd/caxton.svg?style=for-the-badge
+
+[stars-url]: https://github.com/dzhalaevd/caxton/stargazers
+
+[issues-shield]: https://img.shields.io/github/issues/dzhalaevd/caxton.svg?style=for-the-badge
+
+[issues-url]: https://github.com/dzhalaevd/caxton/issues
+
+[python-shield]: https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54
+
+[uv-shield]: https://img.shields.io/badge/uv-%23DE5FE9.svg?style=for-the-badge&logo=uv&logoColor=white
+
+[fastapi-shield]: https://img.shields.io/badge/FastAPI-005571.svg?style=for-the-badge&logo=fastapi
+
+[sqlalchemy-shield]: https://img.shields.io/badge/sqlalchemy-%23D71F00.svg?style=for-the-badge&logo=sqlalchemy&logoColor=white
+
+[pytest-shield]: https://img.shields.io/badge/pytest-%23ffffff.svg?style=for-the-badge&logo=pytest&logoColor=2f9fe3
+
+[telegram-shield]: https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white
+
+[react-shield]: https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB
+
+[typescript-shield]: https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white
+
+[vite-shield]: https://img.shields.io/badge/vite-%23646CFF.svg?style=for-the-badge&logo=vite&logoColor=white
+
+[postgres-shield]: https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge&logo=postgresql&logoColor=white
+
+[otel-shield]: https://img.shields.io/badge/OpenTelemetry-FFFFFF?style=for-the-badge&logo=opentelemetry&logoColor=black
+
+[grafana-shield]: https://img.shields.io/badge/grafana-%23F46800.svg?style=for-the-badge&logo=grafana&logoColor=white
+
+[prometheus-shield]: https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge&logo=Prometheus&logoColor=white
+
+[docker-shield]: https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white
+
+[wemake-shield]: https://img.shields.io/badge/Style_WPS-%23000000.svg?style=for-the-badge&logo=python&logoColor=white
+
+[excel-shield]: https://img.shields.io/badge/Microsoft_Excel-217346?style=for-the-badge&logo=microsoft-excel&logoColor=white

caxton-0.1.0/README.md

@@ -0,0 +1,119 @@
+<div align="center">
+
+# Caxton
+
+**Declarative document generation for Python**
+
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stars][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+
+</div>
+
+---
+
+| 🏗️ This project is currently under development and is **not ready for production use**. |
+|------------------------------------------------------------------------------------------|
+
+## :mag: About
+
+Declarative Python library for describing and generating documents
+from application data. Users define the document structure and semantics, while
+renderers handle output formats and backend-specific details.
+
+## :alembic: Built With
+
+![Python][python-shield]
+![Excel][excel-shield]
+![uv][uv-shield]
+![wps][wemake-shield]
+
+## Quick start
+
+```python
+from caxton import render, sheet, spreadsheet, table, text, write
+
+rows = [{"name": "Ada Lovelace"}, {"name": "Grace Hopper"}]
+
+report = spreadsheet(
+    sheet(
+        "People",
+        table(
+            rows,
+            text("name").titled("Name"),
+        ),
+    ),
+)
+
+result = render(report)
+
+write(report, "people.xlsx")
+```
+
+More examples are available in the [example projects](example).
+
+## :books: Documentation
+
+Full documentation is at [dzhalaevd.github.io/caxton](https://dzhalaevd.github.io/caxton/).
+
+## :scroll: Licensing
+
+- The project is licensed under the [MIT](LICENSE)
+
+<div align="center">
+
+### Works on Open-Source
+
+If you find this project interesting, consider giving it a ⭐
+
+</div>
+
+
+[contributors-shield]: https://img.shields.io/github/contributors/dzhalaevd/caxton.svg?style=for-the-badge
+
+[contributors-url]: https://github.com/dzhalaevd/caxton/graphs/contributors
+
+[forks-shield]: https://img.shields.io/github/forks/dzhalaevd/caxton.svg?style=for-the-badge
+
+[forks-url]: https://github.com/dzhalaevd/caxton/network/members
+
+[stars-shield]: https://img.shields.io/github/stars/dzhalaevd/caxton.svg?style=for-the-badge
+
+[stars-url]: https://github.com/dzhalaevd/caxton/stargazers
+
+[issues-shield]: https://img.shields.io/github/issues/dzhalaevd/caxton.svg?style=for-the-badge
+
+[issues-url]: https://github.com/dzhalaevd/caxton/issues
+
+[python-shield]: https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54
+
+[uv-shield]: https://img.shields.io/badge/uv-%23DE5FE9.svg?style=for-the-badge&logo=uv&logoColor=white
+
+[fastapi-shield]: https://img.shields.io/badge/FastAPI-005571.svg?style=for-the-badge&logo=fastapi
+
+[sqlalchemy-shield]: https://img.shields.io/badge/sqlalchemy-%23D71F00.svg?style=for-the-badge&logo=sqlalchemy&logoColor=white
+
+[pytest-shield]: https://img.shields.io/badge/pytest-%23ffffff.svg?style=for-the-badge&logo=pytest&logoColor=2f9fe3
+
+[telegram-shield]: https://img.shields.io/badge/Telegram-2CA5E0?style=for-the-badge&logo=telegram&logoColor=white
+
+[react-shield]: https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB
+
+[typescript-shield]: https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white
+
+[vite-shield]: https://img.shields.io/badge/vite-%23646CFF.svg?style=for-the-badge&logo=vite&logoColor=white
+
+[postgres-shield]: https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge&logo=postgresql&logoColor=white
+
+[otel-shield]: https://img.shields.io/badge/OpenTelemetry-FFFFFF?style=for-the-badge&logo=opentelemetry&logoColor=black
+
+[grafana-shield]: https://img.shields.io/badge/grafana-%23F46800.svg?style=for-the-badge&logo=grafana&logoColor=white
+
+[prometheus-shield]: https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge&logo=Prometheus&logoColor=white
+
+[docker-shield]: https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white
+
+[wemake-shield]: https://img.shields.io/badge/Style_WPS-%23000000.svg?style=for-the-badge&logo=python&logoColor=white
+
+[excel-shield]: https://img.shields.io/badge/Microsoft_Excel-217346?style=for-the-badge&logo=microsoft-excel&logoColor=white

caxton-0.1.0/changelog.d/README.md

@@ -0,0 +1,35 @@
+# Changelog fragments
+
+Towncrier reads release notes from this directory and renders them into
+`CHANGELOG.md`.
+
+Create one fragment per change:
+
+```text
+<issue-id>.<type>.md
+```
+
+Supported types are `breaking`, `feature`, `bugfix`, `doc`, `generation` and
+`ci`. For example: `123.feature.md`.
+
+Create a fragment with Towncrier:
+
+```bash
+hatch run towncrier create --content "Describe the user-visible change." 123.feature.md
+```
+
+Use a GitHub issue or pull request number when one exists. Otherwise, prefix a
+short unique identifier with `+`, for example `+typing.bugfix.md`.
+
+Preview the next changelog entry without modifying files:
+
+```bash
+hatch run changelog-draft
+```
+
+Build the changelog during a release, using the version from
+`src/caxton/__version__.py`:
+
+```bash
+hatch run changelog-build "$(hatch version)"
+```

caxton-0.1.0/pyproject.toml

@@ -0,0 +1,239 @@
+[build-system]
+requires = ["hatchling>=1.31,<2.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "caxton"
+dynamic = ["version"]
+description = "A declarative way to describe files in Python"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "David Dzhalaev" },
+]
+keywords = ["files", "declarative", "validation"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "xlsxwriter>=3.2.9,<4.0",
+    "openpyxl>=3.1.5,<4.0",
+]
+
+[project.optional-dependencies]
+hypothesis = ["hypothesis>=6.165,<7.0"]
+
+[project.urls]
+Homepage = "https://github.com/dzhalaevd/caxton"
+Repository = "https://github.com/dzhalaevd/caxton"
+Issues = "https://github.com/dzhalaevd/caxton/issues"
+
+[tool.hatch.version]
+path = "src/caxton/__version__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/caxton"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/LICENSE",
+    "/CHANGELOG.md",
+    "/README.md",
+    "/changelog.d",
+    "/pyproject.toml",
+    "/setup.cfg",
+    "/scripts",
+    "/src",
+    "/tests",
+]
+
+[tool.hatch.envs.default]
+dependency-groups = ["dev"]
+
+[tool.hatch.envs.default.scripts]
+lint = "flake8 ."
+typecheck = "mypy"
+test = "pytest {args:tests}"
+docs = "mkdocs build --strict"
+docs-serve = "mkdocs serve {args}"
+api-compatibility = "griffe check --search src caxton {args}"
+check = [
+    "flake8 .",
+    "mypy",
+    "pytest",
+    "towncrier build --draft",
+]
+changelog-draft = "towncrier build --draft"
+changelog-build = "towncrier build --yes --version {args}"
+validate-changelog = "python scripts/validate_files.py {args}"
+bump-version = "python scripts/bump_version.py {args}"
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["caxton"]
+
+[tool.coverage.paths]
+source = [
+    "src/caxton",
+    "*/.tox/*/lib/python*/site-packages/caxton",
+    "*/.tox/*/Lib/site-packages/caxton",
+    "*\\.tox\\*\\Lib\\site-packages\\caxton",
+]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true
+
+[tool.deptry]
+known_first_party = ["caxton"]
+
+[tool.importlinter]
+root_packages = ["caxton"]
+
+[[tool.importlinter.contracts]]
+name = "Core does not depend on orchestration"
+type = "forbidden"
+source_modules = ["caxton.core"]
+forbidden_modules = [
+    "caxton.api",
+    "caxton._internal",
+    "caxton.testing",
+]
+
+[[tool.importlinter.contracts]]
+name = "Internal implementation does not depend on public API"
+type = "forbidden"
+source_modules = ["caxton._internal"]
+forbidden_modules = ["caxton.api"]
+
+[[tool.importlinter.contracts]]
+name = "Internal spreadsheet pipeline is layered"
+type = "layers"
+layers = [
+    "caxton._internal.compiler",
+    "caxton._internal.validation",
+    "caxton._internal.layout",
+    "caxton._internal.aggregation",
+    "caxton._internal.semantic",
+    "caxton._internal.data",
+]
+
+[[tool.importlinter.contracts]]
+name = "Bundled XLSX backends are independent"
+type = "independence"
+modules = [
+    "caxton._internal.backends.openpyxl",
+    "caxton._internal.backends.xlsxwriter",
+]
+
+[dependency-groups]
+build = [
+    "twine>=7.0,<8.0",
+]
+coverage = [
+    "coverage>=7.15,<8.0",
+]
+dependencies = [
+    "deptry>=0.25.1,<0.26",
+]
+docs = [
+    "hypothesis>=6.165,<7.0",
+    "mkdocs>=1.6,<2.0",
+    "mkdocs-material>=9.7,<10.0",
+    "mkdocstrings[python]>=1.0,<2.0",
+]
+imports = [
+    "import-linter>=2.13,<3.0",
+]
+lint = [
+    "flake8>=7.3,<8.0",
+    "ruff>=0.16,<0.17",
+    "wemake-python-styleguide>=1.7,<2.0",
+]
+maintenance = [
+    "griffe>=2.1,<3.0",
+    "hatch>=1.17,<2.0",
+    "pip>=25,<27",
+    "towncrier>=25.8,<26.0",
+]
+pre-commit = [
+    "pre-commit>=4.6.1,<5.0",
+]
+test = [
+    "hypothesis>=6.165,<7.0",
+    "pytest>=9.1,<10.0",
+    "pytest-benchmark>=5.2,<6.0",
+    "pytest-cov>=7.1,<8.0",
+]
+tox = [
+    "tox>=4.52.1,<5.0",
+    "tox-uv>=1.29,<2.0",
+]
+typecheck = [
+    "mypy>=2.3,<3.0",
+    "types-openpyxl>=3.1.5.20260518,<3.2",
+]
+dev = [
+    { include-group = "build" },
+    { include-group = "coverage" },
+    { include-group = "dependencies" },
+    { include-group = "docs" },
+    { include-group = "imports" },
+    { include-group = "lint" },
+    { include-group = "maintenance" },
+    { include-group = "pre-commit" },
+    { include-group = "test" },
+    { include-group = "tox" },
+    { include-group = "typecheck" },
+]
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+issue_format = "[#{issue}](https://github.com/dzhalaevd/caxton/issues/{issue})"
+orphan_prefix = "+"
+start_string = "<!-- towncrier release notes start -->\n"
+title_format = "## [{version}] - {project_date}"
+underlines = ["", "", ""]
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "Features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Bug fixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "generation"
+name = "Code generation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "ci"
+name = "CI and tooling"
+showcontent = true