From 6606a4a2386a9635b8ad25b4ae6329be783e00b3 Mon Sep 17 00:00:00 2001 From: David Baumgold Date: Mon, 6 May 2019 10:54:57 -0400 Subject: [PATCH] fix RST line too long --- docs/advanced_foreword.rst | 9 +++++---- docs/becomingbig.rst | 3 ++- docs/blueprints.rst | 15 ++++++++------- docs/cli.rst | 6 +++--- docs/deploying/cgi.rst | 6 +++--- docs/deploying/fastcgi.rst | 8 ++++---- docs/deploying/mod_wsgi.rst | 27 +++++++++++++------------- docs/deploying/uwsgi.rst | 9 +++++---- docs/errorhandling.rst | 18 +++++++++++------- docs/extensiondev.rst | 8 ++++---- docs/foreword.rst | 9 +++++---- docs/htmlfaq.rst | 4 ++-- docs/quickstart.rst | 38 +++++++++++++++++++------------------ docs/testing.rst | 27 ++++++++++++++------------ docs/upgrading.rst | 6 +++--- 15 files changed, 104 insertions(+), 89 deletions(-) diff --git a/docs/advanced_foreword.rst b/docs/advanced_foreword.rst index bd56f53c..4ac81905 100644 --- a/docs/advanced_foreword.rst +++ b/docs/advanced_foreword.rst @@ -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 diff --git a/docs/becomingbig.rst b/docs/becomingbig.rst index 0facbfee..58e1778d 100644 --- a/docs/becomingbig.rst +++ b/docs/becomingbig.rst @@ -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. --------------------- diff --git a/docs/blueprints.rst b/docs/blueprints.rst index 2b8e8d91..fb639966 100644 --- a/docs/blueprints.rst +++ b/docs/blueprints.rst @@ -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) diff --git a/docs/cli.rst b/docs/cli.rst index 78f8e3d5..efe94e98 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -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 diff --git a/docs/deploying/cgi.rst b/docs/deploying/cgi.rst index 503d9426..e6c768b4 100644 --- a/docs/deploying/cgi.rst +++ b/docs/deploying/cgi.rst @@ -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 diff --git a/docs/deploying/fastcgi.rst b/docs/deploying/fastcgi.rst index 65b35cab..33704062 100644 --- a/docs/deploying/fastcgi.rst +++ b/docs/deploying/fastcgi.rst @@ -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 diff --git a/docs/deploying/mod_wsgi.rst b/docs/deploying/mod_wsgi.rst index 203e0d36..76d986b7 100644 --- a/docs/deploying/mod_wsgi.rst +++ b/docs/deploying/mod_wsgi.rst @@ -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 - - ServerName example.com - WSGIScriptAlias / C:\yourdir\yourapp.wsgi - - Order deny,allow - Allow from all - - + + ServerName example.com + WSGIScriptAlias / C:\yourdir\yourapp.wsgi + + Order deny,allow + Allow from all + + -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 diff --git a/docs/deploying/uwsgi.rst b/docs/deploying/uwsgi.rst index d3c38642..dd0f315d 100644 --- a/docs/deploying/uwsgi.rst +++ b/docs/deploying/uwsgi.rst @@ -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 diff --git a/docs/errorhandling.rst b/docs/errorhandling.rst index 557f07ed..92a88a07 100644 --- a/docs/errorhandling.rst +++ b/docs/errorhandling.rst @@ -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 diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index aa4eff76..fc65a350 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -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: diff --git a/docs/foreword.rst b/docs/foreword.rst index 4142cb83..f0dfaee2 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -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 ------------------ diff --git a/docs/htmlfaq.rst b/docs/htmlfaq.rst index 500a35ce..37075381 100644 --- a/docs/htmlfaq.rst +++ b/docs/htmlfaq.rst @@ -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. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index ee2f8ef2..acf6dc15 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -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 diff --git a/docs/testing.rst b/docs/testing.rst index 23ce2105..a18aca6c 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -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 diff --git a/docs/upgrading.rst b/docs/upgrading.rst index 612e3634..805bf4ed 100644 --- a/docs/upgrading.rst +++ b/docs/upgrading.rst @@ -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 `````````