webdev 1.0.0__tar.gz → 2.0.0__tar.gz

webdev-2.0.0/.gitignore

@@ -0,0 +1,18 @@
+*.py[cod]
+__pycache__
+
+# Packages
+*.egg
+*.egg-info
+dist/*
+build/*
+
+# Virtual environments & tooling caches
+.venv/
+.tox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Misc
+*~

{webdev-1.0.0 → webdev-2.0.0}/LICENSE

@@ -1,4 +1,4 @@
-Apache License
+                                 Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 

webdev-2.0.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: webdev
+Version: 2.0.0
+Summary: Small, fast development web server with a modern dark directory index
+Project-URL: Homepage, https://github.com/kuralabs/webdev
+Project-URL: Repository, https://github.com/kuralabs/webdev
+Project-URL: Issues, https://github.com/kuralabs/webdev/issues
+Author-email: "KuraLabs S.R.L" <info@kuralabs.io>, Carlos Jenkins <carlos@jenkins.co.cr>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: dev,development,http,server,static,web
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: colorlog>=6.8
+Requires-Dist: jinja2>=3.1
+Requires-Dist: qrcode>=7.4
+Requires-Dist: starlette>=0.37
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: watchfiles>=0.21
+Description-Content-Type: text/x-rst
+
+======================
+Development Web Server
+======================
+
+About
+=====
+
+``webdev`` is a small, fast development web server. It serves any local
+directory over HTTP (or HTTPS) with developer-friendly conveniences, and ships
+a modern, dark-themed directory index.
+
+It is built on `Starlette <https://www.starlette.io/>`_ and
+`Uvicorn <https://www.uvicorn.org/>`_ (an ASGI stack), and requires Python 3.10+.
+
+Features
+========
+
+- **Serve any directory** — passed as the first positional argument; defaults to
+  the current directory.
+- **Graceful when the folder disappears** — responds with ``404`` instead of
+  crashing if the served directory is removed, and **recovers automatically**
+  the moment it is recreated. Paths are resolved against the live filesystem on
+  every request, which is great with build systems that perform clean/rebuild
+  actions.
+- **Automatic port selection** — if the base port is busy, the next free port in
+  a range is used. Can be forced to a single port.
+- **Serve a not-yet-existing folder** — ``--future`` assumes the folder will be
+  created later.
+- **Modern dark directory index** — breadcrumbs, file-type icons, human-readable
+  sizes, modified dates and client-side sortable columns. Themable: drop a new
+  directory under ``webdev/templates/<theme>/``.
+- **Live reload** — connected browsers refresh automatically on file changes
+  (via a WebSocket; a tiny auto-reconnecting snippet is injected into HTML).
+- **No-cache headers** for always-fresh development content.
+- **SPA fallback** — optionally serve ``index.html`` for unknown routes.
+- **Gzip**, **CORS**, optional **HTTPS** (self-signed if no cert/key is given),
+  and a startup **QR code / LAN URL** for quick mobile testing.
+- **Config file** — every option can be set via ``webdev.toml`` (or a
+  ``[tool.webdev]`` table). Precedence: CLI flag > config file > default.
+
+Installation
+============
+
+::
+
+   pip install webdev
+
+Usage
+=====
+
+::
+
+   $ webdev --help
+   usage: webdev [-h] [-v] [--version] [-i IP] [-p PORT] [-f] [-r RANGE] [-u]
+                 [--reload | --no-reload] [--cache] [--no-cache]
+                 [--spa | --no-spa] [--gzip | --no-gzip] [--cors | --no-cors]
+                 [--qr | --no-qr] [--color | --no-color]
+                 [--https | --no-https] [--cert CERT]
+                 [--key KEY] [--theme THEME] [--config CONFIG]
+                 [path]
+
+Examples::
+
+   # Serve the current directory on http://localhost:8080
+   webdev
+
+   # Serve ./public on a forced port, over HTTPS, without live reload
+   webdev -p 3000 -f --https --no-reload ./public
+
+   # Single-page app: fall back to index.html for client-side routes
+   webdev --spa ./dist
+
+Options and config keys
+-----------------------
+
+Every option has both a CLI flag and a config-file key. Booleans accept
+``--x`` / ``--no-x``.
+
+=====================  ========================  ==================  ==========
+Feature                CLI flag                  Config key          Default
+=====================  ========================  ==================  ==========
+Serve path             positional ``path``       ``path``            CWD
+Bind IP                ``-i/--ip``               ``ip``              0.0.0.0
+Base port              ``-p/--port``             ``port``            8080
+Force exact port       ``-f/--force-port``       ``force_port``      false
+Port range             ``-r/--range``            ``range``           20
+Serve missing folder   ``-u/--future``           ``future``          false
+No-cache headers       ``--no-cache/--cache``    ``no_cache``        enabled
+Live reload            ``--reload/--no-reload``  ``reload``          enabled
+SPA fallback           ``--spa/--no-spa``        ``spa``             disabled
+Gzip                   ``--gzip/--no-gzip``      ``gzip``            enabled
+CORS                   ``--cors/--no-cors``      ``cors``            disabled
+QR / LAN URL           ``--qr/--no-qr``          ``qr``              enabled
+Colorized logs         ``--color/--no-color``    ``color``           enabled
+HTTPS/TLS              ``--https/--no-https``    ``https``           disabled
+TLS cert / key         ``--cert`` / ``--key``    ``cert`` / ``key``  self-signed
+Index theme            ``--theme``               ``theme``           dark
+=====================  ========================  ==================  ==========
+
+Example ``webdev.toml``::
+
+   port = 3000
+   force_port = true
+   spa = true
+   cors = true
+
+Design notes
+============
+
+- **Framework:** Starlette + Uvicorn was chosen over a full framework such as
+  Sanic because this is a static file server: Starlette provides exactly the
+  primitives needed (routing, static serving, WebSockets, middleware) with a
+  small surface, and Uvicorn handles fast binding, HTTP keep-alive, HTTPS and
+  graceful shutdown.
+- **The legacy reload hack is gone.** The old server patched ``send_head`` to
+  ``chdir`` back into the served folder; modern ``http.server`` captures the
+  working directory in the handler constructor, so that hook stopped running and
+  a removed folder crashed the request. ``webdev`` now resolves every request
+  against the live filesystem, so missing folders yield a real ``404`` and
+  recover automatically.
+
+Development
+===========
+
+The development workflow is driven by `tox <https://tox.wiki/>`_ using
+`uv <https://docs.astral.sh/uv/>`_ as the backend (via ``tox-uv``). ``uv`` is the
+only tool you need preinstalled::
+
+   # Lint, format-check and type-check
+   tox -e style
+
+   # Run the test suite
+   tox -e test
+
+   # Build and verify the distribution
+   tox -e build
+
+Each environment declares its own tooling dependencies in ``tox.ini`` so it
+installs only what it needs.
+
+Changelog
+=========
+
+2.0.0
+-----
+
+**Reimplemented** on a modern async stack (Starlette + Uvicorn), Python 3.10+.
+
+**New**
+
+- Modern dark, themable directory index (breadcrumbs, icons, sizes, dates,
+  sortable columns), rendered with Jinja2.
+- Live reload over WebSocket.
+- No-cache headers, SPA fallback, gzip, CORS, optional HTTPS (self-signed),
+  startup QR code / LAN URL.
+- Colorized, level-aware log output (``--color/--no-color``, via colorlog).
+- Config-file support (``webdev.toml`` / ``[tool.webdev]``); every option has a
+  CLI flag and a config key (precedence CLI > config > default).
+- ``pyproject.toml`` packaging; tox + uv development workflow; Ruff, mypy and a
+  pytest suite.
+
+**Fixed**
+
+- The directory auto-recovery feature, which silently broke on modern Python
+  when ``http.server`` began capturing the working directory in the request
+  handler constructor. Path resolution is now per-request against the live
+  filesystem.
+
+**Changed**
+
+- Dropped Python 2 support.
+
+1.1.0
+-----
+
+**New**
+
+- Added support for Python 3 (issue #5).
+- Added support for incremental automatic port selection (issue #2).
+- Added the ``--future`` flag that allows the webserver to serve a non-existent
+  folder, assuming it will be created in the future (issue #3).
+
+**Changed**
+
+- Ctrl+C is now handled (issue #4).
+
+1.0.0
+-----
+
+- Initial release.
+
+License
+=======
+
+::
+
+   Copyright (C) 2015-2026 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-2.0.0/README.rst

@@ -0,0 +1,210 @@
+======================
+Development Web Server
+======================
+
+About
+=====
+
+``webdev`` is a small, fast development web server. It serves any local
+directory over HTTP (or HTTPS) with developer-friendly conveniences, and ships
+a modern, dark-themed directory index.
+
+It is built on `Starlette <https://www.starlette.io/>`_ and
+`Uvicorn <https://www.uvicorn.org/>`_ (an ASGI stack), and requires Python 3.10+.
+
+Features
+========
+
+- **Serve any directory** — passed as the first positional argument; defaults to
+  the current directory.
+- **Graceful when the folder disappears** — responds with ``404`` instead of
+  crashing if the served directory is removed, and **recovers automatically**
+  the moment it is recreated. Paths are resolved against the live filesystem on
+  every request, which is great with build systems that perform clean/rebuild
+  actions.
+- **Automatic port selection** — if the base port is busy, the next free port in
+  a range is used. Can be forced to a single port.
+- **Serve a not-yet-existing folder** — ``--future`` assumes the folder will be
+  created later.
+- **Modern dark directory index** — breadcrumbs, file-type icons, human-readable
+  sizes, modified dates and client-side sortable columns. Themable: drop a new
+  directory under ``webdev/templates/<theme>/``.
+- **Live reload** — connected browsers refresh automatically on file changes
+  (via a WebSocket; a tiny auto-reconnecting snippet is injected into HTML).
+- **No-cache headers** for always-fresh development content.
+- **SPA fallback** — optionally serve ``index.html`` for unknown routes.
+- **Gzip**, **CORS**, optional **HTTPS** (self-signed if no cert/key is given),
+  and a startup **QR code / LAN URL** for quick mobile testing.
+- **Config file** — every option can be set via ``webdev.toml`` (or a
+  ``[tool.webdev]`` table). Precedence: CLI flag > config file > default.
+
+Installation
+============
+
+::
+
+   pip install webdev
+
+Usage
+=====
+
+::
+
+   $ webdev --help
+   usage: webdev [-h] [-v] [--version] [-i IP] [-p PORT] [-f] [-r RANGE] [-u]
+                 [--reload | --no-reload] [--cache] [--no-cache]
+                 [--spa | --no-spa] [--gzip | --no-gzip] [--cors | --no-cors]
+                 [--qr | --no-qr] [--color | --no-color]
+                 [--https | --no-https] [--cert CERT]
+                 [--key KEY] [--theme THEME] [--config CONFIG]
+                 [path]
+
+Examples::
+
+   # Serve the current directory on http://localhost:8080
+   webdev
+
+   # Serve ./public on a forced port, over HTTPS, without live reload
+   webdev -p 3000 -f --https --no-reload ./public
+
+   # Single-page app: fall back to index.html for client-side routes
+   webdev --spa ./dist
+
+Options and config keys
+-----------------------
+
+Every option has both a CLI flag and a config-file key. Booleans accept
+``--x`` / ``--no-x``.
+
+=====================  ========================  ==================  ==========
+Feature                CLI flag                  Config key          Default
+=====================  ========================  ==================  ==========
+Serve path             positional ``path``       ``path``            CWD
+Bind IP                ``-i/--ip``               ``ip``              0.0.0.0
+Base port              ``-p/--port``             ``port``            8080
+Force exact port       ``-f/--force-port``       ``force_port``      false
+Port range             ``-r/--range``            ``range``           20
+Serve missing folder   ``-u/--future``           ``future``          false
+No-cache headers       ``--no-cache/--cache``    ``no_cache``        enabled
+Live reload            ``--reload/--no-reload``  ``reload``          enabled
+SPA fallback           ``--spa/--no-spa``        ``spa``             disabled
+Gzip                   ``--gzip/--no-gzip``      ``gzip``            enabled
+CORS                   ``--cors/--no-cors``      ``cors``            disabled
+QR / LAN URL           ``--qr/--no-qr``          ``qr``              enabled
+Colorized logs         ``--color/--no-color``    ``color``           enabled
+HTTPS/TLS              ``--https/--no-https``    ``https``           disabled
+TLS cert / key         ``--cert`` / ``--key``    ``cert`` / ``key``  self-signed
+Index theme            ``--theme``               ``theme``           dark
+=====================  ========================  ==================  ==========
+
+Example ``webdev.toml``::
+
+   port = 3000
+   force_port = true
+   spa = true
+   cors = true
+
+Design notes
+============
+
+- **Framework:** Starlette + Uvicorn was chosen over a full framework such as
+  Sanic because this is a static file server: Starlette provides exactly the
+  primitives needed (routing, static serving, WebSockets, middleware) with a
+  small surface, and Uvicorn handles fast binding, HTTP keep-alive, HTTPS and
+  graceful shutdown.
+- **The legacy reload hack is gone.** The old server patched ``send_head`` to
+  ``chdir`` back into the served folder; modern ``http.server`` captures the
+  working directory in the handler constructor, so that hook stopped running and
+  a removed folder crashed the request. ``webdev`` now resolves every request
+  against the live filesystem, so missing folders yield a real ``404`` and
+  recover automatically.
+
+Development
+===========
+
+The development workflow is driven by `tox <https://tox.wiki/>`_ using
+`uv <https://docs.astral.sh/uv/>`_ as the backend (via ``tox-uv``). ``uv`` is the
+only tool you need preinstalled::
+
+   # Lint, format-check and type-check
+   tox -e style
+
+   # Run the test suite
+   tox -e test
+
+   # Build and verify the distribution
+   tox -e build
+
+Each environment declares its own tooling dependencies in ``tox.ini`` so it
+installs only what it needs.
+
+Changelog
+=========
+
+2.0.0
+-----
+
+**Reimplemented** on a modern async stack (Starlette + Uvicorn), Python 3.10+.
+
+**New**
+
+- Modern dark, themable directory index (breadcrumbs, icons, sizes, dates,
+  sortable columns), rendered with Jinja2.
+- Live reload over WebSocket.
+- No-cache headers, SPA fallback, gzip, CORS, optional HTTPS (self-signed),
+  startup QR code / LAN URL.
+- Colorized, level-aware log output (``--color/--no-color``, via colorlog).
+- Config-file support (``webdev.toml`` / ``[tool.webdev]``); every option has a
+  CLI flag and a config key (precedence CLI > config > default).
+- ``pyproject.toml`` packaging; tox + uv development workflow; Ruff, mypy and a
+  pytest suite.
+
+**Fixed**
+
+- The directory auto-recovery feature, which silently broke on modern Python
+  when ``http.server`` began capturing the working directory in the request
+  handler constructor. Path resolution is now per-request against the live
+  filesystem.
+
+**Changed**
+
+- Dropped Python 2 support.
+
+1.1.0
+-----
+
+**New**
+
+- Added support for Python 3 (issue #5).
+- Added support for incremental automatic port selection (issue #2).
+- Added the ``--future`` flag that allows the webserver to serve a non-existent
+  folder, assuming it will be created in the future (issue #3).
+
+**Changed**
+
+- Ctrl+C is now handled (issue #4).
+
+1.0.0
+-----
+
+- Initial release.
+
+License
+=======
+
+::
+
+   Copyright (C) 2015-2026 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-2.0.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webdev"
+dynamic = ["version"]
+description = "Small, fast development web server with a modern dark directory index"
+readme = "README.rst"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "KuraLabs S.R.L", email = "info@kuralabs.io" },
+    { name = "Carlos Jenkins", email = "carlos@jenkins.co.cr" },
+]
+keywords = ["development", "web", "server", "static", "http", "dev"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+    "starlette>=0.37",
+    "uvicorn[standard]>=0.29",
+    "jinja2>=3.1",
+    "watchfiles>=0.21",
+    "qrcode>=7.4",
+    "colorlog>=6.8",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.scripts]
+webdev = "webdev.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/kuralabs/webdev"
+Repository = "https://github.com/kuralabs/webdev"
+Issues = "https://github.com/kuralabs/webdev/issues"
+
+[tool.hatch.version]
+path = "webdev/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["webdev"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/webdev",
+    "/tests",
+    "/README.rst",
+    "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+# flake8-equivalent rule set: pycodestyle (E, W), pyflakes (F) and
+# pep8-naming (N). Import sorting (I) is intentionally left out.
+select = ["E", "W", "F", "N"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

webdev-2.0.0/tests/conftest.py

@@ -0,0 +1,28 @@
+"""Shared pytest fixtures."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from webdev.config import Settings
+
+
+@pytest.fixture
+def served_dir(tmp_path: Path) -> Path:
+    (tmp_path / 'hello.txt').write_text('hello world')
+    (tmp_path / 'page.html').write_text('<html><body>Hi</body></html>')
+    (tmp_path / 'sub').mkdir()
+    (tmp_path / 'sub' / 'nested.txt').write_text('nested')
+    return tmp_path
+
+
+@pytest.fixture
+def settings(served_dir: Path) -> Settings:
+    return Settings(
+        path=str(served_dir),
+        reload=False,
+        qr=False,
+        gzip=False,
+    ).normalized()

webdev-2.0.0/tests/test_config.py

@@ -0,0 +1,87 @@
+"""Tests for config-file loading and CLI/config precedence."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from webdev.cli import resolve_settings
+from webdev.config import Settings, load_config_file
+
+
+def test_defaults() -> None:
+    s = Settings()
+    assert s.port == 8080
+    assert s.no_cache is True
+    assert s.reload is True
+    assert s.spa is False
+    assert s.color is True
+    assert s.theme == 'dark'
+
+
+def test_force_port_zeroes_range() -> None:
+    s = Settings(force_port=True, range=20).normalized()
+    assert s.range == 0
+
+
+def test_load_flat_config(tmp_path: Path) -> None:
+    cfg = tmp_path / 'webdev.toml'
+    cfg.write_text('port = 9999\nspa = true\ntheme = "dark"\n')
+    values = load_config_file(cfg, tmp_path)
+    assert values == {'port': 9999, 'spa': True, 'theme': 'dark'}
+
+
+def test_load_tool_table(tmp_path: Path) -> None:
+    cfg = tmp_path / 'pyproject.toml'
+    cfg.write_text('[tool.webdev]\nport = 7000\ncors = true\n')
+    values = load_config_file(cfg, tmp_path)
+    assert values == {'port': 7000, 'cors': True}
+
+
+def test_unknown_keys_ignored(tmp_path: Path) -> None:
+    cfg = tmp_path / 'webdev.toml'
+    cfg.write_text('port = 1234\nbogus = "x"\n')
+    values = load_config_file(cfg, tmp_path)
+    assert values == {'port': 1234}
+
+
+def test_missing_config_raises(tmp_path: Path) -> None:
+    with pytest.raises(FileNotFoundError):
+        load_config_file(tmp_path / 'nope.toml', tmp_path)
+
+
+def test_cli_overrides_config(tmp_path: Path) -> None:
+    (tmp_path / 'webdev.toml').write_text('port = 9999\n')
+    s = resolve_settings(['-p', '8081', str(tmp_path)])
+    assert s.port == 8081  # CLI wins over config
+
+
+def test_config_used_when_no_cli(tmp_path: Path) -> None:
+    (tmp_path / 'webdev.toml').write_text('port = 9999\n')
+    s = resolve_settings([str(tmp_path)])
+    assert s.port == 9999  # config wins over default
+
+
+def test_boolean_optional_flags() -> None:
+    s = resolve_settings(['--no-reload', '--spa', '--no-gzip', '/tmp'])
+    assert s.reload is False
+    assert s.spa is True
+    assert s.gzip is False
+
+
+def test_no_color_flag() -> None:
+    s = resolve_settings(['--no-color', '/tmp'])
+    assert s.color is False
+
+
+def test_verbose_counts_from_cli() -> None:
+    # Regression: ``-v`` with the unset sentinel used to crash argparse.
+    assert resolve_settings(['/tmp']).verbose == 0
+    assert resolve_settings(['-v', '/tmp']).verbose == 1
+    assert resolve_settings(['-vvv', '/tmp']).verbose == 3
+
+
+def test_verbose_config_used_when_no_cli(tmp_path: Path) -> None:
+    (tmp_path / 'webdev.toml').write_text('verbose = 2\n')
+    assert resolve_settings([str(tmp_path)]).verbose == 2