Update Entity metadata interface -- Entity.metadata => Entity.access & Entity.fields plus improved entity units (found/fixed a bug in Message entity).

Author: blovering

CHANGELOG.md

@@ -50,7 +50,8 @@ properties:
 
 * `Entity.state` returns the entire state record
 * `Entity.content` returns the content field of the state record
-* `Entity.metadata` returns the metadata field of the state record
+* `Entity.access` returns entity access metadata
+* `Entity.fields` returns entity content metadata
 
 `Entity.refresh` is a new method that issues a round-trip to the server
 and updates the local, cached state record.

docs/index.rst

@@ -97,6 +97,10 @@ splunklib.client
     :inherited-members:
     :undoc-members:
 
+.. autoclass:: Loggers
+    :members:
+    :inherited-members:
+
 .. autoclass:: Message
     :members:
     :inherited-members:

examples/index.py

@@ -70,12 +70,11 @@ def create(self, argv):
             print "Index '%s' already exists" % name
             return
 
-        # Read item metadata and construct command line parser rules that 
+        # Read index metadata and construct command line parser rules that 
         # correspond to each editable field.
 
         # Request editable fields
-        itemmeta = self.service.indexes.itemmeta()
-        fields = itemmeta['eai:attributes'].optionalFields
+        fields = self.service.indexes.itemmeta().fields.optional
 
         # Build parser rules
         rules = dict([(field, {'flags': ["--%s" % field]}) for field in fields])
@@ -142,15 +141,16 @@ def update(self, argv):
         if len(argv) == 0: 
             error("Command requires an index name", 2)
         name = argv[0]
+
         if not self.service.indexes.contains(name):
             error("Index '%s' does not exist" % name, 2)
         index = self.service.indexes[name]
 
-        # Read entity metadata and construct command line parser rules that 
+        # Read index metadata and construct command line parser rules that 
         # correspond to each editable field.
 
         # Request editable fields
-        fields = index.readmeta()['eai:attributes'].optionalFields
+        fields = self.service.indexes.itemmeta().fields.optional
 
         # Build parser rules
         rules = dict([(field, {'flags': ["--%s" % field]}) for field in fields])

splunklib/client.py

@@ -108,17 +108,37 @@ def _parse_atom_entry(entry):
     elink = elink if isinstance(elink, list) else [elink]
     links = record((link.rel, link.href) for link in elink)
 
-    econtent = entry.get('content', {})
-    content = record((k, v) for k, v in econtent.iteritems()
+    # Retrieve entity content values
+    content = entry.get('content', {})
+
+    # Host entry metadata
+    metadata = _parse_atom_metadata(content)
+
+    # Filter some of the noise out of the content record
+    content = record((k, v) for k, v in content.iteritems()
         if k not in ['eai:acl', 'eai:attributes', 'type'])
-    metadata = dict((k, econtent.get(k, None)) 
-        for k in ['eai:acl', 'eai:attributes'])
 
     return record({
         'title': title,
         'links': links,
-        'content': content,
-        'metadata': metadata })
+        'access': metadata.access,
+        'fields': metadata.fields,
+        'content': content
+    })
+
+# Parse the metadata fields out of the given atom entry content record
+def _parse_atom_metadata(content):
+    # Hoist access metadata
+    access = content.get('eai:acl', None)
+
+    # Hoist content metadata (and cleanup some naming)
+    attributes = content.get('eai:attributes', {})
+    fields = record({
+        'required': attributes.get('requiredFields', []),
+        'optional': attributes.get('optionalFields', []),
+        'wildcard': attributes.get('wildcardFields', [])})
+
+    return record({'access': access, 'fields': fields})
 
 # kwargs: scheme, host, port, app, owner, username, password
 def connect(**kwargs):
@@ -220,7 +240,7 @@ def jobs(self):
     def loggers(self):
         """Returns a collection of service logging categories and their status.
         """
-        return Collection(self, PATH_LOGGER)
+        return Loggers(self)
 
     @property
     def messages(self):
@@ -233,7 +253,7 @@ def parse(self, query, **kwargs):
 
         :param `query`: The search query to parse.
         :param `kwargs`: Optional arguments to pass to the ``search/parser`` 
-                       endpoint.
+                         endpoint.
         :return: A semantic map of the parsed search query.
         """
         return self.get("search/parser", q=query, **kwargs)
@@ -302,17 +322,6 @@ def __call__(self, *args):
     def __getitem__(self, key):
         return self.content[key]
 
-    #
-    # Given that update doesn't automatically refresh the cached local state,
-    # this operation now violates the principle of least surprise, because it
-    # allows you to do what appears to be a local assignment, which is then
-    # not reflected in the value you see if you do a subsequent __getitem__ 
-    # without an explicit refresh.
-    #
-    # def __setitem__(self, key, value):
-    #     self.update(**{ key: value })
-    #
-
     # Load the Atom entry record from the given response - this is a method
     # because the "entry" record varies slightly by entity and this allows
     # for a subclass to override and handle any special cases.
@@ -331,6 +340,11 @@ def refresh(self, state=None):
         self._state = state if state is not None else self.read()
         return self
 
+    @property
+    def access(self):
+        """Returns entity access metadata."""
+        return self.state.access
+
     @property
     def content(self):
         """Returns the contents of the entity."""
@@ -346,16 +360,16 @@ def enable(self):
         self.post("enable")
         return self
 
+    @property
+    def fields(self):
+        """Returns entity content metadata."""
+        return self.state.fields
+
     @property
     def links(self):
         """Returns a dictionary of related resources."""
         return self.state.links
 
-    @property
-    def metadata(self):
-        """Returns the entity metadata."""
-        return self.state.metadata
-
     @property
     def name(self):
         """Returns the entity name."""
@@ -448,10 +462,7 @@ def itemmeta(self):
         """Returns metadata for members of the collection."""
         response = self.get("_new")
         content = _load_atom(response, MATCH_ENTRY_CONTENT)
-        return {
-            'eai:acl': content['eai:acl'],
-            'eai:attributes': content['eai:attributes']
-        }
+        return _parse_atom_metadata(content)
 
     # kwargs: count, offset, search, sort_dir, sort_key, sort_mode
     def list(self, count=-1, **kwargs):
@@ -674,10 +685,7 @@ def itemmeta(self, kind):
         """Returns metadata for the members of a given kind."""
         response = self.get("%s/_new" % self._kindmap[kind])
         content = _load_atom(response, MATCH_ENTRY_CONTENT)
-        return {
-            'eai:acl': content['eai:acl'],
-            'eai:attributes': content['eai:attributes']
-        }
+        return _parse_atom_metadata(content)
 
     @property
     def kinds(self):
@@ -884,9 +892,17 @@ def create(self, query, **kwargs):
     def list(self, count=0, **kwargs):
         return Collection.list(self, count, **kwargs)
 
+class Loggers(Collection):
+    """This class represents a collection of service logging categories."""
+    def __init__(self, service):
+        Collection.__init__(self, service, PATH_LOGGER)
+
+    def itemmeta(self):
+        raise NotSupportedError
+
 class Message(Entity):
-    def __init__(self, service, name, **kwargs):
-        Entity.__init__(self, service, _path(PATH_MESSAGES, name), **kwargs)
+    def __init__(self, service, path, **kwargs):
+        Entity.__init__(self, service, path, **kwargs)
 
     @property
     def value(self):

tests/splunklib.client.baseline

@@ -1,2 +1,2 @@
-['AlertGroup', 'Collection', 'Conf', 'Confs', 'Context', 'Endpoint', 'Entity', 'HTTPError', 'INPUT_KINDMAP', 'Index', 'Input', 'Inputs', 'Job', 'Jobs', 'MATCH_ENTRY_CONTENT', 'Message', 'NotSupportedError', 'OperationError', 'PATH_APPS', 'PATH_CAPABILITIES', 'PATH_CONF', 'PATH_CONFS', 'PATH_EVENT_TYPES', 'PATH_FIRED_ALERTS', 'PATH_INDEXES', 'PATH_INPUTS', 'PATH_JOBS', 'PATH_LOGGER', 'PATH_MESSAGES', 'PATH_ROLES', 'PATH_SAVED_SEARCHES', 'PATH_STANZA', 'PATH_USERS', 'SavedSearch', 'SavedSearches', 'Service', 'Settings', 'Stanza', 'Users', 'XNAMEF_ATOM', 'XNAME_CONTENT', 'XNAME_ENTRY', '__all__', '__builtins__', '__doc__', '__file__', '__name__', '__package__', '_filter_content', '_load_atom', '_load_atom_entries', '_load_sid', '_parse_atom_entry', '_path', '_path_conf', 'connect', 'data', 'quote', 'record', 'sleep', 'urlencode']
+['AlertGroup', 'Collection', 'Conf', 'Confs', 'Context', 'Endpoint', 'Entity', 'HTTPError', 'INPUT_KINDMAP', 'Index', 'Input', 'Inputs', 'Job', 'Jobs', 'Loggers', 'MATCH_ENTRY_CONTENT', 'Message', 'NotSupportedError', 'OperationError', 'PATH_APPS', 'PATH_CAPABILITIES', 'PATH_CONF', 'PATH_CONFS', 'PATH_EVENT_TYPES', 'PATH_FIRED_ALERTS', 'PATH_INDEXES', 'PATH_INPUTS', 'PATH_JOBS', 'PATH_LOGGER', 'PATH_MESSAGES', 'PATH_ROLES', 'PATH_SAVED_SEARCHES', 'PATH_STANZA', 'PATH_USERS', 'SavedSearch', 'SavedSearches', 'Service', 'Settings', 'Stanza', 'Users', 'XNAMEF_ATOM', 'XNAME_CONTENT', 'XNAME_ENTRY', '__all__', '__builtins__', '__doc__', '__file__', '__name__', '__package__', '_filter_content', '_load_atom', '_load_atom_entries', '_load_sid', '_parse_atom_entry', '_parse_atom_metadata', '_path', '_path_conf', 'connect', 'data', 'quote', 'record', 'sleep', 'urlencode']
 

tests/test_app.py

@@ -20,10 +20,7 @@
 
 class TestCase(testlib.TestCase):
     def check_app(self, app):
-        app.name
-        app.path
-        app.content
-        app.metadata
+        self.check_entity(app)
 
     def test_read(self):
         service = client.connect(**self.opts.kwargs)

tests/test_collection.py

@@ -21,6 +21,14 @@
 class TestCase(testlib.TestCase):
     # Verify that the given collections interface behaves as expected
     def check_collection(self, collection):
+        # Check item metadata
+        try:
+            metadata = collection.itemmeta()
+            self.assertTrue(isinstance(metadata, dict))
+            self.assertTrue(isinstance(metadata.access, dict))
+            self.assertTrue(isinstance(metadata.fields, dict))
+        except client.NotSupportedError: pass
+
         # Check various collection options
         collection.list() # Default
         collection.list(search="title=*")

tests/test_conf.py

@@ -36,10 +36,7 @@ def test_read(self):
             conf.name
             conf.path
             for stanza in conf: 
-                stanza.name
-                stanza.path
-                stanza.content
-                stanza.metadata
+                self.check_entity(stanza)
 
     def test_crud(self):
         service = client.connect(**self.opts.kwargs)

tests/test_event_type.py

@@ -19,22 +19,26 @@
 import testlib
 
 class TestCase(testlib.TestCase):
-    def check_content(self, entity, **kwargs):
-        for k, v in kwargs.iteritems(): 
-            self.assertEqual(entity[k], str(v))
+    def check_event_type(self, event_type):
+        self.check_entity(event_type)
+        keys = ['description', 'priority', 'search']
+        for key in keys: self.assertTrue(key, event_type)
 
-    def test(self):
-        event_types = client.connect(**self.opts.kwargs).event_types
+    def test_read(self):
+        service = client.connect(**self.opts.kwargs)
+
+        for event_type in service.event_types:
+            self.check_event_type(event_type)
+
+    def test_crud(self):
+        service = client.connect(**self.opts.kwargs)
+
+        event_types = service.event_types
 
         if 'sdk-test' in event_types:
             event_types.delete('sdk-test')
         self.assertFalse('sdk-test' in event_types)
 
-        for event_type in event_types:
-            event_type.content.description
-            event_type.content.priority
-            event_type.content.search
-
         kwargs = {}
         kwargs['search'] = "index=_internal *"
         kwargs['description'] = "An internal event"

tests/test_fired_alert.py

@@ -31,6 +31,9 @@ def test_crud(self):
         searches = service.saved_searches
         fired_alerts = service.fired_alerts
 
+        if 'sdk-tests' not in service.indexes:
+            service.indexes.create("sdk-tests")
+
         # Clean out the test index
         index = service.indexes['sdk-tests']
         index.clean()