From e90fb28b288979de4cf17e487cd97ebdab9a473d Mon Sep 17 00:00:00 2001 From: Travis Cunningham Date: Wed, 13 Mar 2013 23:31:44 -0400 Subject: [PATCH 1/6] updated the README for simplicity until we make some changes to the client --- README.rst | 88 ++++++++++++++---------------------------------------- 1 file changed, 22 insertions(+), 66 deletions(-) diff --git a/README.rst b/README.rst index 762ef52..d4eb7c3 100644 --- a/README.rst +++ b/README.rst @@ -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 @@ -27,27 +23,16 @@ SmartFile API information is available at the Installation ------------ -You can install via ``pip``. - -:: - - $ pip install smartfile - -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 -More information is available at `GitHub `_ -and `PyPI `_. - Usage ----- -Some of the details this library takes care of are. +Some of the details this library takes care of are: * Encoding and decoding of parameters and return values. You deal with Python types only. @@ -59,63 +44,34 @@ Some of the details this library takes care of are. Authentication -------------- -Three methods are supported for providing API credentials. - -1. Environment variables. +1. Basic Authentication - Export your credentials via your environment. - - :: - - $ export SMARTFILE_API_KEY=********** - $ export SMARTFILE_API_PASSWORD=********** - - And then you can use the client without providing any credentials in your - code. +Authentication using basic authentication is as easy as giving it parameters when instantiating the client. +(Environmental variables are not safe for most implementations, as these are exposed to the whole user account) .. code:: python >>> from smartfile import BasicClient - >>> # Credentials are read automatically from environment - >>> api = BasicClient() - >>> api.get('/ping') - -2. `netrc `_ file (not supported with OAuth). - - You can place the following into ``~/.netrc``: - - :: - - machine app.smartfile.com - login ********** - password ********** - - And then you can use the client without providing any credentials in your - code. - - .. code:: python - - >>> from smartfile import BasicClient - >>> # Credentials are read automatically from netrc - >>> api = BasicClient() + >>> api = BasicClient('**********', '**********') >>> api.get('/ping') - You can override the default netrc file location, using the optional - ``netrcfile`` kwarg. +2. OAuth Authentication - .. code:: python - - >>> from smartfile import BasicClient - >>> # Credentials are read automatically from netrc - >>> api = BasicClient(netrcfile='/etc/smartfile.keys') - >>> api.get('/ping') - -3. Parameters when instantiating the client. +Authentication using OAuth authentication is bit more complicated, as it involves tokens and secrets. .. code:: python - >>> from smartfile import BasicClient - >>> api = BasicClient('**********', '**********') + >>> 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 From d6b618708772267f9fd304a402cec9c877731c2e Mon Sep 17 00:00:00 2001 From: Travis Cunningham Date: Thu, 14 Mar 2013 00:09:03 -0400 Subject: [PATCH 2/6] put the basic auth methods back on the readme and cleaned it up --- README.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 71 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index d4eb7c3..ccff520 100644 --- a/README.rst +++ b/README.rst @@ -23,12 +23,23 @@ SmartFile API information is available at the Installation ------------ +You can install via ``pip``. + +:: + + $ pip install smartfile + +Or via source code / GitHub. + :: $ git clone https://github.com/kissync/smartfile-client-python.git smartfile $ cd smartfile $ python setup.py install +More information is available at `GitHub `_ +and `PyPI `_. + Usage ----- @@ -46,8 +57,9 @@ Authentication 1. Basic Authentication -Authentication using basic authentication is as easy as giving it parameters when instantiating the client. -(Environmental variables are not safe for most implementations, as these are exposed to the whole user account) +Three methods are supported for providing API credentials. + +* Parameters when instantiating the client. .. code:: python @@ -55,6 +67,56 @@ Authentication using basic authentication is as easy as giving it parameters whe >>> api = BasicClient('**********', '**********') >>> api.get('/ping') +* Environment variables. + + Export your credentials via your environment. + + :: + + $ export SMARTFILE_API_KEY=********** + $ export SMARTFILE_API_PASSWORD=********** + + And then you can use the client without providing any credentials in your + code. + + .. code:: python + + >>> from smartfile import BasicClient + >>> # Credentials are read automatically from environment + >>> api = BasicClient() + >>> api.get('/ping') + +* `netrc `_ file (not supported with OAuth). + + You can place the following into ``~/.netrc``: + + :: + + machine app.smartfile.com + login ********** + password ********** + + And then you can use the client without providing any credentials in your + code. + + .. code:: python + + >>> from smartfile import BasicClient + >>> # Credentials are read automatically from netrc + >>> api = BasicClient() + >>> api.get('/ping') + + You can override the default netrc file location, using the optional + ``netrcfile`` kwarg. + + .. code:: python + + >>> from smartfile import BasicClient + >>> # Credentials are read automatically from netrc + >>> api = BasicClient(netrcfile='/etc/smartfile.keys') + >>> api.get('/ping') + + 2. OAuth Authentication Authentication using OAuth authentication is bit more complicated, as it involves tokens and secrets. @@ -163,3 +225,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 From 214d7854da37d81f9fe4c5445400a376dbfe4d64 Mon Sep 17 00:00:00 2001 From: Travis Cunningham Date: Thu, 14 Mar 2013 00:13:14 -0400 Subject: [PATCH 3/6] changed the wording under basic authentication for clarity --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index ccff520..dd81358 100644 --- a/README.rst +++ b/README.rst @@ -57,7 +57,7 @@ Authentication 1. Basic Authentication -Three methods are supported for providing API credentials. +Three methods are supported for providing API credentials using basic authentication. * Parameters when instantiating the client. From 2ffb9b3ccf3579d741d752522f932cbd615466fc Mon Sep 17 00:00:00 2001 From: Travis Cunningham Date: Thu, 14 Mar 2013 01:42:36 -0300 Subject: [PATCH 4/6] Update README.rst --- README.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index dd81358..610193b 100644 --- a/README.rst +++ b/README.rst @@ -43,6 +43,8 @@ and `PyPI `_. Usage ----- +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 @@ -52,14 +54,12 @@ 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 --------------- - -1. Basic Authentication +Basic Authentication +-------------------- Three methods are supported for providing API credentials using basic authentication. -* Parameters when instantiating the client. +1. Parameters when instantiating the client. .. code:: python @@ -67,7 +67,7 @@ Three methods are supported for providing API credentials using basic authentica >>> api = BasicClient('**********', '**********') >>> api.get('/ping') -* Environment variables. +2. Environment variables. Export your credentials via your environment. @@ -86,7 +86,7 @@ Three methods are supported for providing API credentials using basic authentica >>> api = BasicClient() >>> api.get('/ping') -* `netrc `_ file (not supported with OAuth). +3. `netrc `_ file (not supported with OAuth). You can place the following into ``~/.netrc``: @@ -117,7 +117,8 @@ Three methods are supported for providing API credentials using basic authentica >>> api.get('/ping') -2. OAuth Authentication +OAuth Authentication +-------------------- Authentication using OAuth authentication is bit more complicated, as it involves tokens and secrets. From 3c6a7826d1def1679ef0db06b0513e18a6abefed Mon Sep 17 00:00:00 2001 From: Travis Cunningham Date: Thu, 14 Mar 2013 01:46:24 -0300 Subject: [PATCH 5/6] Update README.rst --- README.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index 610193b..673f58d 100644 --- a/README.rst +++ b/README.rst @@ -122,20 +122,20 @@ OAuth Authentication Authentication using OAuth authentication is bit more complicated, as it involves tokens and secrets. - .. code:: python +.. 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') + >>> 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 ----------------- From b59eb3b4fa6fc8221e1f8205587f33c01d2e2fd5 Mon Sep 17 00:00:00 2001 From: Travis Cunningham Date: Thu, 14 Mar 2013 01:50:06 -0300 Subject: [PATCH 6/6] Update README.rst --- README.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 673f58d..1338fea 100644 --- a/README.rst +++ b/README.rst @@ -124,18 +124,18 @@ Authentication using OAuth authentication is bit more complicated, as it involve .. 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') + >>> 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 -----------------