BetaCalendars PrintLint

BetaCalendars PrintLint is a typed Python library and command-line tool for checking printable calendar data and page artifacts before they are released. It validates Gregorian month grids, JSON manifests, blank layouts, SVG structure, PDF page boxes, and declared print geometry. It does not fetch web pages or depend on the current date, timezone, or locale.

Human-Readable Calendar References

PrintLint calculates calendar topology independently. These human-readable Beta Calendars pages help developers manually compare a validated fixture with a printable layout.

Installation

python -m pip install betacalendars-printlint

The library supports Python 3.10 and later. PDF checks use the pypdf library. There is no network access during package execution.

Quick Start

Generate a canonical January 2027 grid and validate an exported A4 SVG:

betacal-printlint calendar --year 2027 --month 1 --week-start monday --grid-mode fixed-six-weeks
betacal-printlint check calendar.svg --year 2027 --month 1 --week-start monday --paper a4 --orientation portrait

Validate a JSON manifest or PDF:

betacal-printlint manifest fixtures/2027/01-january.json --format json
betacal-printlint pdf calendar.pdf --paper a4 --orientation portrait

The check command selects a validator by file extension (.json, .svg, .pdf). JSON output has a stable machine-readable shape: valid, errors, warnings, checks, and details. SARIF 2.1.0 output is available for validation findings.

What It Validates

• Gregorian model and grid: month length, first and last weekdays, all seven week starts, chronological date coverage, uniqueness, leading and trailing cells, row and column coordinates, natural grids, and exact 6 × 7 fixed grids.
• JSON manifests: calendar specification, cell dates and positions, paper presets, declared geometry, and optional metadata. See the manifest schema.
• Print geometry: A4, US Letter, A5, and Legal dimensions in millimeters; portrait and landscape; margins; grid bounds; and a configurable day-cell-height warning. These checks do not guarantee margins supported by every physical printer.
• SVG: well-formed XML, physical dimensions, viewBox, optional marked grid bounds (data-printlint-grid="true"), and active or remote content. The validator never executes SVG code or loads referenced resources.
• PDF: parseability, encryption state, page count, page orientation, and media-box dimensions within a documented millimeter tolerance. It does not use OCR or claim to validate the visual location of dates on a page.
• Blank calendars: rectangular cell count and absence of dates or day numbers.

CLI

betacal-printlint --help
betacal-printlint version
betacal-printlint explain geometry
betacal-printlint blank fixtures/blank-calendar.json
betacal-printlint fixture fixtures/2027/02-february.json
betacal-printlint pdf calendar.pdf --paper letter --format sarif

Exit status is 0 when there are no errors, 1 when validation finds errors, and 2 for invalid command-line options. Warnings are reported but do not invalidate a result. check accepts .json, .svg, and .pdf; use the specialized commands for explicit validation.

Python API

from betacalendars_printlint import CalendarSpec, build_month_grid, validate_manifest

grid = build_month_grid(CalendarSpec(2027, 1, "monday", "fixed-six-weeks"))
assert grid.rows == 6 and grid.columns == 7

report = validate_manifest("fixtures/2027/01-january.json")
if not report.valid:
    for issue in report.errors:
        print(issue.code, issue.message)

Public entry points include CalendarSpec, build_month_grid, validate_calendar, validate_manifest, validate_blank_grid, validate_svg, and validate_pdf. Reports expose typed checks, errors, warnings, details, and to_dict().

Gregorian Rules

Leap years are divisible by four, except century years that are not divisible by 400. PrintLint's tests cover the century cases 1900, 2000, 2024, 2027, 2100, and 2400. A broad regression checks every month from 1900 through 2100 under all seven week starts. No current time, timezone, daylight-saving rule, or translated locale enters the calculation.

Manifest and Fixtures

The JSON manifest describes a month, a seven-column grid, optional paper dimensions, and per-cell dates. Adjacent-month cells carry monthOffset; hidden adjacent dates use null cells. The blank-grid fixture is intentionally date-free and is validated separately. Committed examples include twelve 2027 months and the November 2026–February 2027 year boundary.

betacal-printlint manifest fixtures/year-boundary/2026-12.json
betacal-printlint manifest fixtures/year-boundary/2027-01.json

SVG and PDF Safety

SVG input is parsed as XML after rejecting DTD/entity declarations. Scripts, event-handler attributes, foreignObject, remote href/src values, and external CSS resources are reported. Static SVG geometry remains declarative; no JavaScript or remote content is run. For optional grid-bound checking, mark an SVG rectangle or group with data-printlint-grid="true" and numeric x, y, width, and height attributes in viewBox units.

PDF processing reads page boxes using pypdf and does not execute embedded content, render pages, or perform OCR. Encrypted files are reported as unavailable for inspection without a password; PrintLint does not request or guess passwords.

CI Integration

The GitHub Actions workflow runs lint, strict type checking, tests, the 1900–2100 regression, documentation build, distribution build, twine check, and clean installation checks from both wheel and source distribution. JSON and SARIF reports can be consumed by downstream CI jobs.

Documentation

The project documentation covers installation, CLI usage, Python API, schema, validators, geometry, CI, fixtures, and security. Month reference pages link only to their corresponding printable calendar.

Source and Issues

• Source: https://github.com/mateopedersen/betacalendars-printlint
• Issues: https://github.com/mateopedersen/betacalendars-printlint/issues
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md

License

MIT. See LICENSE.