Merge pull request awslabs#29 from JordonPhillips/doc-update

Update README and add user agent suffix

.pylintrc

@@ -59,7 +59,7 @@ confidence=
 # --enable=similarities". If you want to run only the classes checker, but have
 # no Warning level messages displayed, use"--disable=all --enable=classes
 # --disable=W"
-disable=R0201,W0613,I0021,I0020,C0111,W1618,W1619,R0902,R0903,W0231,W0611,R0913,W0703,C0330,R0204,I0011,R0904
+disable=R0201,W0613,I0021,I0020,C0111,W1618,W1619,R0902,R0903,W0231,W0611,R0913,W0703,C0330,R0204,I0011,R0904,R0205
 
 
 [REPORTS]

README.rst

@@ -8,6 +8,9 @@ AWS Process Credential Providers
 A collection of process-based credential providers to be used with the AWS CLI
 and related tools.
 
+This is an experimental package, breaking changes may occur on any minor
+version bump.
+
 
 Installation
 ------------
@@ -68,3 +71,33 @@ Example adfs configuration::
     credential_process = awsprocesscreds-saml -e 'https://corp.example.com/adfs/ls/IdpInitiatedSignOn.aspx?loginToRp=urn:amazon:webservices' -u Monty -p adfs -a arn:aws:iam::123456789012:role/ADFS-Dev
 
 .. _AWS CLI Config docs: http://docs.aws.amazon.com/cli/latest/topic/config-vars.html#cli-aws-help-config-vars
+
+
+Custom Providers
+----------------
+
+The mechanism this package uses to provide credentials is generally available,
+and not specific to this package. It can be used to implement any custom
+credential provider that will work with the AWS CLI, boto3, and other SDKs as
+they implement support.
+
+A detailed breakdown of this mechanism along with a live demo of implementing a
+credential provider that hooks into the macOS keychain can be seen on this
+recorded talk from re:Invent 2017:
+`AWS CLI: 2107 and Beyond <https://youtu.be/W8IyScUGuGI?t=1260>`_
+
+The CLI will call the process provided as the value for ``credential_process``.
+This process must return credentials on stdout in the following JSON form::
+
+   {
+      "Version": 1,
+      "AccessKeyId": "string",
+      "SecretAccessKey": "string",
+      "SessionToken": "string",
+      "Expiration": "2019-01-31T21:45:41+00:00"
+   }
+
+Where ``Expiration`` is an RFC 3339 compatible timestamp. As the expiration
+time nears, the process will be called again to get a new set of credentials.
+The ``Version`` denotes the version of this format, whose only current valid
+value is ``1``. The remaining keys are the AWS credentials you wish to use.

awsprocesscreds/__init__.py

@@ -1,5 +1,7 @@
 import logging
 
+__version__ = '0.0.2'
+
 
 class NullHandler(logging.Handler):
     def emit(self, record):

awsprocesscreds/saml.py

@@ -1,3 +1,4 @@
+# pylint: disable=R1710
 import base64
 import getpass
 import logging
@@ -15,6 +16,7 @@
 from botocore.credentials import CachedCredentialFetcher
 import botocore.session
 
+import awsprocesscreds
 from .compat import escape
 
 
@@ -370,7 +372,12 @@ def _get_credentials(self):
 
     def _create_client(self):
         return self._client_creator(
-            'sts', config=Config(signature_version=botocore.UNSIGNED)
+            'sts', config=Config(
+                signature_version=botocore.UNSIGNED,
+                user_agent_extra=(
+                    'awsprocesscreds-saml/%s' % awsprocesscreds.__version__
+                )
+            )
         )
 
     def _get_role_and_principal_arn(self, assertion):

requirements-dev.txt

@@ -5,7 +5,11 @@ pytest-catchlog==1.2.2
 coverage==4.3.4
 flake8==3.5.0
 mock==2.0.0
-# Pylint will fail on py3.  Locking to a commit on master
-# until pylint2 is released.
--e git://github.com/PyCQA/pylint.git@7cb3ffddfd96f5e099ca697f6b1e30e727544627#egg=pylint
-pydocstyle==2.1.1
+# The latest version of pylint only works on python3.
+pylint==2.2.2 ; python_version >= '3.6'
+astroid==2.1.0 ; python_version >= '3.6'
+# For python2, there are a few bugs in the latest versions of 1.x,
+# so we're locking to a specific version that we know works.
+pylint==1.9.3 ; python_version <= '2.7'
+astroid==1.6.5 ; python_version <= '2.7'
+pydocstyle==2.1.1

setup.py

@@ -1,8 +1,24 @@
 #!/usr/bin/env python
+import codecs
+import os.path
+import re
 from setuptools import setup, find_packages
 
-with open('README.rst') as readme_file:
-    README = readme_file.read()
+HERE = os.path.abspath(os.path.dirname(__file__))
+
+
+def read(*parts):
+    return codecs.open(os.path.join(HERE, *parts), 'r').read()
+
+
+def find_version(*file_paths):
+    version_file = read(*file_paths)
+    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]",
+                              version_file, re.M)
+    if version_match:
+        return version_match.group(1)
+    raise RuntimeError("Unable to find version string.")
+
 
 
 install_requires = [
@@ -13,9 +29,9 @@
 
 setup(
     name='awsprocesscreds',
-    version='0.0.1',
+    version=find_version('awsprocesscreds', '__init__.py'),
     description='AWS Process Credential Providers.',
-    long_description=README,
+    long_description=read('README.rst'),
     author='Amazon Web Services',
     url='https://github.com/awslabs/awsprocesscreds',
     packages=find_packages(exclude=['tests']),