greenpage 0.1.1__tar.gz

greenpage-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,13 @@
+---
+name: Bug report
+about: Something isn't measured or reported correctly
+labels: bug
+---
+
+**Command run**
+
+**Expected**
+
+**Actual**
+
+**greenpage version / Python version / OS**

greenpage-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,9 @@
+---
+name: Feature request
+about: Suggest an improvement
+labels: enhancement
+---
+
+**Problem this solves**
+
+**Proposed solution**

greenpage-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: ruff check .
+      - run: pytest -q
+
+  dogfood:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        with:
+          target: tests/fixtures/site
+          budget: "0.1"

greenpage-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/greenpage
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

greenpage-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

greenpage-0.1.1/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here, following [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.1] - 2026-11-15
+
+### Fixed
+- Green hosting now follows SWD v4: data-centre operational emissions are scaled by
+  `1 - green hosting factor` instead of using a 50 g/kWh renewable intensity (a v3 carry-over).
+
+### Added
+- `green_hosting_factor` parameter (0–1) in the Python API.
+- Release workflow that publishes to PyPI via Trusted Publishing.
+
+## [0.1.0] - 2026-11-15
+
+### Added
+- `greenpage scan` for HTML files, static build directories and live URLs.
+- Sustainable Web Design Model v4 carbon estimates with A+–F ratings.
+- `--budget` option with CI-friendly exit codes.
+- Text, JSON and Markdown output formats.
+- Optimisation suggestions for images, fonts, media and JavaScript.
+- Composite GitHub Action.

greenpage-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful, be inclusive, assume good faith, and give constructive feedback.
+Harassment of any kind is not tolerated.
+
+Report unacceptable behaviour to the maintainers by opening a private security advisory
+or emailing the address listed on the maintainer's GitHub profile. All reports will be
+handled confidentially.

greenpage-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing to greenpage
+
+Thanks for helping make the web lighter! All contributions are welcome: code, docs, bug reports and methodology reviews.
+
+## Development setup
+
+```bash
+git clone https://github.com/Amxr-tech/greenpage && cd greenpage
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check .
+```
+
+## Guidelines
+
+- **No runtime dependencies.** greenpage uses only the standard library so it installs anywhere, including CI.
+- **Tests required.** Every behaviour change needs a test. Local-mode tests use `tests/fixtures/site`; avoid network calls in tests.
+- **Methodology changes** (anything in `model.py`) must cite a source in the PR description.
+- Keep pull requests focused. Open an issue first for large changes.
+
+## Good first issues
+
+Look for the `good first issue` label, or pick an item from the README roadmap.
+
+## Code of Conduct
+
+By participating you agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md).

greenpage-0.1.1/LICENSE

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

greenpage-0.1.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: greenpage
+Version: 0.1.1
+Summary: Estimate and budget the carbon footprint of web pages, locally or in CI.
+Author: greenpage contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: carbon,ci,green-software,sustainability,web-performance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🌱 greenpage
+
+**Estimate and budget the carbon footprint of web pages, locally or in CI.**
+
+[![CI](https://github.com/Amxr-tech/greenpage/actions/workflows/ci.yml/badge.svg)](https://github.com/Amxr-tech/greenpage/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+The internet accounts for an estimated 3–4% of global greenhouse gas emissions,
+about the same as the aviation industry. Every byte a page sends uses energy in data
+centres, networks and on the visitor's device. Teams already set **performance budgets**;
+greenpage adds a **carbon budget** that stops pages from quietly getting heavier.
+
+- 📏 **Measures** every page in a static build (`dist/`, `public/`, `_site/`) offline, or any live URL
+- 🧮 **Estimates** grams of CO₂e per page view using the open [Sustainable Web Design Model v4](https://sustainablewebdesign.org/estimating-digital-emissions/)
+- 🏷️ **Rates** each page A+ to F on the SWD digital carbon rating scale
+- 🚦 **Enforces** a budget: exits non-zero when a page goes over, so CI fails
+- 💡 **Suggests** fixes: oversized images, legacy font formats, autoplaying media, heavy JS
+- 📦 **No dependencies**: pure Python standard library
+
+## Install
+
+```bash
+pip install greenpage
+# or from source
+pip install git+https://github.com/Amxr-tech/greenpage
+```
+
+## Usage
+
+```bash
+# A whole static-site build
+greenpage scan ./dist
+
+# A single live page
+greenpage scan https://example.com
+
+# Fail if any page emits more than 0.2 g CO2e per view
+greenpage scan ./dist --budget 0.2
+
+# Site runs on renewable energy, 50k views/month: project yearly impact
+greenpage scan ./dist --green-host --views 50000
+
+# Machine-readable or PR-comment-ready output
+greenpage scan ./dist --format json
+greenpage scan ./dist --format markdown
+```
+
+Example output:
+
+```
+index.html
+  150.5 kB transferred · 0.022 g CO2e/view · rating A+
+  ≈ 2.68 kg CO2e/year at 10,000 views/month
+  Heaviest resources:
+     150.0 kB  image    assets/hero.png
+        280 B  document index.html
+  → assets/hero.png is 150 kB; serving it as AVIF or WebP typically saves 30-50%.
+```
+
+| Exit code | Meaning |
+|---|---|
+| `0` | All pages are within budget (or no budget set) |
+| `1` | At least one page is over budget |
+| `2` | Usage error, e.g. the target was not found |
+
+## GitHub Action
+
+```yaml
+- uses: actions/checkout@v4
+- run: npm ci && npm run build
+- uses: Amxr-tech/greenpage@v0
+  with:
+    target: dist
+    budget: "0.2"
+```
+
+The action writes a Markdown report to the job summary and fails the job when a page is over budget.
+
+## Python API
+
+```python
+from greenpage import estimate, scan_directory
+
+for page in scan_directory("dist"):
+    e = estimate(page.total_bytes, green_hosting=True)
+    print(page.page, f"{e.grams_co2e:.3f} g", e.rating)
+```
+
+## Methodology
+
+greenpage implements the **Sustainable Web Design Model v4**:
+
+1. **Bytes.** Every resource a page references (HTML, CSS, JS, images, fonts, media, iframes) is counted.
+   Text assets are measured gzip-compressed, which is how servers deliver them.
+2. **Energy.** Bytes are converted to energy at 0.194 kWh/GB operational and 0.106 kWh/GB embodied,
+   split across data centres, networks and user devices.
+3. **Carbon.** Energy is multiplied by grid intensity: 494 gCO₂e/kWh global average by default, configurable
+   with `--grid-intensity`. Embodied energy always uses the global average.
+4. **Green hosting.** Data-centre operational emissions are multiplied by `1 - green hosting factor`.
+   `--green-host` sets the factor to 1, as SWD v4 prescribes for hosts verified by the
+   [Green Web Foundation](https://www.thegreenwebfoundation.org/). The Python API also accepts a partial
+   `green_hosting_factor` (0–1).
+
+All constants live in [`src/greenpage/model.py`](src/greenpage/model.py).
+
+**Limitations.** These are estimates, not measurements. Local mode doesn't count resources loaded
+at runtime by JavaScript, or external URLs (it flags them instead). The model assumes a first-time
+visit with no caching. Use the numbers to compare pages and spot regressions, not as audited figures.
+
+## Roadmap
+
+- [ ] Count CSS `url()` references (background images, `@font-face`)
+- [ ] Automatic green-host lookup via the Green Web Foundation API
+- [ ] Headless-browser mode to capture runtime-loaded resources
+- [ ] Per-country grid intensity presets
+- [ ] Track history and chart trends across commits
+
+Want to work on one of these? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

greenpage-0.1.1/README.md

@@ -0,0 +1,124 @@
+# 🌱 greenpage
+
+**Estimate and budget the carbon footprint of web pages, locally or in CI.**
+
+[![CI](https://github.com/Amxr-tech/greenpage/actions/workflows/ci.yml/badge.svg)](https://github.com/Amxr-tech/greenpage/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+The internet accounts for an estimated 3–4% of global greenhouse gas emissions,
+about the same as the aviation industry. Every byte a page sends uses energy in data
+centres, networks and on the visitor's device. Teams already set **performance budgets**;
+greenpage adds a **carbon budget** that stops pages from quietly getting heavier.
+
+- 📏 **Measures** every page in a static build (`dist/`, `public/`, `_site/`) offline, or any live URL
+- 🧮 **Estimates** grams of CO₂e per page view using the open [Sustainable Web Design Model v4](https://sustainablewebdesign.org/estimating-digital-emissions/)
+- 🏷️ **Rates** each page A+ to F on the SWD digital carbon rating scale
+- 🚦 **Enforces** a budget: exits non-zero when a page goes over, so CI fails
+- 💡 **Suggests** fixes: oversized images, legacy font formats, autoplaying media, heavy JS
+- 📦 **No dependencies**: pure Python standard library
+
+## Install
+
+```bash
+pip install greenpage
+# or from source
+pip install git+https://github.com/Amxr-tech/greenpage
+```
+
+## Usage
+
+```bash
+# A whole static-site build
+greenpage scan ./dist
+
+# A single live page
+greenpage scan https://example.com
+
+# Fail if any page emits more than 0.2 g CO2e per view
+greenpage scan ./dist --budget 0.2
+
+# Site runs on renewable energy, 50k views/month: project yearly impact
+greenpage scan ./dist --green-host --views 50000
+
+# Machine-readable or PR-comment-ready output
+greenpage scan ./dist --format json
+greenpage scan ./dist --format markdown
+```
+
+Example output:
+
+```
+index.html
+  150.5 kB transferred · 0.022 g CO2e/view · rating A+
+  ≈ 2.68 kg CO2e/year at 10,000 views/month
+  Heaviest resources:
+     150.0 kB  image    assets/hero.png
+        280 B  document index.html
+  → assets/hero.png is 150 kB; serving it as AVIF or WebP typically saves 30-50%.
+```
+
+| Exit code | Meaning |
+|---|---|
+| `0` | All pages are within budget (or no budget set) |
+| `1` | At least one page is over budget |
+| `2` | Usage error, e.g. the target was not found |
+
+## GitHub Action
+
+```yaml
+- uses: actions/checkout@v4
+- run: npm ci && npm run build
+- uses: Amxr-tech/greenpage@v0
+  with:
+    target: dist
+    budget: "0.2"
+```
+
+The action writes a Markdown report to the job summary and fails the job when a page is over budget.
+
+## Python API
+
+```python
+from greenpage import estimate, scan_directory
+
+for page in scan_directory("dist"):
+    e = estimate(page.total_bytes, green_hosting=True)
+    print(page.page, f"{e.grams_co2e:.3f} g", e.rating)
+```
+
+## Methodology
+
+greenpage implements the **Sustainable Web Design Model v4**:
+
+1. **Bytes.** Every resource a page references (HTML, CSS, JS, images, fonts, media, iframes) is counted.
+   Text assets are measured gzip-compressed, which is how servers deliver them.
+2. **Energy.** Bytes are converted to energy at 0.194 kWh/GB operational and 0.106 kWh/GB embodied,
+   split across data centres, networks and user devices.
+3. **Carbon.** Energy is multiplied by grid intensity: 494 gCO₂e/kWh global average by default, configurable
+   with `--grid-intensity`. Embodied energy always uses the global average.
+4. **Green hosting.** Data-centre operational emissions are multiplied by `1 - green hosting factor`.
+   `--green-host` sets the factor to 1, as SWD v4 prescribes for hosts verified by the
+   [Green Web Foundation](https://www.thegreenwebfoundation.org/). The Python API also accepts a partial
+   `green_hosting_factor` (0–1).
+
+All constants live in [`src/greenpage/model.py`](src/greenpage/model.py).
+
+**Limitations.** These are estimates, not measurements. Local mode doesn't count resources loaded
+at runtime by JavaScript, or external URLs (it flags them instead). The model assumes a first-time
+visit with no caching. Use the numbers to compare pages and spot regressions, not as audited figures.
+
+## Roadmap
+
+- [ ] Count CSS `url()` references (background images, `@font-face`)
+- [ ] Automatic green-host lookup via the Green Web Foundation API
+- [ ] Headless-browser mode to capture runtime-loaded resources
+- [ ] Per-country grid intensity presets
+- [ ] Track history and chart trends across commits
+
+Want to work on one of these? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

greenpage-0.1.1/action.yml

@@ -0,0 +1,37 @@
+name: greenpage carbon budget
+description: Estimate the carbon footprint of your built site and fail when pages exceed a budget.
+branding:
+  icon: feather
+  color: green
+inputs:
+  target:
+    description: Build directory, HTML file, or URL to scan
+    required: true
+  budget:
+    description: Maximum grams CO2e per page view
+    required: false
+    default: ""
+  green-host:
+    description: Set to "true" if the site is hosted on renewable energy
+    required: false
+    default: "false"
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - shell: bash
+      run: pip install --quiet "$GITHUB_ACTION_PATH"
+    - shell: bash
+      env:
+        TARGET: ${{ inputs.target }}
+        BUDGET: ${{ inputs.budget }}
+        GREEN_HOST: ${{ inputs.green-host }}
+      run: |
+        args=(scan "$TARGET" --format markdown)
+        [ -n "$BUDGET" ] && args+=(--budget "$BUDGET")
+        [ "$GREEN_HOST" = "true" ] && args+=(--green-host)
+        set +e
+        greenpage "${args[@]}" | tee -a "$GITHUB_STEP_SUMMARY"
+        exit "${PIPESTATUS[0]}"

greenpage-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "greenpage"
+dynamic = ["version"]
+description = "Estimate and budget the carbon footprint of web pages, locally or in CI."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "greenpage contributors" }]
+keywords = ["sustainability", "carbon", "green-software", "web-performance", "ci"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: WWW/HTTP :: Site Management",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+greenpage = "greenpage.cli:main"
+
+[tool.hatch.version]
+path = "src/greenpage/__init__.py"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

greenpage-0.1.1/src/greenpage/__init__.py

@@ -0,0 +1,11 @@
+"""greenpage: estimate and budget the carbon footprint of web pages."""
+
+__version__ = "0.1.1"
+
+from .model import Estimate, estimate, rating_for  # noqa: E402
+from .scan import PageScan, Resource, scan_directory, scan_file, scan_url  # noqa: E402
+
+__all__ = [
+    "Estimate", "PageScan", "Resource", "estimate", "rating_for",
+    "scan_directory", "scan_file", "scan_url", "__version__",
+]

greenpage-0.1.1/src/greenpage/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

greenpage-0.1.1/src/greenpage/advice.py

@@ -0,0 +1,34 @@
+"""Actionable suggestions for reducing a page's footprint."""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from urllib.parse import urlparse
+
+from .scan import PageScan
+
+KB = 1000
+
+
+def suggestions(scan: PageScan) -> list[str]:
+    tips: list[str] = []
+    by_kind: dict[str, int] = {}
+    for r in scan.resources:
+        by_kind[r.kind] = by_kind.get(r.kind, 0) + r.bytes
+
+    for r in scan.resources:
+        ext = PurePosixPath(urlparse(r.url).path).suffix.lower()
+        if r.kind == "image" and ext in {".png", ".jpg", ".jpeg", ".gif"} and r.bytes > 100 * KB:
+            tips.append(f"{r.url} is {r.bytes // KB} kB; serving it as AVIF or WebP typically saves 30-50%.")
+        elif r.kind == "font" and ext in {".ttf", ".otf"}:
+            tips.append(f"{r.url} uses {ext}; WOFF2 is much smaller and universally supported.")
+        elif r.kind == "media" and r.bytes > 1000 * KB:
+            tips.append(f"{r.url} is {r.bytes // KB} kB; use preload=\"none\" or a poster so it only loads on demand.")
+
+    if by_kind.get("script", 0) > 300 * KB:
+        tips.append(
+            f"JavaScript totals {by_kind['script'] // KB} kB; consider code-splitting or removing unused libraries."
+        )
+    if by_kind.get("font", 0) > 150 * KB:
+        tips.append(f"Web fonts total {by_kind['font'] // KB} kB; subset them or prefer system fonts.")
+    return tips