From 6262a89a70b0e7baef54959beb1a3b97be36341e Mon Sep 17 00:00:00 2001 From: Jiri Kuncar Date: Fri, 29 Aug 2014 15:40:53 +0200 Subject: [PATCH] docs: minimal application example Reviewed-by: Tibor Simko Signed-off-by: Jiri Kuncar --- AUTHORS | 2 +- CHANGES | 6 +- CONTRIBUTING.rst | 30 ++++++ MANIFEST.in | 2 +- docs/_templates/sidebarintro.html | 14 --- docs/api.rst | 14 --- docs/changelog.rst | 3 - docs/conf.py | 7 +- docs/contributing.rst | 4 - docs/index.rst | 162 +++++++++++++++++++++++++----- docs/installation.rst | 25 ----- docs/license.rst | 8 -- docs/quickstart.rst | 26 ----- docs/userguide.rst | 3 - flask_sso/__init__.py | 51 +++++----- flask_sso/config.py | 52 +++++----- flask_sso/version.py | 3 +- setup.py | 3 + 18 files changed, 230 insertions(+), 185 deletions(-) create mode 100644 CONTRIBUTING.rst delete mode 100644 docs/_templates/sidebarintro.html delete mode 100644 docs/api.rst delete mode 100644 docs/changelog.rst delete mode 100644 docs/contributing.rst delete mode 100644 docs/installation.rst delete mode 100644 docs/license.rst delete mode 100644 docs/quickstart.rst delete mode 100644 docs/userguide.rst diff --git a/AUTHORS b/AUTHORS index 93e4e4a..abf7fac 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,5 @@ Authors -------- +======= Flask-SSO is developed for use in `Invenio `_ digital library software. diff --git a/CHANGES b/CHANGES index 9aa3672..c26a1d2 100644 --- a/CHANGES +++ b/CHANGES @@ -5,7 +5,7 @@ Here you can see the full list of changes between each Flask-SSO release. Version 0.2.0 (released 2014-06-26) ------------------------------------ + - Allowing ';' separator in HTTP data. - Fix for dictionary key order in tests. - Fix for Python 3.3 string comparison. @@ -14,5 +14,5 @@ Version 0.2.0 (released 2014-06-26) - New configuration option SSO_LOGIN_ENDPOINT. Version 0.1 ------------ -- Initial public release + +- Initial public release. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..9a6d623 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,30 @@ +Contributing +============ + +Bug reports, feature requests, and other contributions are welcome. +If you find a demonstrable problem that is caused by the code of this +library, please: + +1. Search for `already reported problems + `_. +2. Check if the issue has been fixed or is still reproducible on the + latest `master` branch. +3. Create an issue with **a test case**. + +If you create a feature branch, you can run the tests to ensure everything is +operating correctly: + +.. code-block:: console + + $ ./run-tests.sh + ... + Ran 8 tests in 0.246s + + OK + Name Stmts Miss Cover Missing + -------------------------------------------------- + flask_sso/__init__ 47 0 100% + flask_sso/config 4 0 100% + flask_sso/version 2 0 100% + -------------------------------------------------- + TOTAL 53 0 100% diff --git a/MANIFEST.in b/MANIFEST.in index 9bd035e..5c0afed 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -7,7 +7,7 @@ ## it under the terms of the Revised BSD License; see LICENSE file for ## more details. -include LICENSE AUTHORS CHANGES README.rst +include LICENSE AUTHORS CHANGES CONTRIBUTING.rst README.rst include .coveragerc run-tests.sh include docs/*.rst docs/*.py docs/Makefile include tests/*.py diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html deleted file mode 100644 index 5abee88..0000000 --- a/docs/_templates/sidebarintro.html +++ /dev/null @@ -1,14 +0,0 @@ -

About

-

- Flask-SSO is an extension for Flask that CHANGEME -

-

Useful Links

- - -Fork me on GitHub diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 204e5c3..0000000 --- a/docs/api.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _api: - -API Docs -======== - -.. automodule:: flask_sso - -.. autoclass:: SSO - :members: - -.. automodule:: flask_sso.apackage.amodule - -.. autoclass:: AClass - :members: diff --git a/docs/changelog.rst b/docs/changelog.rst deleted file mode 100644 index 828a2f0..0000000 --- a/docs/changelog.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. _changes: - -.. include:: ../CHANGES diff --git a/docs/conf.py b/docs/conf.py index ac5497b..6dadf4b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -104,14 +104,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme_path = ['_themes'] -html_theme = 'flask' +html_theme = 'flask_small' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'index_logo_height': '0' + 'index_logo': False, + 'index_logo_height': '40px;' } # Add any paths that contain custom themes here, relative to this directory. @@ -136,7 +137,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 15aa02d..0000000 --- a/docs/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -Contributing -============ - -See for now. diff --git a/docs/index.rst b/docs/index.rst index 99349a9..a354be1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,52 +1,162 @@ =========== Flask-SSO =========== +.. currentmodule:: flask_sso -Flask-SSO -========= -.. image:: https://travis-ci.org/inveniosoftware/flask-sso.png?branch=master - :target: https://travis-ci.org/inveniosoftware/flask-sso -.. image:: https://coveralls.io/repos/inveniosoftware/flask-sso/badge.png?branch=master - :target: https://coveralls.io/r/inveniosoftware/flask-sso +.. raw:: html + +

+ + travis-ci badge + + + coveralls.io badge + +

+ Flask-SSO is a Flask extension permitting to set up Shibboleth Single-Sign-On authentication in Flask based web applications. -User's Guide +Contents +-------- + +.. contents:: + :local: + :backlinks: none + + +Installation ============ +Flask-SSO is on PyPI so all you need is : + +.. code-block:: console + + $ pip install flask-sso + +The development version can be downloaded from `its page at GitHub +`_. + +.. code-block:: console + + $ git clone https://github.com/inveniosoftware/flask-sso.git + $ cd flask-sso + $ python setup.py develop + $ ./run-tests.sh + +Requirements +^^^^^^^^^^^^ + +Flask-SSO has the following dependencies: + +* `Flask `_ +* `blinker `_ +* `six `_ + +Flask-SSO requires Python version 2.6, 2.7 or 3.3+ + + +Quickstart +========== + This part of the documentation will show you how to get started in using Flask-SSO with Flask. -.. toctree:: - :maxdepth: 2 +This guide assumes you have successfully installed Flask-SSO and a working +understanding of Flask. If not, follow the installation steps and read about +Flask at http://flask.pocoo.org/docs/. + + +A Minimal Example +^^^^^^^^^^^^^^^^^ + +A minimal Flask-SSO usage example looks like this. + +First, let's create the application and initialise the extension: - installation - quickstart - userguide +.. code-block:: python + from flask import Flask, session, redirect + from flask_sso import SSO + app = Flask("myapp") + ext = SSO(app=app) -API Reference + +Second, let's configure the attribute map for converting environment +variables to a dictionary containing user information: + +.. code-block:: python + + #: Default attribute map + SSO_ATTRIBUTE_MAP = { + 'ADFS_AUTHLEVEL': (False, 'authlevel'), + 'ADFS_GROUP': (True, 'group'), + 'ADFS_LOGIN': (True, 'nickname'), + 'ADFS_ROLE': (False, 'role'), + 'ADFS_EMAIL': (True, 'email'), + 'ADFS_IDENTITYCLASS': (False, 'external'), + 'HTTP_SHIB_AUTHENTICATION_METHOD': (False, 'authmethod'), + } + + app.config.setdefault('SSO_ATTRIBUTE_MAP', SSO_ATTRIBUTE_MAP) + + +Third, let's set up a login handler function that reads user information +and stores it for later usage: + +.. code-block:: python + + @sso.login_handler + def login_callback(user_info): + """Store information in session.""" + session["user"] = user_info + + +Fourth, we can now greet the user using his SSO login name: + +.. code-block:: python + + @app.route("/") + def index(): + """Display user information or force login.""" + if "user" in session: + return "Welcome {name}".format(name=session["user"]["nickname"]) + return redirect(app.config["SSO_LOGIN_URL"]) + + +Configuration ============= -If you are looking for information on a specific function, class or -method, this part of the documentation is for you. +.. automodule:: flask_sso.config + + +API +=== + +This documentation section is automatically generated from Flask-SSO's +source code. + +Flask-SSO +^^^^^^^^^ + +.. automodule:: flask_sso + +.. autoclass:: SSO + :members: -.. toctree:: - :maxdepth: 2 - api +.. include:: ../CHANGES +.. include:: ../CONTRIBUTING.rst -Additional Notes -================ -Notes on how to contribute, legal information and changelog are here for the interested. +License +======= -.. toctree:: - :maxdepth: 2 +.. include:: ../LICENSE - contributing - changelog - license +.. include:: ../AUTHORS diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 40c9814..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _installation: - -Installation -============ - -Install Flask-SSO with ``pip`` :: - - pip install flask-sso - -The development version can be downloaded from `its page at GitHub -`_. :: - - git clone https://github.com/inveniosoftware/flask-sso.git - cd flask-sso - python setup.py develop - ./run-tests.sh - -Requirements ------------- -Flask-SSO has the following dependencies: - -* `Flask `_ -* `six `_ - -Flask-SSO requires Python version 2.6, 2.7 or 3.3+ diff --git a/docs/license.rst b/docs/license.rst deleted file mode 100644 index ab0539f..0000000 --- a/docs/license.rst +++ /dev/null @@ -1,8 +0,0 @@ -License -======= - -.. include:: ../LICENSE - -.. _authors: - -.. include:: ../AUTHORS diff --git a/docs/quickstart.rst b/docs/quickstart.rst deleted file mode 100644 index 65ca6d2..0000000 --- a/docs/quickstart.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _quickstart: - -Quickstart -========== - -This guide assumes you have successfully installed Flask-SSO and a working -understanding of Flask. If not, follow the installation steps and read about -Flask at http://flask.pocoo.org/docs/. - - -A Minimal Example ------------------ - -A minimal Flask-SSO usage example looks like this. First create the -application and initialize the extension: - ->>> from flask import Flask ->>> from flask_sso import SSO ->>> app = Flask('myapp') ->>> ext = SSO(app=app) - -Some Extended Example ---------------------- -Flask-SSO also has support for CHANGEME - -.. literalinclude:: ../tests/helpers.py diff --git a/docs/userguide.rst b/docs/userguide.rst deleted file mode 100644 index 8a90e05..0000000 --- a/docs/userguide.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. automodule:: flask_sso - -.. automodule:: flask_sso.apackage.amodule diff --git a/flask_sso/__init__.py b/flask_sso/__init__.py index 792b863..df8971f 100644 --- a/flask_sso/__init__.py +++ b/flask_sso/__init__.py @@ -8,15 +8,22 @@ ## more details. """ -Flask extension -=============== +Implement Shibboleth Single-Sign-On authentication. Flask-SSO is initialized like this: +Initialization of the extension: + >>> from flask import Flask >>> from flask_sso import SSO >>> app = Flask('myapp') >>> ext = SSO(app=app) + +or alternatively using the factory pattern: + +>>> app = Flask('myapp') +>>> ext = SSO() +>>> ext.init_app(app) """ from __future__ import absolute_import @@ -26,9 +33,12 @@ from flask import current_app, request from flask.signals import Namespace +from .version import __version__ + class SSOAttributeError(Exception): - pass + + """General SSO Attribute error.""" # Signals _signals = Namespace() @@ -39,32 +49,18 @@ class SSOAttributeError(Exception): class SSO(object): - """ - Flask extension - Initialization of the extension: + """Flask extension implementation.""" - >>> from flask import Flask - >>> from flask_sso import SSO - >>> app = Flask('myapp') - >>> ext = SSO(app=app) - - or alternatively using the factory pattern: - - >>> app = Flask('myapp') - >>> ext = SSO() - >>> ext.init_app(app) - """ def __init__(self, app=None): + """Initialize login callback.""" self.login_callback = None if app is not None: self.init_app(app) def init_app(self, app): - """ - Initialize a Flask application. - """ + """Initialize a Flask application.""" self.app = app # Follow the Flask guidelines on usage of app.extensions if not hasattr(app, 'extensions'): @@ -83,9 +79,10 @@ def init_app(self, app): self.login) def login_handler(self, callback): - """ - This will set the callback for the `login` method. It takes one - argument with attributes map, and should return a Flask response. + """Set the callback for the `login` method. + + It takes one argument with attributes map, and should return a Flask + response. :param callback: The callback for login. :type callback: function @@ -93,6 +90,7 @@ def login_handler(self, callback): self.login_callback = callback def login(self): + """Implement application login endpoint for SSO.""" attrs, error = self.parse_attributes() if error: raise SSOAttributeError @@ -103,6 +101,7 @@ def login(self): return self.login_callback(attrs) def parse_attributes(self): + """Parse arguments from environment variables.""" attrs = {} error = False for header, attr in self.app.config['SSO_ATTRIBUTE_MAP'].items(): @@ -115,9 +114,5 @@ def parse_attributes(self): error = True return attrs, error -# Version information -from .version import __version__ -__all__ = [ - 'SSO', '__version__' -] +__all__ = ('SSO', '__version__') diff --git a/flask_sso/config.py b/flask_sso/config.py index 49e3e4b..62da346 100644 --- a/flask_sso/config.py +++ b/flask_sso/config.py @@ -7,9 +7,8 @@ ## it under the terms of the Revised BSD License; see LICENSE file for ## more details. -""" -Configuration -============= +"""The details of the application settings that can be customized. + SSO_ATTRIBUTE_MAP ----------------- @@ -17,23 +16,26 @@ A dictionary mapping HTTP headers to a tuple. The tuple contains whether the attribute is required and then the name of the attribute. -Example:: +Example: + +.. code-block:: python -# CERN Single-Sign-On -SSO_ATTRIBUTE_MAP = { - "ADFS_LOGIN": (True, nickname), - "ADFS_EMAIL": (True, email), -} + # CERN Single-Sign-On + SSO_ATTRIBUTE_MAP = { + "ADFS_LOGIN": (True, nickname), + "ADFS_EMAIL": (True, email), + } + + # General Shibboleth + SSO_ATTRIBUTE_MAP = { + "HTTP_SHIB_IDENTITY_PROVIDER": (True, "idp"), + "HTTP_SHIB_SHARED_TOKEN": (True, "shared_token"), + "HTTP_SHIB_CN": (True, "cn"), + "HTTP_SHIB_MAIL": (True, "email"), + "HTTP_SHIB_GIVENNAME": (False, "first_name"), + "HTTP_SHIB_SN": (False, "last_name"), + } -# General Shibboleth -SSO_ATTRIBUTE_MAP = { - "HTTP_SHIB_IDENTITY_PROVIDER": (True, "idp"), - "HTTP_SHIB_SHARED_TOKEN": (True, "shared_token"), - "HTTP_SHIB_CN": (True, "cn"), - "HTTP_SHIB_MAIL": (True, "email"), - "HTTP_SHIB_GIVENNAME": (False, "first_name"), - "HTTP_SHIB_SN": (False, "last_name"), -} SSO_LOGIN_URL ------------- @@ -45,13 +47,15 @@ Name of login handler endpoint to be used in `url_for` function. -Example:: +Example: + +.. code-block:: python ->>> from flask.ext.sso.config import * ->>> url_for(SSO_LOGIN_ENDPOINT) -/login/sso ->>> SSO_LOGIN_URL -/login/sso + >>> from flask.ext.sso.config import * + >>> url_for(SSO_LOGIN_ENDPOINT) + /login/sso + >>> SSO_LOGIN_URL + /login/sso Default: `sso_login`. diff --git a/flask_sso/version.py b/flask_sso/version.py index 7345ebf..a6a45cf 100644 --- a/flask_sso/version.py +++ b/flask_sso/version.py @@ -7,8 +7,7 @@ ## it under the terms of the Revised BSD License; see LICENSE file for ## more details. -""" -Version information for Flask-SSO +"""Version information for Flask-SSO. This file is imported by ``flask_sso.__init__``, and parsed by ``setup.py`` as well as ``docs/conf.py``. diff --git a/setup.py b/setup.py index ad13bb1..355ea24 100644 --- a/setup.py +++ b/setup.py @@ -36,6 +36,9 @@ 'blinker', 'six', ], + extras_require={ + 'docs': ['sphinx'], + }, classifiers=[ 'Environment :: Web Environment', 'Intended Audience :: Developers',