From 55aa2dd6e012afb9134795298ec8c0e67a1e5327 Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:15:43 -0500 Subject: [PATCH 1/9] Fix inline examples --- splunklib/binding.py | 1 + splunklib/client.py | 6 ++-- .../modularinput/validation_definition.py | 32 ++++++++++--------- 3 files changed, 21 insertions(+), 18 deletions(-) diff --git a/splunklib/binding.py b/splunklib/binding.py index 3fe7c8495..62efd03f2 100644 --- a/splunklib/binding.py +++ b/splunklib/binding.py @@ -80,6 +80,7 @@ def _parse_cookies(cookie_str, dictionary): then updates the the dictionary with any key-value pairs found. **Example**:: + dictionary = {} _parse_cookies('my=value', dictionary) # Now the following is True diff --git a/splunklib/client.py b/splunklib/client.py index 1e624ba42..a39261206 100644 --- a/splunklib/client.py +++ b/splunklib/client.py @@ -1200,7 +1200,7 @@ def __getitem__(self, key): :raises ValueError: Raised if no namespace is specified and *key* does not refer to a unique name. - *Example*:: + **Example**:: s = client.connect(...) saved_searches = s.saved_searches @@ -1636,9 +1636,9 @@ def get(self, name="", owner=None, app=None, sharing=None, **query): :rtype: ``dict`` with keys ``body``, ``headers``, ``reason``, and ``status`` - Example: + **Example**:: - import splunklib.client + import splunklib.client s = client.service(...) saved_searches = s.saved_searches saved_searches.get("my/saved/search") == \\ diff --git a/splunklib/modularinput/validation_definition.py b/splunklib/modularinput/validation_definition.py index 8904e40b1..ac9a89f53 100755 --- a/splunklib/modularinput/validation_definition.py +++ b/splunklib/modularinput/validation_definition.py @@ -28,7 +28,7 @@ class ValidationDefinition(object): **Example**:: - ``v = ValidationDefinition()`` + v = ValidationDefinition() """ def __init__(self): @@ -46,20 +46,22 @@ def parse(stream): The XML typically will look like this: - ```` - `` myHost`` - `` https://127.0.0.1:8089`` - `` 123102983109283019283`` - `` /opt/splunk/var/lib/splunk/modinputs`` - `` `` - `` value1`` - `` `` - `` value2`` - `` value3`` - `` value4`` - `` `` - `` `` - ```` + .. code-block:: xml + + + myHost + https://127.0.0.1:8089 + 123102983109283019283 + /opt/splunk/var/lib/splunk/modinputs + + value1 + + value2 + value3 + value4 + + + :param stream: ``Stream`` containing XML to parse. :return definition: A ``ValidationDefinition`` object. From 1c78030856b0a4f3df14a884978406964234c6fe Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:19:54 -0500 Subject: [PATCH 2/9] Fix param indentation Continuation lines after a :param: must be indented. --- splunklib/modularinput/argument.py | 4 ++-- splunklib/modularinput/script.py | 6 +++--- splunklib/searchcommands/external_search_command.py | 8 ++++---- splunklib/searchcommands/search_command.py | 6 +++--- splunklib/searchcommands/validators.py | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/splunklib/modularinput/argument.py b/splunklib/modularinput/argument.py index 4c4b3c82c..04214d16d 100755 --- a/splunklib/modularinput/argument.py +++ b/splunklib/modularinput/argument.py @@ -54,9 +54,9 @@ def __init__(self, name, description=None, validation=None, :param name: ``string``, identifier for this argument in Splunk. :param description: ``string``, human-readable description of the argument. :param validation: ``string`` specifying how the argument should be validated, if using internal validation. - If using external validation, this will be ignored. + If using external validation, this will be ignored. :param data_type: ``string``, data type of this field; use the class constants. - "data_type_boolean", "data_type_number", or "data_type_string". + "data_type_boolean", "data_type_number", or "data_type_string". :param required_on_edit: ``Boolean``, whether this arg is required when editing an existing modular input of this kind. :param required_on_create: ``Boolean``, whether this arg is required when creating a modular input of this kind. :param title: ``String``, a human-readable title for the argument. diff --git a/splunklib/modularinput/script.py b/splunklib/modularinput/script.py index 040a07d9f..a254dfa25 100755 --- a/splunklib/modularinput/script.py +++ b/splunklib/modularinput/script.py @@ -118,9 +118,9 @@ def service(self): available as soon as the :code:`Script.stream_events` method is called. - :return: :class:splunklib.client.Service. A value of None is returned, - if you call this method before the :code:`Script.stream_events` method - is called. + :return: :class:`splunklib.client.Service`. A value of None is returned, + if you call this method before the :code:`Script.stream_events` method + is called. """ if self._service is not None: diff --git a/splunklib/searchcommands/external_search_command.py b/splunklib/searchcommands/external_search_command.py index 2c4ce50b7..c2306241e 100644 --- a/splunklib/searchcommands/external_search_command.py +++ b/splunklib/searchcommands/external_search_command.py @@ -105,13 +105,13 @@ def _execute(path, argv=None, environ=None): :param argv: Argument list. :type argv: list or tuple - The arguments to the child process should start with the name of the command being run, but this is not - enforced. A value of :const:`None` specifies that the base name of path name :param:`path` should be used. + The arguments to the child process should start with the name of the command being run, but this is not + enforced. A value of :const:`None` specifies that the base name of path name :param:`path` should be used. :param environ: A mapping which is used to define the environment variables for the new process. :type environ: dict or None. - This mapping is used instead of the current process’s environment. A value of :const:`None` specifies that - the :data:`os.environ` mapping should be used. + This mapping is used instead of the current process’s environment. A value of :const:`None` specifies that + the :data:`os.environ` mapping should be used. :return: None diff --git a/splunklib/searchcommands/search_command.py b/splunklib/searchcommands/search_command.py index 47918abb6..77291123d 100644 --- a/splunklib/searchcommands/search_command.py +++ b/splunklib/searchcommands/search_command.py @@ -256,7 +256,7 @@ def search_results_info(self): invocation. :return: Search results info:const:`None`, if the search results info file associated with the command - invocation is inaccessible. + invocation is inaccessible. :rtype: SearchResultsInfo or NoneType """ @@ -345,8 +345,8 @@ def service(self): :code:`requires_srinfo` setting is false by default. Hence, you must set it. :return: :class:`splunklib.client.Service`, if :code:`enableheader` and :code:`requires_srinfo` are both - :code:`true`. Otherwise, if either :code:`enableheader` or :code:`requires_srinfo` are :code:`false`, a value - of :code:`None` is returned. + :code:`true`. Otherwise, if either :code:`enableheader` or :code:`requires_srinfo` are :code:`false`, a value + of :code:`None` is returned. """ if self._service is not None: diff --git a/splunklib/searchcommands/validators.py b/splunklib/searchcommands/validators.py index 66329375c..dca4cf422 100644 --- a/splunklib/searchcommands/validators.py +++ b/splunklib/searchcommands/validators.py @@ -81,9 +81,9 @@ class Code(Validator): def __init__(self, mode='eval'): """ :param mode: Specifies what kind of code must be compiled; it can be :const:`'exec'`, if source consists of a - sequence of statements, :const:`'eval'`, if it consists of a single expression, or :const:`'single'` if it - consists of a single interactive statement. In the latter case, expression statements that evaluate to - something other than :const:`None` will be printed. + sequence of statements, :const:`'eval'`, if it consists of a single expression, or :const:`'single'` if it + consists of a single interactive statement. In the latter case, expression statements that evaluate to + something other than :const:`None` will be printed. :type mode: unicode or bytes """ From d2455613136bff381c98b9f3bc370d91797fd5a1 Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:24:35 -0500 Subject: [PATCH 3/9] Fix returns Return variable name shouldn't be included via :returns: --- splunklib/modularinput/scheme.py | 2 +- splunklib/modularinput/validation_definition.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/splunklib/modularinput/scheme.py b/splunklib/modularinput/scheme.py index ff4f97832..4104e4a3f 100755 --- a/splunklib/modularinput/scheme.py +++ b/splunklib/modularinput/scheme.py @@ -55,7 +55,7 @@ def add_argument(self, arg): def to_xml(self): """Creates an ``ET.Element`` representing self, then returns it. - :returns root, an ``ET.Element`` representing this scheme. + :returns: an ``ET.Element`` representing this scheme. """ root = ET.Element("scheme") diff --git a/splunklib/modularinput/validation_definition.py b/splunklib/modularinput/validation_definition.py index ac9a89f53..3bbe9760e 100755 --- a/splunklib/modularinput/validation_definition.py +++ b/splunklib/modularinput/validation_definition.py @@ -64,7 +64,7 @@ def parse(stream): :param stream: ``Stream`` containing XML to parse. - :return definition: A ``ValidationDefinition`` object. + :return: A ``ValidationDefinition`` object. """ From 862d295edf552928da8442425d3b9dbd3295e81e Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:26:29 -0500 Subject: [PATCH 4/9] Fixed up code-blocks Also fixed command.conf spelling of "retainsevents" (not "retains events") --- splunklib/searchcommands/decorators.py | 6 ++-- .../searchcommands/generating_command.py | 35 ++++++++++++------- splunklib/searchcommands/search_command.py | 5 +-- 3 files changed, 29 insertions(+), 17 deletions(-) diff --git a/splunklib/searchcommands/decorators.py b/splunklib/searchcommands/decorators.py index b5e16064a..02c1326e8 100644 --- a/splunklib/searchcommands/decorators.py +++ b/splunklib/searchcommands/decorators.py @@ -229,8 +229,9 @@ class Option(property): Short form (recommended). When you are satisfied with built-in or custom validation behaviors. - .. code-block:: python + .. code-block:: python :linenos: + from splunklib.searchcommands.decorators import Option from splunklib.searchcommands.validators import Fieldname @@ -247,8 +248,9 @@ class Option(property): also provide a deleter. You must be prepared to accept a value of :const:`None` which indicates that your :code:`Option` is unset. - .. code-block:: python + .. code-block:: python :linenos: + from splunklib.searchcommands import Option @Option() diff --git a/splunklib/searchcommands/generating_command.py b/splunklib/searchcommands/generating_command.py index fd0585e4c..46858cbdd 100644 --- a/splunklib/searchcommands/generating_command.py +++ b/splunklib/searchcommands/generating_command.py @@ -92,9 +92,10 @@ class StreamingGeneratingCommand(GeneratingCommand) +==========+===================================================+===================================================+ | streams | 1. Add this line to your command's stanza in | 1. Add this configuration setting to your code: | | | | | - | | default/commands.conf. | .. code-block:: python | - | | .. code-block:: python | @Configuration(distributed=True) | - | | local = false | class SomeCommand(GeneratingCommand) | + | | default/commands.conf:: | .. code-block:: python | + | | | | + | | local = false | @Configuration(distributed=True) | + | | | class SomeCommand(GeneratingCommand) | | | | ... | | | 2. Restart splunk | | | | | 2. You are good to go; no need to restart Splunk | @@ -112,6 +113,7 @@ class StreamingGeneratingCommand(GeneratingCommand) | | settings to your command class: | setting to your command class: | | | | | | | .. code-block:: python | .. code-block:: python | + | | | | | | @Configuration( | @Configuration(type='events') | | | retainsevents=True, streaming=False) | class SomeCommand(GeneratingCommand) | | | class SomeCommand(GeneratingCommand) | ... | @@ -119,22 +121,25 @@ class StreamingGeneratingCommand(GeneratingCommand) | | | | | | Or add these lines to default/commands.conf: | | | | | | - | | .. code-block:: | | - | | retains events = true | | + | | .. code-block:: text | | + | | | | + | | retainsevents = true | | | | streaming = false | | +----------+---------------------------------------------------+---------------------------------------------------+ Configure your command class like this, if you wish to support both protocols: - .. code-block:: python + .. code-block:: python + @Configuration(type='events', retainsevents=True, streaming=False) class SomeCommand(GeneratingCommand) ... You might also consider adding these lines to commands.conf instead of adding them to your command class: - .. code-block:: python - retains events = false + .. code-block:: python + + retainsevents = false streaming = false Reporting Generating command @@ -149,28 +154,32 @@ class SomeCommand(GeneratingCommand) | | settings to your command class: | setting to your command class: | | | | | | | .. code-block:: python | .. code-block:: python | + | | | | | | @Configuration(retainsevents=False) | @Configuration(type='reporting') | | | class SomeCommand(GeneratingCommand) | class SomeCommand(GeneratingCommand) | | | ... | ... | | | | | | | Or add this lines to default/commands.conf: | | | | | | - | | .. code-block:: | | - | | retains events = false | | + | | .. code-block:: text | | + | | | | + | | retainsevents = false | | | | streaming = false | | +----------+---------------------------------------------------+---------------------------------------------------+ Configure your command class like this, if you wish to support both protocols: - .. code-block:: python + .. code-block:: python + @Configuration(type='reporting', streaming=False) class SomeCommand(GeneratingCommand) ... You might also consider adding these lines to commands.conf instead of adding them to your command class: - .. code-block:: python - retains events = false + .. code-block:: text + + retainsevents = false streaming = false """ diff --git a/splunklib/searchcommands/search_command.py b/splunklib/searchcommands/search_command.py index 77291123d..c3b309790 100644 --- a/splunklib/searchcommands/search_command.py +++ b/splunklib/searchcommands/search_command.py @@ -338,6 +338,7 @@ def service(self): specifying this pair of configuration settings in commands.conf: .. code-block:: python + enableheader = true requires_srinfo = true @@ -1080,7 +1081,7 @@ def dispatch(command_class, argv=sys.argv, input_file=sys.stdin, output_file=sys **Example** - .. code-block:: python + .. code-block:: python :linenos: #!/usr/bin/env python @@ -1096,7 +1097,7 @@ def stream(records): **Example** - .. code-block:: python + .. code-block:: python :linenos: from splunklib.searchcommands import dispatch, StreamingCommand, Configuration, Option, validators From 0c79366b8ab749bc5ef6967e75ebe5cef6f23303 Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:28:28 -0500 Subject: [PATCH 5/9] Misc doc fixes - Indentation issues - Removed ":param:`p`" references. Just using "``p``" instead. --- splunklib/searchcommands/__init__.py | 2 +- splunklib/searchcommands/search_command.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/splunklib/searchcommands/__init__.py b/splunklib/searchcommands/__init__.py index 12b14f32c..326e3e28e 100644 --- a/splunklib/searchcommands/__init__.py +++ b/splunklib/searchcommands/__init__.py @@ -30,7 +30,7 @@ field-name = ( "_" / alpha ) *( alpha / digit / "_" / "." / "-" ) It does not show that :code:`field-name` values may be comma-separated. This is because Splunk strips commas from - the command line. A search command will never see them. + the command line. A search command will never see them. 2. Search commands targeting versions of Splunk prior to 6.3 must be statically configured as follows: diff --git a/splunklib/searchcommands/search_command.py b/splunklib/searchcommands/search_command.py index c3b309790..64b06aba1 100644 --- a/splunklib/searchcommands/search_command.py +++ b/splunklib/searchcommands/search_command.py @@ -810,15 +810,15 @@ def write_metric(self, name, value): :param name: Name of the metric. :type name: basestring - :param value: A 4-tuple containing the value of metric :param:`name` where + :param value: A 4-tuple containing the value of metric ``name`` where value[0] = Elapsed seconds or :const:`None`. value[1] = Number of invocations or :const:`None`. value[2] = Input count or :const:`None`. value[3] = Output count or :const:`None`. - The :data:`SearchMetric` type provides a convenient encapsulation of :param:`value`. - The :data:`SearchMetric` type provides a convenient encapsulation of :param:`value`. + The :data:`SearchMetric` type provides a convenient encapsulation of ``value``. + The :data:`SearchMetric` type provides a convenient encapsulation of ``value``. :return: :const:`None`. From 01558e4f111fca98a7f58700f9bc3b57c28871a6 Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:32:39 -0500 Subject: [PATCH 6/9] Fixed missing function references - Moved splunklib.searchcommands.validators into it's own rst file. Not sure if this best. But it makes doc generation exceptions stop. :-) --- docs/searchcommands.rst | 7 ------- docs/searchcommandsvalidators.rst | 12 ++++++++++++ 2 files changed, 12 insertions(+), 7 deletions(-) create mode 100644 docs/searchcommandsvalidators.rst diff --git a/docs/searchcommands.rst b/docs/searchcommands.rst index ece2e6a08..a620fbb84 100644 --- a/docs/searchcommands.rst +++ b/docs/searchcommands.rst @@ -80,10 +80,6 @@ splunklib.searchcommands :members: :inherited-members: -.. autoclass:: Fieldname - :members: - :inherited-members: - .. autoclass:: File :members: :inherited-members: @@ -100,6 +96,3 @@ splunklib.searchcommands :members: :inherited-members: -.. autoclass:: Validator - :members: - :inherited-members: diff --git a/docs/searchcommandsvalidators.rst b/docs/searchcommandsvalidators.rst new file mode 100644 index 000000000..8a54db264 --- /dev/null +++ b/docs/searchcommandsvalidators.rst @@ -0,0 +1,12 @@ +splunklib.searchcommands.validators +----------------------------------- + +.. automodule:: splunklib.searchcommands.validators + +.. autoclass:: Fieldname + :members: + :inherited-members: + +.. autoclass:: Validator + :members: + :inherited-members: From 31e7beaaf38b3d9982cd6324b82fffaf2279456d Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:38:49 -0500 Subject: [PATCH 7/9] Stop complaints about "Search command style guide" WARNING: Duplicate explicit target name: "search command style guide". Switched `<>`_ to `<>`__ to links. Frankly, I don't understand the difference, but not more complains. --- splunklib/searchcommands/__init__.py | 2 +- splunklib/searchcommands/decorators.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/splunklib/searchcommands/__init__.py b/splunklib/searchcommands/__init__.py index 326e3e28e..c56c510d5 100644 --- a/splunklib/searchcommands/__init__.py +++ b/splunklib/searchcommands/__init__.py @@ -134,7 +134,7 @@ .. topic:: References - 1. `Search command style guide `_ + 1. `Search command style guide `__ 2. `Commands.conf.spec `_ diff --git a/splunklib/searchcommands/decorators.py b/splunklib/searchcommands/decorators.py index 02c1326e8..36590a76b 100644 --- a/splunklib/searchcommands/decorators.py +++ b/splunklib/searchcommands/decorators.py @@ -36,7 +36,7 @@ class Configuration(object): variable to search command classes that don't have one. The :code:`name` is derived from the name of the class. By convention command class names end with the word "Command". To derive :code:`name` the word "Command" is removed from the end of the class name and then converted to lower case for conformance with the `Search command style guide - `_ + `__ """ def __init__(self, o=None, **kwargs): From d7c989f3099a8874f393708b3cd7bb338e3c3d99 Mon Sep 17 00:00:00 2001 From: Lowell Alleman Date: Thu, 14 Feb 2019 17:53:05 -0500 Subject: [PATCH 8/9] All docs to the toctree to fix sidebar This doesn't seem ideal, but the prior behavior was that the side bar is ONLY usable on the index. As soon as you click on the sub-page you can see it's name, and nothing else. This makes navigation painful, IMHO. This seems like an improvements, even if not great. --- docs/index.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index b04f51b1d..8f209468f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,16 @@ For more information, see the `Splunk Developer Portal Date: Thu, 14 Feb 2019 17:57:45 -0500 Subject: [PATCH 9/9] Add ReadTheDocs badge to README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 4e67795ff..e23767b76 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ [![Build Status](https://travis-ci.org/splunk/splunk-sdk-python.svg?branch=master)](https://travis-ci.org/splunk/splunk-sdk-python) +[![Documentation Status](https://readthedocs.org/projects/splunk-python-sdk/badge/?version=latest)](https://splunk-python-sdk.readthedocs.io/en/latest/?badge=latest) + # The Splunk Software Development Kit for Python #### Version 1.6.6