Skip to content

Commit d17f63a

Browse files
mtevenan-splunkmtevenan-splunk
committed
Updates to doc strings
Punctuation, capitalization, other updates.
1 parent c4f663d commit d17f63a

9 files changed

Lines changed: 84 additions & 82 deletions

File tree

‎splunklib/modularinput/__init__.py‎

100644100755
File mode changed.

‎splunklib/modularinput/argument.py‎

100644100755
Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,16 @@
2020
class Argument(object):
2121
"""Class representing an argument to a modular input kind.
2222
23-
Argument is meant to be used with Scheme to generate an XML definition of the modular input
24-
kind that Splunk understands.
23+
``Argument`` is meant to be used with ``Scheme`` to generate an XML
24+
definition of the modular input kind that Splunk understands.
2525
26-
name is the only required parameter for the constructor
26+
``name`` is the only required parameter for the constructor.
2727
28-
Example with least parameters:
28+
**Example with least parameters**::
2929
3030
arg1 = Argument(name="arg1")
3131
32-
Example with all parameters:
32+
**Example with all parameters**::
3333
3434
arg2 = Argument(
3535
name="arg2",
@@ -50,14 +50,14 @@ class Argument(object):
5050
def __init__(self, name, description=None, validation=None,
5151
data_type=data_type_string, required_on_edit=False, required_on_create=False):
5252
"""
53-
:param name: string, identifier for this argument in Splunk
54-
:param description: string, human readable description of the argument
55-
:param validation: string, specifying how the argument should be validated, if using internal validation.
53+
:param name: ``string``, identifier for this argument in Splunk.
54+
:param description: ``string``, human-readable description of the argument.
55+
:param validation: ``string`` specifying how the argument should be validated, if using internal validation.
5656
If using external validation, this will be ignored.
57-
:param data_type: string, data type of this field; use the class constants
58-
data_type_boolean, data_type_number, or data_type_string
59-
:param required_on_edit: boolean, is this arg required when editing an existing modular input of this kind?
60-
:param required_on_create: boolean, is this arg required when creating a modular input of this kind?
57+
:param data_type: ``string``, data type of this field; use the class constants.
58+
"data_type_boolean", "data_type_number", or "data_type_string".
59+
:param required_on_edit: ``Boolean``, whether this arg is required when editing an existing modular input of this kind.
60+
:param required_on_create: ``Boolean``, whether this arg is required when creating a modular input of this kind.
6161
"""
6262
self.name = name
6363
self.description = description
@@ -67,13 +67,13 @@ def __init__(self, name, description=None, validation=None,
6767
self.required_on_create = required_on_create
6868

6969
def add_to_document(self, parent):
70-
"""Add an Argument object to this ElementTree Document
70+
"""Adds an ``Argument`` object to this ElementTree document.
7171
72-
Adds an <arg> SubElement to the Parent Element, typically <args>
73-
and setup its subelements with their respective text
72+
Adds an <arg> subelement to the parent element, typically <args>
73+
and sets up its subelements with their respective text.
7474
75-
:param parent: an ET.Element to be the parent of a new <arg> SubElement
76-
:return: an ET.Element object representing this argument #TODO: might not need to return here..
75+
:param parent: An ``ET.Element`` to be the parent of a new <arg> subelement
76+
:returns: An ``ET.Element`` object representing this argument. #TODO: might not need to return here..
7777
"""
7878
arg = ET.SubElement(parent, "arg")
7979
arg.set("name", self.name)

‎splunklib/modularinput/event.py‎

100644100755
Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,21 @@
2020
class Event(object):
2121
"""Represents an event or fragment of an event to be written by this modular input to Splunk.
2222
23-
To write an input to a stream, call the write_to function, passing in a stream.
23+
To write an input to a stream, call the ``write_to`` function, passing in a stream.
2424
"""
2525
def __init__(self, data=None, stanza=None, time=None, host=None, index=None, source=None,
2626
sourcetype=None, done=True, unbroken=True):
2727
"""There are no required parameters for constructing an Event
2828
29-
Example with minimal configuration:
29+
**Example with minimal configuration**::
3030
3131
my_event = Event(
3232
data="This is a test of my new event.",
3333
stanza="myStanzaName",
3434
time="%.3f" % 1372187084.000
3535
)
3636
37-
Example with full configuration:
37+
**Example with full configuration**::
3838
3939
excellent_event = Event(
4040
data="This is a test of my excellent event.",
@@ -48,15 +48,15 @@ def __init__(self, data=None, stanza=None, time=None, host=None, index=None, sou
4848
unbroken=True
4949
)
5050
51-
:param data: string, the event's text
52-
:param stanza: string, name of the input this event should be sent to
53-
:param time: float, time in seconds, including up to 3 decimal places to represent milliseconds
54-
:param host: string, the event's host, ex: localhost
55-
:param index: string, the index this event is specified to write to, or None if default index
56-
:param source: string, the source of this event, or None to have Splunk guess
57-
:param sourcetype: string, source type currently set on this event, or None to have Splunk guess
58-
:param done: boolean, is this a complete Event? False if an Event fragment
59-
:param unbroken: boolean, Is this event completely encapsulated in this Event object?
51+
:param data: ``string``, the event's text.
52+
:param stanza: ``string``, name of the input this event should be sent to.
53+
:param time: ``float``, time in seconds, including up to 3 decimal places to represent milliseconds.
54+
:param host: ``string``, the event's host, ex: localhost.
55+
:param index: ``string``, the index this event is specified to write to, or None if default index.
56+
:param source: ``string``, the source of this event, or None to have Splunk guess.
57+
:param sourcetype: ``string``, source type currently set on this event, or None to have Splunk guess.
58+
:param done: ``boolean``, is this a complete ``Event``? False if an ``Event`` fragment.
59+
:param unbroken: ``boolean``, Is this event completely encapsulated in this ``Event`` object?
6060
"""
6161
self.data = data
6262
self.done = done
@@ -69,12 +69,12 @@ def __init__(self, data=None, stanza=None, time=None, host=None, index=None, sou
6969
self.unbroken = unbroken
7070

7171
def write_to(self, stream):
72-
"""Write an XML representation of self, an Event object, to the given stream
72+
"""Write an XML representation of self, an ``Event`` object, to the given stream.
7373
74-
The Event object will only be written if its data field is defined,
75-
otherwise a ValueError is raised.
74+
The ``Event`` object will only be written if its data field is defined,
75+
otherwise a ``ValueError`` is raised.
7676
77-
:param stream: stream to write XML to
77+
:param stream: stream to write XML to.
7878
"""
7979
if self.data is None:
8080
raise ValueError("Events must have at least the data field set to be written to XML.")

‎splunklib/modularinput/event_writer.py‎

100644100755
Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,10 @@
2222
from StringIO import StringIO
2323

2424
class EventWriter(object):
25-
"""EventWriter writes events and error messages to Splunk from a modular input.
25+
"""``EventWriter`` writes events and error messages to Splunk from a modular input.
2626
27-
Its two important methods are writeEvent, which takes an Event object,
28-
and log, which takes a severity and an error message.
27+
Its two important methods are ``writeEvent``, which takes an ``Event`` object,
28+
and ``log``, which takes a severity and an error message.
2929
"""
3030

3131
# Severities that Splunk understands for log messages from modular inputs.
@@ -38,8 +38,8 @@ class EventWriter(object):
3838

3939
def __init__(self, output = sys.stdout, error = sys.stderr):
4040
"""
41-
:param output: where to write the output, defaults to sys.stdout
42-
:param error: where to write any errors, defaults to sys.stderr
41+
:param output: Where to write the output; defaults to sys.stdout.
42+
:param error: Where to write any errors; defaults to sys.stderr.
4343
"""
4444
self._out = output
4545
self._err = error
@@ -48,9 +48,9 @@ def __init__(self, output = sys.stdout, error = sys.stderr):
4848
self.header_written = False
4949

5050
def write_event(self, event):
51-
"""Write an Event object to Splunk.
51+
"""Writes an ``Event`` object to Splunk.
5252
53-
:param event: an Event object
53+
:param event: An ``Event`` object.
5454
"""
5555

5656
if not self.header_written:
@@ -60,21 +60,21 @@ def write_event(self, event):
6060
event.write_to(self._out)
6161

6262
def log(self, severity, message):
63-
"""Log messages about the state of this modular input to Splunk.
64-
These messages will show up in Splunk's internal logs
63+
"""Logs messages about the state of this modular input to Splunk.
64+
These messages will show up in Splunk's internal logs.
6565
66-
:param severity: string, severity of message, see severites defined as class constants
67-
:param message: message to log
66+
:param severity: ``string``, severity of message, see severites defined as class constants.
67+
:param message: Message to log.
6868
"""
6969

7070
self._err.write("%s %s\n" % (severity, message))
7171
self._err.flush()
7272

7373
def write_xml_document(self, document):
74-
"""Write a string representation of an
75-
ElementTree object to the output stream
74+
"""Writes a string representation of an
75+
``ElementTree`` object to the output stream.
7676
77-
:param document: an ElementTree object
77+
:param document: An ``ElementTree`` object.
7878
"""
7979
self._out.write(ET.tostring(document, "utf-8", "xml"))
8080
self._out.flush()

‎splunklib/modularinput/input_definition.py‎

100644100755
Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# Copyright 2011-2013 Splunk, Inc.
2+
#
13
# Licensed under the Apache License, Version 2.0 (the "License"): you may
24
# not use this file except in compliance with the License. You may obtain
35
# a copy of the License at
@@ -18,8 +20,8 @@
1820
from utils import parse_xml_data
1921

2022
class InputDefinition:
21-
"""InputDefinition encodes the XML defining inputs that Splunk passes to
22-
a modular input script
23+
"""``InputDefinition`` encodes the XML defining inputs that Splunk passes to
24+
a modular input script.
2325
2426
**Example**::
2527
@@ -37,10 +39,10 @@ def __eq__(self, other):
3739

3840
@staticmethod
3941
def parse(stream):
40-
"""Parse a stream containing XML into an InputDefinition.
42+
"""Parse a stream containing XML into an ``InputDefinition``.
4143
42-
:param stream: stream containing XML to parse
43-
:return: definition: a InputDefinition object
44+
:param stream: stream containing XML to parse.
45+
:return: definition: an ``InputDefinition`` object.
4446
"""
4547
definition = InputDefinition()
4648

‎splunklib/modularinput/scheme.py‎

100644100755
Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,10 @@
2020
class Scheme(object):
2121
"""Class representing the metadata for a modular input kind.
2222
23-
A Scheme specifies a title, description, several options of how Splunk should run modular inputs of this
23+
A ``Scheme`` specifies a title, description, several options of how Splunk should run modular inputs of this
2424
kind, and a set of arguments which define a particular modular input's properties.
2525
26-
The primary use of Scheme is to abstract away the construction of XML to feed to Splunk.
26+
The primary use of ``Scheme`` is to abstract away the construction of XML to feed to Splunk.
2727
"""
2828

2929
# Constant values, do not change
@@ -33,7 +33,7 @@ class Scheme(object):
3333

3434
def __init__(self, title):
3535
"""
36-
:param title: string identifier for this Scheme in Splunk
36+
:param title: ``string`` identifier for this Scheme in Splunk.
3737
"""
3838
self.title = title
3939
self.description = None
@@ -45,16 +45,16 @@ def __init__(self, title):
4545
self.arguments = []
4646

4747
def add_argument(self, arg):
48-
"""Add the provided argument, arg, to the self.arguments list
48+
"""Add the provided argument, ``arg``, to the ``self.arguments`` list.
4949
50-
:param arg: an Argument object to add to self.arguments
50+
:param arg: An ``Argument`` object to add to ``self.arguments``.
5151
"""
5252
self.arguments.append(arg)
5353

5454
def to_xml(self):
55-
"""Creates an ET.Element representing self, then returns it
55+
"""Creates an ``ET.Element`` representing self, then returns it.
5656
57-
:return root, an ET.Element representing this scheme
57+
:returns root, an ``ET.Element`` representing this scheme.
5858
"""
5959
root = ET.Element("scheme")
6060

‎splunklib/modularinput/script.py‎

100644100755
Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -28,20 +28,20 @@
2828
class Script(object):
2929
"""An abstract base class for implementing modular inputs.
3030
31-
Subclasses should override get_scheme, stream_events,
32-
and optionally validate_input if the modular Input uses
31+
Subclasses should override ``get_scheme``, ``stream_events``,
32+
and optionally ``validate_input`` if the modular input uses
3333
external validation.
3434
35-
The run function is used to run modular inputs, it typically should
35+
The ``run`` function is used to run modular inputs; it typically should
3636
not be overridden.
3737
"""
3838
__metaclass__ = ABCMeta
3939

4040
def run(self, args):
41-
"""Run this modular input
41+
"""Runs this modular input
4242
43-
:param args: list of command line arguments passed to this script
44-
:return: an integer to be used as the exit value of this program
43+
:param args: List of command line arguments passed to this script.
44+
:returns: An integer to be used as the exit value of this program.
4545
"""
4646

4747
# call the run_script function, which handles the specifics of running
@@ -51,10 +51,10 @@ def run(self, args):
5151
def run_script(self, args, event_writer, input_stream):
5252
"""Handles all the specifics of running a modular input
5353
54-
:param args: list of command line arguments passed to this script
55-
:param event_writer: an EventWriter object for writing events
56-
:param input_stream: an input stream for reading inputs
57-
:return: an integer to be used as the exit value of this program
54+
:param args: List of command line arguments passed to this script.
55+
:param event_writer: An ``EventWriter`` object for writing events.
56+
:param input_stream: An input stream for reading inputs.
57+
:returns: An integer to be used as the exit value of this program.
5858
"""
5959

6060
try:
@@ -101,21 +101,21 @@ def run_script(self, args, event_writer, input_stream):
101101
def get_scheme(self):
102102
"""The scheme defines the parameters understood by this modular input.
103103
104-
:return: a Scheme object representing the parameters for this modular input
104+
:return: a ``Scheme`` object representing the parameters for this modular input.
105105
"""
106106

107107
def validate_input(self, definition):
108108
"""Handles external validation for modular input kinds. When Splunk
109-
called a modular input script in validation mode, it will pass in an XML document
109+
calls a modular input script in validation mode, it will pass in an XML document
110110
giving information about the Splunk instance (so you can call back into it if needed)
111111
and the name and parameters of the proposed input.
112112
113113
If this function does not throw an exception, the validation is assumed to succeed.
114-
Otherwise any error throws will be turned into a string and logged back to Splunk.
114+
Otherwise any errors thrown will be turned into a string and logged back to Splunk.
115115
116116
The default implementation always passes.
117117
118-
:param definition: The parameters for the proposed input passed by splunkd
118+
:param definition: The parameters for the proposed input passed by splunkd.
119119
"""
120120
pass
121121

@@ -124,6 +124,6 @@ def stream_events(self, inputs, ew):
124124
"""The method called to stream events into Splunk. It should do all of its output via
125125
EventWriter rather than assuming that there is a console attached.
126126
127-
:param inputs: an InputDefinition object
128-
:param ew: an object with methods to write events and log messages to Splunk
127+
:param inputs: An ``InputDefinition`` object.
128+
:param ew: An object with methods to write events and log messages to Splunk.
129129
"""

‎splunklib/modularinput/utils.py‎

100644100755
Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,11 @@
1515
# File for utility functions
1616

1717
def xml_compare(expected, found):
18-
"""Checks equality of two ElementTree objects
18+
"""Checks equality of two ``ElementTree`` objects.
1919
20-
:param expected: an ElementTree object
21-
:param found: an ElementTree object
22-
:return: boolean, equality of expected and found
20+
:param expected: An ``ElementTree`` object.
21+
:param found: An ``ElementTree`` object.
22+
:return: ``Boolean``, whether the two objects are equal.
2323
"""
2424

2525
# if comparing the same ET object

‎splunklib/modularinput/validation_definition.py‎

100644100755
Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ def __eq__(self, other):
3838

3939
@staticmethod
4040
def parse(stream):
41-
"""Creates a ValidationDefinition from a provided stream containing XML.
41+
"""Creates a ``ValidationDefinition`` from a provided stream containing XML.
4242
4343
The XML typically will look like
4444
@@ -57,8 +57,8 @@ def parse(stream):
5757
</item>
5858
</items>
5959
60-
:param stream: stream containing XML to parse
61-
:return definition: a ValidationDefinition object
60+
:param stream: ``Stream`` containing XML to parse.
61+
:return definition: A ``ValidationDefinition`` object.
6262
"""
6363

6464
definition = ValidationDefinition()

0 commit comments

Comments
 (0)