Add docs for user actions. Improve error summaries. Go to b3.

The user action docs made it clear that we need to show the user as well as the command when summarize an error we got back from the server.  So now we do.

Author: brotskydotcom

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.

setup.py

@@ -21,7 +21,7 @@
 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 '

tests/test_actions.py

@@ -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() == []
 
 

umapi_client/api.py

@@ -111,6 +111,7 @@ def report_command_error(self, error_dict):
         """
         error = dict(error_dict)
         error["command"] = self.commands[error_dict["step"]]
+        error["target"] = self.frame
         del error["index"]  # throttling can change which action this was in the batch
         del error["step"]   # throttling can change which step this was in the action
         self.errors.append(error)