Development¶
Contributions are very welcome. Please read this guide if you want to contribute.
Development Environment Setup¶
Fork the Authomatic repository on Github and clone it:
$ git clone https://github.com/<your-github-id>/authomatic.git
$ cd authomatic
Note
The rest of this document assumes that you are working in the authomatic/ directory.
Although Authomatic has no dependencies except for the optional python-openid package required by the openid.OpenID provider, it has quite a lot of development dependencies.
The easiest way to set up the development environment is to run the ./bootstrap.sh script.
$ sh bootstrap.sh
The script does following:
Initializes and updates GIT submodules. The Foundation Sphinx Theme located in ./doc/source_/themes/foundation-sphinx-theme is currently the only GIT submodule used.
Creates a virtual environment ./e.
Installs the development dependencies specified in ./requirements.txt to the e virtual environment.
Runs the tox -r --notest command which creates virtual environments ./.tox/py26, ./.tox/py27 and ./tox/py34.
Creates symbolic links to ./.tox/py27/lib/python2.7/site-packages/openid and ./authomatic in each of the ./examples/gae/* directories.
- Prepares the ./doc/build/html directory for deployment of the compiled documentation to Github Pages.
- Removes the ./doc/build/ directory if it exists.
- Clones the origin of this repository to ./doc/build/html.
- Creates the gh-pages branch there.
- Sets the GIT HEAD to gh-pages.
- Removes the GIT index.
- Removes everything in the directory with git claen -fdx.
Compiles the documentation with the ./.tox/py27 virtual environment activated.
PyOpenSSL Error¶
It is likely, that you will encounter some of following errors during installation of the pyopenssl package:
Missing Python headers Python.h: No such file or directory:
Fix it by installing Python development package e.g:
$ sudo apt-get install python3.4-dev
Missing libffi headers ffi.h: No such file or directory:
Fix it by installing libffi development package e.g:
$ sudo apt-get install libffi-dev
Documentation Compilation and Deployment¶
Warning
Allways keep the documentation in sync with the latest code changes.
Compile the documentation with this commands:
$ . ./.tox/py27/bin/activate
(py27)$ cd doc
(py27)$ make html
The documentation will be compiled to ./doc/build/html. For easy deploiment to Github Pages, the ./doc/build/html directory is actually a clone of the origin of the actual project repository that you cloned from (your fork) with the gh-pages branch checked out.
To deploy a compiled documentation to GitHub page go to the ./doc/build/html directory, commit all changes and push to origin gh-pages:
$ cd doc/build/html
$ git add -A
$ git commit -m "Updated documentation."
$ git push origin gh-pages
Testing¶
Tests are written in pytest and Tox is used to run them in Python 2.6, Python 2.7 and Python 3.4.
There are currently only functional (end-to-end) Selenium tests. They are designed to test the login procedure and credentials refreshment and to discover changes in provider APIs. Currently the tests cover all of the OAuth 2.0 and select OpenID providers.
To run functional tests, you first need to create the ./tests/functional_tests/config.py module by copying and filling out the ./tests/functional_tests/config-template.py template.
$ cd tests/functional_tests
$ cp config-template.py config.py
If you want to run tests for all of the covered providers, you should register an application and a user account by each of them and fill out all possible settings in the user profile. You can exclude providers from the tests by comenting them out of the INCLUDE_PROVIDERS list.
You should also add an alias for the IP address of your localhost, because some providers like Twitter require the callback_uri to match a domain pattern.
$ sudo echo -e "127.0.0.1\tauthomatic.com" >> /etc/hosts
$ cat /etc/hosts
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
127.0.0.1 authomatic.com
Finally launch the tests:
(e)$ tox
If you want tox to only run tests for let’s say Python 2.6 and Python 3.4 use the -e option:
(e)$ tox -e py26, py34
Running the Examples¶
If you want to run any of the ./examples/ just copy the example’s config-template.py to config.py, fill it out, activate one of the virtual environments in ./tox/ and run the example the usual way according to its framework.
Note
The examples for functional tests (currently there is only one in ./examples/flask/functional_test/) use the config from ./tests/functional_tests/config.py.
Note
The Google App Engine examples will only work in Python 2.7 The Google App Engine command line tools are installed in the ./tox/py27/bin directory.