webdev 2.0.0__tar.gz → 2.1.0__tar.gz

{webdev-2.0.0 → webdev-2.1.0}/.gitignore

@@ -13,6 +13,7 @@ build/*
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
+uv.lock
 
 # Misc
 *~

{webdev-2.0.0 → webdev-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: webdev
-Version: 2.0.0
+Version: 2.1.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
@@ -32,49 +32,77 @@ 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.
+``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 ASGI stack), and requires Python 3.10+.
+`Uvicorn <https://www.uvicorn.org/>`_ (an async ASGI stack) and requires
+**Python 3.10+**.
 
-Features
-========
+Quick start
+===========
 
-- **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.
+::
+
+   # 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.
+- 👀 **Previews text inline** — plain-text, config and template files (``.txt``,
+  ``.json``, ``.yaml``, ``.ini``, ``.toml``, ``.j2``/``.jinja2``, ``.template``,
+  ``.config`` and more) open in the browser instead of being downloaded.
+- 🧭 **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
 =====
 
@@ -100,6 +128,9 @@ Examples::
    # 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
 -----------------------
 
@@ -125,30 +156,19 @@ 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
 =====================  ========================  ==================  ==========
 
-Example ``webdev.toml``::
+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
 
-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
 ===========
 
@@ -165,12 +185,32 @@ only tool you need preinstalled::
    # 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.1.0
+-----
+
+**New**
+
+- Plain-text, config and template files (such as ``.yaml``, ``.tpl``, ``.j2``,
+  ``.jinja2``, ``.template`` and ``.config``) now open inline in the browser
+  instead of being downloaded (issue #8). Thanks to zaro0508 for the report.
+
+2.0.1
+-----
+
+**Changed**
+
+- Modernized and expanded the README (uv-first installation, refreshed feature
+  overview and usage).
+
 2.0.0
 -----
 
@@ -224,7 +264,8 @@ License
 
 ::
 
-   Copyright (C) 2015-2026 Carlos Jenkins <carlos@jenkins.co.cr>
+   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.

{webdev-2.0.0 → webdev-2.1.0}/README.rst

@@ -2,49 +2,77 @@
 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.
+``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 ASGI stack), and requires Python 3.10+.
+`Uvicorn <https://www.uvicorn.org/>`_ (an async ASGI stack) and requires
+**Python 3.10+**.
 
-Features
-========
+Quick start
+===========
 
-- **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.
+::
+
+   # 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.
+- 👀 **Previews text inline** — plain-text, config and template files (``.txt``,
+  ``.json``, ``.yaml``, ``.ini``, ``.toml``, ``.j2``/``.jinja2``, ``.template``,
+  ``.config`` and more) open in the browser instead of being downloaded.
+- 🧭 **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
 =====
 
@@ -70,6 +98,9 @@ Examples::
    # 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
 -----------------------
 
@@ -95,30 +126,19 @@ 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
 =====================  ========================  ==================  ==========
 
-Example ``webdev.toml``::
+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
 
-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
 ===========
 
@@ -135,12 +155,32 @@ only tool you need preinstalled::
    # 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.1.0
+-----
+
+**New**
+
+- Plain-text, config and template files (such as ``.yaml``, ``.tpl``, ``.j2``,
+  ``.jinja2``, ``.template`` and ``.config``) now open inline in the browser
+  instead of being downloaded (issue #8). Thanks to zaro0508 for the report.
+
+2.0.1
+-----
+
+**Changed**
+
+- Modernized and expanded the README (uv-first installation, refreshed feature
+  overview and usage).
+
 2.0.0
 -----
 
@@ -194,7 +234,8 @@ License
 
 ::
 
-   Copyright (C) 2015-2026 Carlos Jenkins <carlos@jenkins.co.cr>
+   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.

webdev-2.1.0/tests/test_mime.py

@@ -0,0 +1,47 @@
+"""
+Serve the committed ``testfiles`` fixtures and assert plain-text, config and
+template files load inline in the browser instead of being downloaded.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from starlette.testclient import TestClient
+
+from webdev.config import Settings
+from webdev.server import create_app
+from webdev.static import guess_media_type
+
+TESTFILES = Path(__file__).parent / 'testfiles'
+
+#: Every committed fixture, discovered dynamically.
+FIXTURES = sorted(p for p in TESTFILES.iterdir() if p.is_file())
+
+#: Content types browsers render inline rather than offering to download.
+INLINE_TYPES = {'text/plain', 'application/json'}
+
+
+@pytest.fixture
+def testfiles_client() -> TestClient:
+    settings = Settings(
+        path=str(TESTFILES),
+        reload=False,
+        qr=False,
+        gzip=False,
+    ).normalized()
+    return TestClient(create_app(settings))
+
+
+@pytest.mark.parametrize('fixture', FIXTURES, ids=lambda p: p.name)
+def test_file_served_inline(testfiles_client: TestClient, fixture: Path) -> None:
+    with testfiles_client as c:
+        resp = c.get('/{}'.format(fixture.name))
+    assert resp.status_code == 200
+
+    content_type = resp.headers['content-type'].split(';')[0]
+    assert content_type == guess_media_type(fixture)
+    assert content_type in INLINE_TYPES
+    # The browser must render the file, never download it.
+    assert 'attachment' not in resp.headers.get('content-disposition', '')

{webdev-2.0.0 → webdev-2.1.0}/tests/test_static.py

@@ -46,10 +46,35 @@ def test_find_index_file(served_dir: Path) -> None:
 
 
 def test_guess_media_type_registered_extensions(tmp_path: Path) -> None:
-    for name in ('conf.toml', 'setup.ini', 'app.cfg', 'notes.log'):
+    extensions = (
+        'conf.toml',
+        'setup.ini',
+        'app.cfg',
+        'notes.log',
+        'config.yaml',
+        'config.yml',
+        'site.template',
+        'page.tmpl',
+        'legacy.tpl',
+        'email.j2',
+        'base.jinja',
+        'newsletter.jinja2',
+        'app.config',
+    )
+    for name in extensions:
         f = tmp_path / name
         f.write_text('key = 1')
-        assert guess_media_type(f) == 'text/plain'
+        assert guess_media_type(f) == 'text/plain', name
+
+
+def test_guess_media_type_txt_and_json(tmp_path: Path) -> None:
+    txt = tmp_path / 'notes.txt'
+    txt.write_text('hello')
+    assert guess_media_type(txt) == 'text/plain'
+
+    data = tmp_path / 'data.json'
+    data.write_text('{"ok": true}')
+    assert guess_media_type(data) == 'application/json'
 
 
 def test_guess_media_type_known_binary(tmp_path: Path) -> None:

webdev-2.1.0/tests/testfiles/app.config

@@ -0,0 +1,2 @@
+debug = true
+host = localhost

webdev-2.1.0/tests/testfiles/config.yaml

@@ -0,0 +1,2 @@
+name: webdev
+enabled: true

webdev-2.1.0/tests/testfiles/config.yml

@@ -0,0 +1,2 @@
+name: webdev
+enabled: true

webdev-2.1.0/tests/testfiles/data.json

@@ -0,0 +1,4 @@
+{
+  "name": "webdev",
+  "ok": true
+}

webdev-2.1.0/tests/testfiles/email.j2

@@ -0,0 +1 @@
+Hello {{ name }}, this is a Jinja2 template.

webdev-2.1.0/tests/testfiles/newsletter.jinja2

@@ -0,0 +1 @@
+<p>Hello {{ name }}</p>

webdev-2.1.0/tests/testfiles/page.tpl

@@ -0,0 +1 @@
+Hello {{ name }}, this is a .tpl template.

webdev-2.1.0/tests/testfiles/sample.toml

@@ -0,0 +1,2 @@
+[tool.webdev]
+port = 8080

webdev-2.1.0/tests/testfiles/sample.txt

@@ -0,0 +1 @@
+Just a plain text note.

webdev-2.1.0/tests/testfiles/setup.ini

@@ -0,0 +1,2 @@
+[server]
+port = 8080

webdev-2.1.0/tests/testfiles/site.template

@@ -0,0 +1 @@
+Hello {{ name }}, this is a .template file.

{webdev-2.0.0 → webdev-2.1.0}/webdev/__init__.py

@@ -25,6 +25,6 @@ index, optional HTTPS, and more.
 
 from __future__ import annotations
 
-__version__ = '2.0.0'
+__version__ = '2.1.0'
 
 __all__ = ['__version__']

{webdev-2.0.0 → webdev-2.1.0}/webdev/static.py

@@ -50,6 +50,13 @@ EXTRA_MIME_TYPES = {
     '.svelte': 'text/plain',
     '.yml': 'text/plain',
     '.yaml': 'text/plain',
+    '.template': 'text/plain',
+    '.tmpl': 'text/plain',
+    '.tpl': 'text/plain',
+    '.j2': 'text/plain',
+    '.jinja': 'text/plain',
+    '.jinja2': 'text/plain',
+    '.config': 'text/plain',
 }
 
 #: Number of bytes inspected when sniffing whether an unknown file is text.