Merge pull request #22 from adobe-apiplatform/v2

Release 2.0rc1

Author: adobeDan

.gitignore

@@ -1,5 +1,6 @@
 # platform artifacts
 .*
+!.travis.yml
 
 # build and scratch areas
 local/

.travis.yml

@@ -0,0 +1,10 @@
+language: python
+python:
+  - 2.7
+  - 3.4
+  - 3.5
+install:
+  - pip install --upgrade pip setuptools wheel
+  - pip install -r requirements.txt
+script:
+  - python setup.py test

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 Adobe Systems Incorporated.  All rights reserved.
+Copyright (c) 2016-2017 Adobe Systems Incorporated.  All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -8,7 +8,7 @@ which provides Adobe Enterprise customers the ability to manage their users.  Th
 client makes it easy to access the UMAPI from a local Python application.
 
 This client is open source, maintained by Adobe, and distributed under the terms
-of the OSI-approved MIT license.  Copyright (c) 2016 Adobe Systems Incorporated.
+of the OSI-approved MIT license.  Copyright (c) 2016-2017 Adobe Systems Incorporated.
 
 # Installation
 

docs/index.md

@@ -8,7 +8,7 @@ which provides Adobe Enterprise customers the ability to manage their users.  Th
 client makes it easy to access the UMAPI from a local Python application.
 
 This client is open source, maintained by Adobe, and distributed under the terms
-of the OSI-approved MIT license.  Copyright (c) 2016 Adobe Systems Incorporated.
+of the OSI-approved MIT license.  Copyright (c) 2016-2017 Adobe Systems Incorporated.
 
 # Installation
 

docs/usage-instructions-v2.md

@@ -93,8 +93,14 @@ a Python dictionary of its attributes.
 
 ## Get a List of Users
 
+The following code enumerates the first 5 users, printing the email of each.
+This will only have fetched the first page of results.  Then, after the loop,
+the `all_results` call will force the fetch of all remaining pages so the
+list of all results can be constructed.  ()Once the `all_results` call has been made,
+you cannot enumerate again without first calling `reload`.)
+
 ```python
-users = QueryUsers(conn)
+users = umapi_client.QueryUsers(conn)
 # print first 5 users
 for i, user in enumerate(users):
     if i == 5: break
@@ -109,7 +115,7 @@ This list of groups will contain both user groups and product license
 configuration groups.
 
 ```python
-groups = QueryGroups(conn)
+groups = umapi_client.QueryGroups(conn)
 # print all the group details
 for group in groups:
     print(group)
@@ -122,5 +128,160 @@ for group in groups:
 
 # Performing Operations on Users
 
-_...under construction..._
+User operations in the UMAPI are performed in three steps:
+
+1. You specify the user to be operated on.
+2. You specify the operations to be performed on the user.
+3. You submit the user and operations to the UMAPI server.
+
+The combined specification of the user identity and the operations to be performed
+is called an _action_ in the UMAPI documentation, while the individual operations are called
+_commands_.  If you read the documentation carefully, you will see that there
+are limits to how many actions can be submitted to the UMAPI
+service in a single call, how many commands there can be in a single action, and
+how many calls can be submitted in a given period of time.  However,
+the `umapi_client` implementation has been design to insulate
+your application from these limits
+by  
+packing as many commands as allowed into each action,
+batching up as many actions as possible into a call, 
+and spacing calls out when required to by the server.  Thus, from an
+application perspective, you can simply follow the three steps above for each
+user and not worry about the mechanics of server communication limits.
+
+## Step 1: Specify the User
+
+To operate on a user, you first create a `UserAction` object that
+specifies the user's identity type, domain, and unique ID in the domain.
+
+In most cases,
+the user's email ID will be his unique ID and will itself contain his domain,
+as in these examples:
+
+```python
+from umapi_client import IdentityTypes
+user1 = UserAction(id_type=IdentityTypes.adobeID, email="[email protected]")
+user2 = UserAction(id_type=IdentityTypes.enterpriseID, email="[email protected]")
+```
+
+But when Federated ID is being used, and a non-email username is being
+used to identify users across the SAML connection, both the username
+and the domain must be specified separately, as in these examples:
+
+```python
+user3 = UserAction(id_type=IdentityTypes.federatedID,
+                   username="user347", domain="division.conglomerate.com")
+user4 = UserAction(id_type=IdentityTypes.federatedID,
+                   username="user348", domain="division.conglomerate.com",
+                   email="[email protected]")
+```
+
+Note that, as in the last example, it's OK to specify the email when
+creating a user object even if the email is not the unique ID or
+doesn't use the same domain.  If
+you later perform an operations on a user which requires the email
+(such as user creation on the Adobe side), the email will be remembered
+and supplied from the UserAction object.
+
+## Step 2: Specify the Operations
+
+Once you have a `UserAction` object for a user, you can specify
+operations (called _commands_) to perform on that user.  For
+example, to create a new user on the Adobe side, for the users
+that were specified in the last section, we could do:
+
+```python
+user1.create()
+user2.create(first_name="Geoffrey", last_name="Giraffe")
+user3.create(email="[email protected]", country="US")
+user4.create(first_name="John", last_name="User", country="US")
+```
+
+When creating users, the email address is mandatory if not already specified
+when creating the user action.  First and last name and country can be optionally
+specified ()except for Adobe ID users),
+and country _must_ be specified for Federated ID users.
+
+If a user has already been created, but you want to update attributes,
+you can use the `update` rather than the `create` command:
+
+```python
+user2.update(first_name="Jeff", country="AU")
+user4.update(username="user0347")
+```
+
+You can also specify to create if necessary, but update if already created:
+
+```python
+from umapi_client import IfAlreadyExistsOptions
+user4.create(first_name="John", last_name="User", country="US",
+             on_conflict=IfAlreadyExistsOptions.updateIfAlreadyExists)
+```
+
+There are many other operations you can perform, such as adding and removing
+users from user groups and product configuration groups.  Because each
+operation specifier returns the user, it's easy to chain the together:
+
+```python
+user2.add_group(groups=["Photoshop", "Illustrator"]).remove_group(groups=["CC All Apps"])
+```
+
+The details of all the possible commands are specified in the code,
+and more user documentation will be forthcoming.  In general, commands
+are performed in the order they are specified, except for certain special
+commands such as ```create``` which are always performed first regardless
+of when they were specified.
+
+## Step 3: Submit to the UMAPI server
+
+Once you have specified all the desired operations on a given `UserAction`,
+you can submit it to the server as follows (recall that `conn` is an authorized
+connection to the UMAPI server, as created above):
+
+```python
+result = conn.execute_single(user1)
+result = conn.execute_multiple([user2, user3, user4])
+```
+
+By default, `execute_single` queues the action for sending to the server
+when a "full batch" (of 10) actions has been accumulated, but
+`execute_multiple` forces a batch to be sent (including any
+previously queued actions as well as the specified ones).  You can
+override these defaults with the `immediate` argument, as in:
+
+```python
+result = conn.execute_single(user1, immediate=True)
+result = conn.execute_multiple([user2, user3, user4], immediate=False)
+```
+
+The result of either execute operation is a tuple of three numbers
+`(queued, sent, succeeded)` which tell you how many actions were
+queued, how many were sent, and how many of those sent succeeded
+without errors.  So, for example, in the following code:
+
+```python
+queued, _, _ = conn.execute_single(user1)
+_, sent, succeeded = conn.execute_multiple(user2, user3, user4)
+```
+
+we would likely see `queued = 1`, `sent = 4`, and `succeeded = 4`.
+
+If, for some reason, the succeeded number is not equal to the sent
+number for any call, it means that not all of the actions were
+executed successfully on the server-side: one or more of the commands
+failed to execute.  In such cases, the server will have sent back
+error information which the `umapi_client` implementation records
+against the commands that failed, you can call the `execution_errors`
+method on the user actions to get a list of the failed commands
+and the server error information.  For example, if only three
+of the four actions sent had succeeded, then we could execute
+this code:
+
+```python
+actions = (user1, user2, user3, user4)
+errors = [info for action in actions for info in action.execution_errors()]
+```
 
+Each entry in errors would then be a dictionary giving
+the command that failed, the target user it failed on,
+and server information about the reason for the failure.

requirements.txt

@@ -0,0 +1,12 @@
+# running
+requests>=2.4.2
+cryptography
+PyJWT
+six
+enum34
+# testing
+pytest>=3.0.5
+mock
+PyYAML
+# setup.py testing
+pytest-runner

setup.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2016 Adobe Systems Incorporated.  All rights reserved.
+# Copyright (c) 2016-2017 Adobe Systems Incorporated.  All rights reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -21,13 +21,13 @@
 from setuptools import setup, find_packages
 
 setup(name='umapi-client',
-      version='2.0b2',
+      version='2.0b3',
       description='Client for the User Management API (UMAPI) from Adobe - see https://adobe.ly/2h1pHgV',
       long_description=('The User Management API (aka the UMAPI) is an Adobe-hosted network service '
                         'which provides Adobe Enterprise customers the ability to manage their users.  This '
                         'client makes it easy to access the UMAPI from a local Python application.  '
                         'This client is open source, maintained by Adobe, and distributed under the terms '
-                        'of the OSI-approved MIT license.  Copyright (c) 2016 Adobe Systems Incorporated.'),
+                        'of the OSI-approved MIT license.  Copyright (c) 2016-2017 Adobe Systems Incorporated.'),
       classifiers=[
           'Development Status :: 5 - Production/Stable',
           'Programming Language :: Python :: 2.7',

tests/conftest.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2016 Adobe Systems Incorporated.  All rights reserved.
+# Copyright (c) 2016-2017 Adobe Systems Incorporated.  All rights reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

tests/test_actions.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2016 Adobe Systems Incorporated.  All rights reserved.
+# Copyright (c) 2016-2017 Adobe Systems Incorporated.  All rights reserved.
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -87,6 +87,7 @@ def test_execute_single_error_queued_throttled():
         action = Action(top="top").append(a="a").append(b="b").append(c="c").append(d="d")
         assert conn.execute_single(action) == (0, 4, 3)
         assert action.execution_errors() == [{"command": {"d": "d"},
+                                              "target": {"top": "top"},
                                               "errorCode": "test.error",
                                               "message": "Test error message"}]
 
@@ -100,7 +101,7 @@ def test_execute_single_error_immediate_throttled():
         conn = Connection(throttle_commands=2, **mock_connection_params)
         action = Action(top="top0").append(a="a0").append(a="a1").append(a="a2")
         assert conn.execute_single(action, immediate=True) == (0, 2, 1)
-        assert action.execution_errors() == [{"command": {"a": "a2"}, "errorCode": "test"}]
+        assert action.execution_errors() == [{"command": {"a": "a2"}, "target": {"top": "top0"}, "errorCode": "test"}]
 
 
 def test_execute_single_dofirst_success_immediate():
@@ -121,6 +122,7 @@ def test_execute_single_error_immediate():
         action = Action(top="top").append(a="a")
         assert conn.execute_single(action, immediate=True) == (0, 1, 0)
         assert action.execution_errors() == [{"command": {"a": "a"},
+                                              "target": {"top": "top"},
                                               "errorCode": "test.error",
                                               "message": "Test error message"}]
 
@@ -138,9 +140,11 @@ def test_execute_single_multi_error_immediate():
         action = Action(top="top").append(a="a")
         assert conn.execute_single(action, immediate=True) == (0, 1, 0)
         assert action.execution_errors() == [{"command": {"a": "a"},
+                                              "target": {"top": "top"},
                                               "errorCode": "error1",
                                               "message": "message1"},
                                              {"command": {"a": "a"},
+                                              "target": {"top": "top"},
                                               "errorCode": "error2",
                                               "message": "message2"}]
 
@@ -155,6 +159,7 @@ def test_execute_single_dofirst_error_immediate():
         action = Action(top="top").insert(a="a")
         assert conn.execute_single(action, immediate=True) == (0, 1, 0)
         assert action.execution_errors() == [{"command": {"a": "a"},
+                                              "target": {"top": "top"},
                                               "errorCode": "test.error",
                                               "message": "Test error message"}]
 
@@ -201,6 +206,7 @@ def test_execute_multiple_error():
         assert conn.execute_multiple([action0, action1]) == (0, 2, 1)
         assert action0.execution_errors() == []
         assert action1.execution_errors() == [{"command": {"b": "b"},
+                                               "target": {"top": "top1"},
                                                "errorCode": "test.error",
                                                "message": "Test error message"}]
 
@@ -222,9 +228,11 @@ def test_execute_multiple_multi_error():
         assert conn.execute_multiple([action0, action1]) == (0, 2, 1)
         assert action0.execution_errors() == []
         assert action1.execution_errors() == [{"command": {"b": "b"},
+                                               "target": {"top": "top1"},
                                                "errorCode": "error1",
                                                "message": "message1"},
                                               {"command": {"b": "b"},
+                                               "target": {"top": "top1"},
                                                "errorCode": "error2",
                                                "message": "message2"}]
 
@@ -243,6 +251,7 @@ def test_execute_multiple_dofirst_error():
         assert conn.execute_multiple([action0, action1]) == (0, 2, 1)
         assert action0.execution_errors() == []
         assert action1.execution_errors() == [{"command": {"a": "a1"},
+                                               "target": {"top": "top1"},
                                                "errorCode": "test.error",
                                                "message": "Test error message"}]
 
@@ -277,7 +286,7 @@ def test_execute_multiple_single_queued_throttle_actions():
                                 "actions-queued": 0}
         assert action0.execution_errors() == []
         assert action1.execution_errors() == []
-        assert action2.execution_errors() == [{"command": {"a": "a2"}, "errorCode": "test"}]
+        assert action2.execution_errors() == [{"command": {"a": "a2"}, "target": {"top": "top2"}, "errorCode": "test"}]
         assert action3.execution_errors() == []