Flask-Upwork 1.0-pre2
Upwork API support to Flask
License: BSD

============
Flask-Upwork
============

Requirements
============

    * `flask`
    * `python-upwork`
    * `python-oauth2`


Authorization
==============

Quick start
-----------

Before you may use Upwork APIs, you will need to obtain your pair of API keys.
Visit the `Upwork API Center documentation <http://developers.upwork.com/Authentication#authentication>`_
for full details. Please note, that Flask-Upwork uses authorization via OAuth and it needs keys with auth type "OAuth".

Please make sure, that `SECRET_KEY` which is necessary for sessions, based on the secure cookies, is indicated in `settings.py`:: 

    SECRET_KEY = '(your random secret key)'

You need to store your pair of Upwork API keys in `settings.py`::

    ODESK_KEY = '(your Upwork public key)'
    ODESK_SECRET = '(your Upwork secret key)'

You can also set the list of teams in `settings.py`, which will be able to authorize.
If you do not specify this option or leave the list empty, then all Upwork users will be able to authorize::


    ODESK_AUTH_TEAMS = ('teamname',)

Please make sure that you have registered Upwork module in your `app.py` correctly.
Please keep in mind that `url_prefix` can be whatever you like::

    from flask import Flask
    from flaskext.odesk import odesk

    app = Flask(__name__)
    app.config.from_pyfile('settings.py')
    app.register_module(odesk, url_prefix='/odesk')



Using authorization
-------------------

Please use the decorator `login_required` to close the access for anonymous users to the certain parts of your website::

    @app.route('/only/for/odesk/users')
    @odesk.login_required
    def admin():
        return "Welcome, Upwork user!"

If you want to indicate login or logout links in the template, than you can use `url_for` function and `odesk_is_authorized` variable::

    {% if odesk_is_authorized %}
      <a href="{{ url_for('odesk.logout') }}">Log out</a>
    {% else %}
      <a href="{{ url_for('odesk.login') }}">Upwork log in</a>
    {% endif %}

To check the authorization of the current user you can use `is_authorized` method::

    @app.route('/test')
    def test():
        if odesk.is_authorized():
            return "You are authorized."
        else:
            return "You are not authorized yet."

If you need, you can start the authorization process manually from your code::

    if not odesk.is_authorized():
        return odesk.login()

You can also use `next` parameter to indicate URL, where will be redirect after the authorization process ends::

    if not odesk.is_authorized():
        return odesk.login(next='/blah/blah')

You can use `logout` method for user's logging out.
Please pay attention, that unlike `login` this method do not return the bulk of redirects.
It simply deletes the OAuth session. You should return response manually::

    if odesk.is_authorized():
        odesk.logout()
        return redirect('/')

If you want to expand autorization process, you can use `after_login` decorator,
that indicates your function, which will be called after successfully authorization::

    @odesk.after_login
    def save_session():
        # Getting current user's data. Please, see below how to use the Client.
        session['user'] = odesk.get_client().hr.get_user('me')

If you have used `after_login` and saved something to the session, please,
do not forget to delete this session after logging out, using decorator `after_logout`::

    @odesk.after_logout
    def delete_session():
        if 'user' in session:
            del session['user']


Using client
============

You can use `get_access_token` method to get the current access token and access token secret,
that can be stored in DB and used for access to the client later, if necessary::

    if odesk.is_authorized():
        access_token, access_token_secret = odesk.get_access_token()

You can use `get_client` method to get the client::

    if odesk.is_authorized():
        c = odesk.get_client()
        c.team.get_teamrooms()

Or you can use the client even if the current user is not authorized,
but you have the access token and access token secret::

    if not odesk.is_authorized():
        c = odesk.get_client(access_token, access_token_secret)
        c.team.get_teamrooms()