0
# LiveReload
1
2
A Python implementation of LiveReload functionality that automatically reloads web pages when source files change. It provides a tornado-based development server with file watching capabilities, enabling rapid web development workflows without manual browser refreshing.
3
4
## Package Information
5
6
- **Package Name**: livereload
7
- **Language**: Python
8
- **Installation**: `pip install livereload`
9
- **Dependencies**: tornado
10
11
## Core Imports
12
13
```python
14
from livereload import Server, shell
15
```
16
17
Alternative server-only import:
18
19
```python
20
from livereload import Server
21
```
22
23
Advanced imports for custom handlers:
24
25
```python
26
from livereload.handlers import LiveReloadHandler, StaticFileHandler
27
from livereload.watcher import get_watcher_class, Watcher
28
```
29
30
## Basic Usage
31
32
### Simple File Watching Server
33
34
```python
35
from livereload import Server
36
37
# Create a server instance
38
server = Server()
39
40
# Watch current directory for changes
41
server.watch('.')
42
43
# Start serving on default port 5500
44
server.serve()
45
```
46
47
### Server with Shell Command Integration
48
49
```python
50
from livereload import Server, shell
51
52
server = Server()
53
54
# Watch LESS files and compile them when changed
55
server.watch('styles/*.less', shell('lessc styles/main.less styles/main.css'))
56
57
# Watch Python files and restart server
58
server.watch('*.py')
59
60
# Serve with custom configuration
61
server.serve(port=8000, host='0.0.0.0', open_url_delay=1)
62
```
63
64
### Command Line Usage
65
66
```bash
67
# Serve current directory with live reload
68
livereload
69
70
# Serve specific directory on custom port
71
livereload --port 8080 /path/to/project
72
73
# Watch specific files with custom delay
74
livereload --target "*.css" --wait 0.5
75
```
76
77
## Architecture
78
79
LiveReload consists of several key components:
80
81
- **Server**: Main class managing HTTP serving, WebSocket connections, and file watching coordination
82
- **Watcher**: File system monitoring with cross-platform support (polling + Linux inotify)
83
- **Handlers**: Tornado-based HTTP/WebSocket handlers for browser communication and static file serving
84
- **Shell Integration**: Command execution system for build tools and preprocessors
85
- **CLI/Django Integration**: Command-line tools and Django management command
86
87
## Capabilities
88
89
### Server Management
90
91
Core server functionality including HTTP serving, WebSocket communication, and development server features with support for custom headers, debug modes, and automatic browser opening.
92
93
```python { .api }
94
class Server:
95
def __init__(self, app=None, watcher=None): ...
96
def serve(self, port=5500, liveport=None, host=None, root=None, debug=None,
97
open_url=False, restart_delay=2, open_url_delay=None,
98
live_css=True, default_filename='index.html'): ...
99
def watch(self, filepath, func=None, delay=None, ignore=None): ...
100
def setHeader(self, name, value): ...
101
```
102
103
[Server Management](./server.md)
104
105
### File Watching System
106
107
Cross-platform file system monitoring with support for files, directories, and glob patterns. Includes polling-based fallback and Linux inotify optimization for efficient change detection.
108
109
```python { .api }
110
class Watcher:
111
def __init__(self): ...
112
def watch(self, path, func=None, delay=0, ignore=None): ...
113
def is_changed(self, path, ignore=None): ...
114
def start(self, callback): ...
115
116
def get_watcher_class(): ...
117
```
118
119
[File Watching](./file-watching.md)
120
121
### Shell Command Integration
122
123
Execute shell commands as file change callbacks with support for build tools, preprocessors, and custom development workflows.
124
125
```python { .api }
126
def shell(cmd, output=None, mode='w', cwd=None, shell=False): ...
127
```
128
129
[Shell Integration](./server.md#shell-command-integration)
130
131
### Command Line Interface and Framework Integration
132
133
Command-line tool for quick development server setup and Django framework integration for seamless development workflow.
134
135
```python { .api }
136
def main(argv=None): ...
137
138
class Command(BaseCommand):
139
def handle(self, *args, **options): ...
140
```
141
142
[CLI and Integrations](./cli-and-integrations.md)
143
144
## Types
145
146
Common parameter types used throughout the LiveReload API:
147
148
```python { .api }
149
# File change callback function
150
def callback_function():
151
"""Callback function invoked when file changes are detected."""
152
pass
153
154
# Path specifications (files, directories, or glob patterns)
155
path_spec = "file.py" # Single file
156
path_spec = "directory/" # Directory
157
path_spec = "**/*.css" # Glob pattern
158
159
# Ignore function for filtering files
160
def ignore_function(filename):
161
"""
162
Custom function to determine which files should be ignored.
163
164
Args:
165
filename (str): File name to check
166
167
Returns:
168
bool: True if file should be ignored, False otherwise
169
"""
170
return filename.endswith('.tmp')
171
```