webdev 2.0.0__py3-none-any.whl

webdev/__init__.py

@@ -0,0 +1,30 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+WebDev - a small, fast development web server.
+
+Serves any local directory over HTTP with developer-friendly features:
+graceful handling (and auto-recovery) when the served directory disappears,
+incremental automatic port selection, live reload, a modern dark directory
+index, optional HTTPS, and more.
+"""
+
+from __future__ import annotations
+
+__version__ = '2.0.0'
+
+__all__ = ['__version__']

webdev/__main__.py

@@ -0,0 +1,29 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Enable ``python -m webdev``.
+
+Delegates to :func:`webdev.cli.main` and exits with its return code so the
+package can be launched as an executable module.
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == '__main__':
+    raise SystemExit(main())

webdev/cli.py

@@ -0,0 +1,330 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Command-line interface.
+
+Preserves the legacy flags (``-i``, ``-p``, ``-f``, ``-r``, ``-u``, ``-v``,
+positional ``path``) and adds a flag for every new feature. Every flag has a
+matching config-file key; precedence is CLI > config file > built-in default.
+"""
+
+from __future__ import annotations
+
+import logging
+from os import getcwd
+from os.path import isdir
+from typing import cast
+from argparse import Action, ArgumentParser, BooleanOptionalAction, Namespace
+
+from colorlog import ColoredFormatter
+
+from . import __version__
+from .config import Settings, load_config_file
+from .index import ThemeNotFoundError, available_themes
+
+log = logging.getLogger('webdev')
+
+# Colorized log format (colorlog, ``{``-style). ``log_color`` is replaced with
+# the level color; ``thin_white`` dims the timestamp; ``reset`` clears styling.
+COLOR_FORMAT = (
+    '  {thin_white}{asctime}{reset} | '
+    '{log_color}{levelname:8}{reset} | '
+    '{log_color}{message}{reset}'
+)
+# Plain log format used when color is disabled (same layout, no escape codes).
+SIMPLE_FORMAT = '  {asctime} | {levelname:8} | {message}'
+
+_V_LEVELS = {
+    0: logging.ERROR,
+    1: logging.WARNING,
+    2: logging.INFO,
+    3: logging.DEBUG,
+}
+
+# Sentinel marking "flag not provided on the CLI" so config can win.
+_UNSET = object()
+
+
+class _CountFromUnset(Action):
+    """
+    Count repeated flags (like ``-v``) while preserving the unset sentinel.
+
+    A plain ``count`` action cannot increment starting from :data:`_UNSET`, so
+    this action treats the sentinel (or a missing value) as zero before
+    incrementing. When the flag is never given the value stays :data:`_UNSET`,
+    letting a config-file value win during merging.
+    """
+
+    def __init__(self, option_strings: list[str], dest: str, **kwargs) -> None:
+        """
+        Build the action, forcing it to consume no argument values.
+
+        :param option_strings: The option strings that trigger this action.
+        :param dest: The namespace attribute to accumulate the count in.
+        :param kwargs: Remaining keyword arguments forwarded to the base action.
+        """
+        kwargs['nargs'] = 0
+        super().__init__(option_strings, dest, **kwargs)
+
+    def __call__(self, parser, namespace, values, option_string=None) -> None:
+        """
+        Increment the destination counter, seeding the sentinel as zero.
+
+        :param parser: The parser invoking the action.
+        :param namespace: The namespace being populated.
+        :param values: The (empty) argument values for this action.
+        :param option_string: The option string that triggered the action.
+        """
+        current = getattr(namespace, self.dest, _UNSET)
+        count = 0 if current is _UNSET else cast(int, current)
+        setattr(namespace, self.dest, count + 1)
+
+
+def build_parser() -> ArgumentParser:
+    """
+    Construct the ``webdev`` command-line argument parser.
+
+    Every flag defaults to the :data:`_UNSET` sentinel so that options not
+    given on the command line can later be filled in from the config file or
+    the built-in defaults without being overridden by argparse defaults.
+
+    :return: A configured :class:`argparse.ArgumentParser` for the CLI.
+    """
+    parser = ArgumentParser(
+        prog='webdev', description='Small, fast development web server.'
+    )
+    parser.add_argument(
+        '-v',
+        '--verbose',
+        action=_CountFromUnset,
+        default=_UNSET,
+        help='Increase verbosity level (repeatable).',
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'Development Web Server v{__version__}',
+    )
+
+    # Core / back-compatible options.
+    parser.add_argument(
+        '-i',
+        '--ip',
+        default=_UNSET,
+        help='IP to bind to. Default: 0.0.0.0',
+    )
+    parser.add_argument(
+        '-p',
+        '--port',
+        type=int,
+        default=_UNSET,
+        help='Base port to listen on. Default: 8080.',
+    )
+    parser.add_argument(
+        '-f',
+        '--force-port',
+        action='store_true',
+        default=_UNSET,
+        help='Force the use of the given port (disables range probing).',
+    )
+    parser.add_argument(
+        '-r',
+        '--range',
+        type=int,
+        default=_UNSET,
+        help='Number of ports to try from the base port. Default: 20.',
+    )
+    parser.add_argument(
+        '-u',
+        '--future',
+        action='store_true',
+        default=_UNSET,
+        help='Serve a folder that does not exist yet.',
+    )
+
+    # New feature toggles (flag + --no- variant).
+    parser.add_argument(
+        '--reload',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='Live-reload browsers on file changes. Default: enabled.',
+    )
+    parser.add_argument(
+        '--cache',
+        dest='no_cache',
+        action='store_false',
+        default=_UNSET,
+        help='Allow caching (disable no-cache headers).',
+    )
+    parser.add_argument(
+        '--no-cache',
+        dest='no_cache',
+        action='store_true',
+        default=_UNSET,
+        help='Send no-cache headers so content is always fresh. Default.',
+    )
+    parser.add_argument(
+        '--spa',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='SPA fallback: serve index.html for unknown routes. Default: off.',
+    )
+    parser.add_argument(
+        '--gzip',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='Gzip-compress responses. Default: enabled.',
+    )
+    parser.add_argument(
+        '--cors',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='Send permissive CORS headers. Default: off.',
+    )
+    parser.add_argument(
+        '--qr',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='Print a QR code / LAN URL at startup. Default: enabled.',
+    )
+    parser.add_argument(
+        '--color',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='Colorize log output. Default: enabled.',
+    )
+    parser.add_argument(
+        '--https',
+        action=BooleanOptionalAction,
+        default=_UNSET,
+        help='Serve over HTTPS (self-signed if no cert/key). Default: off.',
+    )
+    parser.add_argument(
+        '--cert',
+        default=_UNSET,
+        help='TLS certificate file (with --https).',
+    )
+    parser.add_argument(
+        '--key',
+        default=_UNSET,
+        help='TLS private key file (with --https).',
+    )
+    parser.add_argument(
+        '--theme',
+        default=_UNSET,
+        help='Directory index theme. Default: dark.',
+    )
+    parser.add_argument(
+        '--config',
+        default=None,
+        help='Path to a config file (TOML). Auto-discovered if omitted.',
+    )
+
+    parser.add_argument(
+        'path',
+        nargs='?',
+        default=_UNSET,
+        help='Path to serve. Default: current directory.',
+    )
+    return parser
+
+
+def _provided(args: Namespace) -> dict:
+    """
+    Extract only the options explicitly provided on the command line.
+
+    Any option still set to the :data:`_UNSET` sentinel is omitted, as is the
+    ``config`` key, which is handled separately during resolution.
+
+    :param args: The namespace returned by :meth:`ArgumentParser.parse_args`.
+    :return: A mapping of option names to the values supplied on the CLI.
+    """
+    out = {}
+    for key, value in vars(args).items():
+        if key in ('config',):
+            continue
+        if value is not _UNSET:
+            out[key] = value
+    return out
+
+
+def resolve_settings(argv: list[str] | None = None) -> Settings:
+    """
+    Parse *argv*, merge with the config file, and return resolved settings.
+
+    Values are merged with precedence CLI > config file > built-in default, the
+    result is normalized, and logging is configured from the resolved verbosity.
+
+    :param argv: Argument list to parse, or ``None`` to use ``sys.argv``.
+    :return: The fully resolved and normalized :class:`Settings` instance.
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    cli_values = _provided(args)
+
+    # Where to look for an auto-discovered config file.
+    search_from = cli_values.get('path', getcwd())
+    config_values = load_config_file(args.config, search_from)
+
+    # Precedence: defaults < config file < CLI.
+    merged = {**config_values, **cli_values}
+    settings = Settings(**merged).normalized()
+
+    # Configure logging as early as possible.
+    level = _V_LEVELS.get(settings.verbose, logging.DEBUG)
+    if settings.color:
+        formatter: logging.Formatter = ColoredFormatter(COLOR_FORMAT, style='{')
+    else:
+        formatter = logging.Formatter(SIMPLE_FORMAT, style='{')
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+    logging.basicConfig(handlers=[handler], level=level, force=True)
+    log.debug(f'Resolved settings: {settings}')
+
+    return settings
+
+
+def main(argv: list[str] | None = None) -> int:
+    """
+    Program entry point: resolve settings, validate, and start the server.
+
+    Returns a non-zero exit code without serving when the requested path is not
+    a directory (and ``--future`` was not given) or when the selected theme is
+    unknown.
+
+    :param argv: Argument list to parse, or ``None`` to use ``sys.argv``.
+    :return: Process exit code (``0`` on success, ``1`` on validation errors).
+    """
+    from .run import serve
+
+    settings = resolve_settings(argv)
+
+    if not settings.future and not isdir(settings.path):
+        log.error(f'Not a directory: {settings.path}')
+        return 1
+
+    try:
+        from .index import validate_theme
+
+        validate_theme(settings.theme)
+    except ThemeNotFoundError as error:
+        log.error(str(error))
+        log.error('Available themes: {}'.format(', '.join(available_themes())))
+        return 1
+
+    return serve(settings)

webdev/config.py

@@ -0,0 +1,210 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Configuration model and config-file loading for WebDev.
+
+A single :class:`Settings` dataclass holds every runtime option. Each option is
+exposed both as a CLI flag (see :mod:`webdev.cli`) and as a config-file key.
+
+Resolution precedence (highest wins):
+
+    CLI flag  >  config file  >  built-in default
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field, fields
+from os import getcwd
+from os.path import abspath
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised only on Python 3.10
+    import tomli as tomllib
+
+
+#: Candidate config file names auto-discovered when ``--config`` is not given.
+CONFIG_FILENAMES = ('webdev.toml', '.webdev.toml')
+
+#: Default directory index theme (and currently the only one shipped).
+DEFAULT_THEME = 'dark'
+
+
+@dataclass
+class Settings:
+    """
+    Fully resolved runtime settings.
+
+    Holds every runtime option for the server. Instances are typically produced
+    by merging CLI flags, config-file keys, and built-in defaults, then calling
+    :meth:`normalized`.
+    """
+
+    # Core / back-compatible options.
+    path: str = field(default_factory=getcwd)
+    ip: str = '0.0.0.0'
+    port: int = 8080
+    force_port: bool = False
+    range: int = 20
+    future: bool = False
+    verbose: int = 0
+
+    # New feature toggles (defaults per the plan).
+    no_cache: bool = True
+    reload: bool = True
+    spa: bool = False
+    gzip: bool = True
+    cors: bool = False
+    qr: bool = True
+    color: bool = True
+    https: bool = False
+    cert: str | None = None
+    key: str | None = None
+    theme: str = DEFAULT_THEME
+
+    def normalized(self) -> Settings:
+        """
+        Apply derived and validated invariants in place and return self.
+
+        Resolves :attr:`path` to an absolute path and preserves the historical
+        quirk that forcing a port disables range probing.
+
+        :return: This same :class:`Settings` instance, after normalization.
+        """
+        self.path = abspath(self.path)
+        # Preserve the historical quirk: forcing a port disables range probing.
+        if self.force_port:
+            self.range = 0
+        return self
+
+
+#: Config keys that are not part of :class:`Settings` construction directly.
+_BOOL_KEYS = {
+    'force_port',
+    'future',
+    'no_cache',
+    'reload',
+    'spa',
+    'gzip',
+    'cors',
+    'qr',
+    'color',
+    'https',
+}
+_INT_KEYS = {'port', 'range', 'verbose'}
+_STR_KEYS = {'path', 'ip', 'cert', 'key', 'theme'}
+
+
+def _settings_field_names() -> set[str]:
+    """
+    Return the set of field names declared on :class:`Settings`.
+
+    :return: The names of all dataclass fields of :class:`Settings`.
+    """
+    return {f.name for f in fields(Settings)}
+
+
+def discover_config_file(start: str | Path) -> Path | None:
+    """
+    Find a config file by walking up from *start* to the filesystem root.
+
+    If *start* is a file, the search begins in its parent directory. Each
+    directory is checked for any of :data:`CONFIG_FILENAMES`.
+
+    :param start: Path to begin the upward search from.
+    :return: The first matching config file found, or ``None`` if none exists.
+    """
+    current = Path(start).resolve()
+    if current.is_file():
+        current = current.parent
+    for directory in (current, *current.parents):
+        for name in CONFIG_FILENAMES:
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def load_config_file(
+    config_path: str | Path | None, search_from: str | Path
+) -> dict[str, Any]:
+    """
+    Load config values from a TOML file.
+
+    If *config_path* is given it is used directly; otherwise a file is
+    auto-discovered starting at *search_from*. Returns an empty mapping when no
+    config is found. Supports both a top-level table and a ``[tool.webdev]``
+    table (e.g. inside ``pyproject.toml``).
+
+    :param config_path: Explicit path to a config file, or ``None`` to
+        auto-discover one.
+    :param search_from: Location to start auto-discovery from when
+        *config_path* is ``None``.
+    :return: A mapping of known, type-coerced config keys to their values.
+    :raises FileNotFoundError: If *config_path* is given but does not exist.
+    """
+    path: Path | None
+    if config_path is not None:
+        path = Path(config_path)
+        if not path.is_file():
+            raise FileNotFoundError(f'Config file not found: {path}')
+    else:
+        path = discover_config_file(search_from)
+
+    if path is None:
+        return {}
+
+    with path.open('rb') as fd:
+        data = tomllib.load(fd)
+
+    # Allow [tool.webdev] (pyproject-style) or a flat table.
+    if 'tool' in data and isinstance(data['tool'], dict):
+        data = data['tool'].get('webdev', {}) or {}
+    elif 'webdev' in data and isinstance(data['webdev'], dict):
+        data = data['webdev']
+
+    return _coerce_config(data)
+
+
+def _coerce_config(data: dict[str, Any]) -> dict[str, Any]:
+    """
+    Keep only known keys and coerce them to their expected types.
+
+    Hyphenated keys are normalized to underscores, unknown keys are dropped,
+    and recognized keys are cast to ``bool``, ``int``, or ``str`` as declared.
+
+    :param data: Raw mapping parsed from the config file.
+    :return: A mapping limited to known :class:`Settings` keys, type-coerced.
+    """
+    valid = _settings_field_names()
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        norm = key.replace('-', '_')
+        if norm not in valid:
+            continue
+        if norm in _BOOL_KEYS:
+            result[norm] = bool(value)
+        elif norm in _INT_KEYS:
+            result[norm] = int(value)
+        elif norm in _STR_KEYS:
+            result[norm] = str(value)
+        else:
+            result[norm] = value
+    return result