1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
======
hupper
======
``hupper`` is monitor for your Python process. When files change, the process
will be restarted. It can be extended to watch arbitrary files. Reloads can
also be triggered manually from code.
Builtin file monitors (in order of preference):
- :ref:`watchman_support`
- :ref:`watchdog_support`
- :ref:`polling_support`
Installation
============
Stable release
--------------
To install hupper, run this command in your terminal:
.. code-block:: console
$ pip install hupper
If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.
.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
From sources
------------
The sources for hupper can be downloaded from the `Github repo`_.
.. code-block:: console
$ git clone https://github.com/Pylons/hupper.git
Once you have a copy of the source, you can install it with:
.. code-block:: console
$ pip install -e .
.. _Github repo: https://github.com/Pylons/hupper
Builtin File Monitors
=====================
.. _watchman_support:
Watchman
--------
If the `watchman <https://facebook.github.io/watchman/>`_ daemon is running,
it is the preferred mechanism for monitoring files.
On MacOS it can be installed via:
.. code-block:: console
$ brew install watchman
Implementation: :class:`hupper.watchman.WatchmanFileMonitor`
.. _watchdog_support:
Watchdog
--------
If `watchdog <https://pypi.org/project/watchdog/>`_ is installed, it will be
used to more efficiently watch for changes to files.
.. code-block:: console
$ pip install watchdog
This is an optional dependency and if it's not installed, then ``hupper`` will
fallback to less efficient polling of the filesystem.
Implementation: :class:`hupper.watchdog.WatchdogFileMonitor`
.. _polling_support:
Polling
-------
The least efficient but most portable approach is to use basic file polling.
The ``reload_interval`` parameter controls how often the filesystem is scanned
and defaults to once per second.
Implementation: :class:`hupper.polling.PollingFileMonitor`
Command-line Usage
==================
Hupper can load any Python code similar to ``python -m <module>`` by using the
``hupper -m <module>`` program.
.. code-block:: console
$ hupper -m myapp
Starting monitor for PID 23982.
API Usage
=========
The reloading mechanism is implemented by forking worker processes from a
parent monitor. Start by defining an entry point for your process. This must
be an importable path in string format. For example,
``myapp.scripts.serve.main``:
.. code-block:: python
# myapp/scripts/serve.py
import sys
import hupper
import waitress
def wsgi_app(environ, start_response):
start_response('200 OK', [('Content-Type', 'text/plain'])
yield [b'hello']
def main(args=sys.argv[1:]):
if '--reload' in args:
# start_reloader will only return in a monitored subprocess
reloader = hupper.start_reloader('myapp.scripts.serve.main')
# monitor an extra file
reloader.watch_files(['foo.ini'])
waitress.serve(wsgi_app)
Many applications will tend to re-use the same startup code for both the
monitor and the worker. As a convenience to support this use case, the
:func:`hupper.start_reloader` function can be invoked both from the parent
process as well as the worker. When called initially from the parent process,
it will fork a new worker, then start the monitor and never return. When
called from the worker process it will return a proxy object that can be used
to communicate back to the monitor.
Checking if the reloader is active
----------------------------------
:func:`hupper.is_active` will return ``True`` if the reloader is active and
the current process may be reloaded.
Controlling the monitor
-----------------------
The worker processes may communicate back to the monitor and notify it of
new files to watch. This can be done by acquiring a reference to the
:class:`hupper.interfaces.IReloaderProxy` instance living in the worker
process. The :func:`hupper.start_reloader` function will return the instance
or :func:`hupper.get_reloader` can be used as well.
Overriding the default file monitor
-----------------------------------
.. versionadded:: 1.2
By default, ``hupper`` will auto-select the best file monitor based on what
is available. The preferred order is ``watchdog`` then ``polling``. If
``watchdog`` is installed but you do not want to use it for any reason, you
may override the default by specifying the monitor you wish to use instead in
the ``HUPPER_DEFAULT_MONITOR`` environment variable. For example:
.. code:: bash
$ HUPPER_DEFAULT_MONITOR=hupper.polling.PollingFileMonitor hupper -m foo
More Information
================
.. toctree::
:maxdepth: 1
api
contributing
changes
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
|
