Metadata-Version: 2.5
Name: whatsnewt
Version: 3.15a2
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're not just answering boring questions, you're actually writing and
running code, in a Python 3.15 interpreter.

Some puzzles require a type checker, and in those cases, answers are verified by
[pyrefly](https://pyrefly.org/), which is a dependency for exactly that reason, and the verdict
quotes what it says back.

Here's an example of what the scoreboard looks like:

```
┌─ 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        ?        │
└────────────────────────────────────────┴────────────────────────────────────┘
```

## Play the game

The easiest way to run it is directly from PyPI.  Ensure you have [uv
installed](https://docs.astral.sh/uv/getting-started/installation/) and then run this:

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

From a [git clone](https://gitlab.com/flufl/whatsnewt/-/tree/main) there's a `uv run` shim script
which fetches CPython 3.15 if that version isn't installed on your path, creates all the necessary
virtual environments, installs all the necessary dependencies, and runs the game as an editable
install right where you are:

```console
$ ./play
```

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.

There are many clickable links sprinkled throughout, which can provide clues in the Python 3.15
documentation or various PEPs.  Some of the puzzles are tricky or obscure, but you should have
enough clues available to get you through the game.


## It needs Python 3.15

Since almost every puzzle is checked by *running* your answer against the feature the room explores,
you *actually need Python 3.15*.  Pre-release versions are acceptable, but stick to betas or release
candidates so you're testing post feature-freeze.

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

## Commands

There are many commands, which `help` can explain, but in brief:

* Navigation through the map: `north`, `south`, `east`, `west`, `up`, and `down`
* Interacting with things: `look`, `examine <thing>`, `take`, `drop`
* Checking status: `inventory`, `map`, `score`
* Game play: `save`, `load`, `quit`
* Puzzlin': `solve`, `hint` (cost points!)

I'll neither confirm nor deny any rumors of easter eggs!

Keys follow Emacs where Emacs has an opinion: **ctrl+g** aborts whatever puzzle 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 code 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

<details>
<summary><strong>Spoiler alert</strong> — expand to see which feature each room is about.</summary>

| 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 |

There are souvenirs lying around the place which cover other topics not puzzled: `abi3t`,
`unicodedata.block()`, `slice[int]`, `zlib.crc32_combine`, the colored REPL completer.

</details>

## Development

The project is managed by [Hatch](https://hatch.pypa.io/latest/).  You can

```console
$ hatch run all
```

to run the test suite and static analysis checks.

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

[Feedback](https://gitlab.com/flufl/whatsnewt/-/work_items) is greatly appreciated, especially if
you find bugs or inaccuracies in what the game teaches.


## 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.


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
