mafw.devtools.documentation.server

Local documentation server management for MAFw.

This module provides the ServerStatusEnum, helper functions, and orchestration logic for managing a python -m http.server subprocess used to serve locally built versioned documentation.

Module Attributes

`SERVER_DEFAULT_DIRECTORY`	Default directory served by the local documentation server.
`SERVER_METADATA_FILENAME`	Filename for server metadata stored inside the served directory.

Functions

`format_started_at_utc`(now)	Format a timestamp for server metadata.
`get_server_status`(directory)	Determine the current server status from metadata and process/HTTP checks.
`http_probe`(address, port[, timeout_s])	Probe whether the server responds at the given address:port.
`process_matches_http_server`(proc, address, ...)	Check whether a process resembles the expected http.server invocation.
`read_server_metadata`(directory)	Read local documentation server metadata if available.
`server_default_directory`()	Return the default directory served by the local documentation server.
`server_metadata_path`(directory)	Return the metadata path associated to a served directory.
`server_start_impl`(address, port, directory, ...)	Implementation for starting a local documentation server.
`server_stop_by_metadata`(directory, ...)	Stop the server based on metadata found under a served directory.
`write_server_metadata`(directory, metadata)	Write local documentation server metadata.

Classes

ServerStatusEnum(*values)

Possible status values for the multiversion-doc local documentation server.

class mafw.devtools.documentation.server.ServerStatusEnum(*values)[source]

Bases: StrEnum

Possible status values for the multiversion-doc local documentation server.

Variables:

running – The server process exists, matches the expected signature and responds over HTTP.
stale – The server process exists and matches the expected signature, but does not respond over HTTP.
stopped – The recorded PID does not exist or does not match the expected signature.
unknown – The metadata file is missing, so no status can be determined.

static _generate_next_value_(name, start, count, last_values): Return the lower-cased version of the member name.

mafw.devtools.documentation.server.format_started_at_utc(now: datetime) → str[source]

Format a timestamp for server metadata.

Parameters:: now (datetime) – A datetime instance (timezone-aware is preferred)
Returns:: UTC ISO-8601 timestamp with Z suffix
Return type:: str

mafw.devtools.documentation.server.get_server_status(directory: Path) → tuple[ServerStatusEnum, dict[str, Any] | None][source]: Determine the current server status from metadata and process/HTTP checks.

mafw.devtools.documentation.server.http_probe(address: str, port: int, timeout_s: float = 1.0) → bool[source]

Probe whether the server responds at the given address:port.

Parameters:

address (str) – Server address
port (int) – Server port
timeout_s (float) – Timeout in seconds

Returns:

True if a GET to the server root returns HTTP 200

Return type:

bool

mafw.devtools.documentation.server.process_matches_http_server(proc: Any, address: str, port: int, directory: Path) → bool[source]

Check whether a process resembles the expected http.server invocation.

Parameters:

proc (Any) – psutil Process instance
address (str) – Expected bind address
port (int) – Expected port
directory (Path) – Expected served directory

Returns:

True when the process signature matches

Return type:

bool

mafw.devtools.documentation.server.read_server_metadata(directory: Path) → dict[str, Any] | None[source]

Read local documentation server metadata if available.

Parameters:: directory (Path) – Served directory to locate metadata under
Returns:: Parsed metadata, or None when the metadata file is missing
Return type:: dict[str, Any] | None
Raises:: DevtoolsError – If the metadata file exists but cannot be parsed

mafw.devtools.documentation.server.server_default_directory() → Path[source]

Return the default directory served by the local documentation server.

Returns:: Default documentation build directory
Return type:: Path

mafw.devtools.documentation.server.server_metadata_path(directory: Path) → Path[source]

Return the metadata path associated to a served directory.

Parameters:: directory (Path) – Served directory
Returns:: Metadata JSON file path
Return type:: Path

mafw.devtools.documentation.server.server_start_impl(address: str, port: int, directory: Path, log_file: Path, force_restart: bool) → None[source]: Implementation for starting a local documentation server.

mafw.devtools.documentation.server.server_stop_by_metadata(directory: Path, require_metadata: bool) → None[source]: Stop the server based on metadata found under a served directory.

mafw.devtools.documentation.server.write_server_metadata(directory: Path, metadata: dict[str, Any]) → None[source]

Write local documentation server metadata.

Parameters:

directory (Path) – Served directory where metadata is stored
metadata (dict[str, Any]) – Metadata dictionary to serialize as JSON

Raises:

DevtoolsError – If the metadata file cannot be written

mafw.devtools.documentation.server.SERVER_DEFAULT_DIRECTORY = PosixPath('docs/build'): Default directory served by the local documentation server.

mafw.devtools.documentation.server.SERVER_METADATA_FILENAME = '.multiversion-doc-server.json': Filename for server metadata stored inside the served directory.