Commit 1e81a3fd authored by Thomas Goirand's avatar Thomas Goirand

Merge tag '1.4.1' into debian/stein

Version 1.4.1.post-1

Minor release to backport several doc fixes/changes.
parents 7272134f 0c966605
[run]
parallel = True
branch = True
source = falcon
omit = falcon/tests*,falcon/cmd*,falcon/bench*
parallel = True
[report]
show_missing = True
*.py[cod]
# C extensions
*.c
*.so
......@@ -7,33 +5,36 @@
# Jython
*$py.class
# Packages
# Build artifacts
*.egg
*.egg-info
dist
*.py[cod]
.eggs
.installed.cfg
build
eggs
parts
var
sdist
develop-eggs
.installed.cfg
dist
eggs
lib
lib64
parts
sdist
var
# Installer logs
pip-log.txt
# Unit test / coverage reports
.coverage
.coverage_*
# Test artifacts
*.dat
.cache
.coverage*
.ecosystem
.tox
nosetests.xml
htmlcov
*.dat
nosetests.xml
# Docs
doc/_build
docs/_build
# Translations
*.mo
......@@ -49,3 +50,7 @@ doc/_build
# VIM temp files
*~
# VSCode
.vscode
\ No newline at end of file
language: python
sudo: false
install: travis_scripts/install.sh
install: tools/travis/install.sh
cache:
directories:
- $HOME/.cache/pip
matrix:
include:
- python: 2.7 # these are just to make travis's UI a bit prettier
env: JYTHON=true
- python: pypy
env: TOXENV=pypy
- python: pypy3
env: TOXENV=pypy3
- python: 2.7
env: TOXENV=pep8
- python: 2.7
env: TOXENV=pep8-examples
- python: 2.6
env: TOXENV=py26
- python: 2.7
env: TOXENV=py27
- python: 2.7
env: TOXENV=py27_ujson
- python: 2.7
env: TOXENV=py27_smoke
- python: 2.7
......@@ -27,32 +29,36 @@ matrix:
env: TOXENV=py27_smoke_cython
- python: 3.3
env: TOXENV=py33
- python: 3.3
env: TOXENV=py33_cython
- python: 3.4
env: TOXENV=py34
- python: 3.4
env: TOXENV=py34_cython
- python: 3.5
env: TOXENV=py35
- python: 3.5
env: TOXENV=py35_cython
- python: 3.6
env: TOXENV=py36
- python: 3.6
env: TOXENV=py36_ujson
- python: 3.6
env: TOXENV=py36_cython
- python: 3.6
env: TOXENV=py36_smoke
- python: 3.6
env: TOXENV=py36_smoke_cython
- python: 2.7
env: TOXENV=docs
- python: 3.6
env: TOXENV=hug
script: travis_scripts/run_tests.sh
script: tools/travis/run_tests.sh
notifications:
irc:
channels:
- "chat.freenode.net#falconframework"
webhooks:
urls:
secure: "R4Hr754P2v69tWoy6vKz/4csb6ZHYRM/+8vTVV6ioDWyqsPqyGXAPiXDfZ617C7TLxJiTlbFIJPjlcH64estPg+RZ1NA4D8BrDKS2nKqHJ2Z5Jv6X5Ds6HkEUNnYXsuwsqNvZzhpPRcCKXXRpvmAbkNUSe8ftn4kz2zCOA9MBSY="
on_success: change
on_failure: always
use_notice: true
skip_join: true
before_install:
- pip install codecov
after_success:
- coverage combine .coverage_data
- coverage combine
- codecov
Kurt Griffiths (kgriffs) created Falcon and is its current maintainer.
Kurt Griffiths (kgriffs) created Falcon and currently co-maintains the
framework along with John Vrbanac (jmvrbanac).
Many thanks to all the mighty fine contributors to the project, listed
below in order of date of first contribution:
Many thanks to all of the project's stylish and talented contributors,
listed below by date of first contribution:
* Alejandro Cabrera (cabrera)
* Chad Lung (chadlung)
......@@ -38,7 +39,7 @@ below in order of date of first contribution:
* Rahman Syed (rsyed83)
* Max Brauer (mamachanko)
* Jen Montes (jenmontes)
* Carl George (cgtx)
* Carl George (carlwgeorge)
* Lahache Stéphane (steffgrez)
* John Vrbanac (jmvrbanac)
* Steve McMaster (mcmasterathl)
......@@ -49,7 +50,6 @@ below in order of date of first contribution:
* Christian Pedersen (chripede)
* Harrison Pincket (hpincket)
* Usman Ehtesham Gul (ueg1990)
* Carl George (carlgeorge)
* Adam Yala (adamyala)
* Grigory Bakunov (bobuk)
* Vincent Raiken (Freezerburn)
......@@ -65,3 +65,16 @@ below in order of date of first contribution:
* David Larlet (davidbgk)
* Fran Fitzpatrick (fxfitz)
* Matthew Miller (masterkale)
* michaelboulton
* Jesse Jarzynka (jessehudl)
* Michael Olund (molund)
* Yash Mehrotra (yashmehrotra)
* Stephen Milner (ashcrow)
* ksonj
(et al.)
For a full list of contributors, please visit:
https://github.com/falconry/falcon/graphs/contributors
This diff is collapsed.
......@@ -2,7 +2,7 @@
All contributors and maintainers of this project are subject to this Code of Conduct.
We pledge to respect everyone who contributes to the *Falcon* project or other associated activities by (including but not limited to) creating project issues, submitting pull requests, and providing feedback on the same. We also pledge to respect everyone who participates in discussions on the project's mailing list, in the project's chat channel, and at meetups and conferences.
We pledge to respect everyone who contributes to the *Falcon* project or other associated activities by (including but not limited to) creating project issues, submitting pull requests, and providing feedback on the same. We also pledge to respect everyone who participates in discussions both online and at meetups and conferences.
Unacceptable behavior includes (but is not limited to) offensive verbal comments related to gender, gender identity and expression, age, sexual orientation, disability, physical appearance, body size, race, ethnicity, religion, technology choices, sexual images in public spaces, deliberate intimidation, stalking, following, harassing photography or recording, sustained disruption of talks or other events, inappropriate physical contact, and unwelcome sexual attention.
......
## Contributing
## Contributer's Guide
Hi, thanks for your interest in the project! We welcome pull requests from developers of all skill levels.
Thanks for your interest in the project! We welcome pull requests from
developers of all skill levels. To get started, simply fork the master branch
on GitHub to your personal account and then clone the fork into your
development environment.
Kurt Griffiths (kgriffs) is the creator and current maintainer of the Falcon framework, along with a group of talented and stylish volunteers. Please don't hesitate to reach out if you have any questions, or just need a little help getting started.
If you would like to contribute but don't already have something in mind,
we invite you to take a look at the issues listed under our [next milestone][ms].
If you see one you'd like to work on, please leave a quick comment so that we don't
end up with duplicated effort. Thanks in advance!
Before submitting a pull request, please ensure you have added or updated tests as appropriate, and that all existing tests still pass with your changes on both Python 2 and Python 3. Please also ensure that your coding style follows PEP 8 and doesn't cause pyflakes to complain.
Kurt Griffiths (**kgriffs** on GH, Gitter, and Twitter) is the original
creator of the Falcon framework, and currently co-maintains the project
along with John Vrbanac (**jmvrbanac** on GH and Gitter, and
**jvrbanac** on Twitter). Falcon is developed by a growing community of
users and contributors just like you.
You can check all this by running the following from within the falcon project directory (requires Python 2.7 and Python 3.3 to be installed on your system):
Please don't hesitate to reach out if you have any questions, or just need a
little help getting started. You can find us in
[falconry/dev][gitter] on Gitter.
Please note that all contributors and maintainers of this project are subject to our [Code of Conduct][coc].
### Pull Requests
Before submitting a pull request, please ensure you have added or updated tests as appropriate, and that all existing tests still pass with your changes on both Python 2 and Python 3. Please also ensure that your coding style follows PEP 8.
You can check all this by running the following from within the Falcon project directory (requires Python 2.7 and Python 3.6 to be installed on your system):
```bash
$ pip install tox
$ tox -e py27,py36,pep8
```
You may also use Python 3.3, 3.4 or 3.5 if you don't have 3.6 installed on your system. This is just a quick sanity check to verify that your patch works across both Python 2 and Python 3.
If you are using pyenv and get an error along the lines of "failed to get version_info", you will need to activate all the Python versions required by tox before trying again. For example:
```bash
$ tox -e py27,py33,pep8
$ pyenv shell 2.7.13 3.6.2
```
### Running tests against Jython
In addition to the tests run with tox against CPython, Cython, and PyPy, Travis runs tests against Jython 2.7 outside of tox. If you need to run these tests locally, do the following:
* Install JDK 7 or better
* run `travis_scripts/install_jython2.7.sh` -- this will install jython at `~/jython`
* Install testing requirements `~/jython/bin/pip install -r tools/test-requires`
* May need to set `export JYTHON_HOME=~/jython` first
* Run tests `~/jython/bin/nosetests`
Note: coverage does not support Jython, so the coverage tests will fail.
First, install JDK 7 or better. Then install Jython at `~/jython`:
```bash
$ tools/travis/install_jython2.7.sh
```
Now install all testing dependencies. If you get an error, you may need to `export JYTHON_HOME=~/jython`. Also note that *pytest-xdist* and *pytest-cov* are not compatible with Jython, and therefore must be removed:
```bash
$ ~/jython/bin/pip install -r requirements/tests
$ ~/jython/bin/pip uninstall -y pytest-xdist pytest-cov
```
Finally, run the tests:
```bash
$ ~/jython/bin/pytest tests
```
### Test coverage
Pull requests must maintain 100% test coverage of all code branches. This helps ensure the quality of the Falcon framework. To check coverage before submitting a pull request:
```bash
$ tox -e py26,py27,py34 && tools/combine_coverage.sh
$ tools/mintest.sh
```
It is necessary to combine test coverage from multiple environments in order to account for branches in the code that are only taken for a given Python version.
The script generates an HTML coverage report that can be viewed by simply opening `.coverage_html/index.html` in a browser. This can be helpful in tracking down specific lines or branches that are missing coverage.
### Debugging
We use pytest to run all of our tests. Pytest supports pdb and will break as expected on any
`pdb.set_trace()` calls. If you would like to use pdb++ instead of the standard Python
debugger, run one of the following tox environments:
```bash
$ tox -e py2_debug
$ tox -e py3_debug
```
If you wish, you can customize Falcon's `tox.ini` to install alternative debuggers, such as ipdb or pudb.
### Benchmarking
A few simple benchmarks are included with the source under ``falcon/bench``. These can be taken as a rough measure of the performance impact (if any) that your changes have on the framework. You can run these tests by invoking one of the tox environments included for this purpose (see also the ``tox.ini`` file). For example:
```bash
$ tox -e py27_bench
```
Note that you may pass additional arguments via tox to the falcon-bench command:
```bash
$ tox -e py27_bench -- -h
$ tox -e py27_bench -- -b falcon -i 20000
```
Alternatively, you may run falcon-bench directly by creating a new virtual environment and installing falcon directly in development mode. In this example we use pyenv with pyenv-virtualenv from within a falcon source directory:
```bash
$ pyenv virtualenv 3.6.2 falcon-sandbox-36
$ pyenv shell falcon-sandbox-36
$ pip install -r requirements/bench
$ pip install -e .
$ falcon-bench
```
This generates an HTML coverage report that can be viewed by simply opening `.coverage_html/index.html` in a browser.
Note that benchmark results for the same code will vary between runs based on a number of factors, including overall system load and CPU scheduling. These factors may be somewhat mitigated by running the benchmarks on a Linux server dedicated to this purpose, and pinning the benchmark process to a specific CPU core.
### Documentation
To check documentation changes (including docstrings), before submitting a PR, ensure the tox job
builds the documentation correctly:
To check documentation changes (including docstrings), before submitting a PR, ensure the tox job builds the documentation correctly:
```bash
$ tox -e docs
# OS X
$ open doc/_build/html/index.html
$ open docs/_build/html/index.html
# Gnome
$ gnome-open doc/_build/html/index.html
$ gnome-open docs/_build/html/index.html
# Generic X Windows
$ xdg-open doc/_build/html/index.html
$ xdg-open docs/_build/html/index.html
```
### Code style rules
......@@ -122,6 +204,12 @@ Just as in the **subject**, use the imperative, present tense: "change" not "cha
The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
[ajs]: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit
[docstrings]: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google-style-python-docstrings
[docstrings]: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google-style-python-docstrings
[goog-style]: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
[rtd]: http://falcon.readthedocs.org
[rtd]: https://falcon.readthedocs.io
[coc]: https://github.com/falconry/falcon/blob/master/CODEOFCONDUCT.md
[freenode]: https://www.freenode.net/
[gitter]: https://gitter.im/falconry/dev
[ml-join]: mailto:users-join@mail.falconframework.org?subject=join
[ml-archive]: https://mail.falconframework.org/archives/list/users@mail.falconframework.org/
[ms]: https://github.com/falconry/falcon/milestones
Copyright 2012-2016 by Rackspace Hosting, Inc. and other contributors,
Copyright 2012-2017 by Rackspace Hosting, Inc. and other contributors,
as noted in the individual source code files.
Licensed under the Apache License, Version 2.0 (the "License");
......
recursive-include tests *.py
recursive-include doc *.rst
recursive-include docs *.rst
include .coveragerc
include tox.ini
include README.md
include doc/conf.py doc/Makefile
graft doc/_static
graft doc/_themes
graft doc/_templates
include README.rst
include LICENSE
include docs/conf.py docs/Makefile
graft docs/_static
graft docs/_templates
graft tools
This diff is collapsed.
/*
These are needed if using the RTD theme.
.property {
margin-left: 1em;
}
em {
margin-right: 0.15em;
}
*/
/* The following are used for the KR theme. */
div.sphinxsidebarwrapper {
margin-right: 1.5em;
}
img.logo {
margin-right: 0;
padding-left: 7px;
}
h1.logo-text {
font-family:"Amethysta";
text-shadow: 0 1px #ddd;
color: #333;
position: absolute;
z-index: 10;
top: 17px;
font-size: 18pt;
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family:"Amethysta";
font-weight: normal;
margin: 30px 0px 10px -2px;
padding: 0;
}
table.field-list th {
width: 95px;
}
<!-- Based on TextBlob's template: http://goo.gl/XqFeTq -->
<!-- Dirty hack since RTD doesn't respect 'templates_path' in conf.py-->
<link href='http://fonts.googleapis.com/css?family=Amethysta:400' rel='stylesheet'>
<link rel="stylesheet" type="text/css" href="{{pathto('_static/css/falcon.css', 1)}}" />
<h1 class="logo-text">Falcon</h1>
<p class="logo">
<a href="{{ pathto(master_doc) }}"><img class="logo" src="{{ pathto('_static/img/logo.png', 1) }}" width="170" height="214" alt="Logo"/></a>
</p>
<p>
<iframe src="http://ghbtns.com/github-btn.html?user=racker&repo=falcon&type=watch&count=true&size=large"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
<p>
Falcon is a high-performance Python framework for building web APIs. It
encourages the REST architectural style, and tries to do as little as
possible while remaining highly effective.
</p>
<h3>Useful Links</h3>
<ul>
<li><a href="http://falconframework.org/">Falcon Home</a></li>
<li><a href="https://pypi.python.org/pypi/falcon">Falcon @ PyPI</a></li>
<li><a href="https://github.com/racker/falcon">Falcon @ GitHub</a></li>
<li><a href="https://github.com/racker/falcon/issues">Issue Tracker</a></li>
</ul>
<h3>Get Involved</h3>
<p>
If you have an idea for improving the framework, or come across a bug,
please let us know by
<a href="https://github.com/racker/falcon/issues">submitting an issue</a>
and/or sending in a pull request.
</p>
<p>
We also have a <a href="community/help.html#mailing-list">Falcon mailing list</a> where you can share your ideas and ask questions.
</p>
<p>
Also, if you are ever in the mood to chat, the Falcon crew hangs out in
<strong>#falconframework</strong> on
<a href="http://www.freenode.net/">Freenode</a>. Everyone is
welcome to join; the channel is a great place to
ask questions and keep up to date with the latest developments.
</p>
<h3>Credits</h3>
<p>
Falcon is made possible by the generous support of Rackspace, and
by a team of talented volunteers <strong>like you</strong> from the broader Python community.
</p>
<p>
The Falcon logo is based on a <a href=https://commons.wikimedia.org/wiki/File:Brown-Falcon,-Vic,-3.1.2008.jpg>photograph by John O'Neill</a> used under the
Creative Commons Attribution-Share Alike 3.0 Unported license.
</p>
\ No newline at end of file
<!-- Based on TextBlob's template: http://goo.gl/XqFeTq -->
<!-- Dirty hack since RTD doesn't respect 'templates_path' in conf.py-->
<link href='http://fonts.googleapis.com/css?family=Amethysta:400' rel='stylesheet'>
<link rel="stylesheet" type="text/css" href="{{pathto('_static/css/falcon.css', 1)}}" />
<h1 class="logo-text">Falcon</h1>
<p class="logo">
<a href="{{ pathto(master_doc) }}"><img class="logo" src="{{ pathto('_static/img/logo.png', 1) }}" width="170" height="214" alt="Logo"/></a>
</p>
<p>
<iframe src="http://ghbtns.com/github-btn.html?user=racker&repo=falcon&type=watch&count=true&size=large"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
<p>
Falcon is a high-performance Python framework for building web APIs. It
encourages the REST architectural style, and tries to do as little as
possible while remaining highly effective.
</p>
<h3>Useful Links</h3>
<ul>
<li><a href="http://falconframework.org/">Falcon Home</a></li>
<li><a href="https://pypi.python.org/pypi/falcon">Falcon @ PyPI</a></li>
<li><a href="https://github.com/racker/falcon">Falcon @ GitHub</a></li>
<li><a href="https://github.com/racker/falcon/issues">Issue Tracker</a></li>
</ul>
Modifications:
Copyright (c) 2010 Kenneth Reitz.
Original Project:
Copyright (c) 2010 by Armin Ronacher.
Some rights reserved.
Redistribution and use in source and binary forms of the theme, with or
without modification, are permitted provided that the following conditions
are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
* The names of the contributors may not be used to endorse or
promote products derived from this software without specific
prior written permission.
We kindly ask you to only use these themes in an unmodified manner just
for Flask and Flask-related products, not for unrelated projects. If you
like the visual style and want to use it for your own projects, please
consider making some larger changes to the themes (such as changing
font faces, sizes, colors or margins).
THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
krTheme Sphinx Style
====================
This repository contains sphinx styles Kenneth Reitz uses in most of
his projects. It is a drivative of Mitsuhiko's themes for Flask and Flask related
projects. To use this style in your Sphinx documentation, follow
this guide:
1. put this folder as _themes into your docs folder. Alternatively
you can also use git submodules to check out the contents there.
2. add this to your conf.py: ::
sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'kr'
The following themes exist:
**kr**
the standard flask documentation theme for large projects
**kr_small**
small one-page theme. Intended to be used by very small addon libraries.
# flasky extensions. flasky pygments style based on tango style
from pygments.style import Style
from pygments.token import Keyword, Name, Comment, String, Error, \
Number, Operator, Generic, Whitespace, Punctuation, Other, Literal
class FlaskyStyle(Style):
background_color = "#f8f8f8"
default_style = ""
styles = {
# No corresponding class for the following:
#Text: "", # class: ''
Whitespace: "underline #f8f8f8", # class: 'w'
Error: "#a40000 border:#ef2929", # class: 'err'
Other: "#000000", # class 'x'
Comment: "italic #8f5902", # class: 'c'
Comment.Preproc: "noitalic", # class: 'cp'
Keyword: "bold #004461", # class: 'k'
Keyword.Constant: "bold #004461", # class: 'kc'
Keyword.Declaration: "bold #004461", # class: 'kd'
Keyword.Namespace: "bold #004461", # class: 'kn'
Keyword.Pseudo: "bold #004461", # class: 'kp'
Keyword.Reserved: "bold #004461", # class: 'kr'
Keyword.Type: "bold #004461", # class: 'kt'
Operator: "#582800", # class: 'o'
Operator.Word: "bold #004461", # class: 'ow' - like keywords