Skip to content

Commit ca49360

Browse files
rsyringrsyring
committed
improve readme, docs, tox and update Python versions in CI
See PR 687 for more details: pallets-eco#687
2 parents df7903e + 088bb3e commit ca49360

File tree

13 files changed

+226
-139
lines changed

13 files changed

+226
-139
lines changed

‎.travis.yml

Lines changed: 24 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,39 @@
1-
sudo: false
1+
os: linux
2+
dist: xenial
23
language: python
4+
env: TOXENV=py,codecov
35

46
matrix:
7+
fast_finish: true
58
include:
6-
- python: 3.6
7-
env: TOXENV=py,codecov
8-
- python: 3.5
9-
env: TOXENV=py,codecov
10-
- python: 3.4
11-
env: TOXENV=py,codecov
12-
- python: 3.3
13-
env: TOXENV=py,py-lowest,codecov
149
- python: 2.7
15-
env: TOXENV=py,codecov
16-
- python: 2.6
17-
env: TOXENV=py,py-lowest,codecov
18-
- python: pypy
19-
env: TOXENV=py,codecov
20-
- python: nightly
21-
env: TOXENV=py,codecov
10+
env: TOXENV=py,py27-lowest,codecov
11+
- python: 3.4
12+
- python: 3.5
2213
- python: 3.6
23-
env: TOXENV=docs_html
14+
env: TOXENV=py,py36-lowest,codecov
15+
- python: 3.7
16+
env: TOXENV=py,py37-lowest,codecov
17+
- python: 3.7
18+
env: TOXENV=docs
19+
- python: nightly
20+
- python: pypy3.5-6.0
21+
allow_failures:
22+
# Why test these at all if they aren't going to fail the build? Answered at:
23+
# https://github.com/pallets/flask-sqlalchemy/issues/689
24+
- python: nightly
25+
- python: pypy3.5-6.0
2426

2527
install:
26-
- pip install tox
28+
- pip install -U tox
2729

2830
script:
29-
- tox
31+
- tox --skip-missing-interpreters false
3032

3133
cache:
32-
- pip
34+
directories:
35+
- $HOME/.cache/pip
36+
- $HOME/.cache/pre-commit
3337

3438
branches:
3539
only:
@@ -38,10 +42,3 @@ branches:
3842

3943
notifications:
4044
email: false
41-
irc:
42-
channels:
43-
- "chat.freenode.net#pocoo"
44-
on_success: change
45-
on_failure: always
46-
use_notice: true
47-
skip_join: true

‎CHANGES.rst

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Released on October 11, 2017
99

1010
- Don't mask the parent table for single-table inheritance models. (`#561`_)
1111

12-
.. _#561: https://github.com/mitsuhiko/flask-sqlalchemy/pull/561
12+
.. _#561: https://github.com/pallets/flask-sqlalchemy/pull/561
1313

1414

1515
Version 2.3.1
@@ -29,11 +29,11 @@ Released on October 5, 2017
2929
- For ``paginate`` with ``error_out=False``, the minimum value for ``page`` is
3030
1 and ``per_page`` is 0. (`#558`_)
3131

32-
.. _#542: https://github.com/mitsuhiko/flask-sqlalchemy/pull/542
33-
.. _#551: https://github.com/mitsuhiko/flask-sqlalchemy/pull/551
34-
.. _#555: https://github.com/mitsuhiko/flask-sqlalchemy/pull/555
35-
.. _#556: https://github.com/mitsuhiko/flask-sqlalchemy/pull/556
36-
.. _#558: https://github.com/mitsuhiko/flask-sqlalchemy/pull/558
32+
.. _#542: https://github.com/pallets/flask-sqlalchemy/pull/542
33+
.. _#551: https://github.com/pallets/flask-sqlalchemy/pull/551
34+
.. _#555: https://github.com/pallets/flask-sqlalchemy/pull/555
35+
.. _#556: https://github.com/pallets/flask-sqlalchemy/pull/556
36+
.. _#558: https://github.com/pallets/flask-sqlalchemy/pull/558
3737

3838

3939
Version 2.3.0
@@ -62,10 +62,10 @@ Released on September 28, 2017
6262
``current_app`` rather than the app they were created for. This caused issues
6363
when multiple apps were registered with the extension. (`#547`_)
6464

65-
.. _#530: https://github.com/mitsuhiko/flask-sqlalchemy/pull/530
66-
.. _#541: https://github.com/mitsuhiko/flask-sqlalchemy/pull/541
67-
.. _#546: https://github.com/mitsuhiko/flask-sqlalchemy/pull/546
68-
.. _#547: https://github.com/mitsuhiko/flask-sqlalchemy/pull/547
65+
.. _#530: https://github.com/pallets/flask-sqlalchemy/pull/530
66+
.. _#541: https://github.com/pallets/flask-sqlalchemy/pull/541
67+
.. _#546: https://github.com/pallets/flask-sqlalchemy/pull/546
68+
.. _#547: https://github.com/pallets/flask-sqlalchemy/pull/547
6969

7070

7171
Version 2.2
@@ -86,14 +86,14 @@ Released on February 27, 2017, codename Dubnium
8686
- Tablename generation logic no longer accesses class properties unless they
8787
are ``declared_attr``. (`#467`_)
8888

89-
.. _#328: https://github.com/mitsuhiko/flask-sqlalchemy/pull/328
90-
.. _#364: https://github.com/mitsuhiko/flask-sqlalchemy/pull/364
91-
.. _#373: https://github.com/mitsuhiko/flask-sqlalchemy/pull/373
92-
.. _#409: https://github.com/mitsuhiko/flask-sqlalchemy/pull/409
93-
.. _#443: https://github.com/mitsuhiko/flask-sqlalchemy/pull/443
94-
.. _#460: https://github.com/mitsuhiko/flask-sqlalchemy/pull/460
95-
.. _#461: https://github.com/mitsuhiko/flask-sqlalchemy/pull/461
96-
.. _#467: https://github.com/mitsuhiko/flask-sqlalchemy/pull/467
89+
.. _#328: https://github.com/pallets/flask-sqlalchemy/pull/328
90+
.. _#364: https://github.com/pallets/flask-sqlalchemy/pull/364
91+
.. _#373: https://github.com/pallets/flask-sqlalchemy/pull/373
92+
.. _#409: https://github.com/pallets/flask-sqlalchemy/pull/409
93+
.. _#443: https://github.com/pallets/flask-sqlalchemy/pull/443
94+
.. _#460: https://github.com/pallets/flask-sqlalchemy/pull/460
95+
.. _#461: https://github.com/pallets/flask-sqlalchemy/pull/461
96+
.. _#467: https://github.com/pallets/flask-sqlalchemy/pull/467
9797

9898
Version 2.1
9999
-----------

‎README

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎README.rst

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
.. default-role:: code
2+
3+
Flask-SQLAlchemy
4+
================
5+
6+
Flask-SQLAlchemy is a Flask_ extension which adds support for the SQLAlchemy_.
7+
8+
9+
Installing
10+
----------
11+
12+
Install and update using `pip`_:
13+
14+
.. code-block:: text
15+
16+
$ pip install -U flask-sqlalchemy
17+
18+
We encourage you to use a virtualenv_. Check the docs for complete installation, version
19+
requirement, and usage instructions.
20+
21+
22+
A Simple Example
23+
----------------
24+
25+
Pretty easy to get started:
26+
27+
.. code-block:: python
28+
29+
from flask import Flask
30+
from flask_sqlalchemy import SQLAlchemy
31+
32+
app = Flask(__name__)
33+
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////tmp/test.db'
34+
db = SQLAlchemy(app)
35+
36+
37+
class User(db.Model):
38+
id = db.Column(db.Integer, primary_key=True)
39+
username = db.Column(db.String(80), unique=True, nullable=False)
40+
email = db.Column(db.String(120), unique=True, nullable=False)
41+
42+
For more details, see the `quickstart example
43+
<http://flask-sqlalchemy.pocoo.org/latest/quickstart/#a-minimal-application>`_.
44+
45+
46+
Tests
47+
-----
48+
49+
In short we use pytest_ and tox_. You should be able to::
50+
51+
$ git clone git@github.com:pallets/flask-sqlalchemy.git
52+
$ cd flask-sqlalchemy
53+
$ tox
54+
55+
That will run everything, so you might want to start with something like `tox -e py37` or whatever
56+
version of Python you have installed.
57+
58+
You can figure out our testing and documentation dependencies by further inspecting the `tox.ini`
59+
file in the root of the project.
60+
61+
Help
62+
----
63+
64+
Join us at:
65+
66+
- the #pocoo IRC channel on irc.freenode.net
67+
- https://discord.gg/t6rrQZH
68+
69+
70+
Links
71+
-----
72+
73+
- Home: https://github.com/pallets/flask-sqlalchemy
74+
- Documentation: http://flask-sqlalchemy.pocoo.org/
75+
- Releases: https://pypi.org/project/Flask-SQLAlchemy/
76+
- Issue tracker: https://github.com/pallets/flask-sqlalchemy/issues
77+
- Test status:
78+
79+
- Linux: https://travis-ci.org/pallets/flask-sqlalchemy/
80+
- Mac, Windows: none yet, see `#690 <https://github.com/pallets/flask-sqlalchemy/issues/690>`_
81+
82+
- Test coverage: https://codecov.io/gh/pallets/flask-sqlalchemy/
83+
84+
85+
.. _SQLAlchemy: https://www.sqlalchemy.org/
86+
.. _Flask: https://www.palletsprojects.com/p/flask/
87+
.. _pip: https://pip.pypa.io/en/stable/quickstart/
88+
.. _pytest: https://docs.pytest.org/en/latest/
89+
.. _tox: https://tox.readthedocs.io/en/latest/
90+
.. _virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtualenv/

‎docs/_templates/sidebarintro.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ <h3>Useful Links</h3>
99
<ul>
1010
<li><a href="http://flask.pocoo.org/">The Flask Website</a></li>
1111
<li><a href="https://pypi.python.org/pypi/Flask-SQLAlchemy">Flask-SQLAlchemy @ PyPI</a></li>
12-
<li><a href="https://github.com/mitsuhiko/flask-sqlalchemy">Flask-SQLAlchemy @ github</a></li>
13-
<li><a href="https://github.com/mitsuhiko/flask-sqlalchemy/issues">Issue Tracker</a></li>
12+
<li><a href="https://github.com/pallets/flask-sqlalchemy">Flask-SQLAlchemy @ github</a></li>
13+
<li><a href="https://github.com/pallets/flask-sqlalchemy/issues">Issue Tracker</a></li>
1414
</ul>
1515

16-
<a href="http://github.com/mitsuhiko/flask-sqlalchemy"><img style="position: fixed; top: 0; right: 0; border: 0;"
16+
<a href="http://github.com/pallets/flask-sqlalchemy"><img style="position: fixed; top: 0; right: 0; border: 0;"
1717
src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>

‎docs/conf.py

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,13 @@
2929

3030
# Add any Sphinx extension module names here, as strings. They can be extensions
3131
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
32-
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
32+
extensions = [
33+
'sphinx.ext.autodoc',
34+
'sphinx.ext.intersphinx',
35+
# Without this we get errors in CI when building docs. See:
36+
# https://github.com/pallets/flask-sqlalchemy/issues/686
37+
'sphinx_paramlinks',
38+
]
3339

3440
# Add any paths that contain templates here, relative to this directory.
3541
templates_path = ['_templates']

‎docs/config.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,8 +130,8 @@ specify a `custom constraint naming convention
130130
<http://docs.sqlalchemy.org/en/latest/core/constraints.html#constraint-naming-conventions>`_
131131
in conjunction with SQLAlchemy 0.9.2 or higher.
132132
Doing so is important for dealing with database migrations (for instance using
133-
`alembic <https://alembic.readthedocs.org>`_ as stated
134-
`here <http://alembic.readthedocs.org/en/latest/naming.html>`_. Here's an
133+
`alembic <https://alembic.sqlalchemy.org>`_ as stated
134+
`here <https://alembic.sqlalchemy.org/en/latest/naming.html>`_. Here's an
135135
example, as suggested by the SQLAlchemy docs::
136136

137137
from sqlalchemy import MetaData

‎docs/contents.rst.inc

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,39 @@ method, this part of the documentation is for you.
3030
Additional Notes
3131
----------------
3232
33-
See Flask's license_ for legal information governing this project.
33+
Requirements
34+
............
35+
36+
OS support: Linux, Windows, MacOS
37+
38+
Python support:
39+
40+
.. csv-table::
41+
:header: "Our Version", "Python", "Flask", "SQLAlchemy"
42+
43+
"2.x", "2.7, 3.4+", 0.12+, "0.8+ or 1.0.10+ w/ Python 3.7"
44+
"3.0+ (in dev)", "2.7, 3.5+", 1.0+, 1.0+
45+
46+
If doubts arise, you can always check to see what we are testing:
47+
48+
* `2.x: tox.ini <https://github.com/pallets/flask-sqlalchemy/blob/2.x-maintenance/tox.ini>`_
49+
* `dev: tox.ini <https://github.com/pallets/flask-sqlalchemy/blob/master/tox.ini>`_
50+
* We only run CI for Linux currently (`#690 <https://github.com/pallets/flask-sqlalchemy/issues/690>`_)
51+
52+
53+
54+
License
55+
.......
56+
57+
See `our license <https://github.com/pallets/flask-sqlalchemy/blob/master/LICENSE>`_ for legal
58+
information governing this project.
59+
60+
61+
Changelog
62+
.........
3463
3564
.. toctree::
3665
:maxdepth: 2
3766
3867
changelog
3968
40-
.. _license: http://flask.pocoo.org/docs/license/

‎docs/contexts.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ You will have to setup an application context. If you are working inside
3636
a Flask view function or a CLI command, that automatically happens. However,
3737
if you are working inside the interactive shell, you will have to do that
3838
yourself (see `Creating an Application Context
39-
<http://flask.pocoo.org/docs/appcontext/#creating-an-application-context>`_).
39+
<http://flask.pocoo.org/docs/1.0/appcontext/#manually-push-a-context>`_).
4040

4141
If you try to perform database operations outside an application context, you
4242
will see the following error:

‎docs/index.rst

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,16 @@ Flask-SQLAlchemy
55

66
.. module:: flask_sqlalchemy
77

8-
Flask-SQLAlchemy is an extension for `Flask`_ that adds support for
9-
`SQLAlchemy`_ to your application. It requires SQLAlchemy 0.8 or
10-
higher. It aims to simplify using SQLAlchemy with Flask by providing
11-
useful defaults and extra helpers that make it easier to accomplish common
12-
tasks.
8+
Flask-SQLAlchemy is an extension for `Flask`_ that adds support for `SQLAlchemy`_ to your
9+
application. It aims to simplify using SQLAlchemy with Flask by providing useful defaults and extra
10+
helpers that make it easier to accomplish common tasks.
1311

1412
.. _SQLAlchemy: http://www.sqlalchemy.org/
1513
.. _Flask: http://flask.pocoo.org/
16-
.. _example sourcecode:
17-
http://github.com/mitsuhiko/flask-sqlalchemy/tree/master/examples/
1814

19-
See `the SQLAlchemy documentation`_ to learn how to work with the ORM in depth. The following documentation is a brief overview of the most common tasks, as well as the features specific to Flask-SQLAlchemy.
15+
See `the SQLAlchemy documentation`_ to learn how to work with the ORM in depth. The following
16+
documentation is a brief overview of the most common tasks, as well as the features specific to
17+
Flask-SQLAlchemy.
2018

2119
.. _the SQLAlchemy documentation: http://docs.sqlalchemy.org/
2220

0 commit comments

Comments
 (0)