Add CLI doc and move order generation

Ryan Rossiter · Ryan Rossiter · commit 08255fe2fb8f · 2017-12-19T16:38:31.000-06:00
verifyOrder and placeOrder need to be called with the same generated
order dict, and the output of verifyOrder can't be sent to placeOrder,
since it strips out some extra data.
diff --git a/SoftLayer/CLI/order/category_list.py b/SoftLayer/CLI/order/category_list.py
@@ -17,7 +17,24 @@
               help="List only the required categories for the package")
 @environment.pass_env
 def cli(env, package_keyname, required):
-    """List package categories."""
+    """List the categories of a package.
+
+    Package keynames can be retrieved from `slcli order package-list`
+
+    \b
+    Example:
+        # List the categories of Bare Metal servers
+        slcli order category-list BARE_METAL_SERVER
+
+    When using the --required flag, it will list out only the categories
+    that are required for ordering that package (see `slcli order item-list`)
+
+    \b
+    Example:
+        # List the required categories for Bare Metal servers
+        slcli order category-list BARE_METAL_SERVER --required
+
+    """
     client = env.client
     manager = ordering.OrderingManager(client)
     table = formatting.Table(COLUMNS)
diff --git a/SoftLayer/CLI/order/item_list.py b/SoftLayer/CLI/order/item_list.py
@@ -19,7 +19,28 @@
               help="Category code to filter items by")
 @environment.pass_env
 def cli(env, package_keyname, keyword, category):
-    """List package items."""
+    """List package items used for ordering.
+
+    The items listed can be used with `slcli order place` to specify
+    the items that are being ordered in the package.
+
+    Package keynames can be retrieved using `slcli order package-list`
+
+    \b
+    Example:
+        # List all items in the VSI package
+        slcli order item-list CLOUD_SERVER
+
+    The --keyword option is used to filter items by name.
+    The --category option is used to filter items by category.
+    Both --keyword and --category can be used together.
+
+    \b
+    Example:
+        # List Ubuntu OSes from the os category of the Bare Metal package
+        slcli order item-list BARE_METAL_SERVER --category os --keyword ubuntu
+
+    """
     table = formatting.Table(COLUMNS)
     manager = ordering.OrderingManager(env.client)
 
diff --git a/SoftLayer/CLI/order/package_list.py b/SoftLayer/CLI/order/package_list.py
@@ -1,4 +1,4 @@
-"""List package presets."""
+"""List packages."""
 # :license: MIT, see LICENSE for more details.
 
 import click
@@ -16,7 +16,23 @@
               help="A word (or string) used to filter package names.")
 @environment.pass_env
 def cli(env, keyword):
-    """List package presets."""
+    """List packages that can be ordered via the placeOrder API.
+
+    \b
+    Example:
+        # List out all packages for ordering
+        slcli order package-list
+
+
+    Keywords can also be used for some simple filtering functionality
+    to help find a package easier.
+
+    \b
+    Example:
+        # List out all packages with "server" in the name
+        slcli order package-list --keyword server
+
+    """
     manager = ordering.OrderingManager(env.client)
     table = formatting.Table(COLUMNS)
 
diff --git a/SoftLayer/CLI/order/place.py b/SoftLayer/CLI/order/place.py
@@ -28,12 +28,51 @@
               default='hourly',
               show_default=True,
               help="Billing rate")
+@click.option('--complex-type', help=("The complex type of the order. This typically begins"
+                                      " with 'SoftLayer_Container_Product_Order_'."))
 @click.option('--extras',
               help="JSON string denoting extra data that needs to be sent with the order")
 @click.argument('order_items', nargs=-1)
 @environment.pass_env
-def cli(env, package_keyname, location, preset, verify, billing, extras, order_items):
-    """Place or verify an order."""
+def cli(env, package_keyname, location, preset, verify, billing, complex_type,
+        extras, order_items):
+    """Place or verify an order.
+
+    This CLI command is used for placing/verifying an order of the specified package in
+    the given location (denoted by a datacenter's long name). Orders made via the CLI
+    can then be converted to be made programmatically by calling
+    SoftLayer.OrderingManager.place_order() with the same keynames.
+
+    Packages for ordering can be retrived from `slcli order package-list`
+    Presets for ordering can be retrieved from `slcli order preset-list` (not all packages
+    have presets)
+
+    Items can be retrieved from `slcli order item-list`. In order to find required
+    items for the order, use `slcli order category-list`, and then provide the
+    --category option for each category code in `slcli order item-list`.
+
+    \b
+    Example:
+        # Order an hourly VSI with 4 CPU, 16 GB RAM, 100 GB SAN disk,
+        # Ubuntu 16.04, and 1 Gbps public & private uplink in dal13
+        slcli order place --billing hourly CLOUD_SERVER DALLAS13 \\
+            GUEST_CORES_4 \\
+            RAM_16_GB \\
+            REBOOT_REMOTE_CONSOLE \\
+            1_GBPS_PUBLIC_PRIVATE_NETWORK_UPLINKS \\
+            BANDWIDTH_0_GB_2 \\
+            1_IP_ADDRESS \\
+            GUEST_DISK_100_GB_SAN \\
+            OS_UBUNTU_16_04_LTS_XENIAL_XERUS_MINIMAL_64_BIT_FOR_VSI \\
+            MONITORING_HOST_PING \\
+            NOTIFICATION_EMAIL_AND_TICKET \\
+            AUTOMATED_NOTIFICATION \\
+            UNLIMITED_SSL_VPN_USERS_1_PPTP_VPN_USER_PER_ACCOUNT \\
+            NESSUS_VULNERABILITY_ASSESSMENT_REPORTING \\
+            --extras '{"virtualGuests": [{"hostname": "test", "domain": "softlayer.com"}]}' \\
+            --complex-type SoftLayer_Container_Product_Order_Virtual_Guest
+
+    """
     manager = ordering.OrderingManager(env.client)
 
     if extras:
@@ -43,6 +82,7 @@ def cli(env, package_keyname, location, preset, verify, billing, extras, order_i
     kwargs = {'preset_keyname': preset,
               'extras': extras,
               'quantity': 1,
+              'complex_type': complex_type,
               'hourly': True if billing == 'hourly' else False}
 
     if verify:
diff --git a/SoftLayer/CLI/order/preset_list.py b/SoftLayer/CLI/order/preset_list.py
@@ -18,13 +18,31 @@
               help="A word (or string) used to filter preset names.")
 @environment.pass_env
 def cli(env, package_keyname, keyword):
-    """List package presets."""
+    """List package presets.
+
+    Package keynames can be retrieved from `slcli order package-list`.
+    Some packages do not have presets.
+
+    \b
+    Example:
+        # List the presets for Bare Metal servers
+        slcli order preset-list BARE_METAL_SERVER
+
+    The --keyword option can also be used for additional filtering on
+    the returned presets.
+
+    \b
+    Example:
+        # List the Bare Metal server presets that include a GPU
+        slcli order preset-list BARE_METAL_SERVER --keyword gpu
+
+    """
     table = formatting.Table(COLUMNS)
     manager = ordering.OrderingManager(env.client)
 
     _filter = {}
     if keyword:
-        _filter = {'presets': {'name': {'operation': '*= %s' % keyword}}}
+        _filter = {'activePresets': {'name': {'operation': '*= %s' % keyword}}}
     presets = manager.list_presets(package_keyname, filter=_filter)
 
     for preset in presets:
diff --git a/SoftLayer/managers/ordering.py b/SoftLayer/managers/ordering.py
@@ -5,6 +5,7 @@
 
     :license: MIT, see LICENSE for more details.
 """
+# pylint: disable=no-self-use
 
 from SoftLayer import exceptions
 
@@ -380,7 +381,7 @@ def get_price_id_list(self, package_keyname, item_keynames):
 
         return prices
 
-    def verify_order(self, package_keyname, location, item_keynames,
+    def verify_order(self, package_keyname, location, item_keynames, complex_type=None,
                      hourly=True, preset_keyname=None, extras=None, quantity=1):
         """Verifies an order with the given package and prices.
 
@@ -392,6 +393,8 @@ def verify_order(self, package_keyname, location, item_keynames,
         :param list item_keynames: The list of item keyname strings to order. To see list of
                                    possible keynames for a package, use list_items()
                                    (or `slcli order item-list`)
+        :param str complex_type: The complex type to send with the order. Typically begins
+                                 with 'SoftLayer_Container_Product_Order_'.
         :param bool hourly: If true, uses hourly billing, otherwise uses monthly billing
         :param string preset_keyname: If needed, specifies a preset to use for that package.
                                       To see a list of possible keynames for a package, use
@@ -404,33 +407,13 @@ def verify_order(self, package_keyname, location, item_keynames,
         :param int quantity: The number of resources to order
 
         """
-        order = {}
-        extras = extras or {}
-
-        package = self.get_package_by_key(package_keyname, mask='id')
-        if not package:
-            raise exceptions.SoftLayerError("Package {} does not exist".format(package_keyname))
-
-        # if there was extra data given for the order, add it to the order
-        # example: VSIs require hostname and domain set on the order, so
-        # extras will be {'virtualGuests': [{'hostname': 'test',
-        #                                    'domain': 'softlayer.com'}]}
-        order.update(extras)
-        order['packageId'] = package['id']
-        order['location'] = location
-        order['quantity'] = quantity
-        order['useHourlyPricing'] = hourly
-
-        if preset_keyname:
-            preset_id = self.get_preset_by_key(package_keyname, preset_keyname)['id']
-            order['presetId'] = preset_id
-
-        price_ids = self.get_price_id_list(package_keyname, item_keynames)
-        order['prices'] = [{'id': price_id} for price_id in price_ids]
-
+        order = self.generate_order(package_keyname, location, item_keynames,
+                                    complex_type=complex_type, hourly=hourly,
+                                    preset_keyname=preset_keyname,
+                                    extras=extras, quantity=quantity)
         return self.order_svc.verifyOrder(order)
 
-    def place_order(self, package_keyname, location, item_keynames,
+    def place_order(self, package_keyname, location, item_keynames, complex_type=None,
                     hourly=True, preset_keyname=None, extras=None, quantity=1):
         """Places an order with the given package and prices.
 
@@ -441,6 +424,40 @@ def place_order(self, package_keyname, location, item_keynames,
         :param list item_keynames: The list of item keyname strings to order. To see list of
                                    possible keynames for a package, use list_items()
                                    (or `slcli order item-list`)
+        :param str complex_type: The complex type to send with the order. Typically begins
+                                 with 'SoftLayer_Container_Product_Order_'.
+        :param bool hourly: If true, uses hourly billing, otherwise uses monthly billing
+        :param string preset_keyname: If needed, specifies a preset to use for that package.
+                                      To see a list of possible keynames for a package, use
+                                      list_preset() (or `slcli order preset-list`)
+        :param dict extras: The extra data for the order in dictionary format.
+                            Example: A VSI order requires hostname and domain to be set, so
+                            extras will look like the following:
+                                {'virtualGuests': [{'hostname': 'test',
+                                                    'domain': 'softlayer.com'}]}
+        :param int quantity: The number of resources to order
+
+        """
+        order = self.generate_order(package_keyname, location, item_keynames,
+                                    complex_type=complex_type, hourly=hourly,
+                                    preset_keyname=preset_keyname,
+                                    extras=extras, quantity=quantity)
+        return self.order_svc.placeOrder(order)
+
+    def generate_order(self, package_keyname, location, item_keynames, complex_type=None,
+                       hourly=True, preset_keyname=None, extras=None, quantity=1):
+        """Generates an order with the given package and prices.
+
+        This function takes in parameters needed for an order and generates an order
+        dictionary. This dictionary can then be used in either verify or placeOrder().
+
+        :param str package_keyname: The keyname for the package being ordered
+        :param str location: The datacenter location string for ordering (Ex: DALLAS13)
+        :param list item_keynames: The list of item keyname strings to order. To see list of
+                                   possible keynames for a package, use list_items()
+                                   (or `slcli order item-list`)
+        :param str complex_type: The complex type to send with the order. Typically begins
+                                 with 'SoftLayer_Container_Product_Order_'.
         :param bool hourly: If true, uses hourly billing, otherwise uses monthly billing
         :param string preset_keyname: If needed, specifies a preset to use for that package.
                                       To see a list of possible keynames for a package, use
@@ -453,10 +470,31 @@ def place_order(self, package_keyname, location, item_keynames,
         :param int quantity: The number of resources to order
 
         """
-        # verify the order, and if the order is valid, the proper prices will be filled
-        # into the order template, so we can just send that to placeOrder to order it
-        verified_order = self.verify_order(package_keyname, location, item_keynames,
-                                           hourly=hourly,
-                                           preset_keyname=preset_keyname,
-                                           extras=extras, quantity=quantity)
-        return self.order_svc.placeOrder(verified_order)
+        order = {}
+        extras = extras or {}
+
+        package = self.get_package_by_key(package_keyname, mask='id')
+        if not package:
+            raise exceptions.SoftLayerError("Package {} does not exist".format(package_keyname))
+
+        # if there was extra data given for the order, add it to the order
+        # example: VSIs require hostname and domain set on the order, so
+        # extras will be {'virtualGuests': [{'hostname': 'test',
+        #                                    'domain': 'softlayer.com'}]}
+        order.update(extras)
+        order['packageId'] = package['id']
+        order['location'] = location
+        order['quantity'] = quantity
+        order['useHourlyPricing'] = hourly
+
+        if preset_keyname:
+            preset_id = self.get_preset_by_key(package_keyname, preset_keyname)['id']
+            order['presetId'] = preset_id
+
+        if not complex_type:
+            raise exceptions.SoftLayerError("A complex type must be specified with the order")
+        order['complexType'] = complex_type
+
+        price_ids = self.get_price_id_list(package_keyname, item_keynames)
+        order['prices'] = [{'id': price_id} for price_id in price_ids]
+        return order
diff --git a/tests/CLI/modules/order_tests.py b/tests/CLI/modules/order_tests.py
@@ -75,10 +75,10 @@ def test_place(self):
         place_mock.return_value = order
         items_mock.return_value = self._get_order_items()
 
-        result = self.run_command(['-y', 'order', 'place', 'package', 'DALLAS13', 'ITEM1'])
+        result = self.run_command(['-y', 'order', 'place', 'package', 'DALLAS13', 'ITEM1',
+                                   '--complex-type', 'SoftLayer_Container_Product_Order_Thing'])
 
         self.assert_no_fail(result)
-        self.assert_called_with('SoftLayer_Product_Order', 'verifyOrder')
         self.assert_called_with('SoftLayer_Product_Order', 'placeOrder')
         self.assertEqual({'id': 1234,
                           'created': order_date,
@@ -97,6 +97,7 @@ def test_verify_hourly(self):
         items_mock.return_value = self._get_order_items()
 
         result = self.run_command(['order', 'place', '--billing', 'hourly', '--verify',
+                                   '--complex-type', 'SoftLayer_Container_Product_Order_Thing',
                                    'package', 'DALLAS13', 'ITEM1', 'ITEM2'])
 
         self.assert_no_fail(result)
@@ -123,6 +124,7 @@ def test_verify_monthly(self):
         items_mock.return_value = self._get_order_items()
 
         result = self.run_command(['order', 'place', '--billing', 'monthly', '--verify',
+                                   '--complex-type', 'SoftLayer_Container_Product_Order_Thing',
                                    'package', 'DALLAS13', 'ITEM1', 'ITEM2'])
 
         self.assert_no_fail(result)
diff --git a/tests/managers/ordering_tests.py b/tests/managers/ordering_tests.py
