webdev 1.1.0__tar.gz → 2.0.1__tar.gz

webdev-2.0.1/.gitignore

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

{webdev-1.1.0 → webdev-2.0.1}/LICENSE

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

webdev-2.0.1/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.5
+Name: webdev
+Version: 2.0.1
+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
+======================
+
+``webdev`` is a **small, fast local development web server**. Point it at a
+folder and it serves it over HTTP (or HTTPS) with developer-friendly
+conveniences and a modern, dark-themed directory index.
+
+It is built on `Starlette <https://www.starlette.io/>`_ and
+`Uvicorn <https://www.uvicorn.org/>`_ (an async ASGI stack) and requires
+**Python 3.10+**.
+
+Quick start
+===========
+
+::
+
+   # Install (see more options below)
+   uv tool install webdev
+
+   # Serve the current directory on http://localhost:8080
+   webdev
+
+   # Serve a specific folder
+   webdev ./public
+
+   # See every option
+   webdev --help
+
+Installation
+============
+
+With `uv <https://docs.astral.sh/uv/>`_ (recommended)::
+
+   uv tool install webdev
+
+With `pipx <https://pipx.pypa.io/>`_::
+
+   pipx install webdev
+
+Or with plain ``pip`` into an environment of your choice::
+
+   pip install webdev
+
+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 — ideal for build systems that clean and rebuild output.
+- 🔀 **Automatic port selection** — if the base port is busy, the next free port
+  in a range is used. Can be forced to a single exact 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).
+- 📱 **Instant mobile testing** — a **QR code and LAN URL** are printed at
+  startup so you can open the site on your phone.
+- 🌈 **Colorized, level-aware logs** for readable output.
+- ⚡ **No-cache headers** for always-fresh development content.
+- 🧭 **SPA fallback** — optionally serve ``index.html`` for unknown routes.
+- 📦 **Gzip**, **CORS** and optional **HTTPS** (self-signed if no cert/key is
+  given).
+- ⚙️ **Config file** — every option can be set via ``webdev.toml`` (or a
+  ``[tool.webdev]`` table). Precedence: CLI flag > config file > default.
+
+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
+
+   # Serve a build output folder that does not exist yet
+   webdev --future ./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
+Verbosity              ``-v`` (repeatable)       ``verbose``         0
+=====================  ========================  ==================  ==========
+
+Commit a ``webdev.toml`` next to your project to share settings with your team.
+Any option works as a flat key, or under a ``[tool.webdev]`` table (handy inside
+a ``pyproject.toml``)::
+
+   # webdev.toml
+   port = 3000
+   force_port = true
+   spa = true
+   cors = true
+
+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
+
+   # Build, install in a throwaway venv and run (pass args after --)
+   tox -e run -- -p 3000 ./public
+
+Each environment declares its own tooling dependencies in ``tox.ini`` so it
+installs only what it needs.
+
+Changelog
+=========
+
+2.0.1
+-----
+
+**Changed**
+
+- Modernized and expanded the README (uv-first installation, refreshed feature
+  overview and usage).
+
+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) 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-2.0.1/README.rst

@@ -0,0 +1,239 @@
+======================
+Development Web Server
+======================
+
+``webdev`` is a **small, fast local development web server**. Point it at a
+folder and it serves it over HTTP (or HTTPS) with developer-friendly
+conveniences and a modern, dark-themed directory index.
+
+It is built on `Starlette <https://www.starlette.io/>`_ and
+`Uvicorn <https://www.uvicorn.org/>`_ (an async ASGI stack) and requires
+**Python 3.10+**.
+
+Quick start
+===========
+
+::
+
+   # Install (see more options below)
+   uv tool install webdev
+
+   # Serve the current directory on http://localhost:8080
+   webdev
+
+   # Serve a specific folder
+   webdev ./public
+
+   # See every option
+   webdev --help
+
+Installation
+============
+
+With `uv <https://docs.astral.sh/uv/>`_ (recommended)::
+
+   uv tool install webdev
+
+With `pipx <https://pipx.pypa.io/>`_::
+
+   pipx install webdev
+
+Or with plain ``pip`` into an environment of your choice::
+
+   pip install webdev
+
+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 — ideal for build systems that clean and rebuild output.
+- 🔀 **Automatic port selection** — if the base port is busy, the next free port
+  in a range is used. Can be forced to a single exact 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).
+- 📱 **Instant mobile testing** — a **QR code and LAN URL** are printed at
+  startup so you can open the site on your phone.
+- 🌈 **Colorized, level-aware logs** for readable output.
+- ⚡ **No-cache headers** for always-fresh development content.
+- 🧭 **SPA fallback** — optionally serve ``index.html`` for unknown routes.
+- 📦 **Gzip**, **CORS** and optional **HTTPS** (self-signed if no cert/key is
+  given).
+- ⚙️ **Config file** — every option can be set via ``webdev.toml`` (or a
+  ``[tool.webdev]`` table). Precedence: CLI flag > config file > default.
+
+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
+
+   # Serve a build output folder that does not exist yet
+   webdev --future ./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
+Verbosity              ``-v`` (repeatable)       ``verbose``         0
+=====================  ========================  ==================  ==========
+
+Commit a ``webdev.toml`` next to your project to share settings with your team.
+Any option works as a flat key, or under a ``[tool.webdev]`` table (handy inside
+a ``pyproject.toml``)::
+
+   # webdev.toml
+   port = 3000
+   force_port = true
+   spa = true
+   cors = true
+
+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
+
+   # Build, install in a throwaway venv and run (pass args after --)
+   tox -e run -- -p 3000 ./public
+
+Each environment declares its own tooling dependencies in ``tox.ini`` so it
+installs only what it needs.
+
+Changelog
+=========
+
+2.0.1
+-----
+
+**Changed**
+
+- Modernized and expanded the README (uv-first installation, refreshed feature
+  overview and usage).
+
+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) 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-2.0.1/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.1/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()