The minimal requirement for running the testsuite is ``py.test``. You can
The minimal requirement for running the testsuite is ``pytest``. You can
install it with::
install it with::
pip install pytest
pip install pytest
Clone this repository::
Clone this repository::
git clone https://github.com/mitsuhiko/flask.git
git clone https://github.com/pallets/flask.git
Install Flask as an editable package using the current source::
Install Flask as an editable package using the current source::
@ -54,19 +54,61 @@ Install Flask as an editable package using the current source::
Then you can run the testsuite with::
Then you can run the testsuite with::
py.test
pytest
With only py.test installed, a large part of the testsuite will get skipped
With only pytest installed, a large part of the testsuite will get skipped
though. Whether this is relevant depends on which part of Flask you're working
though. Whether this is relevant depends on which part of Flask you're working
on. Travis is set up to run the full testsuite when you submit your pull
on. Travis is set up to run the full testsuite when you submit your pull
request anyways.
request anyways.
If you really want to test everything, you will have to install ``tox`` instead
If you really want to test everything, you will have to install ``tox`` instead
of ``pytest``. Currently we're depending on a development version of Tox
of ``pytest``. You can install it with::
because the released version is missing features we absolutely need. You can
install it with::
pip install hg+https://bitbucket.org/hpk42/tox
pip install tox
The ``tox`` command will then run all tests against multiple combinations
The ``tox`` command will then run all tests against multiple combinations
Python versions and dependency versions.
Python versions and dependency versions.
Running test coverage
---------------------
Generating a report of lines that do not have unit test coverage can indicate where
to start contributing. ``pytest`` integrates with ``coverage.py``, using the ``pytest-cov``
plugin. This assumes you have already run the testsuite (see previous section)::
pip install pytest-cov
After this has been installed, you can output a report to the command line using this command::
pytest --cov=flask tests/
Generate a HTML report can be done using this command::
pytest --cov-report html --cov=flask tests/
Full docs on ``coverage.py`` are here: https://coverage.readthedocs.io
Caution
=======
pushing
-------
This repository contains several zero-padded file modes that may cause issues when pushing this repository to git hosts other than github. Fixing this is destructive to the commit history, so we suggest ignoring these warnings. If it fails to push and you're using a self-hosted git service like Gitlab, you can turn off repository checks in the admin panel.
cloning
-------
The zero-padded file modes files above can cause issues while cloning, too. If you have
::
[fetch]
fsckobjects = true
or
::
[receive]
fsckObjects = true
set in your git configuration file, cloning this repository will fail. The only solution is to set both of the above settings to false while cloning, and then setting them back to true after the cloning is finished.
In Flask you can easily implement the opening of database connections on
In Flask you can easily implement the opening of database connections on
demand and closing them when the context dies (usually at the end of the
demand and closing them when the context dies (usually at the end of the
request).
request).
Here is a simple example of how you can use SQLite 3 with Flask::
Here is a simple example of how you can use SQLite 3 with Flask::
@ -71,7 +71,8 @@ Now in each request handling function you can access `g.db` to get the
current open database connection. To simplify working with SQLite, a
current open database connection. To simplify working with SQLite, a
row factory function is useful. It is executed for every result returned
row factory function is useful. It is executed for every result returned
from the database to convert the result. For instance, in order to get
from the database to convert the result. For instance, in order to get
dictionaries instead of tuples, this could be inserted into ``get_db``::
dictionaries instead of tuples, this could be inserted into the ``get_db``
function we created above::
def make_dicts(cursor, row):
def make_dicts(cursor, row):
return dict((cursor.description[idx][0], value)
return dict((cursor.description[idx][0], value)
@ -79,21 +80,37 @@ dictionaries instead of tuples, this could be inserted into ``get_db``::
db.row_factory = make_dicts
db.row_factory = make_dicts
Or even simpler::
This will make the sqlite3 module return dicts for this database connection, which are much nicer to deal with. Even more simply, we could place this in ``get_db`` instead::
db.row_factory = sqlite3.Row
db.row_factory = sqlite3.Row
This would use Row objects rather than dicts to return the results of queries. These are ``namedtuple`` s, so we can access them either by index or by key. For example, assuming we have a ``sqlite3.Row`` called ``r`` for the rows ``id``, ``FirstName``, ``LastName``, and ``MiddleInitial``::
>>> # You can get values based on the row's name
>>> r['FirstName']
John
>>> # Or, you can get them based on index
>>> r[1]
John
# Row objects are also iterable:
>>> for value in r:
... print(value)
1
John
Doe
M
Additionally, it is a good idea to provide a query function that combines
Additionally, it is a good idea to provide a query function that combines
getting the cursor, executing and fetching the results::
getting the cursor, executing and fetching the results::
def query_db(query, args=(), one=False):
def query_db(query, args=(), one=False):
cur = get_db().execute(query, args)
cur = get_db().execute(query, args)
rv = cur.fetchall()
rv = cur.fetchall()
cur.close()
cur.close()
return (rv[0] if rv else None) if one else rv
return (rv[0] if rv else None) if one else rv
This handy little function, in combination with a row factory, makes
This handy little function, in combination with a row factory, makes
working with the database much more pleasant than it is by just using the
working with the database much more pleasant than it is by just using the
raw cursor and connection objects.
raw cursor and connection objects.
Here is how you can use it::
Here is how you can use it::
@ -114,7 +131,7 @@ To pass variable parts to the SQL statement, use a question mark in the
statement and pass in the arguments as a list. Never directly add them to
statement and pass in the arguments as a list. Never directly add them to
the SQL statement with string formatting because this makes it possible
the SQL statement with string formatting because this makes it possible
David Lord
8 years ago