HTTP Watcher (Python Library)

0.5.2 · active · verified Thu Apr 16

httpwatcher is a Python library and command-line utility for serving static files with live reload functionality, primarily intended for web development. It leverages the Tornado asynchronous web framework for its HTTP and WebSocket server capabilities. The current version is 0.5.2. Releases appear to be ad-hoc, tied to development needs rather than a fixed cadence.

Common errors

```
httpwatcher: command not found
```
cause The `httpwatcher` command-line utility is not in your system's PATH, or the package was not installed correctly.

fix Ensure `pip install httpwatcher` completed successfully. If using a virtual environment, ensure it is activated. On some systems, you might need to specify the full path to the executable, e.g., `python -m httpwatcher`.
```
Address already in use
```
cause Another process is already using the specified host and port (defaulting to 127.0.0.1:5555).

fix Stop the conflicting process, or specify a different port using the `--port` (command-line) or `port` (library) argument, e.g., `httpwatcher --port 8000`.
```
ModuleNotFoundError: No module named 'httpwatcher'
```
cause The `httpwatcher` package is not installed in the Python environment where you are trying to import it.

fix Activate your Python virtual environment (if applicable) and run `pip install httpwatcher`. Verify installation by running `pip show httpwatcher`.

Warnings

gotcha This Python library 'httpwatcher' is distinct from the 'HttpWatch' browser extension for HTTP debugging. Searching for issues or documentation might lead to irrelevant results for the browser tool.
Fix: Always qualify searches with 'python library' or 'pypi' when looking for information on this specific package.
breaking httpwatcher is explicitly designed for development purposes and is NOT intended for production environments. It has 'only basic security checks' and may have critical vulnerabilities not addressed in smaller sub-projects.
Fix: Do not deploy applications using `httpwatcher` as a production web server. Use production-ready web servers like Nginx, Apache, Gunicorn, or uWSGI instead.
gotcha The live reload functionality relies on injecting `<script>` tags before the `</body>` closing tag. HTML content without a `</body>` tag (e.g., partial HTML files or non-HTML content) will not receive the live reload script injection.
Fix: Ensure that all HTML files intended for live reloading contain a `</body>` tag. For non-HTML content, live reload will not function as expected.

Install

pip install httpwatcher Install stable version
pip install -U httpwatcher Upgrade to latest version

Imports

watch
```
import httpwatcher
httpwatcher.watch(...)
```
Convenience method to quickly set up and run a server.
HttpWatcherServer
```
from httpwatcher import HttpWatcherServer
```
For more fine-grained control over the server and I/O loop.

Quickstart

This example demonstrates how to set up and run an `httpwatcher` server programmatically. It serves files from a 'my_static_app' directory, includes a basic `index.html` file, and starts the server on `http://127.0.0.1:5555`. Changes to files in 'my_static_app' would trigger a live reload in connected browsers. The `open_browser=False` argument is used for programmatic control.

import os
from httpwatcher import HttpWatcherServer
from tornado.ioloop import IOLoop

# Create a dummy directory and file for demonstration
if not os.path.exists('my_static_app'):
    os.makedirs('my_static_app')
with open('my_static_app/index.html', 'w') as f:
    f.write('<!DOCTYPE html><html><head><title>Test</title></head><body><h1>Hello, httpwatcher!</h1></body></html>')

# Instantiate the server
server = HttpWatcherServer(
    root='my_static_app',
    host='127.0.0.1',
    port=5555,
    base_path='/',
    open_browser=False,
    verbose=True
)

# Start the server (usually in a separate thread or process for non-blocking operations)
# For a quick runnable example, we'll run it directly, which will block.
# In a real application, you might use IOLoop.current().start() in a thread.
print(f"Serving 'my_static_app' at http://127.0.0.1:5555")
print("Press Ctrl+C to stop.")

try:
    server.start() # This blocks the current thread
except KeyboardInterrupt:
    print("Server stopped.")
finally:
    server.stop()
    # Clean up dummy files/directories
    os.remove('my_static_app/index.html')
    os.rmdir('my_static_app')

view raw JSON →