gridhour 0.1.0__tar.gz

gridhour-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and the project uses [semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-04
+
+First release.
+
+* 48 hour timeline of regional carbon intensity and Octopus Agile prices for a UK postcode.
+* Best start time for each job (washing, dishwasher, EV charge, batch job, or your own), ranked by
+  carbon, price or both.
+* Generation mix rows (wind, solar, gas, nuclear, ...) on the same time axis.
+* `--line`, `--tmux`, `--watch` and `--json` for status bars and scripts.
+* Six themes (carbon, daylight, slate, ember, mono, colorblind), 12/24 hour clock, compact layout
+  for small panes.
+* Works offline from cache. Talks only to the two APIs over HTTPS.
+
+[Unreleased]: https://github.com/777dimas/gridhour/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/777dimas/gridhour/releases/tag/v0.1.0

gridhour-0.1.0/LICENSE

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

gridhour-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# The sdist carries what it takes to run the test suite (packagers do), not the screenshots or CI.
+graft tests
+include CHANGELOG.md SECURITY.md
+global-exclude *.py[cod] __pycache__

gridhour-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: gridhour
+Version: 0.1.0
+Summary: When British electricity is green and cheap: a 48 hour carbon intensity and Agile price timeline for the terminal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/777dimas/gridhour
+Project-URL: Issues, https://github.com/777dimas/gridhour/issues
+Project-URL: Security, https://github.com/777dimas/gridhour/security/policy
+Project-URL: Changelog, https://github.com/777dimas/gridhour/blob/main/CHANGELOG.md
+Keywords: carbon intensity,octopus agile,electricity,national grid,tui,terminal,tmux
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gridhour
+
+[![CI](https://github.com/777dimas/gridhour/actions/workflows/ci.yml/badge.svg)](https://github.com/777dimas/gridhour/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/777dimas/gridhour/actions/workflows/codeql.yml/badge.svg)](https://github.com/777dimas/gridhour/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/777dimas/gridhour/badge)](https://scorecard.dev/viewer/?uri=github.com/777dimas/gridhour)
+
+When is British electricity green and cheap? gridhour shows the next 48 hours of carbon
+intensity for your postcode and Octopus Agile prices on one timeline in the terminal, then
+picks the best time to start the washing, charge the car or kick off a batch job.
+
+```console
+$ gridhour --line
+⚡ 142g · 14p · green in 2h
+```
+
+![gridhour main view](https://raw.githubusercontent.com/777dimas/gridhour/main/docs/main.png)
+
+## What you see
+
+* **The chart.** Carbon intensity (gCO₂/kWh) rises above the time axis, the Agile unit price
+  hangs below it. Green is clean or cheap, red is dirty or dear, blue is a plunge price where
+  Octopus pays you to use power. The hours already gone are dimmed.
+* **Generation mix.** Wind, solar, gas, nuclear and the rest, as shares of your region's
+  supply, on the same time axis. Handy for seeing *why* tomorrow afternoon is clean.
+* **Best time to run.** One row per job. Each row is shaded by how good every start time is,
+  and the bright block is the best window, with its average carbon and price next to it. The
+  status line tells you how much that saves against starting right now.
+* **A cursor** runs straight down through all of it. Move it with the arrow keys to read any
+  half hour; `Enter` jumps to the selected job's best window.
+
+Jobs are ranked by carbon, by price, or by both (each normalised over the 48 hours and
+averaged). `w` switches between them.
+
+| Scrubbed to tomorrow morning | Compact layout for a tmux split |
+| --- | --- |
+| ![scrubbing](https://raw.githubusercontent.com/777dimas/gridhour/main/docs/scrub.png) | ![compact](https://raw.githubusercontent.com/777dimas/gridhour/main/docs/compact.png) |
+
+## Install
+
+You need Python 3.11 or newer, a terminal with truecolor and a UTF-8 locale. Linux and macOS;
+on Windows use WSL.
+
+```sh
+pipx install git+https://github.com/777dimas/gridhour
+gridhour SW1A 1AA
+```
+
+Once a release is on PyPI this becomes `pipx install gridhour`. From a clone there is nothing to
+build: `python3 -m gridhour SW1A`.
+
+The postcode you give is remembered, so after the first run plain `gridhour` is enough. Only
+the first half (`SW1A`) is ever used or sent anywhere. Northern Ireland is not on the GB grid,
+so BT postcodes have no forecast.
+
+## Usage
+
+```sh
+gridhour                           # your saved postcode
+gridhour M1 1AE                    # a new postcode (saved)
+gridhour --region scotland         # a region instead, for this run only
+gridhour --mode green              # rank by carbon only (also: cheap, both)
+gridhour --no-prices               # skip Agile, for people on a flat tariff
+gridhour --at 2026-10-04T18:00Z    # start with the cursor at a given time
+gridhour --theme slate --12h
+gridhour --reset                   # delete the saved postcode, jobs, settings and the cache
+```
+
+Keys inside the app (`?` lists them all):
+
+| Key | Action |
+| --- | --- |
+| `←` `→` | move the cursor 30 minutes, Shift or `H` `L` for 2 hours |
+| `Home` `End` `r` | start and end of the forecast, back to now |
+| `↑` `↓` | select a job |
+| `+` `-` | make the selected job 30 minutes longer or shorter |
+| `a` `d` | add a job (`Dryer 1h30`), delete the selected one |
+| `Enter` | jump to the selected job's best window |
+| `w` | rank by carbon, price, or both |
+| `p` | change postcode |
+| `m` `c` `T` `t` | mix rows, compact layout, theme, 12/24h |
+| `R` | refetch now |
+| `q` | quit |
+
+Settings and jobs live in `~/.config/gridhour/config.json`.
+
+## Status bars and scripts
+
+```console
+$ gridhour --line
+⚡ 142g · 14p · green in 2h
+
+$ gridhour --line --best 3h
+⚡ 142g · 14p · 3h best 13:00 (in 4h30)
+
+$ gridhour --tmux                  # same, with tmux colour codes for status-right
+$ gridhour --watch                 # same, updating in place
+$ gridhour --json | jq '.jobs[] | {name, start: .best.from}'
+```
+
+"Green" means NESO's forecast grades the half hour as *low* or *very low* for your region.
+If nothing in the next 48 hours makes that grade, the line says `greenest in 9h` instead.
+
+`--json` gives the current half hour, the next green slot, the best window for every job (with
+the carbon and price you would get starting now, for comparison) and the full 48 hour series.
+
+A tmux example:
+
+```tmux
+set -g status-right '#(gridhour --tmux) '
+set -g status-interval 300
+```
+
+## Where the numbers come from
+
+* **Carbon intensity** and the **generation mix**: the [Carbon Intensity API](https://carbonintensity.org.uk/)
+  from the National Energy System Operator (NESO), regional forecast by postcode. Free, no key,
+  CC BY 4.0.
+* **Prices**: the public [Octopus Energy API](https://developer.octopus.energy/), the Agile
+  import tariff for your region, including VAT. Octopus publishes the next day's prices at about
+  4pm, so before that the price half of the chart stops around 11pm tonight and the "cheap"
+  ranking only looks that far ahead.
+
+These are forecasts. The carbon forecast for tomorrow afternoon can be off by a fair
+margin; Agile prices, once published, are what you pay. gridhour is not affiliated with Octopus
+Energy or NESO.
+
+Responses are cached in `~/.cache/gridhour` for 30 minutes. If the network is down the app
+keeps showing the cached data and says how old it is. `GRIDHOUR_OFFLINE=1` stops all network
+access.
+
+## Security and privacy
+
+gridhour talks to those two APIs over HTTPS and nothing else (redirects are refused), sends only
+the first half of your postcode and your region letter, and has no runtime dependencies.
+Responses are checked field by field before they are used or cached, and text from them never
+reaches your terminal or tmux with escape sequences or format codes in it. Details and how to
+report a problem: [SECURITY.md](https://github.com/777dimas/gridhour/blob/main/SECURITY.md).
+
+## Development
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install --require-hashes -r requirements/dev.txt && pip install --no-deps -e .
+pytest
+```
+
+The tests replay real API responses from `tests/fixtures/`; sockets are blocked while they run.
+More in [CONTRIBUTING.md](https://github.com/777dimas/gridhour/blob/main/CONTRIBUTING.md).
+
+| Module | What it does |
+| --- | --- |
+| `grid.py` | the two APIs, regions and postcodes, the cache |
+| `plan.py` | scoring half hours, best windows, "green in 2h" |
+| `compose.py` | turns the state into a frame |
+| `canvas.py` | character grid with colours, rendered to ANSI |
+| `safe.py` | cleaning outside text, private atomic file writes |
+| `app.py`, `keys.py` | the terminal loop and every key |
+| `output.py` | `--line`, `--tmux`, `--json`, `--watch` |
+| `state.py`, `themes.py`, `cli.py` | settings, colours, arguments |
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/777dimas/gridhour/blob/main/LICENSE).

gridhour-0.1.0/README.md

@@ -0,0 +1,163 @@
+# gridhour
+
+[![CI](https://github.com/777dimas/gridhour/actions/workflows/ci.yml/badge.svg)](https://github.com/777dimas/gridhour/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/777dimas/gridhour/actions/workflows/codeql.yml/badge.svg)](https://github.com/777dimas/gridhour/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/777dimas/gridhour/badge)](https://scorecard.dev/viewer/?uri=github.com/777dimas/gridhour)
+
+When is British electricity green and cheap? gridhour shows the next 48 hours of carbon
+intensity for your postcode and Octopus Agile prices on one timeline in the terminal, then
+picks the best time to start the washing, charge the car or kick off a batch job.
+
+```console
+$ gridhour --line
+⚡ 142g · 14p · green in 2h
+```
+
+![gridhour main view](https://raw.githubusercontent.com/777dimas/gridhour/main/docs/main.png)
+
+## What you see
+
+* **The chart.** Carbon intensity (gCO₂/kWh) rises above the time axis, the Agile unit price
+  hangs below it. Green is clean or cheap, red is dirty or dear, blue is a plunge price where
+  Octopus pays you to use power. The hours already gone are dimmed.
+* **Generation mix.** Wind, solar, gas, nuclear and the rest, as shares of your region's
+  supply, on the same time axis. Handy for seeing *why* tomorrow afternoon is clean.
+* **Best time to run.** One row per job. Each row is shaded by how good every start time is,
+  and the bright block is the best window, with its average carbon and price next to it. The
+  status line tells you how much that saves against starting right now.
+* **A cursor** runs straight down through all of it. Move it with the arrow keys to read any
+  half hour; `Enter` jumps to the selected job's best window.
+
+Jobs are ranked by carbon, by price, or by both (each normalised over the 48 hours and
+averaged). `w` switches between them.
+
+| Scrubbed to tomorrow morning | Compact layout for a tmux split |
+| --- | --- |
+| ![scrubbing](https://raw.githubusercontent.com/777dimas/gridhour/main/docs/scrub.png) | ![compact](https://raw.githubusercontent.com/777dimas/gridhour/main/docs/compact.png) |
+
+## Install
+
+You need Python 3.11 or newer, a terminal with truecolor and a UTF-8 locale. Linux and macOS;
+on Windows use WSL.
+
+```sh
+pipx install git+https://github.com/777dimas/gridhour
+gridhour SW1A 1AA
+```
+
+Once a release is on PyPI this becomes `pipx install gridhour`. From a clone there is nothing to
+build: `python3 -m gridhour SW1A`.
+
+The postcode you give is remembered, so after the first run plain `gridhour` is enough. Only
+the first half (`SW1A`) is ever used or sent anywhere. Northern Ireland is not on the GB grid,
+so BT postcodes have no forecast.
+
+## Usage
+
+```sh
+gridhour                           # your saved postcode
+gridhour M1 1AE                    # a new postcode (saved)
+gridhour --region scotland         # a region instead, for this run only
+gridhour --mode green              # rank by carbon only (also: cheap, both)
+gridhour --no-prices               # skip Agile, for people on a flat tariff
+gridhour --at 2026-10-04T18:00Z    # start with the cursor at a given time
+gridhour --theme slate --12h
+gridhour --reset                   # delete the saved postcode, jobs, settings and the cache
+```
+
+Keys inside the app (`?` lists them all):
+
+| Key | Action |
+| --- | --- |
+| `←` `→` | move the cursor 30 minutes, Shift or `H` `L` for 2 hours |
+| `Home` `End` `r` | start and end of the forecast, back to now |
+| `↑` `↓` | select a job |
+| `+` `-` | make the selected job 30 minutes longer or shorter |
+| `a` `d` | add a job (`Dryer 1h30`), delete the selected one |
+| `Enter` | jump to the selected job's best window |
+| `w` | rank by carbon, price, or both |
+| `p` | change postcode |
+| `m` `c` `T` `t` | mix rows, compact layout, theme, 12/24h |
+| `R` | refetch now |
+| `q` | quit |
+
+Settings and jobs live in `~/.config/gridhour/config.json`.
+
+## Status bars and scripts
+
+```console
+$ gridhour --line
+⚡ 142g · 14p · green in 2h
+
+$ gridhour --line --best 3h
+⚡ 142g · 14p · 3h best 13:00 (in 4h30)
+
+$ gridhour --tmux                  # same, with tmux colour codes for status-right
+$ gridhour --watch                 # same, updating in place
+$ gridhour --json | jq '.jobs[] | {name, start: .best.from}'
+```
+
+"Green" means NESO's forecast grades the half hour as *low* or *very low* for your region.
+If nothing in the next 48 hours makes that grade, the line says `greenest in 9h` instead.
+
+`--json` gives the current half hour, the next green slot, the best window for every job (with
+the carbon and price you would get starting now, for comparison) and the full 48 hour series.
+
+A tmux example:
+
+```tmux
+set -g status-right '#(gridhour --tmux) '
+set -g status-interval 300
+```
+
+## Where the numbers come from
+
+* **Carbon intensity** and the **generation mix**: the [Carbon Intensity API](https://carbonintensity.org.uk/)
+  from the National Energy System Operator (NESO), regional forecast by postcode. Free, no key,
+  CC BY 4.0.
+* **Prices**: the public [Octopus Energy API](https://developer.octopus.energy/), the Agile
+  import tariff for your region, including VAT. Octopus publishes the next day's prices at about
+  4pm, so before that the price half of the chart stops around 11pm tonight and the "cheap"
+  ranking only looks that far ahead.
+
+These are forecasts. The carbon forecast for tomorrow afternoon can be off by a fair
+margin; Agile prices, once published, are what you pay. gridhour is not affiliated with Octopus
+Energy or NESO.
+
+Responses are cached in `~/.cache/gridhour` for 30 minutes. If the network is down the app
+keeps showing the cached data and says how old it is. `GRIDHOUR_OFFLINE=1` stops all network
+access.
+
+## Security and privacy
+
+gridhour talks to those two APIs over HTTPS and nothing else (redirects are refused), sends only
+the first half of your postcode and your region letter, and has no runtime dependencies.
+Responses are checked field by field before they are used or cached, and text from them never
+reaches your terminal or tmux with escape sequences or format codes in it. Details and how to
+report a problem: [SECURITY.md](https://github.com/777dimas/gridhour/blob/main/SECURITY.md).
+
+## Development
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install --require-hashes -r requirements/dev.txt && pip install --no-deps -e .
+pytest
+```
+
+The tests replay real API responses from `tests/fixtures/`; sockets are blocked while they run.
+More in [CONTRIBUTING.md](https://github.com/777dimas/gridhour/blob/main/CONTRIBUTING.md).
+
+| Module | What it does |
+| --- | --- |
+| `grid.py` | the two APIs, regions and postcodes, the cache |
+| `plan.py` | scoring half hours, best windows, "green in 2h" |
+| `compose.py` | turns the state into a frame |
+| `canvas.py` | character grid with colours, rendered to ANSI |
+| `safe.py` | cleaning outside text, private atomic file writes |
+| `app.py`, `keys.py` | the terminal loop and every key |
+| `output.py` | `--line`, `--tmux`, `--json`, `--watch` |
+| `state.py`, `themes.py`, `cli.py` | settings, colours, arguments |
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/777dimas/gridhour/blob/main/LICENSE).

gridhour-0.1.0/SECURITY.md

@@ -0,0 +1,65 @@
+# Security policy
+
+## Reporting a problem
+
+Please report security problems privately through
+[GitHub's private vulnerability reporting](https://github.com/777dimas/gridhour/security/advisories/new),
+not in a public issue. You should get a reply within 5 working days. Once a fix is out I credit the
+reporter in the advisory and the changelog, unless you ask me not to.
+
+## Supported versions
+
+Only the latest release gets fixes.
+
+## What gridhour does that matters for security
+
+**Network.** HTTPS GET requests to two hosts and nothing else: `api.carbonintensity.org.uk` (with the
+first half of your postcode, for example `SW1A`) and `api.octopus.energy` (with your region letter).
+
+* `grid.http_json` refuses any other scheme or host, refuses redirects, and checks the final URL.
+* A response may be 4 MB at most. Once connected, the whole body must arrive within 25 seconds,
+  however slowly it trickles in (connecting and DNS have their own 12 second timeout).
+* No API keys, no accounts, no telemetry. `GRIDHOUR_OFFLINE=1` turns the network off.
+
+**Untrusted input.** API responses, the cache and the config file are all treated as hostile.
+
+* Every field is type- and range-checked before use: numbers must be finite and plausible
+  (booleans and strings are refused), fuel and index names must be known values, times must be
+  ISO 8601. A bad row costs that half hour, not the whole forecast.
+* A response is checked before it is cached, so a broken one is never stored. A cache entry that
+  no longer passes the checks, or carries a timestamp from the future, is ignored.
+* Text that is shown (the region name, job names) loses control characters, bidi and zero-width
+  characters, combining marks and double-width characters, so it can neither send escape
+  sequences to your terminal nor shift or reorder the screen. In `--tmux` output every `#` is
+  doubled, so no text can become a tmux format or a `#(command)`. `--json` output is pure ASCII.
+* Error messages never repeat response content.
+* The Agile product code from the API must match `AGILE-[A-Z0-9-]+` exactly, and the region letter
+  must be one of the fourteen known ones, before either goes into a URL.
+* Malformed responses, config files and arguments produce an error message, not a crash. The
+  test suite in `tests/test_security.py` holds the cases.
+
+**Files.** `~/.config/gridhour/config.json` (postcode outward code, jobs, theme) and
+`~/.cache/gridhour/*.json` (checked API responses). Both directories are kept at `0700` (tightened
+if they already exist with looser modes) and the files at `0600`. Writes go to a fresh temporary
+file created with `O_EXCL` and are renamed into place, so a planted symlink is never followed.
+`gridhour --reset` deletes the config and the cache.
+
+**Dependencies.** None at runtime, only the Python standard library.
+
+## Supply chain
+
+* Every GitHub Action is pinned to a full commit SHA. Workflows run with read-only tokens unless a
+  job needs more, and never keep the checkout credentials.
+* CI installs its tools from hash-locked files (`requirements/*.txt`, `pip --require-hashes`).
+* CodeQL (Python and the workflows), OpenSSF Scorecard and dependency review run on the repository.
+  `zizmor --persona=pedantic` and `actionlint` are clean.
+* A release runs only for a `vX.Y.Z` tag on a commit that is already on `main`, needs approval in
+  the `pypi` environment, and goes to PyPI through trusted publishing (OIDC, no stored token). The
+  jobs holding an OIDC token install nothing and can reach only an allowlist of hosts.
+* Every release file carries signed build provenance. To check a file you downloaded:
+
+  ```sh
+  pip download gridhour==0.1.0 --no-deps -d .
+  gh attestation verify gridhour-0.1.0-py3-none-any.whl --repo 777dimas/gridhour \
+      --signer-workflow 777dimas/gridhour/.github/workflows/release.yml --source-ref refs/tags/v0.1.0
+  ```

gridhour-0.1.0/gridhour/__init__.py

@@ -0,0 +1,3 @@
+"""gridhour: when British electricity is green and cheap, in the terminal."""
+
+__version__ = "0.1.0"

gridhour-0.1.0/gridhour/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()