Source code for betty.serve

"""
Provide the Serve API to serve resources within the application.
"""

from __future__ import annotations

import contextlib
import logging
import threading
import webbrowser
from abc import ABC, abstractmethod
from http.server import SimpleHTTPRequestHandler, HTTPServer
from io import StringIO
from pathlib import Path
from typing import Any, TYPE_CHECKING, final

from aiofiles.os import makedirs, symlink
from aiofiles.tempfile import TemporaryDirectory, AiofilesContextManagerTempDir
from aiohttp import ClientSession
from typing_extensions import override

from betty.error import UserFacingError
from betty.functools import Do
from betty.locale.localizable import _

if TYPE_CHECKING:
    from betty.locale.localizer import Localizer
    from betty.project import Project
    from types import TracebackType

DEFAULT_PORT = 8000


[docs] class ServerNotStartedError(RuntimeError): """ Raised when a web server has not (fully) started yet. """ pass # pragma: no cover
[docs] class NoPublicUrlBecauseServerNotStartedError(ServerNotStartedError): """ A public URL is not yet available because the server has not (fully) started yet. """
[docs] def __init__(self): super().__init__( "Cannot get the public URL for a server that has not started yet." )
[docs] class OsError(UserFacingError, OSError): """ Raised for I/O errors. """ pass # pragma: no cover
[docs] class Server(ABC): """ Provide a development web server. """
[docs] def __init__(self, localizer: Localizer): self._localizer = localizer
[docs] async def start(self) -> None: # noqa B027 """ Start the server. """ pass
[docs] async def show(self) -> None: """ Show the served site to the user. """ logging.getLogger(__name__).info( self._localizer._("Serving your site at {url}...").format( url=self.public_url, ) ) webbrowser.open_new_tab(self.public_url)
[docs] async def stop(self) -> None: # noqa B027 """ Stop the server. """ pass
@property @abstractmethod def public_url(self) -> str: """ The server's public URL. """ pass async def __aenter__(self) -> Server: await self.start() return self async def __aexit__( self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None, ) -> None: await self.stop()
[docs] async def assert_available(self) -> None: """ Assert that this server is available. """ # @todo In Betty 0.4.0, require the app's existing client session. async with ClientSession() as session: try: await Do[Any, None](self._assert_available, session).until() except Exception as error: raise UserFacingError( _("The server was unreachable after starting.") ) from error
async def _assert_available(self, session: ClientSession) -> None: """ Assert that this server is available. If this method returns, the server is considered available. If this method raises an exception, the server is considered unavailable. """ async with session.get(self.public_url) as response: assert response.status == 200
[docs] class ProjectServer(Server): """ A web server for a Betty project. """
[docs] def __init__(self, project: Project) -> None: super().__init__(localizer=project.app.localizer) self._project = project
[docs] @override async def start(self) -> None: await makedirs(self._project.configuration.www_directory_path, exist_ok=True) await super().start()
@final class _BuiltinServerRequestHandler(SimpleHTTPRequestHandler): @override def end_headers(self) -> None: self.send_header("Cache-Control", "no-cache") super().end_headers()
[docs] @final class BuiltinServer(Server): """ A built-in server for a WWW directory. """
[docs] def __init__( self, www_directory_path: Path, *, root_path: str | None = None, localizer: Localizer, ) -> None: super().__init__(localizer) self._www_directory_path = www_directory_path self._root_path = root_path self._http_server: HTTPServer | None = None self._port: int | None = None self._thread: threading.Thread | None = None self._temporary_root_directory: AiofilesContextManagerTempDir | None = None
[docs] @override async def start(self) -> None: await super().start() if self._root_path: # To mimic the root path, symlink the project's WWW directory into a temporary # directory, so we do not have to make changes to any existing files. self._temporary_root_directory = TemporaryDirectory() temporary_root_directory_path = Path( await self._temporary_root_directory.__aenter__() ) temporary_www_directory = temporary_root_directory_path for root_path_component in self._root_path.split("/"): temporary_www_directory /= root_path_component if temporary_www_directory != temporary_root_directory_path: await symlink(self._www_directory_path, temporary_www_directory) www_directory_path = temporary_root_directory_path else: www_directory_path = self._www_directory_path logging.getLogger(__name__).info( self._localizer._("Starting Python's built-in web server...") ) for self._port in range(DEFAULT_PORT, 65535): with contextlib.suppress(OSError): self._http_server = HTTPServer( ("", self._port), lambda request, client_address, server: _BuiltinServerRequestHandler( request, client_address, server, directory=str(www_directory_path), ), ) break if self._http_server is None: raise OsError(_("Cannot find an available port to bind the web server to.")) self._thread = threading.Thread(target=self._serve) self._thread.start() await self.assert_available()
@override @property def public_url(self) -> str: if self._port is not None: url = f"http://localhost:{self._port}" if self._root_path: url = f"{url}/{self._root_path}" return url raise NoPublicUrlBecauseServerNotStartedError() def _serve(self) -> None: with contextlib.redirect_stderr(StringIO()): assert self._http_server self._http_server.serve_forever()
[docs] @override async def stop(self) -> None: await super().stop() if self._http_server is not None: self._http_server.shutdown() self._http_server.server_close() if self._thread is not None: self._thread.join() if self._temporary_root_directory is not None: await self._temporary_root_directory.__aexit__(None, None, None)
[docs] @final class BuiltinProjectServer(ProjectServer): """ A built-in server for a Betty project. """
[docs] def __init__(self, project: Project) -> None: super().__init__(project) self._server = BuiltinServer( project.configuration.www_directory_path, root_path=project.configuration.root_path, localizer=project.app.localizer, )
@override @property def public_url(self) -> str: return self._server.public_url
[docs] @override async def start(self) -> None: await super().start() await self._server.start()
[docs] @override async def stop(self) -> None: await super().stop() await self._server.stop()