Make all Input related calls that take both name and kind have name first.

The only breaking change is Inputs.create, which has been noted in the change log.
Removed a couple of UNDONE comments.

Author: Frederick Ross

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 1.0
 
+* The argument order of Inputs.create has been swapped to have name first. This is consistent with
+  all other collections and all other operations on Inputs.
 * All the .contains methods on collections have been removed. Use Python's `in` operator instead.
 * Confs has been renamed to Configurations, and ConfFile to ConfigurationFile.
 * Stanza.submit now takes a dictionary of key/value pairs specifying the stanza instead of a raw string.

splunklib/client.py

@@ -1945,7 +1945,6 @@ def update(self, **kwargs):
 # Inputs is a "kinded" collection, which is a heterogenous collection where
 # each item is tagged with a kind, that provides a single merged view of all
 # input kinds.
-# UNDONE: contains needs to take a kind arg to disambiguate
 class Inputs(Collection):
     """This class represents a collection of inputs. The collection is
     heterogeneous and each member of the collection contains a *kind* property
@@ -1958,7 +1957,7 @@ def __init__(self, service, kindmap=None):
     def __getitem__(self, key):
         if isinstance(key, tuple) and len(key) == 2:
             # Fetch a single kind
-            kind, key = key
+            key, kind = key
             try:
                 response = self.get(self.kindpath(kind) + "/" + key)
                 entries = self._load_list(response)
@@ -2026,10 +2025,12 @@ def __contains__(self, key):
                         raise
             return False
 
-    def create(self, kind, name, **kwargs):
+    def create(self, name, kind, **kwargs):
         """Creates an input of a specific kind in this collection, with any
         arguments you specify.
 
+        :param `name`: The input name.
+        :type name: ``string``
         :param `kind`: The kind of input:
 
             - "ad": Active Directory
@@ -2053,8 +2054,6 @@ def create(self, kind, name, **kwargs):
             - "win-wmi-collections": WMI
 
         :type kind: ``string``
-        :param `name`: The input name.
-        :type name: ``string``
         :param `kwargs`: Additional arguments (optional). For more about the
             available parameters, see `Input parameters <http://dev.splunk.com/view/SP-CAAAEE6#inputparams>`_ on Splunk Developer Portal.
 
@@ -2075,7 +2074,7 @@ def create(self, kind, name, **kwargs):
         )
         return Input(self.service, path, kind)
 
-    def delete(self, kind, name=None):
+    def delete(self, name, kind=None):
         """Removes an input from the collection.
 
         :param `kind`: The kind of input:
@@ -2106,11 +2105,10 @@ def delete(self, kind, name=None):
 
         :return: The :class:`Inputs` collection.
         """
-        if name is None:
-            name = kind
+        if kind is None:
             self.service.delete(self[name].path)
         else:
-            self.service.delete(self[kind, name].path)
+            self.service.delete(self[name, kind].path)
         return self
 
     def itemmeta(self, kind):
@@ -2308,8 +2306,6 @@ def list(self, *kinds, **kwargs):
                 else:
                     raise
 
-            # UNDONE: Should use _load_list for the following, but need to
-            # pass kind to the `item` method.
             entries = _load_atom_entries(response)
             if entries is None: continue # No inputs to process
             for entry in entries:

tests/test_input.py

@@ -44,29 +44,29 @@ def create_tcp_input(self, base_port, kind, **options):
         port = base_port
         while True: # Find the next unbound port
             try:
-                input = self.service.inputs.create(kind, str(port), **options)
+                input = self.service.inputs.create(str(port), kind, **options)
                 return input
             except client.HTTPError as he:
                 if he.status == 400:
                     port += 1
 
     def test_create_tcp_port(self):
         for kind in ['tcp', 'splunktcp']:
-            input = self.service.inputs.create(kind, str(self.base_port))
+            input = self.service.inputs.create(str(self.base_port), kind)
             self.check_entity(input)
             input.delete()
 
     def test_cannot_create_with_restrictToHost_in_name(self):
         self.assertRaises(
             client.HTTPError,
-            lambda: self.service.inputs.create('tcp', 'boris:10000')
+            lambda: self.service.inputs.create('boris:10000', 'tcp')
         )
 
     def test_create_tcp_ports_with_restrictToHost(self):
         for kind in ['tcp', 'splunktcp']: # Multiplexed UDP ports are not supported
             # Make sure we can create two restricted inputs on the same port
-            boris = self.service.inputs.create(kind, str(self.base_port), restrictToHost='boris')
-            natasha = self.service.inputs.create(kind, str(self.base_port), restrictToHost='natasha')
+            boris = self.service.inputs.create(str(self.base_port), kind, restrictToHost='boris')
+            natasha = self.service.inputs.create(str(self.base_port), kind, restrictToHost='natasha')
             # And that they both function
             boris.refresh()
             natasha.refresh()
@@ -77,21 +77,21 @@ def test_create_tcp_ports_with_restrictToHost(self):
 
     def test_restricted_to_unrestricted_collision(self):
         for kind in ['tcp', 'splunktcp', 'udp']:
-            restricted = self.service.inputs.create(kind, str(self.base_port), restrictToHost='boris')
+            restricted = self.service.inputs.create(str(self.base_port), kind, restrictToHost='boris')
             self.assertTrue('boris:' + str(self.base_port) in self.service.inputs)
             self.assertRaises(
                 client.HTTPError,
-                lambda: self.service.inputs.create(kind, str(self.base_port))
+                lambda: self.service.inputs.create(str(self.base_port), kind)
             )
             restricted.delete()
 
     def test_unrestricted_to_restricted_collision(self):
         for kind in ['tcp', 'splunktcp', 'udp']:
-            unrestricted = self.service.inputs.create(kind, str(self.base_port))
+            unrestricted = self.service.inputs.create(str(self.base_port), kind)
             self.assertTrue(str(self.base_port) in self.service.inputs)
             self.assertRaises(
                 client.HTTPError,
-                lambda: self.service.inputs.create(kind, str(self.base_port), restrictToHost='boris')
+                lambda: self.service.inputs.create(str(self.base_port), kind, restrictToHost='boris')
             )
             unrestricted.delete()
 
@@ -177,11 +177,11 @@ def setUp(self):
         self._test_entities = {}
 
         self._test_entities['tcp'] = \
-            inputs.create('tcp', unrestricted_port, host='sdk-test')
+            inputs.create(unrestricted_port, 'tcp', host='sdk-test')
         self._test_entities['udp'] = \
-            inputs.create('udp', unrestricted_port, host='sdk-test')
+            inputs.create(unrestricted_port, 'udp', host='sdk-test')
         self._test_entities['restrictedTcp'] = \
-            inputs.create('tcp', restricted_port, restrictToHost='boris')
+            inputs.create(restricted_port, 'tcp', restrictToHost='boris')
 
     def tearDown(self):
         super(TestInput, self).tearDown()
@@ -210,10 +210,10 @@ def test_lists_modular_inputs(self):
             self.uncheckedRestartSplunk()
 
             inputs = self.service.inputs
-            if ('test2','abcd') not in inputs:
-                inputs.create('test2', 'abcd', field1='boris')
+            if ('abcd','test2') not in inputs:
+                inputs.create('abcd', 'test2', field1='boris')
 
-            input = inputs['test2', 'abcd']
+            input = inputs['abcd', 'test2']
             self.assertEqual(input.field1, 'boris')
 
 
@@ -232,7 +232,7 @@ def test_read(self):
         inputs = self.service.inputs
         for this_entity in self._test_entities.itervalues():
             kind, name = this_entity.kind, this_entity.name
-            read_entity = inputs[kind, name]
+            read_entity = inputs[name, kind]
             self.assertEqual(this_entity.kind, read_entity.kind)
             self.assertEqual(this_entity.name, read_entity.name)
             self.assertEqual(this_entity.host, read_entity.host)
@@ -253,16 +253,16 @@ def test_delete(self):
             name = input_entity.name
             kind = input_entity.kind
             self.assertTrue(name in inputs)
-            self.assertTrue((kind,name) in inputs)
+            self.assertTrue((name,kind) in inputs)
             if remaining == 0:
                 inputs.delete(name)
                 self.assertFalse(name in inputs)
             else:
                 if not name.startswith('boris'):
                     self.assertRaises(client.AmbiguousReferenceException,
                         inputs.delete, name)
-                self.service.inputs.delete(kind, name)
-                self.assertFalse((kind,name) in inputs)
+                self.service.inputs.delete(name, kind)
+                self.assertFalse((name, kind) in inputs)
             self.assertRaises(client.HTTPError,
                               input_entity.refresh)
             remaining -= 1