From 23fc2e56a8f169efbc31adfcedf82d8724ba9604 Mon Sep 17 00:00:00 2001 From: Kevin Yap Date: Fri, 12 Dec 2014 22:52:36 -0800 Subject: [PATCH] Grammatical fixes in Foreword and Tutorial --- docs/foreword.rst | 6 ++-- docs/tutorial/css.rst | 4 +-- docs/tutorial/dbcon.rst | 26 +++++++++--------- docs/tutorial/dbinit.rst | 40 +++++++++++++-------------- docs/tutorial/folders.rst | 12 ++++---- docs/tutorial/index.rst | 6 ++-- docs/tutorial/introduction.rst | 22 +++++++-------- docs/tutorial/schema.rst | 8 +++--- docs/tutorial/setup.rst | 50 ++++++++++++++++++---------------- docs/tutorial/templates.rst | 6 ++-- docs/tutorial/testing.rst | 2 +- docs/tutorial/views.rst | 12 ++++---- 12 files changed, 98 insertions(+), 96 deletions(-) diff --git a/docs/foreword.rst b/docs/foreword.rst index 7b151f53..4142cb83 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -9,7 +9,7 @@ What does "micro" mean? ----------------------- “Micro” does not mean that your whole web application has to fit into a single -Python file, although it certainly can. Nor does it mean that Flask is lacking +Python file (although it certainly can), nor does it mean that Flask is lacking in functionality. The "micro" in microframework means Flask aims to keep the core simple but extensible. Flask won't make many decisions for you, such as what database to use. Those decisions that it does make, such as what @@ -28,9 +28,9 @@ 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 +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 +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/tutorial/css.rst b/docs/tutorial/css.rst index 01d15699..3f0e932a 100644 --- a/docs/tutorial/css.rst +++ b/docs/tutorial/css.rst @@ -4,8 +4,8 @@ Step 7: Adding Style ==================== Now that everything else works, it's time to add some style to the -application. Just create a stylesheet called :file:`style.css` in the :file:`static` -folder we created before: +application. Just create a stylesheet called :file:`style.css` in the +:file:`static` folder we created before: .. sourcecode:: css diff --git a/docs/tutorial/dbcon.rst b/docs/tutorial/dbcon.rst index 9b60a40f..8757114c 100644 --- a/docs/tutorial/dbcon.rst +++ b/docs/tutorial/dbcon.rst @@ -4,29 +4,29 @@ Step 3: Database Connections ---------------------------- We have created a function for establishing a database connection with -`connect_db` but by itself that's not particularly useful. Creating and +`connect_db`, but by itself, that's not particularly useful. Creating and closing database connections all the time is very inefficient, so we want to keep it around for longer. Because database connections encapsulate a -transaction we also need to make sure that only one request at the time -uses the connection. So how can we elegantly do that with Flask? +transaction, we also need to make sure that only one request at the time +uses the connection. How can we elegantly do that with Flask? -This is where the application context comes into play. So let's start +This is where the application context comes into play, so let's start there. Flask provides us with two contexts: the application context and the -request context. For the time being all you have to know is that there -are special variables that use these. For instance the +request context. For the time being, all you have to know is that there +are special variables that use these. For instance, the :data:`~flask.request` variable is the request object associated with the current request, whereas :data:`~flask.g` is a general purpose variable associated with the current application context. We will go into the details of this a bit later. -For the time being all you have to know is that you can store information +For the time being, all you have to know is that you can store information safely on the :data:`~flask.g` object. So when do you put it on there? To do that you can make a helper -function. The first time the function is called it will create a database -connection for the current context and successive calls will return the +function. The first time the function is called, it will create a database +connection for the current context, and successive calls will return the already established connection:: def get_db(): @@ -39,7 +39,7 @@ already established connection:: So now we know how to connect, but how do we properly disconnect? For -that flask provides us with the :meth:`~flask.Flask.teardown_appcontext` +that, Flask provides us with the :meth:`~flask.Flask.teardown_appcontext` decorator. It's executed every time the application context tears down:: @app.teardown_appcontext @@ -49,11 +49,11 @@ decorator. It's executed every time the application context tears down:: g.sqlite_db.close() Functions marked with :meth:`~flask.Flask.teardown_appcontext` are called -every time the app context tears down. So what does this mean? -Essentially the app context is created before the request comes in and is +every time the app context tears down. What does this mean? +Essentially, the app context is created before the request comes in and is destroyed (torn down) whenever the request finishes. A teardown can happen because of two reasons: either everything went well (the error -parameter will be ``None``) or an exception happened in which case the error +parameter will be ``None``) or an exception happened, in which case the error is passed to the teardown function. Curious about what these contexts mean? Have a look at the diff --git a/docs/tutorial/dbinit.rst b/docs/tutorial/dbinit.rst index d8fc8569..b3cf39dc 100644 --- a/docs/tutorial/dbinit.rst +++ b/docs/tutorial/dbinit.rst @@ -5,24 +5,24 @@ Step 4: Creating The Database As outlined earlier, Flaskr is a database powered application, and more precisely, it is an application powered by a relational database system. Such -systems need a schema that tells them how to store that information. So -before starting the server for the first time it's important to create +systems need a schema that tells them how to store that information. +Before starting the server for the first time, it's important to create that schema. -Such a schema can be created by piping the `schema.sql` file into the +Such a schema can be created by piping the ``schema.sql`` file into the `sqlite3` command as follows:: sqlite3 /tmp/flaskr.db < schema.sql -The downside of this is that it requires the sqlite3 command to be -installed which is not necessarily the case on every system. This also -requires that we provide the path to the database which can introduce +The downside of this is that it requires the ``sqlite3`` command to be +installed, which is not necessarily the case on every system. This also +requires that we provide the path to the database, which can introduce errors. It's a good idea to add a function that initializes the database for you to the application. -To do this we can create a function and hook it into the :command:`flask` command -that initializes the database. Let me show you the code first. Just add -this function below the `connect_db` function in :file:`flaskr.py`:: +To do this, we can create a function and hook it into the :command:`flask` +command that initializes the database. Let me show you the code first. Just +add this function below the `connect_db` function in :file:`flaskr.py`:: def init_db(): db = get_db() @@ -37,36 +37,36 @@ this function below the `connect_db` function in :file:`flaskr.py`:: print 'Initialized the database.' The ``app.cli.command()`` decorator registers a new command with the -:command:`flask` script. When the command executes Flask will automatically +:command:`flask` script. When the command executes, Flask will automatically create a application context for us bound to the right application. -Within the function we can then access :attr:`flask.g` and other things as +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 -though so that we can easily create databases in unittests later. (For +We want to keep an actual functions around that initializes the database, +though, so that we can easily create databases in unit tests later on. (For more information see :ref:`testing`.) The :func:`~flask.Flask.open_resource` method of the application object is a convenient helper function that will open a resource that the application provides. This function opens a file from the resource -location (your `flaskr` folder) and allows you to read from it. We are +location (your ``flaskr`` folder) and allows you to read from it. We are using this here to execute a script on the database connection. The connection object provided by SQLite can give us a cursor object. -On that cursor there is a method to execute a complete script. Finally we -only have to commit the changes. SQLite 3 and other transactional +On that cursor, there is a method to execute a complete script. Finally, we +only have to commit the changes. SQLite3 and other transactional databases will not commit unless you explicitly tell it to. -Now it is possible to create a database with the :command:`flask` script:: +Now, it is possible to create a database with the :command:`flask` script:: flask --app=flaskr initdb Initialized the database. .. admonition:: Troubleshooting - If you get an exception later that a table cannot be found check that - you did execute the `initdb` command and that your table names are - correct (singular vs. plural for example). + If you get an exception later on stating that a table cannot be found, check + that you did execute the ``initdb`` command and that your table names are + correct (singular vs. plural, for example). Continue with :ref:`tutorial-views` diff --git a/docs/tutorial/folders.rst b/docs/tutorial/folders.rst index 4723f797..fba19d72 100644 --- a/docs/tutorial/folders.rst +++ b/docs/tutorial/folders.rst @@ -10,13 +10,13 @@ application:: /static /templates -The `flaskr` folder is not a python package, but just something where we -drop our files. We will then put our database schema as well as main module -into this folder. It is done in the following way. The files inside +The ``flaskr`` folder is not a Python package, but just something where we +drop our files. Later on, we will put our database schema as well as main +module into this folder. It is done in the following way. The files inside the :file:`static` folder are available to users of the application via HTTP. -This is the place where css and javascript files go. Inside the -:file:`templates` folder Flask will look for `Jinja2`_ templates. The -templates you create later in the tutorial will go in this directory. +This is the place where CSS and Javascript files go. Inside the +:file:`templates` folder, Flask will look for `Jinja2`_ templates. The +templates you create later on in the tutorial will go in this directory. Continue with :ref:`tutorial-schema`. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 326cea9f..4b680b9b 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -4,11 +4,11 @@ Tutorial ======== You want to develop an application with Python and Flask? Here you have -the chance to learn that by example. In this tutorial we will create a -simple microblog application. It only supports one user that can create +the chance to learn by example. In this tutorial, we will create a simple +microblogging application. It only supports one user that can create text-only entries and there are no feeds or comments, but it still features everything you need to get started. We will use Flask and SQLite -as database which comes out of the box with Python, so there is nothing +as a database (which comes out of the box with Python) so there is nothing else you need. If you want the full source code in advance or for comparison, check out diff --git a/docs/tutorial/introduction.rst b/docs/tutorial/introduction.rst index 1dcc40ed..d30bd5cf 100644 --- a/docs/tutorial/introduction.rst +++ b/docs/tutorial/introduction.rst @@ -3,25 +3,25 @@ Introducing Flaskr ================== -We will call our blogging application flaskr here, feel free to choose a -less web-2.0-ish name ;) Basically we want it to do the following things: +We will call our blogging application flaskr, but feel free to choose your own +less Web-2.0-ish name ;) Essentially, we want it to do the following things: -1. let the user sign in and out with credentials specified in the +1. Let the user sign in and out with credentials specified in the configuration. Only one user is supported. -2. when the user is logged in they can add new entries to the page +2. When the user is logged in, they can add new entries to the page consisting of a text-only title and some HTML for the text. This HTML is not sanitized because we trust the user here. -3. the page shows all entries so far in reverse order (newest on top) and - the user can add new ones from there if logged in. +3. The index page shows all entries so far in reverse chronological order + (newest on top) and the user can add new ones from there if logged in. -We will be using SQLite3 directly for that application because it's good -enough for an application of that size. For larger applications however -it makes a lot of sense to use `SQLAlchemy`_ that handles database -connections in a more intelligent way, allows you to target different +We will be using SQLite3 directly for this application because it's good +enough for an application of this size. For larger applications, however, +it makes a lot of sense to use `SQLAlchemy`_, as it handles database +connections in a more intelligent way, allowing you to target different relational databases at once and more. You might also want to consider one of the popular NoSQL databases if your data is more suited for those. -Here a screenshot from the final application: +Here a screenshot of the final application: .. image:: ../_static/flaskr.png :align: center diff --git a/docs/tutorial/schema.rst b/docs/tutorial/schema.rst index 246baccd..b164b94c 100644 --- a/docs/tutorial/schema.rst +++ b/docs/tutorial/schema.rst @@ -3,8 +3,8 @@ Step 1: Database Schema ======================= -First we want to create the database schema. Only a single table is needed -for this application and we only want to support SQLite so creating the +First, we want to create the database schema. Only a single table is needed +for this application and we only want to support SQLite, so creating the database schema is quite easy. Just put the following contents into a file named `schema.sql` in the just created `flaskr` folder: @@ -17,8 +17,8 @@ named `schema.sql` in the just created `flaskr` folder: 'text' text not null ); -This schema consists of a single table called `entries` and each row in -this table has an `id`, a `title` and a `text`. The `id` is an +This schema consists of a single table called ``entries``. Each row in +this table has an ``id``, a ``title``, and a ``text``. The ``id`` is an automatically incrementing integer and a primary key, the other two are strings that must not be null. diff --git a/docs/tutorial/setup.rst b/docs/tutorial/setup.rst index ee043845..703d5504 100644 --- a/docs/tutorial/setup.rst +++ b/docs/tutorial/setup.rst @@ -3,15 +3,15 @@ Step 2: Application Setup Code ============================== -Now that we have the schema in place we can create the application module. -Let's call it flaskr.py. We will place this file inside the flaskr folder. -We will begin by adding the imports we need and by adding the config +Now that we have the schema in place, we can create the application module. +Let's call it ``flaskr.py``. We will place this file inside the ``flaskr`` +folder. We will begin by adding the imports we need and by adding the config section. For small applications, it is possible to drop the configuration -directly into the module, and this is what we will be doing here. However -a cleaner solution would be to create a separate ``.ini`` or ``.py`` file and -load that or import the values from there. +directly into the module, and this is what we will be doing here. However, +a cleaner solution would be to create a separate ``.ini`` or ``.py`` file, +load that, and import the values from there. -First we add the imports in :file:`flaskr.py`:: +First, we add the imports in :file:`flaskr.py`:: # all the imports import os @@ -19,8 +19,8 @@ First we add the imports in :file:`flaskr.py`:: from flask import Flask, request, session, g, redirect, url_for, abort, \ render_template, flash -Next we can create our actual application and initialize it with the -config from the same file, in :file:`flaskr.py`:: +Next, we can create our actual application and initialize it with the +config from the same file in :file:`flaskr.py`:: # create our little application :) app = Flask(__name__) @@ -35,45 +35,47 @@ config from the same file, in :file:`flaskr.py`:: )) app.config.from_envvar('FLASKR_SETTINGS', silent=True) -The :class:`~flask.Config` object works similar to a dictionary so we +The :class:`~flask.Config` object works similarly to a dictionary so we can update it with new values. .. admonition:: Database Path Operating systems know the concept of a current working directory for - each process. Unfortunately you cannot depend on this in web + each process. Unfortunately, you cannot depend on this in web applications because you might have more than one application in the same process. For this reason the ``app.root_path`` attribute can be used to - get the path to the application. Together with the ``os.path`` module - files can then easily be found. In this example we place the + get the path to the application. Together with the ``os.path`` module, + files can then easily be found. In this example, we place the database right next to it. - For a real-work application it's recommended to use + For a real-world application, it's recommended to use :ref:`instance-folders` instead. -Usually, it is a good idea to load a separate, environment specific +Usually, it is a good idea to load a separate, environment-specific configuration file. Flask allows you to import multiple configurations and it will use the setting defined in the last import. This enables robust configuration setups. :meth:`~flask.Config.from_envvar` can help achieve this. - app.config.from_envvar('FLASKR_SETTINGS', silent=True) +.. code-block:: python + + app.config.from_envvar('FLASKR_SETTINGS', silent=True) Simply define the environment variable :envvar:`FLASKR_SETTINGS` that points to a config file to be loaded. The silent switch just tells Flask to not complain if no such environment key is set. -In addition to that you can use the :meth:`~flask.Config.from_object` +In addition to that, you can use the :meth:`~flask.Config.from_object` method on the config object and provide it with an import name of a module. Flask will then initialize the variable from that module. Note -that in all cases only variable names that are uppercase are considered. +that in all cases, only variable names that are uppercase are considered. The ``SECRET_KEY`` is needed to keep the client-side sessions secure. Choose that key wisely and as hard to guess and complex as possible. -We will also add a method that allows for easily connecting to the -specified database. This can be used to open a connection on request and +We will also add a method that allows for easy connections to the +specified database. This can be used to open a connection on request and also from the interactive Python shell or a script. This will come in handy later. We create a simple database connection through SQLite and then tell it to use the :class:`sqlite3.Row` object to represent rows. @@ -88,7 +90,7 @@ tuples. rv.row_factory = sqlite3.Row return rv -With that out of the way you should be able to start up the application +With that out of the way, you should be able to start up the application without problems. Do this with the following command:: flask --app=flaskr --debug run @@ -100,9 +102,9 @@ users to execute code on the server! You will see a message telling you that server has started along with the address at which you can access it. -When you head over to the server in your browser you will get an 404 -page not found error because we don't have any views yet. But we will -focus on that a little later. First we should get the database working. +When you head over to the server in your browser, you will get a 404 error +because we don't have any views yet. We will focus on that a little later, +but first, we should get the database working. .. admonition:: Externally Visible Server diff --git a/docs/tutorial/templates.rst b/docs/tutorial/templates.rst index 6982fa99..3487a9e1 100644 --- a/docs/tutorial/templates.rst +++ b/docs/tutorial/templates.rst @@ -3,8 +3,8 @@ Step 6: The Templates ===================== -Now we should start working on the templates. If we request the URLs now -we would only get an exception that Flask cannot find the templates. The +Now we should start working on the templates. If we were torequest the URLs +now, we would only get an exception that Flask cannot find the templates. The templates are using `Jinja2`_ syntax and have autoescaping enabled by default. This means that unless you mark a value in the code with :class:`~flask.Markup` or with the ``|safe`` filter in the template, @@ -88,7 +88,7 @@ method: login.html ---------- -Finally the login template which basically just displays a form to allow +This is the login template, which basically just displays a form to allow the user to login: .. sourcecode:: html+jinja diff --git a/docs/tutorial/testing.rst b/docs/tutorial/testing.rst index 34edd791..d70b4abe 100644 --- a/docs/tutorial/testing.rst +++ b/docs/tutorial/testing.rst @@ -6,5 +6,5 @@ Bonus: Testing the Application Now that you have finished the application and everything works as expected, it's probably not a bad idea to add automated tests to simplify modifications in the future. The application above is used as a basic -example of how to perform unittesting in the :ref:`testing` section of the +example of how to perform unit testing in the :ref:`testing` section of the documentation. Go there to see how easy it is to test Flask applications. diff --git a/docs/tutorial/views.rst b/docs/tutorial/views.rst index 1801bb66..10b578a7 100644 --- a/docs/tutorial/views.rst +++ b/docs/tutorial/views.rst @@ -3,7 +3,7 @@ Step 5: The View Functions ========================== -Now that the database connections are working we can start writing the +Now that the database connections are working, we can start writing the view functions. We will need four of them: Show Entries @@ -15,7 +15,7 @@ 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 the :class:`sqlite3.Row` row factory. -The view function will pass the entries as dicts to the +The view function will pass the entries as dictionaries to the :file:`show_entries.html` template and return the rendered one:: @app.route('/') @@ -29,8 +29,8 @@ Add New Entry ------------- This view lets the user add new entries if they are logged in. This only -responds to ``POST`` requests, the actual form is shown on the -`show_entries` page. If everything worked out well we will +responds to ``POST`` requests; the actual form is shown on the +`show_entries` page. If everything worked out well, we will :func:`~flask.flash` an information message to the next request and redirect back to the `show_entries` page:: @@ -60,7 +60,7 @@ Login and Logout These functions are used to sign the user in and out. Login checks the username and password against the ones from the configuration and sets the -`logged_in` key in the session. If the user logged in successfully, that +`logged_in` key for the session. If the user logged in successfully, that key is set to ``True``, and the user is redirected back to the `show_entries` page. In addition, a message is flashed that informs the user that he or she was logged in successfully. If an error occurred, the template is @@ -80,7 +80,7 @@ notified about that, and the user is asked again:: return redirect(url_for('show_entries')) return render_template('login.html', error=error) -The logout function, on the other hand, removes that key from the session +The `logout` function, on the other hand, removes that key from the session again. We use a neat trick here: if you use the :meth:`~dict.pop` method of the dict and pass a second parameter to it (the default), the method will delete the key from the dictionary if present or do nothing when that