blindgrid 0.2.0__tar.gz

blindgrid-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Local configuration and generated output
+config.toml
+plan.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+
+# Not committed: this is an application installed from source, not a
+# reproducible deployment. Pinning here would freeze contributors to one
+# resolution of the dependency tree.
+uv.lock

blindgrid-0.2.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-27
+
+### Added
+
+- **Households.** Declare people with `blindgrid player add`, or `[[player]]`
+  blocks in the config, and `generate` plans for everyone in one pass. Each
+  person keeps their own ceiling and their own lotteries, with their own
+  weights; nobody's budget affects anyone else's share, and there is
+  deliberately no household cap.
+- Draws are spread across dates so the same lottery is not played twice on the
+  same day while free dates remain. This does **not** improve anyone's odds —
+  two grids are two independent chances either way — and the documentation
+  says so plainly. When dates run short they are shared rather than grids
+  dropped, and the output reports it.
+- `player add`, `player list` and `player remove`.
+- **Windows support.** `install.ps1` mirrors the Unix installer, and
+  configuration and state follow `%APPDATA%` / `%LOCALAPPDATA%` on Windows
+  while keeping XDG elsewhere. CI now runs the test suite on Linux, macOS and
+  Windows, and exercises both installers end to end on each.
+- Past draws are struck through when a plan is shown again, so what is left to
+  play stands out.
+- **Translations.** The interface is available in English, French, Spanish and
+  German, chosen with `--lang`, `BLINDGRID_LANG`, the config file or your
+  system locale. Tests enforce that every catalogue matches the English one
+  key for key and placeholder for placeholder. Terms follow each country's own
+  vocabulary: a played grid is an *apuesta* in Spanish, a *Tipp* in German.
+- **Published on PyPI**, so installing is `pip install blindgrid` rather than a
+  ninety-character URL. Releases run from a tag and refuse to publish unless
+  the tag matches the declared version, the changelog carries an entry, and the
+  built wheel installs and runs.
+- A month is now drawn once. `generate` saves the plan to the state directory
+  and shows it again on later runs, so it can be found while the grids are
+  being filled in. `--force` draws a new one and states what it replaces.
+- `config show` reports where the current plan lives and when it was drawn.
+- **Runs on an iPad.** `install.py` installs anywhere Python exists, which is
+  what iOS needs: a-Shell has neither bash nor git, so it pulls a source
+  archive rather than a git URL. `python -m blindgrid` works where a
+  pip-installed command does not reach the PATH.
+- The plan lays itself out for narrow terminals. Below the width the table
+  needs, each draw becomes two lines with its numbers unwrapped on their own —
+  at 60 columns the table used to stack them one digit per line and cut the
+  lottery name to `Eur…`. `--compact` and `--table` force either layout.
+
+### Changed
+
+- Number columns line up across the whole plan. Lotteries of different shapes
+  used to leave the separator and pool names drifting from row to row, which
+  is exactly the wrong thing when numbers are being copied onto a slip.
+  Weights share one precision so their decimal points align.
+- Amounts accept the way people type them: `30 €`, `30€`, `30 EUR`, commas and
+  non-breaking spaces. Nonsense is still refused.
+- `--lang` is accepted before the command as well as after it.
+- The stored plan is one file, replaced when the month turns, and a
+  self-contained snapshot: editing the configuration afterwards does not alter
+  a plan already drawn. This narrows the original "no persistence" rule to
+  what it was protecting against — an accumulated history of past grids, which
+  is still out of scope — while removing the ability to reroll a month until
+  the numbers look right.
+
+### Fixed
+
+- Asked to prompt with no terminal attached — a pipe, a cron job, one of the
+  iOS shells — the tool now says which option to use instead, rather than
+  raising a bare `OSError` from inside prompt_toolkit.
+- The help screen no longer mixed languages: Typer takes a command's docstring
+  as its help text unless told otherwise, which left the top-level commands in
+  English while the sub-apps were translated.
+- The message shown when no configuration exists yet — the first thing a new
+  user sees — is translated.
+- A language given before the command is no longer overwritten when the
+  configuration is read.
+
+## [0.1.0] - 2026-07-25
+
+First public release.
+
+### Added
+
+- `generate` — interactive monthly planning: prompts for a budget and a set of
+  lotteries, allocates the money by weight, picks draw dates at random and
+  produces one grid per selected draw.
+- Weighted budget allocation with a hard ceiling that has no override. Shares
+  round down, leftovers stay unspent, and a share too small for one grid skips
+  that lottery with an explicit note rather than borrowing from another.
+- Draw planner enumerating real calendar dates, capped by the draws actually
+  remaining in the period.
+- Grid generation from `secrets.SystemRandom` with rejection sampling against
+  five anti-pattern filters, each expressed relative to pool size and each
+  switching itself off on pools too small to satisfy it.
+- `rich` table output and a Markdown export, overwritten on every run.
+- `config init` / `config show` / `config edit` and `lottery add` /
+  `lottery list`.
+- TOML configuration describing lotteries generically: any game in any country
+  is a matter of price, draw days and pools of numbers.
+- Test suite covering allocation, planning, filters, generation, config and
+  the CLI, including a contract test asserting that `random` is never imported
+  by the package.
+
+[Unreleased]: https://github.com/adrnbttr/blindgrid/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/adrnbttr/blindgrid/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/adrnbttr/blindgrid/releases/tag/v0.1.0

blindgrid-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing
+
+Thanks for taking a look. This is a small project with a narrow purpose, so
+the most useful thing to read first is the section below on what will not be
+merged — it is not a long list, but it is a firm one.
+
+## Out of scope, permanently
+
+The README explains the reasoning; this is the short version.
+
+- **Anything predictive.** Frequency analysis, hot/cold numbers, historical
+  draw data, "due" numbers, statistical models of past results. Lottery draws
+  are independent events. A feature that implies otherwise is a bug in the
+  product, not a missing capability.
+- **Seeding or reproducible output.** No `--seed`, no deterministic mode, no
+  fixed generator in the package. A test enforces this.
+- **A history of past months.** The current plan is kept in one file so it can
+  be found again, and replaced when the month turns. Accumulating months is a
+  different thing: it makes past grids comparable to results, which is where
+  pattern-hunting starts.
+- **Consuming the budget exactly.** Leftover money stays unspent.
+- **Hardcoding a country or a game.** Lotteries live in configuration. If
+  something cannot be expressed as a price, a set of draw days and pools of
+  numbers, open an issue and let's discuss the model rather than special-case
+  the code.
+- **Claiming that spreading a household's draws improves anyone's odds.** It
+  does not. Two grids are two independent chances whether they sit on one draw
+  or two. Spreading buys exposure to more distinct jackpots and avoids
+  near-duplicate tickets in one house; the wording in the code and docs says
+  exactly that, and should stay that way.
+
+Everything else is fair game: better rendering, clearer errors, more
+platforms, faster tests, documentation.
+
+## Setup
+
+```bash
+git clone https://github.com/adrnbttr/blindgrid.git
+cd blindgrid
+uv venv
+uv pip install -e ".[dev]"
+```
+
+## Before opening a pull request
+
+```bash
+ruff check .
+ruff format .
+pytest
+shellcheck install.sh   # only if you touched the Unix installer
+```
+
+CI runs the same commands on Linux (3.11, 3.12, 3.13), macOS and Windows, and
+a pull request needs them green. It also installs the project with
+`install.sh` and `install.ps1` on clean runners and uninstalls them again, so
+a change to either is exercised for real rather than merely linted.
+
+If you touched `install.ps1` and have no Windows machine, push and let CI run
+PSScriptAnalyzer and the install-uninstall round trip — that is how it is
+maintained here. The same goes for `install.py`, which exists for iOS: no CI
+runner is an iPad, so it is checked on a bare interpreter, at 55 columns, and
+with no terminal attached.
+
+### Platform-specific code
+
+There is exactly one place that branches on the operating system:
+`src/blindgrid/paths.py`, which decides where configuration and state live.
+Everything else is platform-neutral, and should stay that way. `tests/
+test_paths.py` fakes each platform, so both layouts are checked wherever the
+suite runs.
+
+## Conventions
+
+- **Commits** follow [Conventional Commits](https://www.conventionalcommits.org):
+  `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`, `ci:`.
+- **Line length** is 100 characters, enforced by ruff.
+- **Type annotations** are required on new functions; `ANN` rules are on.
+- **Money** is `Decimal`, never `float`. Budget arithmetic in binary floating
+  point drifts, and the whole point of the ceiling is that it does not move.
+- **Randomness** comes from the `RandomSource` protocol, and production code
+  passes `secrets.SystemRandom`. Do not import `random` inside the package.
+
+## Adding an anti-pattern filter
+
+Think twice. Every active rule shrinks the sample space, and a heavily
+filtered draw is a predictable draw. If a rule is still worth it:
+
+1. Add the predicate functions and a `Rule` entry in `src/blindgrid/filters.py`.
+2. Give it an `applies_to` that switches it off for pools too small to satisfy
+   it, expressed relative to `count` and `maximum` — never against a specific
+   lottery's numbers.
+3. Add it to the `[filters]` block in `config.example.toml`.
+4. Cover both the rejection and the degradation in `tests/test_filters.py`.
+
+## Adding a language
+
+One file in `src/blindgrid/i18n/`, copied from `en.py` and translated, plus one
+line in that package's `__init__.py` and one entry in `LANGUAGE_NAMES`.
+
+Tests then check that your catalogue carries exactly the English keys, with
+exactly the same `{placeholders}`, and that nothing longer than three words was
+left in English. A half-finished translation fails the build rather than
+leaking English into someone's session.
+
+Translate the interface only. Lottery labels, pool names and player names come
+from configuration, and the weekday keys in the config file (`monday`, …) are
+a file format rather than text for reading — both stay as they are.
+
+## Regenerating the README image
+
+`docs/demo.gif` is recorded from a real run, not drawn by hand. It needs
+[vhs](https://github.com/charmbracelet/vhs):
+
+```bash
+brew install vhs        # or see the vhs README for other platforms
+vhs docs/demo.tape      # from the repository root
+```
+
+The tape points the tool at a throwaway config in a temporary directory, so
+recording never touches your own `config.toml`. Regenerate after any change to
+`render.py`, and expect different numbers every time — the demo draws from the
+real CSPRNG like everything else.
+
+Keep it in English and keep it short. Switching languages mid-recording spends
+five seconds saying what one line of the README says better, and every second
+is weight on a page people load before deciding whether to read it.

blindgrid-0.2.0/LICENSE

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