Skip to content
Browse files

Move debugger details into a new section, #343.

  • Loading branch information...
1 parent dfd3ef6 commit 69e7a0a2a0391ed1bdd102deffbd98137790f959 @rduplain rduplain committed
Showing with 70 additions and 38 deletions.
  1. +67 −2 docs/errorhandling.rst
  2. +3 −36 docs/quickstart.rst
View
69 docs/errorhandling.rst
@@ -1,7 +1,7 @@
.. _application-errors:
-Handling Application Errors
-===========================
+Logging Application Errors
+==========================
.. versionadded:: 0.3
@@ -235,3 +235,68 @@ iterating over them to attach handlers::
for logger in loggers:
logger.addHandler(mail_handler)
logger.addHandler(file_handler)
+
+
+Debugging Application Errors
+============================
+
+For production applications, configure your application with logging and
+notifications as described in :ref:`application-errors`. This section provides
+pointers when debugging deployment configuration and digging deeper with a
+full-featured Python debugger.
+
+
+When in Doubt, Run Manually
+---------------------------
+
+Having problems getting your application configured for production? If you
+have shell access to your host, verify that you can run your application
+manually from the shell in the deployment environment. Be sure to run under
+the same user account as the configured deployment to troubleshoot permission
+issues. You can use Flask's builtin development server with `debug=True` on
+your production host, which is helpful in catching configuration issues, but
+**be sure to do this temporarily in a controlled environment.** Do not run in
+production with `debug=True`.
+
+
+.. _working-with-debuggers:
+
+Working with Debuggers
+----------------------
+
+To dig deeper, possibly to trace code execution, Flask provides a debugger out
+of the box (see :ref:`debug-mode`). If you would like to use another Python
+debugger, note that debuggers interfere with each other. You have to set some
+options in order to use your favorite debugger:
+
+* ``debug`` - whether to enable debug mode and catch exceptinos
+* ``use_debugger`` - whether to use the internal Flask debugger
+* ``use_reloader`` - whether to reload and fork the process on exception
+
+``debug`` must be True (i.e., exceptions must be caught) in order for the other
+two options to have any value.
+
+If you're using Aptana/Eclipse for debugging you'll need to set both
+``use_debugger`` and ``use_reloader`` to False.
+
+A possible useful pattern for configuration is to set the following in your
+config.yaml (change the block as approriate for your application, of course)::
+
+ FLASK:
+ DEBUG: True
+ DEBUG_WITH_APTANA: True
+
+Then in your application's entry-point (main.py), you could have something like::
+
+ if __name__ == "__main__":
+ # To allow aptana to receive errors, set use_debugger=False
+ app = create_app(config="config.yaml")
+
+ if app.debug: use_debugger = True
+ try:
+ # Disable Flask's debugger if external debugger is requested
+ use_debugger = not(app.config.get('DEBUG_WITH_APTANA'))
+ except:
+ pass
+ app.run(use_debugger=use_debugger, debug=app.debug,
+ use_reloader=use_debugger, host='0.0.0.0')
View
39 docs/quickstart.rst
@@ -77,6 +77,8 @@ To stop the server, hit control-C.
This tells your operating system to listen on all public IPs.
+.. _debug-mode:
+
Debug Mode
----------
@@ -112,42 +114,7 @@ Screenshot of the debugger in action:
:class: screenshot
:alt: screenshot of debugger in action
-.. admonition:: Working With Other Debuggers
-
- Debuggers interfere with each other.
- That said, you may still wish to use the debugger in a tool of your choice.
- Flask provides the following options to manage the debug process:
-
- * ``debug`` - whether to enable debug mode and catch exceptinos
- * ``use_debugger`` - whether to use the internal Flask debugger
- * ``use_reloader`` - whether to reload and fork the process on exception
-
- ``debug`` must be True (i.e., exceptions must be caught) in order for the
- other two options to have any value.
-
- If you're using Aptana/Eclipse for debugging you'll need to set both
- ``use_debugger`` and ``use_reloader`` to False.
-
- A possible useful pattern for configuration is to set the following in your
- config.yaml (change the block as approriate for your application, of course)::
-
- FLASK:
- DEBUG: True
- DEBUG_WITH_APTANA: True
-
- Then in your application's entry-point (main.py), you could have something like::
-
- if __name__ == "__main__":
- # To allow aptana to receive errors, set use_debugger=False
- app = create_app(config="config.yaml")
-
- if app.debug: use_debugger = True
- try:
- # Disable Flask's debugger if external debugger is requested
- use_debugger = not(app.config.get('DEBUG_WITH_APTANA'))
- except:
- pass
- app.run(use_debugger=use_debugger, debug=app.debug, use_reloader=use_debugger, host='0.0.0.0')
+Have another debugger in mind? See :ref:`working-with-debuggers`.
Routing

0 comments on commit 69e7a0a

Please sign in to comment.
Something went wrong with that request. Please try again.