Merge pull request #355 from shanx/fix/wsgi-env-behaviour

Added documentation about wsgi env behaviour strategies
unbit · May 9, 2017 · 070b696 · 070b696
2 parents 4125a80 + 1af8b3f
commit 070b696
Show file tree

Hide file tree

Showing 4 changed files with 17 additions and 5 deletions.
diff --git a/Options.rst b/Options.rst
@@ -10,7 +10,7 @@ works, you should read the various quickstarts and tutorials.
 
 Each option has the following attributes:
 
-* argument: it is the struct option (used by getopt()/getopt_long()) has_arg element. Can be 'required', 'no_argument' or 'optional_argument'
+* argument: it is the struct option (used by getopt()/getopt_long()) has_arg element. Can be 'required_argument', 'no_argument' or 'optional_argument'
 * shortcut: some option can be specified with the short form (a dash followed by a single letter)
 * parser: this is how uWSGI parses the parameter. There are dozens of way, the most common are 'uwsgi_opt_set_str' when it takes a simple string, 'uwsgi_opt_set_int' when it takes a 32bit number, 'uwsgi_opt_add_string_list' when the parameter can be specified multiple times to build a list.
 * help: the help message, the same you get from ``uwsgi --help``
@@ -11981,8 +11981,9 @@ wsgi-env-behaviour
 
 ``parser``: uwsgi_opt_set_str
 
-``help``: set the strategy for allocating/deallocating the WSGI env
+``help``: set the strategy for allocating/deallocating the WSGI env, can be: "cheat" or "holy"
 
+``reference``: :doc:`articles/WSGIEnvBehaviour`
 
 
 wsgi-env-behavior
@@ -11991,9 +11992,9 @@ wsgi-env-behavior
 
 ``parser``: uwsgi_opt_set_str
 
-``help``: set the strategy for allocating/deallocating the WSGI env
-
+``help``: set the strategy for allocating/deallocating the WSGI env, can be: "cheat" or "holy"
 
+``reference``: :doc:`articles/WSGIEnvBehaviour`
 
 start_response-nodelay
 **********************

diff --git a/_options/optdefs.py b/_options/optdefs.py
@@ -571,7 +571,7 @@ def python_options():
         s.o("py-tracebacker", str, "enable the uWSGI Python tracebacker")
         s.o(("py-auto-reload", "py-autoreload", "python-auto-reload", "python-autoreload"), int, "Monitor Python modules' modification times to trigger reload (use only in development)")
         s.o("py-auto-reload-ignore", [str], "ignore the specified module during auto-reload scan")
-        s.o(("wsgi-env-behaviour", "wsgi-env-behavior"), str, "set the strategy for allocating/deallocating the WSGI env")
+        s.o(("wsgi-env-behaviour", "wsgi-env-behavior"), str, "set the strategy for allocating/deallocating the WSGI env, can be: \"cheat\" or \"holy\"")
         s.o("start_response-nodelay", True, "send WSGI http headers as soon as possible (PEP violation)")
         s.o("python-version", True, "report python version")
     return config

diff --git a/articles/WSGIEnvBehaviour.rst b/articles/WSGIEnvBehaviour.rst
@@ -0,0 +1,10 @@
+WSGI env behaviour policies
+===========================
+
+When using uWSGI two different strategies can be used for allocating/deallocating the WSGI env using either the
+``wsgi-env-behaviour`` or ``wsgi-env-behavior`` option:
+
+``cheat``: it preallocates the env dictionary on uWSGI startup and clears it after each request.
+This is the default behaviour in uWSGI<=2.0.x
+
+``holy``: creates and destroys the environ dictionary at each request. This is the default behaviour in uWSGI>=2.1
diff --git a/index.rst b/index.rst
@@ -112,6 +112,7 @@ Articles
    articles/TheArtOfGracefulReloading
    articles/FunWithPerlEyetoyRaspberrypi
    articles/OffloadingWebsocketsAndSSE
+   articles/WSGIEnvBehaviour