Skip to content

README updated #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
travcunn wants to merge 6 commits into from
Closed

README updated #1

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e90fb28
updated the README for simplicity until we make some changes to the c…
Mar 14, 2013
d6b6187
put the basic auth methods back on the readme and cleaned it up
Mar 14, 2013
214d785
changed the wording under basic authentication for clarity
Mar 14, 2013
2ffb9b3
Update README.rst
Mar 14, 2013
3c6a782
Update README.rst
Mar 14, 2013
b59eb3b
Update README.rst
Mar 14, 2013
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 45 additions & 19 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,16 @@
.. figure:: https://travis-ci.org/smartfile/client-python.png
:alt: Travis CI Status
:target: https://travis-ci.org/smartfile/client-python

A `SmartFile`_ Open Source project. `Read more`_ about how SmartFile
uses and contributes to Open Source software.

.. figure:: http://www.smartfile.com/images/logo.jpg
:alt: SmartFile

Introduction
Summary
------------

This library includes two API clients. Each one represents one of the supported
authentication methods. ``BasicClient`` is used for HTTP Basic authentication,
using an API key and password. ``OAuthClient`` is used for OAuth authentication,
using tokens.
using an API key and password. ``OAuthClient`` is used for OAuth (version 1) authentication,
using tokens, which will require user interaction to complete authentication with the API.

Both clients provide a thin wrapper around an HTTP library, taking care of some
of the mundane details for you. The intended use of this library is to refer to
Expand All @@ -37,7 +33,7 @@ Or via source code / GitHub.

::

$ git clone https://github.com/smartfile/client-python.git smartfile
$ git clone https://github.com/kissync/smartfile-client-python.git smartfile
$ cd smartfile
$ python setup.py install

Expand All @@ -47,7 +43,9 @@ and `PyPI <https://pypi.python.org/pypi/smartfile/>`_.
Usage
-----

Some of the details this library takes care of are.
Choose between Basic and OAuth authentication methods, then continue to use the SmartFile API.

Some of the details this library takes care of are:

* Encoding and decoding of parameters and return values. You deal with Python
types only.
Expand All @@ -56,12 +54,20 @@ Some of the details this library takes care of are.
* Authentication. Provide the credentials that you obtained from SmartFile,
and plug them into this library. It will take care of the details.

Authentication
--------------
Basic Authentication
--------------------

Three methods are supported for providing API credentials using basic authentication.

Three methods are supported for providing API credentials.
1. Parameters when instantiating the client.

1. Environment variables.
.. code:: python

>>> from smartfile import BasicClient
>>> api = BasicClient('**********', '**********')
>>> api.get('/ping')

2. Environment variables.

Export your credentials via your environment.

Expand All @@ -80,7 +86,7 @@ Three methods are supported for providing API credentials.
>>> api = BasicClient()
>>> api.get('/ping')

2. `netrc <http://man.cx/netrc%284%29>`_ file (not supported with OAuth).
3. `netrc <http://man.cx/netrc%284%29>`_ file (not supported with OAuth).

You can place the following into ``~/.netrc``:

Expand Down Expand Up @@ -110,13 +116,26 @@ Three methods are supported for providing API credentials.
>>> api = BasicClient(netrcfile='/etc/smartfile.keys')
>>> api.get('/ping')

3. Parameters when instantiating the client.

.. code:: python
OAuth Authentication
--------------------

>>> from smartfile import BasicClient
>>> api = BasicClient('**********', '**********')
>>> api.get('/ping')
Authentication using OAuth authentication is bit more complicated, as it involves tokens and secrets.

.. code:: python

>>> from smartfile import OAuthClient
>>> api = OAuthClient('**********', '**********')
>>> # Be sure to only call each method once for each OAuth login
>>> #
>>> # This is the first step with the client, which should be left alone
>>> api.get_request_token()
>>> # Redirect users to the following URL:
>>> # print "In your browser, go to: " + api.get_authorization_url()
>>> # This example uses raw_input to get the verification from the console:
>>> client_verification = raw_input("What was the verification? :")
>>> api.get_access_token(None, client_verification)
>>> api.get('/ping')

Calling endpoints
-----------------
Expand Down Expand Up @@ -207,3 +226,10 @@ to poll the status of the task.

.. _SmartFile: http://www.smartfile.com/
.. _Read more: http://www.smartfile.com/open-source.html

A `SmartFile`_ Open Source project. `Read more`_ about how SmartFile
uses and contributes to Open Source software.

.. figure:: https://travis-ci.org/smartfile/client-python.png
:alt: Travis CI Status
:target: https://travis-ci.org/smartfile/client-python