| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: django-maintenance-mode |
| 3 |
Version: 0.16.1 |
| 4 |
Summary: django-maintenance-mode shows a 503 error page when maintenance-mode is on. |
| 5 |
Home-page: https://github.com/fabiocaccamo/django-maintenance-mode |
| 6 |
Author: Fabio Caccamo |
| 7 |
Author-email: [email protected] |
| 8 |
License: MIT |
| 9 |
Download-URL: https://github.com/fabiocaccamo/django-maintenance-mode/archive/0.16.1.tar.gz |
| 10 |
Description: [](https://www.python.org/) |
| 11 |
[](https://www.djangoproject.com/) |
| 12 |
|
| 13 |
[](https://pypi.org/project/django-maintenance-mode/) |
| 14 |
[](https://pepy.tech/project/django-maintenance-mode) |
| 15 |
[](https://github.com/fabiocaccamo/django-maintenance-mode/) |
| 16 |
[](https://badges.pufler.dev) |
| 17 |
[](https://github.com/fabiocaccamo/django-maintenance-mode/blob/master/LICENSE.txt) |
| 18 |
|
| 19 |
[](https://travis-ci.org/fabiocaccamo/django-maintenance-mode) |
| 20 |
[](https://codecov.io/gh/fabiocaccamo/django-maintenance-mode) |
| 21 |
[](https://www.codacy.com/app/fabiocaccamo/django-maintenance-mode) |
| 22 |
[](https://codeclimate.com/github/fabiocaccamo/django-maintenance-mode/) |
| 23 |
[](https://requires.io/github/fabiocaccamo/django-maintenance-mode/requirements/?branch=master) |
| 24 |
|
| 25 |
# django-maintenance-mode |
| 26 |
django-maintenance-mode shows a 503 error page when **maintenance-mode** is **on**. |
| 27 |
|
| 28 |
It works at application level, so your django instance should be up. |
| 29 |
|
| 30 |
It doesn't use database and doesn't prevent database access. |
| 31 |
|
| 32 |
## Installation |
| 33 |
|
| 34 |
1. Run ``pip install django-maintenance-mode`` or [download django-maintenance-mode](http://pypi.python.org/pypi/django-maintenance-mode) and add the **maintenance_mode** package to your project |
| 35 |
2. Add ``'maintenance_mode'`` to ``settings.INSTALLED_APPS`` before custom applications |
| 36 |
3. Add ``'maintenance_mode.middleware.MaintenanceModeMiddleware'`` to ``settings.MIDDLEWARE_CLASSES``/``settings.MIDDLEWARE`` as last middleware |
| 37 |
4. Add your custom ``templates/503.html`` file |
| 38 |
5. Restart your application server |
| 39 |
|
| 40 |
## Configuration (optional) |
| 41 |
|
| 42 |
### Settings |
| 43 |
All these settings are optional, if not defined in ``settings.py`` the default values (listed below) will be used. |
| 44 |
|
| 45 |
```python |
| 46 |
# if True the maintenance-mode will be activated |
| 47 |
MAINTENANCE_MODE = None |
| 48 |
``` |
| 49 |
|
| 50 |
```python |
| 51 |
# by default, to get/set the state value a local file backend is used |
| 52 |
# if you want to use the db or cache, you can create a custom backend |
| 53 |
# custom backends must extend 'maintenance_mode.backends.AbstractStateBackend' class |
| 54 |
# and implement get_value(self) and set_value(self, val) methods |
| 55 |
MAINTENANCE_MODE_STATE_BACKEND = 'maintenance_mode.backends.LocalFileBackend' |
| 56 |
|
| 57 |
# alternatively it is possible to use the default storage backend |
| 58 |
MAINTENANCE_MODE_STATE_BACKEND = 'maintenance_mode.backends.DefaultStorageBackend' |
| 59 |
``` |
| 60 |
|
| 61 |
```python |
| 62 |
# by default, a file named "maintenance_mode_state.txt" will be created in the settings.py directory |
| 63 |
# you can customize the state file path in case the default one is not writable |
| 64 |
MAINTENANCE_MODE_STATE_FILE_PATH = 'maintenance_mode_state.txt' |
| 65 |
``` |
| 66 |
|
| 67 |
```python |
| 68 |
# if True admin site will not be affected by the maintenance-mode page |
| 69 |
MAINTENANCE_MODE_IGNORE_ADMIN_SITE = False |
| 70 |
``` |
| 71 |
|
| 72 |
```python |
| 73 |
# if True anonymous users will not see the maintenance-mode page |
| 74 |
MAINTENANCE_MODE_IGNORE_ANONYMOUS_USER = False |
| 75 |
``` |
| 76 |
|
| 77 |
```python |
| 78 |
# if True authenticated users will not see the maintenance-mode page |
| 79 |
MAINTENANCE_MODE_IGNORE_AUTHENTICATED_USER = False |
| 80 |
``` |
| 81 |
|
| 82 |
```python |
| 83 |
# if True the staff will not see the maintenance-mode page |
| 84 |
MAINTENANCE_MODE_IGNORE_STAFF = False |
| 85 |
``` |
| 86 |
|
| 87 |
```python |
| 88 |
# if True the superuser will not see the maintenance-mode page |
| 89 |
MAINTENANCE_MODE_IGNORE_SUPERUSER = False |
| 90 |
``` |
| 91 |
|
| 92 |
```python |
| 93 |
# list of ip-addresses that will not be affected by the maintenance-mode |
| 94 |
# ip-addresses will be used to compile regular expressions objects |
| 95 |
MAINTENANCE_MODE_IGNORE_IP_ADDRESSES = () |
| 96 |
``` |
| 97 |
|
| 98 |
```python |
| 99 |
# the path of the function that will return the client IP address given the request object -> 'myapp.mymodule.myfunction' |
| 100 |
# the default function ('maintenance_mode.utils.get_client_ip_address') returns request.META['REMOTE_ADDR'] |
| 101 |
# in some cases the default function returns None, to avoid this scenario just use 'django-ipware' |
| 102 |
MAINTENANCE_MODE_GET_CLIENT_IP_ADDRESS = None |
| 103 |
``` |
| 104 |
Retrieve user's real IP address using [`django-ipware`](https://github.com/un33k/django-ipware): |
| 105 |
```python |
| 106 |
MAINTENANCE_MODE_GET_CLIENT_IP_ADDRESS = 'ipware.ip.get_ip' |
| 107 |
``` |
| 108 |
|
| 109 |
```python |
| 110 |
# list of urls that will not be affected by the maintenance-mode |
| 111 |
# urls will be used to compile regular expressions objects |
| 112 |
MAINTENANCE_MODE_IGNORE_URLS = () |
| 113 |
``` |
| 114 |
|
| 115 |
```python |
| 116 |
# if True the maintenance mode will not return 503 response while running tests |
| 117 |
# useful for running tests while maintenance mode is on, before opening the site to public use |
| 118 |
MAINTENANCE_MODE_IGNORE_TESTS = False |
| 119 |
``` |
| 120 |
|
| 121 |
```python |
| 122 |
# the absolute url where users will be redirected to during maintenance-mode |
| 123 |
MAINTENANCE_MODE_REDIRECT_URL = None |
| 124 |
``` |
| 125 |
|
| 126 |
```python |
| 127 |
# the template that will be shown by the maintenance-mode page |
| 128 |
MAINTENANCE_MODE_TEMPLATE = '503.html' |
| 129 |
``` |
| 130 |
|
| 131 |
```python |
| 132 |
# the path of the function that will return the template context -> 'myapp.mymodule.myfunction' |
| 133 |
MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT = None |
| 134 |
``` |
| 135 |
|
| 136 |
```python |
| 137 |
# the HTTP status code to send |
| 138 |
MAINTENANCE_MODE_STATUS_CODE = 503 |
| 139 |
``` |
| 140 |
|
| 141 |
```python |
| 142 |
# the value in seconds of the Retry-After header during maintenance-mode |
| 143 |
MAINTENANCE_MODE_RETRY_AFTER = 3600 # 1 hour |
| 144 |
``` |
| 145 |
|
| 146 |
#### Context Processors |
| 147 |
Add **maintenance_mode.context_processors.maintenance_mode** to your context_processors list in ``settings.py`` if you want to access the maintenance_mode status in your templates. |
| 148 |
|
| 149 |
```python |
| 150 |
TEMPLATES = [ |
| 151 |
{ |
| 152 |
# ... |
| 153 |
'OPTIONS': { |
| 154 |
'context_processors': [ |
| 155 |
# ... |
| 156 |
'maintenance_mode.context_processors.maintenance_mode', |
| 157 |
# ... |
| 158 |
], |
| 159 |
}, |
| 160 |
# ... |
| 161 |
}, |
| 162 |
] |
| 163 |
``` |
| 164 |
|
| 165 |
#### Logging |
| 166 |
You can disable emailing 503 errors to admins while maintenance mode is enabled: |
| 167 |
|
| 168 |
```python |
| 169 |
LOGGING = { |
| 170 |
'filters': { |
| 171 |
'require_not_maintenance_mode_503': { |
| 172 |
'()': 'maintenance_mode.logging.RequireNotMaintenanceMode503', |
| 173 |
}, |
| 174 |
... |
| 175 |
}, |
| 176 |
'handlers': { |
| 177 |
... |
| 178 |
}, |
| 179 |
... |
| 180 |
} |
| 181 |
``` |
| 182 |
|
| 183 |
### Context Managers |
| 184 |
You can force a block of code execution to run under maintenance mode or not using context managers: |
| 185 |
|
| 186 |
```python |
| 187 |
from maintenance_mode.core import maintenance_mode_off, maintenance_mode_on |
| 188 |
|
| 189 |
with maintenance_mode_on(): |
| 190 |
# do stuff |
| 191 |
pass |
| 192 |
|
| 193 |
with maintenance_mode_off(): |
| 194 |
# do stuff |
| 195 |
pass |
| 196 |
``` |
| 197 |
|
| 198 |
### URLs |
| 199 |
Add **maintenance_mode.urls** to ``urls.py`` if you want superusers able to set maintenance_mode using urls. |
| 200 |
|
| 201 |
```python |
| 202 |
urlpatterns = [ |
| 203 |
# ... |
| 204 |
url(r'^maintenance-mode/', include('maintenance_mode.urls')), |
| 205 |
# ... |
| 206 |
] |
| 207 |
``` |
| 208 |
|
| 209 |
### Views |
| 210 |
You can force maintenance mode on/off at view level using view decorators: |
| 211 |
|
| 212 |
```python |
| 213 |
from maintenance_mode.decorators import force_maintenance_mode_off, force_maintenance_mode_on |
| 214 |
|
| 215 |
@force_maintenance_mode_off |
| 216 |
def my_view_a(request): |
| 217 |
# never return 503 response |
| 218 |
pass |
| 219 |
|
| 220 |
@force_maintenance_mode_on |
| 221 |
def my_view_b(request): |
| 222 |
# always return 503 response |
| 223 |
pass |
| 224 |
``` |
| 225 |
|
| 226 |
## Usage |
| 227 |
|
| 228 |
### Python |
| 229 |
```python |
| 230 |
from maintenance_mode.core import get_maintenance_mode, set_maintenance_mode |
| 231 |
|
| 232 |
set_maintenance_mode(True) |
| 233 |
|
| 234 |
if get_maintenance_mode(): |
| 235 |
set_maintenance_mode(False) |
| 236 |
``` |
| 237 |
or |
| 238 |
```python |
| 239 |
from django.core.management import call_command |
| 240 |
from django.core.management.base import BaseCommand |
| 241 |
|
| 242 |
|
| 243 |
class Command(BaseCommand): |
| 244 |
|
| 245 |
def handle(self, *args, **options): |
| 246 |
|
| 247 |
call_command('maintenance_mode', 'on') |
| 248 |
|
| 249 |
# call your command(s) |
| 250 |
|
| 251 |
call_command('maintenance_mode', 'off') |
| 252 |
|
| 253 |
|
| 254 |
|
| 255 |
``` |
| 256 |
|
| 257 |
### Templates |
| 258 |
```html |
| 259 |
{% if maintenance_mode %} |
| 260 |
<!-- html --> |
| 261 |
{% endif %} |
| 262 |
``` |
| 263 |
|
| 264 |
### Terminal |
| 265 |
|
| 266 |
Run ``python manage.py maintenance_mode <on|off>`` |
| 267 |
|
| 268 |
*(**This is not Heroku-friendly because** any execution of heroku run* `manage.py` *will be run on a separate worker dyno, not the web one. Therefore **the state-file is set but on the wrong machine. You should use a custom*** `MAINTENANCE_MODE_STATE_BACKEND`*.)* |
| 269 |
|
| 270 |
### URLs |
| 271 |
Superusers can change maintenance-mode using the following urls: |
| 272 |
|
| 273 |
``/maintenance-mode/off/`` |
| 274 |
|
| 275 |
``/maintenance-mode/on/`` |
| 276 |
|
| 277 |
## Testing |
| 278 |
```bash |
| 279 |
# create python virtual environment |
| 280 |
virtualenv testing_django_maintenance_mode |
| 281 |
|
| 282 |
# activate virtualenv |
| 283 |
cd testing_django_maintenance_mode && . bin/activate |
| 284 |
|
| 285 |
# clone repo |
| 286 |
git clone https://github.com/fabiocaccamo/django-maintenance-mode.git src && cd src |
| 287 |
|
| 288 |
# run tests |
| 289 |
tox |
| 290 |
# or |
| 291 |
python setup.py test |
| 292 |
# or |
| 293 |
python -m django test --settings "tests.settings" |
| 294 |
``` |
| 295 |
|
| 296 |
## License |
| 297 |
Released under [MIT License](LICENSE.txt). |
| 298 |
|
| 299 |
--- |
| 300 |
|
| 301 |
## See also |
| 302 |
|
| 303 |
- [`django-admin-interface`](https://github.com/fabiocaccamo/django-admin-interface) - the default admin interface made customizable by the admin itself. popup windows replaced by modals. 🧙 ⚡ |
| 304 |
|
| 305 |
- [`django-colorfield`](https://github.com/fabiocaccamo/django-colorfield) - simple color field for models with a nice color-picker in the admin. 🎨 |
| 306 |
|
| 307 |
- [`django-extra-settings`](https://github.com/fabiocaccamo/django-extra-settings) - config and manage typed extra settings using just the django admin. ⚙️ |
| 308 |
|
| 309 |
- [`django-redirects`](https://github.com/fabiocaccamo/django-redirects) - redirects with full control. ↪️ |
| 310 |
|
| 311 |
- [`django-treenode`](https://github.com/fabiocaccamo/django-treenode) - probably the best abstract model / admin for your tree based stuff. 🌳 |
| 312 |
|
| 313 |
- [`python-benedict`](https://github.com/fabiocaccamo/python-benedict) - dict subclass with keylist/keypath support, I/O shortcuts (base64, csv, json, pickle, plist, query-string, toml, xml, yaml) and many utilities. 📘 |
| 314 |
|
| 315 |
- [`python-codicefiscale`](https://github.com/fabiocaccamo/python-codicefiscale) - encode/decode Italian fiscal codes - codifica/decodifica del Codice Fiscale. 🇮🇹 💳 |
| 316 |
|
| 317 |
- [`python-fsutil`](https://github.com/fabiocaccamo/python-fsutil) - file-system utilities for lazy devs. 🧟♂️ |
| 318 |
|
| 319 |
Keywords: django,maintenance,mode,offline,under,503,service,temporarily,unavailable |
| 320 |
Platform: UNKNOWN |
| 321 |
Classifier: Development Status :: 5 - Production/Stable |
| 322 |
Classifier: Environment :: Web Environment |
| 323 |
Classifier: Framework :: Django |
| 324 |
Classifier: Framework :: Django :: 1.7 |
| 325 |
Classifier: Framework :: Django :: 1.8 |
| 326 |
Classifier: Framework :: Django :: 1.9 |
| 327 |
Classifier: Framework :: Django :: 1.10 |
| 328 |
Classifier: Framework :: Django :: 1.11 |
| 329 |
Classifier: Framework :: Django :: 2.0 |
| 330 |
Classifier: Framework :: Django :: 2.1 |
| 331 |
Classifier: Framework :: Django :: 2.2 |
| 332 |
Classifier: Framework :: Django :: 3.0 |
| 333 |
Classifier: Framework :: Django :: 3.1 |
| 334 |
Classifier: Framework :: Django :: 3.2 |
| 335 |
Classifier: Intended Audience :: Developers |
| 336 |
Classifier: License :: OSI Approved :: MIT License |
| 337 |
Classifier: Natural Language :: English |
| 338 |
Classifier: Operating System :: OS Independent |
| 339 |
Classifier: Programming Language :: Python :: 2 |
| 340 |
Classifier: Programming Language :: Python :: 2.7 |
| 341 |
Classifier: Programming Language :: Python :: 3 |
| 342 |
Classifier: Programming Language :: Python :: 3.4 |
| 343 |
Classifier: Programming Language :: Python :: 3.5 |
| 344 |
Classifier: Programming Language :: Python :: 3.6 |
| 345 |
Classifier: Programming Language :: Python :: 3.7 |
| 346 |
Classifier: Programming Language :: Python :: 3.8 |
| 347 |
Classifier: Programming Language :: Python :: 3.9 |
| 348 |
Classifier: Topic :: Software Development :: Build Tools |
| 349 |
Requires: django(>=1.7) |
| 350 |
Description-Content-Type: text/markdown |