From 9a80fe691dfd46664a39edf983332b99a71766d1 Mon Sep 17 00:00:00 2001 From: bagratte Date: Sat, 2 Apr 2016 01:12:25 +0400 Subject: [PATCH] minor revision of documentation. --- docs/appcontext.rst | 4 ++-- docs/config.rst | 2 +- docs/deploying/mod_wsgi.rst | 2 +- docs/deploying/uwsgi.rst | 6 ------ docs/errorhandling.rst | 11 ++++++----- docs/htmlfaq.rst | 2 +- docs/patterns/appdispatch.rst | 14 +++++++------- docs/patterns/deferredcallbacks.rst | 6 +++--- docs/quickstart.rst | 2 +- docs/signals.rst | 6 +++--- docs/testing.rst | 4 ++-- docs/tutorial/dbinit.rst | 4 ++-- docs/tutorial/views.rst | 6 +++--- 13 files changed, 32 insertions(+), 37 deletions(-) diff --git a/docs/appcontext.rst b/docs/appcontext.rst index 07e44f94..672b6bfd 100644 --- a/docs/appcontext.rst +++ b/docs/appcontext.rst @@ -26,8 +26,8 @@ In contrast, during request handling, a couple of other rules exist: There is a third state which is sitting in between a little bit. Sometimes you are dealing with an application in a way that is similar to -how you interact with applications during request handling just that there -is no request active. Consider for instance that you're sitting in an +how you interact with applications during request handling; just that there +is no request active. Consider, for instance, that you're sitting in an interactive Python shell and interacting with the application, or a command line application. diff --git a/docs/config.rst b/docs/config.rst index 245d3bab..8cef0686 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -330,7 +330,7 @@ there are alternative ways as well. For example you could use imports or subclassing. What is very popular in the Django world is to make the import explicit in -the config file by adding an ``from yourapplication.default_settings +the config file by adding ``from yourapplication.default_settings import *`` to the top of the file and then overriding the changes by hand. You could also inspect an environment variable like ``YOURAPPLICATION_MODE`` and set that to `production`, `development` etc diff --git a/docs/deploying/mod_wsgi.rst b/docs/deploying/mod_wsgi.rst index 9145b4f9..b06a1904 100644 --- a/docs/deploying/mod_wsgi.rst +++ b/docs/deploying/mod_wsgi.rst @@ -143,7 +143,7 @@ Troubleshooting If your application does not run, follow this guide to troubleshoot: **Problem:** application does not run, errorlog shows SystemExit ignored - You have a ``app.run()`` call in your application file that is not + You have an ``app.run()`` call in your application file that is not guarded by an ``if __name__ == '__main__':`` condition. Either remove that :meth:`~flask.Flask.run` call from the file and move it into a separate :file:`run.py` file or put it into such an if block. diff --git a/docs/deploying/uwsgi.rst b/docs/deploying/uwsgi.rst index 2d15440f..3bb2a45c 100644 --- a/docs/deploying/uwsgi.rst +++ b/docs/deploying/uwsgi.rst @@ -27,12 +27,6 @@ Starting your app with uwsgi Given a flask application in myapp.py, use the following command: -.. sourcecode:: text - - $ uwsgi -s /tmp/uwsgi.sock --manage-script-name --mount /yourapplication=myapp:app - -Or, if you prefer: - .. sourcecode:: text $ uwsgi -s /tmp/uwsgi.sock --manage-script-name --mount /yourapplication=myapp:app diff --git a/docs/errorhandling.rst b/docs/errorhandling.rst index 6f000717..1e6a771f 100644 --- a/docs/errorhandling.rst +++ b/docs/errorhandling.rst @@ -59,13 +59,14 @@ you with a function to call on your whim (and in tests). Note that are interchangeable when handed to the registration methods or decorator (``BadRequest.code == 400``). -You are however not limited to a :exc:`~werkzeug.exceptions.HTTPException` -or its code but can register a handler for every exception class you like. +You are however not limited to :exc:`~werkzeug.exceptions.HTTPException` +or HTTP status codes but can register a handler for every exception class you +like. .. versionchanged:: 1.0 - Errorhandlers are now prioritized by specifity instead of the order they're - registered in. + Errorhandlers are now prioritized by specificity of the exception classes + they are registered for instead of the order they are registered in. Handling ```````` @@ -74,7 +75,7 @@ Once an exception instance is raised, its class hierarchy is traversed, and searched for in the exception classes for which handlers are registered. The most specific handler is selected. -E.g. if a instance of :exc:`ConnectionRefusedError` is raised, and a handler +E.g. if an instance of :exc:`ConnectionRefusedError` is raised, and a handler is registered for :exc:`ConnectionError` and :exc:`ConnectionRefusedError`, the more specific :exc:`ConnectionRefusedError` handler is called on the exception instance, and its response is shown to the user. diff --git a/docs/htmlfaq.rst b/docs/htmlfaq.rst index cba99fa1..0b6ff504 100644 --- a/docs/htmlfaq.rst +++ b/docs/htmlfaq.rst @@ -30,7 +30,7 @@ the (X)HTML generation on the web is based on non-XML template engines (such as Jinja, the one used in Flask) which do not protect you from accidentally creating invalid XHTML. There are XML based template engines, such as Kid and the popular Genshi, but they often come with a larger -runtime overhead and, are not as straightforward to use because they have +runtime overhead and are not as straightforward to use because they have to obey XML rules. The majority of users, however, assumed they were properly using XHTML. diff --git a/docs/patterns/appdispatch.rst b/docs/patterns/appdispatch.rst index 3ff99e09..726850e2 100644 --- a/docs/patterns/appdispatch.rst +++ b/docs/patterns/appdispatch.rst @@ -4,11 +4,11 @@ Application Dispatching ======================= Application dispatching is the process of combining multiple Flask -applications on the WSGI level. You can not only combine Flask -applications into something larger but any WSGI application. This would -even allow you to run a Django and a Flask application in the same -interpreter side by side if you want. The usefulness of this depends on -how the applications work internally. +applications on the WSGI level. You can combine not only Flask +applications but any WSGI application. This would allow you to run a +Django and a Flask application in the same interpreter side by side if +you want. The usefulness of this depends on how the applications work +internally. The fundamental difference from the :ref:`module approach ` is that in this case you are running the same or @@ -31,7 +31,7 @@ Note that :func:`run_simple ` is not intended for use in production. Use a :ref:`full-blown WSGI server `. In order to use the interactive debugger, debugging must be enabled both on -the application and the simple server, here is the "hello world" example with +the application and the simple server. Here is the "hello world" example with debugging and :func:`run_simple `:: from flask import Flask @@ -56,7 +56,7 @@ If you have entirely separated applications and you want them to work next to each other in the same Python interpreter process you can take advantage of the :class:`werkzeug.wsgi.DispatcherMiddleware`. The idea here is that each Flask application is a valid WSGI application and they -are combined by the dispatcher middleware into a larger one that +are combined by the dispatcher middleware into a larger one that is dispatched based on prefix. For example you could have your main application run on ``/`` and your diff --git a/docs/patterns/deferredcallbacks.rst b/docs/patterns/deferredcallbacks.rst index 83d4fb49..886ae40a 100644 --- a/docs/patterns/deferredcallbacks.rst +++ b/docs/patterns/deferredcallbacks.rst @@ -56,9 +56,9 @@ this the following function needs to be registered as A Practical Example ------------------- -Now we can easily at any point in time register a function to be called at -the end of this particular request. For example you can remember the -current language of the user in a cookie in the before-request function:: +At any time during a request, we can register a function to be called at the +end of the request. For example you can remember the current language of the +user in a cookie in the before-request function:: from flask import request diff --git a/docs/quickstart.rst b/docs/quickstart.rst index bc6f0789..2866b6d7 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -321,7 +321,7 @@ You have no idea what an HTTP method is? Worry not, here is a quick introduction to HTTP methods and why they matter: The HTTP method (also often called "the verb") tells the server what the -clients wants to *do* with the requested page. The following methods are +client wants to *do* with the requested page. The following methods are very common: ``GET`` diff --git a/docs/signals.rst b/docs/signals.rst index b368194c..2426e920 100644 --- a/docs/signals.rst +++ b/docs/signals.rst @@ -19,9 +19,9 @@ more. Also keep in mind that signals are intended to notify subscribers and should not encourage subscribers to modify data. You will notice that there are signals that appear to do the same thing like some of the builtin decorators do (eg: :data:`~flask.request_started` is very similar -to :meth:`~flask.Flask.before_request`). There are however difference in -how they work. The core :meth:`~flask.Flask.before_request` handler for -example is executed in a specific order and is able to abort the request +to :meth:`~flask.Flask.before_request`). However, there are differences in +how they work. The core :meth:`~flask.Flask.before_request` handler, for +example, is executed in a specific order and is able to abort the request early by returning a response. In contrast all signal handlers are executed in undefined order and do not modify any data. diff --git a/docs/testing.rst b/docs/testing.rst index 6387202b..493ba320 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -223,8 +223,8 @@ there does not seem to be a good way to do that, consider switching to application factories (see :ref:`app-factories`). Note however that if you are using a test request context, the -:meth:`~flask.Flask.before_request` functions are not automatically called -same for :meth:`~flask.Flask.after_request` functions. However +:meth:`~flask.Flask.before_request` and :meth:`~flask.Flask.after_request` +functions are not called automatically. However :meth:`~flask.Flask.teardown_request` functions are indeed executed when the test request context leaves the ``with`` block. If you do want the :meth:`~flask.Flask.before_request` functions to be called as well, you diff --git a/docs/tutorial/dbinit.rst b/docs/tutorial/dbinit.rst index b3cf39dc..ebe9ce44 100644 --- a/docs/tutorial/dbinit.rst +++ b/docs/tutorial/dbinit.rst @@ -38,12 +38,12 @@ add this function below the `connect_db` function in :file:`flaskr.py`:: The ``app.cli.command()`` decorator registers a new command with the :command:`flask` script. When the command executes, Flask will automatically -create a application context for us bound to the right application. +create an application context for us bound to the right application. Within the function, we can then access :attr:`flask.g` and other things as we would expect. When the script ends, the application context tears down and the database connection is released. -We want to keep an actual functions around that initializes the database, +We want to keep an actual function around that initializes the database, though, so that we can easily create databases in unit tests later on. (For more information see :ref:`testing`.) diff --git a/docs/tutorial/views.rst b/docs/tutorial/views.rst index 10b578a7..8ecc41a2 100644 --- a/docs/tutorial/views.rst +++ b/docs/tutorial/views.rst @@ -12,11 +12,11 @@ Show Entries This view shows all the entries stored in the database. It listens on the root of the application and will select title and text from the database. The one with the highest id (the newest entry) will be on top. The rows -returned from the cursor look a bit like tuples because we are using +returned from the cursor look a bit like dictionaries because we are using the :class:`sqlite3.Row` row factory. -The view function will pass the entries as dictionaries to the -:file:`show_entries.html` template and return the rendered one:: +The view function will pass the entries to the :file:`show_entries.html` +template and return the rendered one:: @app.route('/') def show_entries():