Metadata-Version: 2.5
Name: whatsnewt
Version: 3.15a1
Summary: A TUI text adventure through what's new in Python 3.15
Project-URL: Source, https://gitlab.com/flufl/whatsnewt.git
Project-URL: Bug Tracker, https://gitlab.com/flufl/whatsnewt/-/work_items
Author-email: Barry Warsaw <barry@python.org>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: adventure,game,python3.15,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Games/Entertainment :: Puzzle Games
Requires-Python: >=3.15
Requires-Dist: pyrefly>=1.3
Requires-Dist: textual[syntax]>=8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# whatsnewt

A TUI text adventure through **what's new in Python 3.15**.

You wake up in the Startup Foyer, somewhere inside the interpreter, and work your way to the Release
Gate.  Along the way there are eighteen puzzles, and every one of them is a real 3.15 feature you
have to actually use.  You do not answer multiple choice questions about lazy imports; you write
`lazy import json` in a code editor and the game checks that the name really did hold a proxy until
something read it.

The exception is the Typing Sanctum, where the features are about what a type checker sees and
running the code proves nothing: PEP 800 marks a class as a disjoint base and the interpreter still
combines it quite happily.  Those answers go to [pyrefly](https://pyrefly.org/), which is a
dependency for exactly that reason, and the verdict quotes what it says back.

```
┌─ The Hall of Imports ──────────────────┬─ Progress ─────────────────────────┐
│ A hall the size of a cathedral, stacked│ Score    40 / 375                  │
│ to the vaulting with packages.  The    │ Puzzles  2 / 18                    │
│ moment anyone steps through the door,  │ Sigils   2 / 6                     │
│ every lid in the building flies open at│ Rooms    7 / 15                    │
│ once...                                ├─ Carrying ─────────────────────────┤
│                                        │ * the lazy lantern                 │
│ Puzzle: The packages that open         │ * the frozen seal                  │
│ themselves (PEP 810)                   ├─ Map ──────────────────────────────┤
│                                        │                ?                   │
│ > solve                                │   Crypt   -  Loop↓        ?        │
│                                        │                |                   │
│                                        │     ?       Gardens       ?        │
│                                        │                |                   │
│                                        │   Vault   ->Imports< -  Babel↑     │
│                                        │                |                   │
│                                        │              Foyer        ?        │
└────────────────────────────────────────┴────────────────────────────────────┘
```

## Running it

```console
$ ./play
```

That is a `uv run` shim.  It fetches CPython 3.15 if that version isn't installed on your path,
installs this checkout and its dependencies into a cached environment, and starts the game -- no
virtual environment to create and nothing to activate first.  It works from any directory, and it
installs the checkout editable, so it runs your working tree rather than a snapshot of it.

Without a checkout:

```console
$ uvx --python 3.15 whatsnewt
```

That runs straight from PyPI.

Useful flags, passed straight through by `./play`:

| Flag | What it does |
| --- | --- |
| `--text` | Play in a plain scrolling terminal instead of full screen |
| `--load FILE` | Resume a saved game by name |
| `--theme NAME` | `textual-light`, `gruvbox`, … — **ctrl+p** switches it while playing |
| `--reset ROOM` | Unsolve a room so it can be played again — `vault`, `the vault` or `Builtins`, or `all`. Repeatable. Puts back the points and the reward too |

Tab completes at the prompt: verbs first, then whatever the verb can take here -- `ex<tab>` gives
`examine`, and `examine st<tab>` finds the staircase if this room has one.  Ambiguous prefixes fill
in as far as they agree and then show you the choice.

## It needs Python 3.15

Since almost every puzzle is checked by *running* your answer against the feature it is about (such
as : `frozendict` is the real built-in, `math.integer` is the real module, and the lazy-imports
puzzle confirms the name really did hold a `types.LazyImportType` proxy until something read it) you
*actually need Python 3.15*.  A pre-release is acceptable.

Note that reading your source is still part of how answers are checked, and always will be: most of
these puzzles have a boring answer that produces the right value the old way, so the checker looks
at *how* you got there as well as *what* you got.  A nested `for` loop that flattens correctly is
still not what PEP 798 is for.

## Commands

`look` `north`/`n` `examine <thing>` `take` `drop` `inventory` `solve` `hint`
`map` `score` `save` `load` `quit` — and `help` for the rest.

Keys follow Emacs where Emacs has an opinion: **ctrl+g** aborts whatever is open, **ctrl+h** is
help, **ctrl+l** re-shows the room, **ctrl+r** opens a puzzle — and checks your answer once you are
inside it. The function keys still work, and every one of them is a command you can type instead.

Inside the editor: **ctrl+r** checks your answer, **ctrl+h** buys a hint for a point, **ctrl+o**
hands the draft to `$EDITOR` and takes back whatever you save, and **ctrl+g** closes the window,
keeping your draft for next time.

`ctrl+o` only suspends the game for editors that need the terminal. If yours opens a window of its
own — `emacsclient`, `code --wait`, `subl -w` — the game stays up while you type, and takes the
draft back when you save. Set `WHATSNEWT_EDITOR_WINDOWED=1` (or `=0`) if the guess is wrong for
yours.

## Saving

The game saves itself after anything that changes it, so quitting, closing the terminal or losing
the window costs you nothing — including whatever you had half-written in a puzzle editor. It writes
to `$XDG_STATE_HOME/whatsnewt/`, falling back to `~/.local/state/whatsnewt/`, rather than the
working directory, since `./play` deliberately runs from anywhere.

Start it again and it offers to resume your game. Declining doesn't throw it away: the old game is
moved to `previous-game.json` beside it, so a mis-click is recoverable. `save <file>` and `--load
FILE` still work for games you want to keep by name.

## What it covers

| Room | Feature |
| --- | --- |
| The Startup Foyer | PEP 829 — package startup configuration files |
| The Hall of Imports | PEP 810 — explicit lazy imports |
| The Builtins Vault | PEP 814 `frozendict`, PEP 661 `sentinel` |
| The Encoding Tower of Babel | PEP 686 — UTF-8 as the default encoding |
| The Scriptorium | Unicode 17.0.0 and `unicodedata.iter_graphemes` |
| The Threading Weir | `threading.serialize_iterator` and friends |
| The Comprehension Gardens | PEP 798 — unpacking in comprehensions |
| The Typing Sanctum | PEP 728 `TypedDict`, PEP 747 `TypeForm`, PEP 800 `disjoint_base` |
| The Forge | the upgraded JIT, mimalloc, `bytearray.take_bytes` |
| The Numerarium | PEP 791 — `math.integer` |
| The Observatory | PEP 799 — Tachyon, and PEP 831 frame pointers |
| The Deprecation Crypt | what 3.15 removed |
| The Great Loop | rather more color than there used to be |
| The Error Oracle | improved error messages, `re.prefixmatch` |
| The Release Gate | all of it, at once |

Souvenirs lying around the place cover the rest: `abi3t`, Unicode 17 and grapheme clusters,
`slice[int]`, `zlib.crc32_combine`, the colored REPL completer.

## Development

```console
$ uv venv --python 3.15 && uv pip install -e '.[dev]'
$ pytest
```

The tests check that every puzzle rejects its own unedited starter, accepts the reference answer in
`tests/solutions.py`, and survives being handed an empty string or something that is not Python at
all.  There is a full playthrough that walks every room, solves all eighteen and arrives at a
perfect score, and the Textual front end is driven headlessly through `Pilot` rather than mocked.
`tests/test_shim.py` keeps `./play`, `pyproject.toml` and the version guard from disagreeing about
which Python this needs.

`tests/solutions.py` doubles as the walkthrough, if you would rather read than play.

Everything the game teaches is answerable from
[`Doc/whatsnew/3.15.rst`](https://docs.python.org/3.15/whatsnew/3.15.html).


## Author

``whatsnewt`` is Copyright (C) 2026 Barry Warsaw <barry@python.org>

Licensed under the terms of the Apache License Version 2.0.  See the LICENSE file for details.

The game was largely co-written with Claude, so maybe Barry should be considered a Director
or Producer in the music and film sense of the word.  The game has been test run by Barry and
several prominent Pythonistas before its release.


Project details
===============

 * Project home: https://gitlab.com/flufl/whatsnewt
 * Report bugs at: https://gitlab.com/flufl/whatsnewt/-/work_items
 * Code hosting: https://gitlab.com/flufl/whatsnewt.git
 * PyPI: https://pypi.python.org/pypi/whatsnewt
