Skip to content

Commit fec6e0d

Browse files
aprunedaapruneda
committed
edits
1 parent 181cbfe commit fec6e0d

File tree

1 file changed

+72
-190
lines changed

1 file changed

+72
-190
lines changed

‎README.md‎

Lines changed: 72 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -5,98 +5,69 @@
55

66
#### Version 1.6.14
77

8-
The Splunk Software Development Kit (SDK) for Python contains library code and
9-
examples designed to enable developers to build applications using Splunk.
8+
The Splunk Software Development Kit (SDK) for Python contains library code and examples designed to enable developers to build applications using the Splunk platform.
109

11-
Splunk is a search engine and analytic environment that uses a distributed
12-
map-reduce architecture to efficiently index, search and process large
13-
time-varying data sets.
10+
Splunk is a search engine and analytic environment that uses a distributed map-reduce architecture to efficiently index, search, and process large time-varying data sets.
1411

15-
The Splunk product is popular with system administrators for aggregation and
16-
monitoring of IT machine data, security, compliance and a wide variety of other
17-
scenarios that share a requirement to efficiently index, search, analyze and
18-
generate real-time notifications from large volumes of time series data.
12+
The Splunk platform is popular with system administrators for aggregation and monitoring of IT machine data, security, compliance, and a wide variety of other scenarios that share a requirement to efficiently index, search, analyze, and generate real-time notifications from large volumes of time-series data.
1913

20-
The Splunk developer platform enables developers to take advantage of the same
21-
technology used by the Splunk product to build exciting new applications that
22-
are enabled by Splunk's unique capabilities.
14+
The Splunk developer platform enables developers to take advantage of the same technology used by the Splunk platform to build exciting new applications.
2315

2416

25-
## Getting started with the Splunk SDK for Python
17+
## Get started with the Splunk SDK for Python
2618

27-
The Splunk SDK for Python contains library code and examples that show how to
28-
programmatically interact with Splunk for a variety of scenarios including
29-
searching, saved searches, data inputs, and many more, along with building
30-
complete applications.
19+
The Splunk SDK for Python contains library code and examples that show how to programmatically interact with Splunk for a variety of scenarios including searching, saved searches, data inputs, and many more, along with building complete applications.
3120

32-
The information in this Readme provides steps to get going quickly, but for more
33-
in-depth information be sure to visit the
34-
[Splunk Developer Portal](http://dev.splunk.com/view/SP-CAAAEBB).
3521
### Requirements
3622

3723
Here's what you need to get going with the Splunk SDK for Python.
3824

3925
#### Python
4026

41-
The Splunk SDK for Python requires Python 2.7+, including Python 3. The Splunk SDK for Python has been tested with Python v2.7 and v3.5.
27+
The Splunk SDK for Python requires Python 2.7+ and Python 3. The Splunk SDK for Python has been tested with Python v2.7 and v3.5.
4228

4329
#### Splunk
4430

45-
If you haven't already installed Splunk, download it
46-
[here](http://www.splunk.com/download). For more about installing and running
47-
Splunk and system requirements, see
48-
[Installing & Running Splunk](http://dev.splunk.com/view/SP-CAAADRV). The Splunk SDK for Python has been tested with Splunk Enterprise 7.0 and 7.2.
31+
If you haven't already installed Splunk, download it [here](http://www.splunk.com/download).
32+
For more information, see [System requirements for use of Splunk Enterprise on-premises](https://docs.splunk.com/Documentation/Splunk/latest/Installation/Systemrequirements) in the Splunk Enterprise _Installation Manual_.
4933

5034
#### Splunk SDK for Python
51-
Get the Splunk SDK for Python; [download the SDK as a ZIP](http://dev.splunk.com/view/SP-CAAAEBB)
52-
and extract the files. Or, if you want to contribute to the SDK, clone the
53-
repository from [GitHub](https://github.com/splunk/splunk-sdk-python).
5435

36+
Get the Splunk SDK for Python from [PyPI](https://pypi.org/project/splunk-sdk/). If you want to contribute to the SDK, clone the repository from [GitHub](https://github.com/splunk/splunk-sdk-python).
5537

56-
### Installing the SDK
5738

58-
You can install the Splunk SDK for Python libraries by using `easy_install` or `pip`:
39+
### Install the SDK
40+
41+
Use the following commands to install the Splunk SDK for Python libraries in different ways. However, it's not necessary to install the libraries to run the examples and unit tests from the SDK.
42+
43+
Use `easy_install`:
5944

6045
[sudo] easy_install splunk-sdk
6146

62-
Or
47+
Use `pip`:
6348

6449
[sudo] pip install splunk-sdk
6550

66-
Or to install the Python egg
51+
Install the Python egg:
6752

6853
[sudo] pip install --egg splunk-sdk
6954

70-
Alternatively, you can use **setup.py** on the sources you cloned from GitHub:
55+
Install the sources you cloned from GitHub:
7156

7257
[sudo] python setup.py install
7358

74-
However, it's not necessary to install the libraries to run the
75-
examples and unit tests from the SDK.
76-
7759

78-
### Running the examples and unit tests
60+
### Run the examples and unit tests
7961

80-
To run the examples and unit tests, you must put the root of
81-
the SDK on your PYTHONPATH. For example, if you have downloaded the SDK to your
82-
home folder and are running OS X or Linux, add the following line to your
83-
**.bash_profile**:
62+
To run the examples and unit tests, you must put the root of the SDK on your PYTHONPATH. For example, if you downloaded the SDK to your home folder and are running OS X or Linux, add the following line to your **.bash_profile** file:
8463

8564
export PYTHONPATH=~/splunk-sdk-python
8665

87-
The SDK command-line examples require a common set of arguments
88-
that specify things like the Splunk host, port, and login credentials. For a
89-
full list of command-line arguments, include `--help` as an argument to any of
90-
the examples.
66+
The SDK command-line examples require a common set of arguments that specify the host, port, and login credentials for Splunk Enterprise. For a full list of command-line arguments, include `--help` as an argument to any of the examples.
9167

9268
#### .splunkrc
9369

94-
To connect to Splunk, many of the SDK examples and unit tests take command-line
95-
arguments that specify values for the host, port, and login credentials for
96-
Splunk. For convenience during development, you can store these arguments as
97-
key-value pairs in a text file named **.splunkrc**. Then, the SDK examples and
98-
unit tests use the values from the **.splunkrc** file when you don't specify
99-
them.
70+
To connect to Splunk, many of the SDK examples and unit tests take command-line arguments that specify values for the host, port, and login credentials for Splunk Enterprise. For convenience during development, you can store these arguments as key-value pairs in a text file named **.splunkrc**. Then, the SDK examples and unit tests use the values from the **.splunkrc** file when you don't specify them.
10071

10172
To use this convenience file, create a text file with the following format:
10273

@@ -110,8 +81,8 @@ To use this convenience file, create a text file with the following format:
11081
password=changeme
11182
# Access scheme (default: https)
11283
scheme=https
113-
# Your version of Splunk (default: 5.0)
114-
version=5.0
84+
# Your version of Splunk
85+
version=8.0
11586

11687
Save the file as **.splunkrc** in the current user's home directory.
11788

@@ -123,32 +94,22 @@ Save the file as **.splunkrc** in the current user's home directory.
12394

12495
C:\Users\currentusername\.splunkrc
12596

126-
You might get errors in Windows when you try to name the file because
127-
".splunkrc" looks like a nameless file with an extension. You can use
128-
the command line to create this file—go to the
129-
**C:\Users\currentusername** directory and enter the following command:
97+
You might get errors in Windows when you try to name the file because ".splunkrc" appears to be a nameless file with an extension. You can use the command line to create this file by going to the **C:\Users\**_currentusername_ directory and entering the following command:
13098

13199
Notepad.exe .splunkrc
132100

133101
Click **Yes**, then continue creating the file.
134102

135-
**Note**: Storing login credentials in the **.splunkrc** file is only for
136-
convenience during development. This file isn't part of the Splunk platform and
137-
shouldn't be used for storing user credentials for production. And, if you're
138-
at all concerned about the security of your credentials, just enter them at
139-
the command line rather than saving them in this file.
103+
**Note**: Storing login credentials in the **.splunkrc** file is only for convenience during development. This file isn't part of the Splunk platform and shouldn't be used for storing user credentials for production. And, if you're at all concerned about the security of your credentials, enter them at the command line rather than saving them in this file.
140104

141105

142106
#### Examples
143107

144-
Examples are located in the **/splunk-sdk-python/examples** directory. To run
145-
the examples at the command line, use the Python interpreter and include any
146-
arguments that are required by the example:
108+
Examples are located in the **/splunk-sdk-python/examples** directory. To run the examples at the command line, use the Python interpreter and include any arguments that are required by the example:
147109

148110
python examplename.py --username="admin" --password="changeme"
149111

150-
If you saved your login credentials in the **.splunkrc** file, you can omit
151-
those arguments:
112+
If you saved your login credentials in the **.splunkrc** file, you can omit those arguments:
152113

153114
python examplename.py
154115

@@ -158,172 +119,93 @@ To get help for an example, use the `--help` argument with an example:
158119

159120
#### Unit tests
160121

161-
The Splunk SDK for Python contains a collection of unit tests. To run them, open a
162-
command prompt in the **/splunk-sdk-python** directory and enter:
122+
The Splunk SDK for Python contains a collection of unit tests. To run them, open a command prompt in the **/splunk-sdk-python** directory and enter:
163123

164124
make
165125

166-
You can also run individual test files, which are located in
167-
**/splunk-sdk-python/tests**. The following command explains how to run
168-
a specific test:
126+
You can also run individual test files, which are located in **/splunk-sdk-python/tests**. To run a specific test, enter:
169127

170-
make test_specific
128+
make specific_test_name
171129

172-
The test suite uses Python's standard library, the built-in `unittest`
173-
library, `pytest`, and `tox`.
130+
The test suite uses Python's standard library, the built-in `unittest` library, `pytest`, and `tox`.
174131

175-
**Important Notes:**
132+
**Notes:**
176133

177-
The test run will fail unless the
178-
[SDK App Collection](https://github.com/splunk/sdk-app-collection) is installed.
134+
The test run fails unless the [SDK App Collection](https://github.com/splunk/sdk-app-collection) app is installed.
179135

180-
You can exclude app-specific tests with the following command:
136+
To exclude app-specific tests, use the following command:
181137

182138
make test_no_app
183139

184-
You can read more about our testing framework on
185-
[GitHub](https://github.com/splunk/splunk-sdk-python/tree/master/tests).
140+
To learn about our testing framework, see [Splunk Test Suite](https://github.com/splunk/splunk-sdk-python/tree/master/tests) on GitHub.
186141

187-
In addition, the test run requires the searchcommands app to be built. The `make`
188-
command runs the tasks to do this, but more complex testing may require you to
189-
rebuild using `make build_app`.
142+
In addition, the test run requires you to build the searchcommands app. The `make` command runs the tasks to do this, but more complex testing may require you to rebuild using the `make build_app` command.
190143

191144
## Repository
192145

193-
<table>
194-
195-
<tr>
196-
<td><b>/docs</b></td>
197-
<td>Source for Sphinx-based docs and build</td>
198-
</tr>
199-
200-
<tr>
201-
<td><b>/examples</b></td>
202-
<td>Examples demonstrating various SDK features</td>
203-
<tr>
204-
205-
<tr>
206-
<td><b>/splunklib</b></td>
207-
<td>Source for the Splunk library modules</td>
208-
<tr>
209-
210-
<tr>
211-
<td><b>/tests</b></td>
212-
<td>Source for unit tests</td>
213-
<tr>
214-
215-
<tr>
216-
<td><b>/utils</b></td>
217-
<td>Source for utilities shared by the examples and unit tests</td>
218-
<tr>
219-
220-
</table>
146+
| Directory | Description |
147+
|:--------- |:---------------------------------------------------------- |
148+
|/docs | Source for Sphinx-based docs and build |
149+
|/examples | Examples demonstrating various SDK features |
150+
|/splunklib | Source for the Splunk library modules |
151+
|/tests | Source for unit tests |
152+
|/utils | Source for utilities shared by the examples and unit tests |
221153

222154
### Changelog
223155

224-
The **CHANGELOG.md** file in the root of the repository contains a description
225-
of changes for each version of the SDK. You can also find it online at
226-
[https://github.com/splunk/splunk-sdk-python/blob/master/CHANGELOG.md](https://github.com/splunk/splunk-sdk-python/blob/master/CHANGELOG.md).
156+
The CHANGELOG.md file in the root of this repository contains a description
157+
of changes for each version of the SDK. For the latest version, see the [CHANGELOG.md](https://github.com/splunk/splunk-sdk-python/blob/master/CHANGELOG.md) on GitHub.
227158

228159
### Branches
229160

230-
The **master** branch always represents a stable and released version of the SDK.
231-
You can read more about our branching model on our Wiki at
232-
[https://github.com/splunk/splunk-sdk-python/wiki/Branching-Model](https://github.com/splunk/splunk-sdk-python/wiki/Branching-Model).
161+
The **master** branch represents a stable and released version of the SDK.
162+
To learn about our branching model, see [Branching Model](https://github.com/splunk/splunk-sdk-python/wiki/Branching-Model) on GitHub.
233163

234164
## Documentation and resources
235-
If you need to know more:
236-
237-
* For all things developer with Splunk, your main resource is the
238-
[Splunk Developer Portal](http://dev.splunk.com).
239-
240-
* For conceptual and how-to documentation, see the
241-
[Overview of the Splunk SDK for Python](http://dev.splunk.com/view/SP-CAAAEBB).
242-
243-
* For API reference documentation, see the
244-
[Splunk SDK for Python Reference](http://docs.splunk.com/Documentation/PythonSDK).
245165

246-
* For more about the Splunk REST API, see the
247-
[REST API Reference](http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI).
166+
| Resource | Description |
167+
|:----------------------- |:----------- |
168+
| [Splunk Developer Portal](http://dev.splunk.com) | General developer documentation, tools, and examples |
169+
| [Integrate the Splunk platform using development tools for Python](https://dev.splunk.com/enterprise/docs/devtools/python)| Documentation for Python development |
170+
| [Splunk SDK for Python Reference](http://docs.splunk.com/Documentation/PythonSDK) | SDK API reference documentation |
171+
| [REST API Reference Manual](https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTprolog) | Splunk REST API reference documentation |
172+
| [Splunk>Docs](https://docs.splunk.com/Documentation) | General documentation for the Splunk platform |
173+
| [GitHub Wiki](https://github.com/splunk/splunk-sdk-python/wiki/) | Documentation for this SDK's repository on GitHub |
248174

249-
* For more about about Splunk in general, see
250-
[Splunk>Docs](http://docs.splunk.com/Documentation/Splunk).
251-
252-
* For more about this SDK's repository, see our
253-
[GitHub Wiki](https://github.com/splunk/splunk-sdk-python/wiki/).
254175

255176
## Community
256177

257-
Stay connected with other developers building on Splunk.
258-
259-
<table>
260-
261-
<tr>
262-
<td><b>Email</b></td>
263-
<td>[email protected]</td>
264-
</tr>
178+
Stay connected with other developers building on the Splunk platform.
265179

266-
<tr>
267-
<td><b>Issues</b>
268-
<td><span>https://github.com/splunk/splunk-sdk-python/issues/</span></td>
269-
</tr>
180+
* [Email](mailto:[email protected])
181+
* [Issues and pull requests](https://github.com/splunk/splunk-sdk-python/issues/)
182+
* [Community Slack](https://splunk-usergroups.slack.com/app_redirect?channel=appdev)
183+
* [Splunk Answers](https://community.splunk.com/t5/Splunk-Development/ct-p/developer-tools)
184+
* [Splunk Blogs](https://www.splunk.com/blog)
185+
* [Twitter](https://twitter.com/splunkdev)
270186

271-
<tr>
272-
<td><b>Answers</b>
273-
<td><span>http://splunk-base.splunk.com/tags/python/</span></td>
274-
</tr>
275-
276-
<tr>
277-
<td><b>Blog</b>
278-
<td><span>http://blogs.splunk.com/dev/</span></td>
279-
</tr>
280-
281-
<tr>
282-
<td><b>Twitter</b>
283-
<td>@splunkdev</td>
284-
</tr>
187+
### How to contribute
285188

286-
</table>
189+
If you would like to contribute to the SDK, see [Contributions to Splunk](https://www.splunk.com/en_us/form/contributions.html).
287190

288-
### How to contribute
191+
### Support
289192

290-
If you would like to contribute to the SDK, go here for more information:
193+
1. You will be granted support if you or your company are already covered under an existing maintenance/support agreement.
291194

292-
* [Splunk and open source](http://dev.splunk.com/view/opensource/SP-CAAAEDM)
195+
Submit a new case in the [Support Portal](https://www.splunk.com/en_us/support-and-services.html)) and include "Splunk SDK for Python" in the subject line.
293196

294-
* [Individual contributions](http://dev.splunk.com/goto/individualcontributions)
197+
2. If you are not covered under an existing maintenance/support agreement, you can find help through the broader community at [Splunk Answers](https://community.splunk.com/t5/Splunk-Development/ct-p/developer-tools).
295198

296-
* [Company contributions](http://dev.splunk.com/view/companycontributions/SP-CAAAEDR)
199+
3. Splunk will NOT provide support for SDKs if the core library (the code in the <b>/splunklib</b> directory) has been modified. If you modify an SDK and want support, you can find help through the broader community and [Splunk Answers](https://community.splunk.com/t5/Splunk-Development/ct-p/developer-tools).
297200

298-
### Support
201+
We would also like to know why you modified the core library, so please send feedback to _[email protected]_.
299202

300-
1. You will be granted support if you or your company are already covered
301-
under an existing maintenance/support agreement.
302-
Submit a new case in the [Support Portal][contact] and include "Splunk SDK for Python"
303-
in the subject line.
304-
2. If you are not covered under an existing maintenance/support agreement, you
305-
can find help through the broader community at:
306-
<ul>
307-
<li><a href='http://splunk-base.splunk.com/answers/'>Splunk Answers</a> (use
308-
the <b>sdk</b>, <b>java</b>, <b>python</b>, and <b>javascript</b> tags to
309-
identify your questions)</li>
310-
</ul>
311-
3. Splunk will NOT provide support for SDKs if the core library (the
312-
code in the <b>/splunklib</b> directory) has been modified. If you modify an
313-
SDK and want support, you can find help through the broader community and
314-
Splunk answers (see above). We would also like to know why you modified the
315-
core library&mdash;please send feedback to [email protected].
316203
4. File any issues on [GitHub](https://github.com/splunk/splunk-sdk-python/issues).
317204

318205
### Contact Us
319206

320-
You can [contact support][contact] if you have Splunk related questions.
321-
322207
You can reach the Developer Platform team at _[email protected]_.
323208

324209
## License
325210

326-
The Splunk Software Development Kit for Python is licensed under the Apache
327-
License 2.0. Details can be found in the file LICENSE.
328-
329-
[contact]: https://www.splunk.com/en_us/support-and-services.html
211+
The Splunk Software Development Kit for Python is licensed under the Apache License 2.0. Details can be found in the file LICENSE.

0 commit comments

Comments
 (0)