Release 1.6.0

.travis.yml

@@ -0,0 +1,46 @@
+notifications:
+    email: false
+sudo: required
+
+services:
+    - docker
+
+before_install:
+    # Create .splunkrc file with default credentials
+    - echo host=127.0.0.1 >> $HOME/.splunkrc
+    - echo username=admin >> $HOME/.splunkrc
+    - echo password=changeme >> $HOME/.splunkrc
+    # Set SPLUNK_HOME
+    - export SPLUNK_HOME="/opt/splunk"
+    # Pull docker image
+    - docker pull splunk/splunk-sdk-travis-ci:$SPLUNK_VERSION
+    # Add DOCKER to iptables, 1/10 times this is needed, force 0 exit status
+    - sudo iptables -N DOCKER || true
+    # Start Docker container
+    - docker run -p 127.0.0.1:8089:8089 -d splunk/splunk-sdk-travis-ci:$SPLUNK_VERSION
+    # curl Splunk until it returns valid data indicating it has been setup, try 20 times maximum
+    - for i in `seq 0 20`; do if curl --fail -k https://localhost:8089/services/server/info &> /dev/null; then break; fi; echo $i; sleep 1; done
+    # The upload test needs to refer to a file that Splunk has in the docker
+    # container
+    - export INPUT_EXAMPLE_UPLOAD=$SPLUNK_HOME/var/log/splunk/splunkd_ui_access.log
+    # After initial setup, we do not want to give the SDK any notion that it has
+    # a local Splunk installation it can use, so we create a blank SPLUNK_HOME
+    # for it, and make a placeholder for log files (which some tests generate)
+    - export SPLUNK_HOME=`pwd`/splunk_home
+    - mkdir -p $SPLUNK_HOME/var/log/splunk
+
+env:
+    - SPLUNK_VERSION=6.2.6-sdk
+    - SPLUNK_VERSION=6.3.1-sdk
+
+language: python
+
+python:
+  - "2.7"
+  - "2.6"
+
+install: "pip install unittest2"
+
+before_script: python setup.py build dist
+
+script: python setup.py test

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Splunk SDK for Python Changelog
 
+## Version 1.6.0
+
+### New Features and APIs
+
+* Added support for KV Store.
+
+* Added support for HTTP basic authentication (GitHub issue #117).
+
+* Improve support for HTTP keep-alive connections (GitHub issue #122).
+
+
+### Bug Fixes
+
+* Fixed Python 2.6 compatibility (GitHub issue #141).
+
+* Fixed appending restrictToHost to UDP inputs (GitHub issue #128).
+
+### Minor Changes
+
+* Added support for Travis CI.
+
+* Updated the default test runner.
+
+* Removed shortened links from documentation and comments.
+
 ## Version 1.5.0
 
 ### New features and APIs
@@ -51,9 +76,9 @@
 
 * Restored support for Python 2.6 (GitHub issues #96 & #114).
 
-* Fix `SearchCommands` decorators and `Validator` classes (Github issue #113).
+* Fix `SearchCommands` decorators and `Validator` classes (GitHub issue #113).
 
-* Fix `SearchCommands` bug iterating over `None` in `dict_reader.fieldnames` (Github issue #110).
+* Fix `SearchCommands` bug iterating over `None` in `dict_reader.fieldnames` (GitHub issue #110).
 
 * Fixed JSON parsing errors (GitHub issue #100).
 

README.md

@@ -1,6 +1,7 @@
+[![Build Status](https://travis-ci.org/splunk/splunk-sdk-python.svg?branch=master)](https://travis-ci.org/splunk/splunk-sdk-python)
 # The Splunk Software Development Kit for Python
 
-#### Version 1.5.0
+#### Version 1.6.0
 
 The Splunk Software Development Kit (SDK) for Python contains library code and 
 examples designed to enable developers to build applications using Splunk.

docs/client.rst

@@ -68,6 +68,18 @@ splunklib.client
     :members: create, export, itemmeta, oneshot
     :inherited-members:
 
+.. autoclass:: KVStoreCollection
+    :members: data, update_index, update_field
+    :inherited-members:
+
+.. autoclass:: KVStoreCollectionData
+    :members: query, query_by_id, insert, delete, delete_by_id, update, batch_save
+    :inherited-members:
+
+.. autoclass:: KVStoreCollections
+    :members: create
+    :inherited-members:
+
 .. autoclass:: Loggers
     :members: itemmeta
     :inherited-members:
@@ -110,7 +122,7 @@ splunklib.client
     :inherited-members:
 
 .. autoclass:: Service
-    :members: apps, confs, capabilities, event_types, fired_alerts, indexes, info, inputs, job, jobs, loggers, messages, modular_input_kinds, parse, restart, restart_required, roles, search, saved_searches, settings, splunk_version, storage_passwords, users
+    :members: apps, confs, capabilities, event_types, fired_alerts, indexes, info, inputs, job, jobs, kvstore, loggers, messages, modular_input_kinds, parse, restart, restart_required, roles, search, saved_searches, settings, splunk_version, storage_passwords, users
     :inherited-members:
 
 .. autoclass:: Settings

docs/index.rst

@@ -69,6 +69,12 @@ For more information, see the `Splunk Developer Portal <http://dev.splunk.com/vi
 
     :class:`~splunklib.client.Jobs` class
 
+    :class:`~splunklib.client.KVStoreCollection` class
+
+    :class:`~splunklib.client.KVStoreCollectionData` class
+
+    :class:`~splunklib.client.KVStoreCollections` class
+
     :class:`~splunklib.client.Loggers` class
 
     :class:`~splunklib.client.Message` class
@@ -147,6 +153,8 @@ For more information, see the `Splunk Developer Portal <http://dev.splunk.com/vi
 :doc:`searchcommands`
 ---------------------
 
+    :class:`~splunklib.searchcommands.EventingCommand` class
+
     :class:`~splunklib.searchcommands.GeneratingCommand` class
 
     :class:`~splunklib.searchcommands.ReportingCommand` class

docs/searchcommands.rst

@@ -5,6 +5,20 @@ splunklib.searchcommands
 
 .. autofunction:: dispatch(command_class[, argv=sys.argv, input_file=sys.stdin, output_file=sys.stdout, module_name=None])
 
+.. autoclass:: EventingCommand
+    :members:
+    :inherited-members:
+    :exclude-members: ConfigurationSettings, process, transform
+
+    .. autoclass:: splunklib.searchcommands::EventingCommand.ConfigurationSettings
+        :members:
+        :inherited-members:
+        :exclude-members: configuration_settings, fix_up, items, keys
+
+    .. automethod:: splunklib.searchcommands::EventingCommand.transform
+
+    .. automethod:: splunklib.searchcommands::EventingCommand.process(args=sys.argv[, input_file=sys.stdin, output_file=sys.stdout])
+
 .. autoclass:: GeneratingCommand
     :members:
     :inherited-members:

examples/kvstore.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+#
+# Copyright 2011-2015 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""A command line utility for interacting with Splunk KV Store Collections."""
+
+import sys, os, json
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from splunklib.client import connect
+
+try:
+    from utils import parse
+except ImportError:
+    raise Exception("Add the SDK repository to your PYTHONPATH to run the examples "
+                    "(e.g., export PYTHONPATH=~/splunk-sdk-python.")
+
+def main():
+    opts = parse(sys.argv[1:], {}, ".splunkrc")
+    opts.kwargs["owner"] = "nobody"
+    opts.kwargs["app"] = "search"
+    service = connect(**opts.kwargs)
+
+    print "KV Store Collections:"
+    for collection in service.kvstore:
+        print "  %s" % collection.name
+
+    # Let's delete a collection if it already exists, and then create it
+    collection_name = "example_collection"
+    if collection_name in service.kvstore:
+        service.kvstore.delete(collection_name)
+
+    # Let's create it and then make sure it exists    
+    service.kvstore.create(collection_name)
+    collection = service.kvstore[collection_name]
+
+    # Let's make sure it doesn't have any data
+    print "Should be empty: %s" % json.dumps(collection.data.query())
+
+    # Let's add some data
+    collection.data.insert(json.dumps({"_key": "item1", "somekey": 1, "otherkey": "foo"}))
+    collection.data.insert(json.dumps({"_key": "item2", "somekey": 2, "otherkey": "foo"}))
+    collection.data.insert(json.dumps({"somekey": 3, "otherkey": "bar"}))
+
+    # Let's make sure it has the data we just entered
+    print "Should have our data: %s" % json.dumps(collection.data.query(), indent=1)
+
+    # Let's run some queries
+    print "Should return item1: %s" % json.dumps(collection.data.query_by_id("item1"), indent=1)
+
+    query = json.dumps({"otherkey": "foo"})
+    print "Should return item1 and item2: %s" % json.dumps(collection.data.query(query=query), indent=1)
+
+    query = json.dumps({"otherkey": "bar"})
+    print "Should return third item with auto-generated _key: %s" % json.dumps(collection.data.query(query=query), indent=1)
+
+    # Let's delete the collection
+    collection.delete()
+
+if __name__ == "__main__":
+    main()
+
+

examples/searchcommands_app/README.md

@@ -41,7 +41,7 @@ The app is tested on Splunk 5 and 6. Here is its manifest:
 [3] [Python Logging HOWTO](http://docs.python.org/2/howto/logging.html)  
 [4] [ConfigParser—Configuration file parser](http://docs.python.org/2/library/configparser.html)
 [5] [searchbnf.conf](http://docs.splunk.com/Documentation/Splunk/latest/admin/Searchbnfconf)
-[6] [Set permissions in the file system](http://goo.gl/1oDT7r)
+[6] [Set permissions in the file system](http://docs.splunk.com/Documentation/Splunk/latest/AdvancedDev/SetPermissions#Set_permissions_in_the_filesystem)
 
 ## Installation
 

examples/searchcommands_app/package/README/logging.conf.spec

@@ -1,7 +1,7 @@
 #
 # The format of this file is described in this article at Python.org:
 #
-#     [Configuration file format](http://goo.gl/K6edZ8)
+#     [Configuration file format](https://docs.python.org/2/library/logging.config.html#configuration-file-format)
 #
 # This file must contain sections called [loggers], [handlers] and [formatters] which identify by name the entities of
 # each type which are defined in the file. For each such entity, there is a separate section which identifies how that
@@ -57,7 +57,7 @@ propagate = [0|1]
 
 [handlers]
     * Specifies a list of handler keys.
-    * See [logging.handlers](http://goo.gl/9aoOx)
+    * See [logging.handlers](https://docs.python.org/2/library/logging.handlers.html)
 
 keys = <comma-separated strings>
     * A comma-separated list of handlers keys. Each key must have a corresponding [handler_<string>] section in the
@@ -86,7 +86,7 @@ formatter = <string>
 
 [formatters]
     * Specifies a list of formatter keys.
-    * See [logging.formatters](http://goo.gl/z5CBR3)
+    * See [logging.formatters](https://docs.python.org/2/howto/logging.html#formatters)
 
 keys = <comma-separated strings>
     * A comma-separated list of formatter keys. Each key must have a corresponding [formatter_<string>] section in the
@@ -105,12 +105,12 @@ datefmt = <string>
     * The strftime-compatible date/time format string. If empty, the package substitutes ISO8601 format date/times.
     * An example ISO8601 date/time is datetime(2015, 2, 6, 15, 53, 36, 786309).isoformat() ==
     * '2015-02-06T15:53:36.786309'. For a complete list of formatting directives, see section [strftime() and strptime()
-    * Behavior](http://goo.gl/6zUAGv)
+    * Behavior](https://docs.python.org/2/library/datetime.html#strftime-strptime-behavior)
     * Defaults to empty.
 
 format = <string>
     * The overall format string. This string uses %(<dictionary key>)s styled string substitution; the possible keys are
-    * documented in [LogRecord](http://goo.gl/qW83Dg) attributes. The following format string will log the time in a
+    * documented in [LogRecord](https://docs.python.org/2/library/logging.html#logging.LogRecord) attributes. The following format string will log the time in a
     * human-readable format, the severity of the message, and the contents of the message, in that order:
     *    format = '%(asctime)s - %(levelname)s - %(message)s'
     * A value is required.

examples/searchcommands_app/package/bin/countmatches.py

@@ -64,7 +64,7 @@ def stream(self, records):
         for record in records:
             count = 0L
             for fieldname in self.fieldnames:
-                matches = pattern.findall(unicode(record[fieldname]))
+                matches = pattern.findall(unicode(record[fieldname].decode("utf-8")))
                 count += len(matches)
             record[self.fieldname] = count
             yield record

examples/searchcommands_app/package/default/logging.conf

@@ -1,7 +1,7 @@
 #
 # The format and semantics of this file are described in this article at Python.org:
 #
-#     [Configuration file format](http://goo.gl/K6edZ8)
+#     [Configuration file format](https://docs.python.org/2/library/logging.config.html#configuration-file-format)
 #
 [loggers]
 keys = root, splunklib, CountMatchesCommand, GenerateHelloCommand, GenerateTextCommand, SimulateCommand, SumCommand
@@ -47,7 +47,7 @@ handlers = app    ; Default: stderr
 propagate = 0     ; Default: 1
 
 [handlers]
-# See [logging.handlers](http://goo.gl/9aoOx)
+# See [logging.handlers](https://docs.python.org/2/library/logging.handlers.html)
 keys = app, splunklib, stderr
 
 [handler_app]

examples/searchcommands_app/setup.py

@@ -57,7 +57,10 @@ def symlink(source, link_name):
     patch_os()
     del locals()['patch_os']  # since this function has done its job
 
-from collections import OrderedDict
+try:
+    from collections import OrderedDict
+except:
+    from splunklib.ordereddict import OrderedDict
 from glob import glob
 from itertools import chain
 from setuptools import setup, Command
@@ -429,7 +432,7 @@ def run(self):
     setup(
         description='Custom Search Command examples',
         name=os.path.basename(project_dir),
-        version='1.5.0',
+        version='1.6.0',
         author='Splunk, Inc.',
         author_email='devinfo@splunk.com',
         url='http://github.com/splunk/splunk-sdk-python',

examples/searchcommands_template/default/logging.conf

@@ -1,7 +1,7 @@
 #
 # The format of this file is described in this article at Python.org:
 #
-#     [Configuration file format](http://goo.gl/K6edZ8)
+#     [Configuration file format](https://docs.python.org/2/library/logging.config.html#configuration-file-format)
 #
 [loggers]
 keys = root, splunklib, %(command.title())Command

examples/upload.py

@@ -72,9 +72,9 @@ def main(argv):
         'host_segment', 'rename-source', 'sourcetype')
 
     for arg in opts.args: 
+        # Note that it's possible the file may not exist (if you had a typo),
+        # but it only needs to exist on the Splunk server, which we can't verify.
         fullpath = path.abspath(arg)
-        if not path.exists(fullpath):
-            error("File '%s' does not exist" % arg, 2)
         index.upload(fullpath, **kwargs_submit)
 
 if __name__ == "__main__":