# _state

URL: /pounce/api/_state/
Section: api
Description: Server lifecycle state machine — Elm Architecture via milo.

Centralizes the server lifecycle (init → startup → ready → serving →
reloading → shutting_down → stopped) into an immutable state model with a
pure reducer.  A render middleware produces branded output on each dispatch,
replacing the procedural ``if _is_pretty(): _write(_render(...))`` pattern
with a single dispatch-driven view layer.

Usage from server.py / supervisor.py::

    from pounce._state import dispatch

    dispatch("BANNER", config=config, effective_workers=4, ...)
    dispatch("READY", host="127.0.0.1", port=8000)
    dispatch("SHUTDOWN_COMPLETE")

---

> For a complete page index, fetch /pounce/llms.txt.

Open LLM text
(/pounce/api/_state/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_state%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_state%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_state%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_state%2Findex.txt)

Module

#
`_state`

Server lifecycle state machine — Elm Architecture via milo.

Centralizes the server lifecycle (init → startup → ready → serving →
reloading → shutting_down → stopped) into an immutable state model with a
pure reducer. A render middleware produces branded output on each dispatch,
replacing the procedural`if _is_pretty(): _write(_render(...))`pattern
with a single dispatch-driven view layer.

Usage from server.py / supervisor.py::

```
from pounce._state import dispatch

dispatch("BANNER", config=config, effective_workers=4, ...)
dispatch("READY", host="127.0.0.1", port=8000)
dispatch("SHUTDOWN_COMPLETE")
```

2Classes9Functions

## Classes

`Phase`

0

▼

Server lifecycle phases.

Bases:

`StrEnum`

Server lifecycle phases.

`ServerModel`

8

▼

Immutable server lifecycle state.

Immutable server lifecycle state.

#### Attributes

Name
Type
Description

`phase`

`Phase (/pounce/api/_state/#Phase)`

—

`effective_workers`

`int`

—

`mode_label`

`str`

—

`worker_model`

`str`

—

`gil_status`

`str`

—

`supervisor_mode`

`str`

—

`generation`

`int`

—

`connections`

`int`

—

## Functions

`server_reducer`

2

`ServerModel (/pounce/api/_state/#ServerModel)`

▼

Pure reducer — advances lifecycle state in response to actions.

`def server_reducer(state: ServerModel | None, action: Action) -> ServerModel`

##### Parameters

Name
Type
Description

`state`
`ServerModel (/pounce/api/_state/#ServerModel) | None`

`action`
`Action`

##### Returns

`ServerModel (/pounce/api/_state/#ServerModel)`

`_render_middleware`

2

▼

Middleware that renders branded lifecycle output on each action.

`def _render_middleware(dispatch_fn, get_state)`

##### Parameters

Name
Type
Description

`dispatch_fn`
`—`

`get_state`
`—`

`_log_startup_banner_text`

6

`None`

▼

Emit startup identity lines when pretty banners are off or stderr is not a TTY.

`def _log_startup_banner_text(*, config: ServerConfig, display: DisplayConfig, effective_workers: int, mode_label: str, worker_model: str, gil_status: str) -> None`

Emit startup identity lines when pretty banners are off or stderr is not a TTY.

##### Parameters

Name
Type
Description

`config`
`ServerConfig (/pounce/api/config/#ServerConfig)`

`display`
`DisplayConfig (/pounce/api/display/#DisplayConfig)`

`effective_workers`
`int`

`mode_label`
`str`

`worker_model`
`str`

`gil_status`
`str`

`_startup_hints`

2

`list[str]`

▼

Generate smart startup hints based on config vs environment.

`def _startup_hints(config, effective_workers: int) -> list[str]`

##### Parameters

Name
Type
Description

`config`
`—`

`effective_workers`
`int`

##### Returns

`list[str]`

`_render_action`

1

`None`

▼

Route an action to its branded template or logger fallback.

`def _render_action(action: Action) -> None`

##### Parameters

Name
Type
Description

`action`
`Action`

`_get_store`

0

`Store`

▼

Get or create the lifecycle store (thread-safe, lazy).

`def _get_store() -> Store`

##### Returns

`Store`

`dispatch`

2

`None`

▼

Dispatch a lifecycle action to the server store.

Example::

dispatch("READ…

`def dispatch(action_type: str, **payload: Any) -> None`

Dispatch a lifecycle action to the server store.

Example::

```
dispatch("READY", host="127.0.0.1", port=8000)
dispatch("SHUTDOWN_COMPLETE")
```

##### Parameters

Name
Type
Description

`action_type`
`str`

`**payload`
`Any`

`get_state`

0

`ServerModel (/pounce/api/_state/#ServerModel)`

▼

Return the current server lifecycle state.

`def get_state() -> ServerModel`

##### Returns

`ServerModel (/pounce/api/_state/#ServerModel)`

`_reset_store`

0

`None`

▼

Reset the store to initial state (testing only).

`def _reset_store() -> None`