forked from orbit-oss/flask
fix RST line too long
This commit is contained in:
David Baumgold
parent
c5c8bbc7f6
commit
6606a4a238
15 changed files with 104 additions and 89 deletions
|
|
@ -8,10 +8,11 @@ Thread-Locals in Flask
|
|||
|
||||
One of the design decisions in Flask was that simple tasks should be simple;
|
||||
they should not take a lot of code and yet they should not limit you. Because
|
||||
of that, Flask has a few design choices that some people might find surprising or
|
||||
unorthodox. For example, Flask uses thread-local objects internally so that you
|
||||
don’t have to pass objects around from function to function within a request in
|
||||
order to stay threadsafe. This approach is convenient, but requires a valid
|
||||
of that, Flask has a few design choices that some people might find
|
||||
surprising or unorthodox. For example, Flask uses thread-local objects
|
||||
internally so that you don’t have to pass objects around from
|
||||
function to function within a request in order to stay threadsafe.
|
||||
This approach is convenient, but requires a valid
|
||||
request context for dependency injection or when attempting to reuse code which
|
||||
uses a value pegged to the request. The Flask project is honest about
|
||||
thread-locals, does not hide them, and calls out in the code and documentation
|
||||
|
|
|
|||
|
|
@ -35,7 +35,8 @@ Subclass.
|
|||
The :class:`~flask.Flask` class has many methods designed for subclassing. You
|
||||
can quickly add or customize behavior by subclassing :class:`~flask.Flask` (see
|
||||
the linked method docs) and using that subclass wherever you instantiate an
|
||||
application class. This works well with :ref:`app-factories`. See :doc:`/patterns/subclassing` for an example.
|
||||
application class. This works well with :ref:`app-factories`.
|
||||
See :doc:`/patterns/subclassing` for an example.
|
||||
|
||||
Wrap with middleware.
|
||||
---------------------
|
||||
|
|
|
|||
|
|
@ -258,13 +258,14 @@ Here is an example for a "404 Page Not Found" exception::
|
|||
|
||||
Most errorhandlers will simply work as expected; however, there is a caveat
|
||||
concerning handlers for 404 and 405 exceptions. These errorhandlers are only
|
||||
invoked from an appropriate ``raise`` statement or a call to ``abort`` in another
|
||||
of the blueprint's view functions; they are not invoked by, e.g., an invalid URL
|
||||
access. This is because the blueprint does not "own" a certain URL space, so
|
||||
the application instance has no way of knowing which blueprint errorhandler it
|
||||
should run if given an invalid URL. If you would like to execute different
|
||||
handling strategies for these errors based on URL prefixes, they may be defined
|
||||
at the application level using the ``request`` proxy object::
|
||||
invoked from an appropriate ``raise`` statement or a call to ``abort``
|
||||
in another of the blueprint's view functions; they are not invoked by,
|
||||
e.g., an invalid URL access. This is because the blueprint does not
|
||||
"own" a certain URL space, so the application instance has no way of
|
||||
knowing which blueprint errorhandler it should run if given an invalid URL.
|
||||
If you would like to execute different handling strategies for these errors
|
||||
based on URL prefixes, they may be defined at the application level using
|
||||
the ``request`` proxy object::
|
||||
|
||||
@app.errorhandler(404)
|
||||
@app.errorhandler(405)
|
||||
|
|
|
|||
|
|
@ -193,7 +193,7 @@ environment variables. The variables use the pattern
|
|||
``FLASK_COMMAND_OPTION``. For example, to set the port for the run
|
||||
command, instead of ``flask run --port 8000``:
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: bash
|
||||
|
||||
$ export FLASK_RUN_PORT=8000
|
||||
$ flask run
|
||||
|
|
@ -209,7 +209,7 @@ Disable dotenv
|
|||
The ``flask`` command will show a message if it detects dotenv files but
|
||||
python-dotenv is not installed.
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: bash
|
||||
|
||||
$ flask run
|
||||
* Tip: There are .env files present. Do "pip install python-dotenv" to use them.
|
||||
|
|
@ -221,7 +221,7 @@ a project runner that loads them already. Keep in mind that the
|
|||
environment variables must be set before the app loads or it won't
|
||||
configure as expected.
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: bash
|
||||
|
||||
$ export FLASK_SKIP_DOTENV=1
|
||||
$ flask run
|
||||
|
|
|
|||
|
|
@ -46,9 +46,9 @@ In Apache for example you can put something like this into the config:
|
|||
ScriptAlias /app /path/to/the/application.cgi
|
||||
|
||||
On shared webhosting, though, you might not have access to your Apache config.
|
||||
In this case, a file called ``.htaccess``, sitting in the public directory you want
|
||||
your app to be available, works too but the ``ScriptAlias`` directive won't
|
||||
work in that case:
|
||||
In this case, a file called ``.htaccess``, sitting in the public directory
|
||||
you want your app to be available, works too but the ``ScriptAlias`` directive
|
||||
won't work in that case:
|
||||
|
||||
.. sourcecode:: apache
|
||||
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ FastCGI
|
|||
=======
|
||||
|
||||
FastCGI is a deployment option on servers like `nginx`_, `lighttpd`_, and
|
||||
`cherokee`_; see :doc:`uwsgi` and :doc:`wsgi-standalone` for other options. To
|
||||
use your WSGI application with any of them you will need a FastCGI server first.
|
||||
The most popular one is `flup`_ which we will use for this guide. Make sure to
|
||||
have it installed to follow along.
|
||||
`cherokee`_; see :doc:`uwsgi` and :doc:`wsgi-standalone` for other options.
|
||||
To use your WSGI application with any of them you will need a FastCGI
|
||||
server first. The most popular one is `flup`_ which we will use for
|
||||
this guide. Make sure to have it installed to follow along.
|
||||
|
||||
.. admonition:: Watch Out
|
||||
|
||||
|
|
|
|||
|
|
@ -52,10 +52,10 @@ reload you can safely ignore them. Just restart the server.
|
|||
Creating a `.wsgi` file
|
||||
-----------------------
|
||||
|
||||
To run your application you need a :file:`yourapplication.wsgi` file. This file
|
||||
contains the code `mod_wsgi` is executing on startup to get the application
|
||||
object. The object called `application` in that file is then used as
|
||||
application.
|
||||
To run your application you need a :file:`yourapplication.wsgi` file.
|
||||
This file contains the code `mod_wsgi` is executing on startup
|
||||
to get the application object. The object called `application`
|
||||
in that file is then used as application.
|
||||
|
||||
For most applications the following file should be sufficient::
|
||||
|
||||
|
|
@ -108,16 +108,17 @@ refuse to run with the above configuration. On a Windows system, eliminate those
|
|||
|
||||
.. sourcecode:: apache
|
||||
|
||||
<VirtualHost *>
|
||||
ServerName example.com
|
||||
WSGIScriptAlias / C:\yourdir\yourapp.wsgi
|
||||
<Directory C:\yourdir>
|
||||
Order deny,allow
|
||||
Allow from all
|
||||
</Directory>
|
||||
</VirtualHost>
|
||||
<VirtualHost *>
|
||||
ServerName example.com
|
||||
WSGIScriptAlias / C:\yourdir\yourapp.wsgi
|
||||
<Directory C:\yourdir>
|
||||
Order deny,allow
|
||||
Allow from all
|
||||
</Directory>
|
||||
</VirtualHost>
|
||||
|
||||
Note: There have been some changes in access control configuration for `Apache 2.4`_.
|
||||
Note: There have been some changes in access control configuration
|
||||
for `Apache 2.4`_.
|
||||
|
||||
.. _Apache 2.4: https://httpd.apache.org/docs/trunk/upgrading.html
|
||||
|
||||
|
|
|
|||
|
|
@ -31,10 +31,11 @@ Given a flask application in myapp.py, use the following command:
|
|||
|
||||
$ uwsgi -s /tmp/yourapplication.sock --manage-script-name --mount /yourapplication=myapp:app
|
||||
|
||||
The ``--manage-script-name`` will move the handling of ``SCRIPT_NAME`` to uwsgi,
|
||||
since it is smarter about that. It is used together with the ``--mount``
|
||||
directive which will make requests to ``/yourapplication`` be directed to
|
||||
``myapp:app``. If your application is accessible at root level, you can use a
|
||||
The ``--manage-script-name`` will move the handling of ``SCRIPT_NAME``
|
||||
to uwsgi, since it is smarter about that.
|
||||
It is used together with the ``--mount`` directive which will make
|
||||
requests to ``/yourapplication`` be directed to ``myapp:app``.
|
||||
If your application is accessible at root level, you can use a
|
||||
single ``/`` instead of ``/yourapplication``. ``myapp`` refers to the name of
|
||||
the file of your flask application (without extension) or the module which
|
||||
provides ``app``. ``app`` is the callable inside of your application (usually
|
||||
|
|
|
|||
|
|
@ -50,14 +50,15 @@ And then add this to your Flask app::
|
|||
|
||||
import sentry_sdk
|
||||
from sentry_sdk.integrations.flask import FlaskIntegration
|
||||
|
||||
|
||||
sentry_sdk.init('YOUR_DSN_HERE',integrations=[FlaskIntegration()])
|
||||
|
||||
The `YOUR_DSN_HERE` value needs to be replaced with the DSN value you get
|
||||
from your Sentry installation.
|
||||
|
||||
After installation, failures leading to an Internal Server Error are automatically reported to
|
||||
Sentry and from there you can receive error notifications.
|
||||
After installation, failures leading to an Internal Server Error
|
||||
are automatically reported to Sentry and from there you can
|
||||
receive error notifications.
|
||||
|
||||
Follow-up reads:
|
||||
|
||||
|
|
@ -126,8 +127,9 @@ registered, :class:`~werkzeug.exceptions.HTTPException` subclasses show a
|
|||
generic message about their code, while other exceptions are converted to a
|
||||
generic 500 Internal Server Error.
|
||||
|
||||
For example, if an instance of :exc:`ConnectionRefusedError` is raised, and a handler
|
||||
is registered for :exc:`ConnectionError` and :exc:`ConnectionRefusedError`,
|
||||
For example, 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 with the
|
||||
exception instance to generate the response.
|
||||
|
||||
|
|
@ -183,7 +185,8 @@ options in order to use your favorite debugger:
|
|||
|
||||
* ``debug`` - whether to enable debug mode and catch exceptions
|
||||
* ``use_debugger`` - whether to use the internal Flask debugger
|
||||
* ``use_reloader`` - whether to reload and fork the process if modules were changed
|
||||
* ``use_reloader`` - whether to reload and fork the process if modules
|
||||
were changed
|
||||
|
||||
``debug`` must be True (i.e., exceptions must be caught) in order for the other
|
||||
two options to have any value.
|
||||
|
|
@ -198,7 +201,8 @@ config.yaml (change the block as appropriate for your application, of course)::
|
|||
DEBUG: True
|
||||
DEBUG_WITH_APTANA: True
|
||||
|
||||
Then in your application's entry-point (main.py), you could have something like::
|
||||
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
|
||||
|
|
|
|||
|
|
@ -197,8 +197,8 @@ So here's what these lines of code do:
|
|||
instantiated without requiring an app object. This method supports the
|
||||
factory pattern for creating applications. The ``init_app`` will set the
|
||||
configuration for the database, defaulting to an in memory database if
|
||||
no configuration is supplied. In addition, the ``init_app`` method attaches
|
||||
the ``teardown`` handler.
|
||||
no configuration is supplied. In addition, the ``init_app`` method
|
||||
attaches the ``teardown`` handler.
|
||||
3. Next, we define a ``connect`` method that opens a database connection.
|
||||
4. Finally, we add a ``connection`` property that on first access opens
|
||||
the database connection and stores it on the context. This is also
|
||||
|
|
@ -312,8 +312,8 @@ extension to be approved you have to follow these guidelines:
|
|||
or ``python setup.py test``. For test suites invoked with ``make
|
||||
test`` the extension has to ensure that all dependencies for the test
|
||||
are installed automatically. If tests are invoked with ``python setup.py
|
||||
test``, test dependencies can be specified in the :file:`setup.py` file. The
|
||||
test suite also has to be part of the distribution.
|
||||
test``, test dependencies can be specified in the :file:`setup.py` file.
|
||||
The test suite also has to be part of the distribution.
|
||||
3. APIs of approved extensions will be checked for the following
|
||||
characteristics:
|
||||
|
||||
|
|
|
|||
|
|
@ -28,10 +28,11 @@ Configuration and Conventions
|
|||
-----------------------------
|
||||
|
||||
Flask has many configuration values, with sensible defaults, and a few
|
||||
conventions when getting started. By convention, templates and static files are
|
||||
stored in subdirectories within the application's Python source tree, with the
|
||||
names :file:`templates` and :file:`static` respectively. While this can be changed, you
|
||||
usually don't have to, especially when getting started.
|
||||
conventions when getting started. By convention, templates and static
|
||||
files are stored in subdirectories within the application's Python
|
||||
source tree, with the names :file:`templates` and :file:`static`
|
||||
respectively. While this can be changed, you usually don't have to,
|
||||
especially when getting started.
|
||||
|
||||
Growing with Flask
|
||||
------------------
|
||||
|
|
|
|||
|
|
@ -16,8 +16,8 @@ However, barely any websites on the Internet are actual XHTML (which is
|
|||
HTML processed using XML rules). There are a couple of major reasons
|
||||
why this is the case. One of them is Internet Explorer's lack of proper
|
||||
XHTML support. The XHTML spec states that XHTML must be served with the MIME
|
||||
type :mimetype:`application/xhtml+xml`, but Internet Explorer refuses to read files
|
||||
with that MIME type.
|
||||
type :mimetype:`application/xhtml+xml`, but Internet Explorer refuses
|
||||
to read files with that MIME type.
|
||||
While it is relatively easy to configure Web servers to serve XHTML properly,
|
||||
few people do. This is likely because properly using XHTML can be quite
|
||||
painful.
|
||||
|
|
|
|||
|
|
@ -93,9 +93,9 @@ should see your hello world greeting.
|
|||
What to do if the Server does not Start
|
||||
---------------------------------------
|
||||
|
||||
In case the :command:`python -m flask` fails or :command:`flask` does not exist,
|
||||
there are multiple reasons this might be the case. First of all you need
|
||||
to look at the error message.
|
||||
In case the :command:`python -m flask` fails or :command:`flask`
|
||||
does not exist, there are multiple reasons this might be the case.
|
||||
First of all you need to look at the error message.
|
||||
|
||||
Old Version of Flask
|
||||
````````````````````
|
||||
|
|
@ -560,9 +560,9 @@ filesystem. You can access those files by looking at the
|
|||
:attr:`~flask.request.files` attribute on the request object. Each
|
||||
uploaded file is stored in that dictionary. It behaves just like a
|
||||
standard Python :class:`file` object, but it also has a
|
||||
:meth:`~werkzeug.datastructures.FileStorage.save` method that allows you to store that
|
||||
file on the filesystem of the server. Here is a simple example showing how
|
||||
that works::
|
||||
:meth:`~werkzeug.datastructures.FileStorage.save` method that
|
||||
allows you to store that file on the filesystem of the server.
|
||||
Here is a simple example showing how that works::
|
||||
|
||||
from flask import request
|
||||
|
||||
|
|
@ -575,10 +575,11 @@ that works::
|
|||
|
||||
If you want to know how the file was named on the client before it was
|
||||
uploaded to your application, you can access the
|
||||
:attr:`~werkzeug.datastructures.FileStorage.filename` attribute. However please keep in
|
||||
mind that this value can be forged so never ever trust that value. If you
|
||||
want to use the filename of the client to store the file on the server,
|
||||
pass it through the :func:`~werkzeug.utils.secure_filename` function that
|
||||
:attr:`~werkzeug.datastructures.FileStorage.filename` attribute.
|
||||
However please keep in mind that this value can be forged
|
||||
so never ever trust that value. If you want to use the filename
|
||||
of the client to store the file on the server, pass it through the
|
||||
:func:`~werkzeug.utils.secure_filename` function that
|
||||
Werkzeug provides for you::
|
||||
|
||||
from flask import request
|
||||
|
|
@ -681,8 +682,9 @@ About Responses
|
|||
The return value from a view function is automatically converted into a
|
||||
response object for you. If the return value is a string it's converted
|
||||
into a response object with the string as response body, a ``200 OK``
|
||||
status code and a :mimetype:`text/html` mimetype. The logic that Flask applies to
|
||||
converting return values into response objects is as follows:
|
||||
status code and a :mimetype:`text/html` mimetype.
|
||||
The logic that Flask applies to converting return values into
|
||||
response objects is as follows:
|
||||
|
||||
1. If a response object of the correct type is returned it's directly
|
||||
returned from the view.
|
||||
|
|
@ -806,12 +808,12 @@ Logging
|
|||
.. versionadded:: 0.3
|
||||
|
||||
Sometimes you might be in a situation where you deal with data that
|
||||
should be correct, but actually is not. For example you may have some client-side
|
||||
code that sends an HTTP request to the server but it's obviously
|
||||
malformed. This might be caused by a user tampering with the data, or the
|
||||
client code failing. Most of the time it's okay to reply with ``400 Bad
|
||||
Request`` in that situation, but sometimes that won't do and the code has
|
||||
to continue working.
|
||||
should be correct, but actually is not. For example you may have
|
||||
some client-side code that sends an HTTP request to the server
|
||||
but it's obviously malformed. This might be caused by a user tampering
|
||||
with the data, or the client code failing. Most of the time it's okay
|
||||
to reply with ``400 Bad Request`` in that situation, but sometimes
|
||||
that won't do and the code has to continue working.
|
||||
|
||||
You may still want to log that something fishy happened. This is where
|
||||
loggers come in handy. As of Flask 0.3 a logger is preconfigured for you
|
||||
|
|
|
|||
|
|
@ -73,9 +73,9 @@ this does is disable error catching during request handling, so that
|
|||
you get better error reports when performing test requests against the
|
||||
application.
|
||||
|
||||
Because SQLite3 is filesystem-based, we can easily use the :mod:`tempfile` module
|
||||
to create a temporary database and initialize it. The
|
||||
:func:`~tempfile.mkstemp` function does two things for us: it returns a
|
||||
Because SQLite3 is filesystem-based, we can easily use the
|
||||
:mod:`tempfile` module to create a temporary database and initialize it.
|
||||
The :func:`~tempfile.mkstemp` function does two things for us: it returns a
|
||||
low-level file handle and a random file name, the latter we use as
|
||||
database name. We just have to keep the `db_fd` around so that we can use
|
||||
the :func:`os.close` function to close the file.
|
||||
|
|
@ -93,9 +93,9 @@ If we now run the test suite, we should see the following output::
|
|||
|
||||
=========== no tests ran in 0.07 seconds ============
|
||||
|
||||
Even though it did not run any actual tests, we already know that our ``flaskr``
|
||||
application is syntactically valid, otherwise the import would have died
|
||||
with an exception.
|
||||
Even though it did not run any actual tests, we already know that our
|
||||
``flaskr`` application is syntactically valid, otherwise the import
|
||||
would have died with an exception.
|
||||
|
||||
.. _pytest fixture:
|
||||
https://docs.pytest.org/en/latest/fixture.html
|
||||
|
|
@ -117,11 +117,13 @@ test function to :file:`test_flaskr.py`, like this::
|
|||
Notice that our test functions begin with the word `test`; this allows
|
||||
`pytest`_ to automatically identify the function as a test to run.
|
||||
|
||||
By using ``client.get`` we can send an HTTP ``GET`` request to the application with
|
||||
the given path. The return value will be a :class:`~flask.Flask.response_class` object.
|
||||
We can now use the :attr:`~werkzeug.wrappers.BaseResponse.data` attribute to inspect
|
||||
the return value (as string) from the application. In this case, we ensure that
|
||||
``'No entries here so far'`` is part of the output.
|
||||
By using ``client.get`` we can send an HTTP ``GET`` request to the
|
||||
application with the given path. The return value will be a
|
||||
:class:`~flask.Flask.response_class` object. We can now use the
|
||||
:attr:`~werkzeug.wrappers.BaseResponse.data` attribute to inspect
|
||||
the return value (as string) from the application.
|
||||
In this case, we ensure that ``'No entries here so far'``
|
||||
is part of the output.
|
||||
|
||||
Run it again and you should see one passing test::
|
||||
|
||||
|
|
@ -333,7 +335,8 @@ happen. With Flask 0.4 this is possible by using the
|
|||
|
||||
If you were to use just the :meth:`~flask.Flask.test_client` without
|
||||
the ``with`` block, the ``assert`` would fail with an error because `request`
|
||||
is no longer available (because you are trying to use it outside of the actual request).
|
||||
is no longer available (because you are trying to use it
|
||||
outside of the actual request).
|
||||
|
||||
|
||||
Accessing and Modifying Sessions
|
||||
|
|
|
|||
|
|
@ -68,9 +68,9 @@ to the release we decided to push out a 0.11 release first with some
|
|||
changes removed to make the transition easier. If you have been tracking
|
||||
the master branch which was 1.0 you might see some unexpected changes.
|
||||
|
||||
In case you did track the master branch you will notice that :command:`flask --app`
|
||||
is removed now. You need to use the environment variable to specify an
|
||||
application.
|
||||
In case you did track the master branch you will notice that
|
||||
:command:`flask --app` is removed now.
|
||||
You need to use the environment variable to specify an application.
|
||||
|
||||
Debugging
|
||||
`````````
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue