flask-snow
=============

.. module:: flask_snow

Enables easy access to the ServiceNow REST API with seamless authentication and authorization in Flask.

Create your own lightweight ServiceNow instance, integrate with your current Flask server or just use it to relay API-calls in a micro-service.



Installation
------------

Use pip to install the extension::

    $ pip install flask-snow


Usage
-----

flask-snow is managed through a ``Pysnow`` instance::

    from flask import Flask
    from flask_snow import Pysnow

    app = Flask(__name__)
    pysnow = Pysnow(app)

you may also set up your ``Pysnow`` instance later using **init_app** method::

    pysnow = Pysnow()

    app = Flask(__name__)
    pysnow.init_app(app)


Once created, the pysnow client instance is available in `pysnow.client`::

    c = pysnow.client
    incident = c.resource(api_path='/table/incident')
    record = incident.get(query={}, limit=1).first()


Check out the `pysnow API documentation <http://pysnow.readthedocs.io/en/latest>`_ for more info.


Configuration
-------------

The following configuration values exist for flask-snow.

========================== ============== ================
Name                       Default value  Description
========================== ============== ================
PYSNOW_INSTANCE            None           Instance name
PYSNOW_HOST                None           FQDN (instead of instance)
PYSNOW_ENABLE_LOGGING      True           Logs information about requests
PYSNOW_USE_SSL             True           Whether or not to use SSL
PYSNOW_RAISE_ON_EMPTY      False          Raise an exception on empty result sets
========================== ============== ================

Authentication
^^^^^^^^^^^^^^
The following authentication methods are supported:

- Static - Set a static username and password to use for all requests
- Oauth - set client id and secret, and authenticate users in the application context
- session - pre-made requests-compatible session

**Static**

========================== ============== ================
Name                       Default value  Description
========================== ============== ================
PYSNOW_USER                None           Username
PYSNOW_PASSWORD            None           Password
========================== ============== ================


**Oauth**

========================== ============== ================
Name                       Default value  Description
========================== ============== ================
PYSNOW_OAUTH_CLIENT_ID     None           Client ID (from ServiceNow)
PYSNOW_OAUTH_CLIENT_SECRET None           Client secret (from ServiceNow)
========================== ============== ================

**Session**

Passing a custom **session** to `flask-snow` doesn't require any configuration. Simply::

    import requests
    from flask import Flask
    from flask_snow import Pysnow

    s = requests.Session()
    s.verify = False  # In this case, we use a custom session to disable SSL verification
    s.auth = requests.auth.HTTPBasicAuth('myusername', 'mypassword')

    pysnow = Pysnow()

    app = Flask(__name__)
    pysnow.init_app(app, session=s)


Examples
--------

Full examples can be found `here <https://github.com/rbw0/flask-snow/tree/master/examples>`_



API
---

.. autoclass:: flask_snow.Pysnow
    :members:

.. autoattribute:: Pysnow.client