# Copyright © 2011-2026 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.

"""The **splunklib.binding** module provides a low-level binding interface to the

`Splunk REST API <http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI/RESTcontents>`_.

This module handles the wire details of calling the REST API, such as

authentication tokens, prefix paths, URL encoding, and so on. Actual path

segments, ``GET`` and ``POST`` arguments, and the parsing of responses is left

to the user.

If you want a friendlier interface to the Splunk REST API, use the

:mod:`splunklib.client` module.

"""

import importlib.metadata

import io

import json

import logging

import socket

import ssl

import time

from base64 import b64encode

from contextlib import contextmanager

from datetime import datetime

from functools import wraps

from http import client

from http.cookies import SimpleCookie

from io import BytesIO

from urllib import parse

from xml.etree.ElementTree import XML, ParseError

from .data import record

logger = logging.getLogger(__name__)

__all__ = [

"AuthenticationError",

"Context",

"HTTPError",

"UrlEncoded",

"_NoAuthenticationToken",

"_encode",

"_make_cookie_header",

"connect",

"handler",

"namespace",

]

SENSITIVE_KEYS = [

"Authorization",

"Cookie",

"action.email.auth_password",

"auth",

"auth_password",

"clear_password",

"clientId",

"crc-salt",

"encr_password",

"oldpassword",

"passAuth",

"password",

"session",

"suppressionKey",

"token",

]

# If you change these, update the docstring

# on _authority as well.

DEFAULT_HOST = "localhost"

DEFAULT_PORT = "8089"

DEFAULT_SCHEME = "https"

def _log_duration(f):

@wraps(f)

def new_f(*args, **kwargs):

start_time = datetime.now()

val = f(*args, **kwargs)

end_time = datetime.now()

logger.debug("Operation took %s", end_time - start_time)

return val

return new_f

def mask_sensitive_data(data):

"""

Masked sensitive fields data for logging purpose

"""

if not isinstance(data, dict):

try:

data = json.loads(data)

except Exception:

return data

# json.loads will return "123"(str) as 123(int), so return the data if it's not 'dict' type

if not isinstance(data, dict):

return data

mdata = {}

for k, v in data.items():

if k in SENSITIVE_KEYS:

mdata[k] = "******"

else:

mdata[k] = mask_sensitive_data(v)

return mdata

def _parse_cookies(cookie_str, dictionary):

"""Tries to parse any key-value pairs of cookies in a string,

then updates the the dictionary with any key-value pairs found.

**Example**::

dictionary = {}

_parse_cookies("my=value", dictionary)

# Now the following is True

dictionary["my"] == "value"

:param cookie_str: A string containing "key=value" pairs from an HTTP "Set-Cookie" header.

:type cookie_str: ``str``

:param dictionary: A dictionary to update with any found key-value pairs.

:type dictionary: ``dict``

"""

parsed_cookie = SimpleCookie(cookie_str)

for cookie in parsed_cookie.values():

dictionary[cookie.key] = cookie.coded_value

def _make_cookie_header(cookies):

"""

Takes a list of 2-tuples of key-value pairs of

cookies, and returns a valid HTTP ``Cookie``

header.

**Example**::

header = _make_cookie_header([("key", "value"), ("key_2", "value_2")])

# Now the following is True

header == "key=value; key_2=value_2"

:param cookies: A list of 2-tuples of cookie key-value pairs.

:type cookies: ``list`` of 2-tuples

:return: ``str` An HTTP header cookie string.

:rtype: ``str``

"""

return "; ".join(f"{key}={value}" for key, value in cookies)

# Singleton values to eschew None

class _NoAuthenticationToken:

"""The value stored in a :class:`Context` or :class:`splunklib.client.Service`

class that is not logged in.

If a ``Context`` or ``Service`` object is created without an authentication

token, and there has not yet been a call to the ``login`` method, the token

field of the ``Context`` or ``Service`` object is set to

``_NoAuthenticationToken``.

Likewise, after a ``Context`` or ``Service`` object has been logged out, the

token is set to this value again.

"""

class UrlEncoded(str):

"""This class marks URL-encoded strings.

It should be considered an SDK-private implementation detail.

Manually tracking whether strings are URL encoded can be difficult. Avoid

calling ``urllib.quote`` to replace special characters with escapes. When

you receive a URL-encoded string, *do* use ``urllib.unquote`` to replace

escapes with single characters. Then, wrap any string you want to use as a

URL in ``UrlEncoded``. Note that because the ``UrlEncoded`` class is

idempotent, making multiple calls to it is OK.

``UrlEncoded`` objects are identical to ``str`` objects (including being

equal if their contents are equal) except when passed to ``UrlEncoded``

again.

``UrlEncoded`` removes the ``str`` type support for interpolating values

with ``%`` (doing that raises a ``TypeError``). There is no reliable way to

encode values this way, so instead, interpolate into a string, quoting by

hand, and call ``UrlEncode`` with ``skip_encode=True``.

**Example**::

import urllib

UrlEncoded(f"{scheme}://{urllib.quote(host)}", skip_encode=True)

If you append ``str`` strings and ``UrlEncoded`` strings, the result is also

URL encoded.

**Example**::

UrlEncoded("ab c") + "de f" == UrlEncoded("ab cde f")

"ab c" + UrlEncoded("de f") == UrlEncoded("ab cde f")

"""

def __new__(self, val="", skip_encode=False, encode_slash=False):

if isinstance(val, UrlEncoded):

# Don't urllib.quote something already URL encoded.

return val

if skip_encode:

return str.__new__(self, val)

if encode_slash:

return str.__new__(self, parse.quote_plus(val))

# When subclassing str, just call str.__new__ method

# with your class and the value you want to have in the

# new string.

return str.__new__(self, parse.quote(val))

def __add__(self, other):

"""self + other

If *other* is not a ``UrlEncoded``, URL encode it before

adding it.

"""

if isinstance(other, UrlEncoded):

return UrlEncoded(str.__add__(self, other), skip_encode=True)

return UrlEncoded(str.__add__(self, parse.quote(other)), skip_encode=True)

def __radd__(self, other):

"""other + self

If *other* is not a ``UrlEncoded``, URL _encode it before

adding it.

"""

if isinstance(other, UrlEncoded):

return UrlEncoded(str.__radd__(self, other), skip_encode=True)

return UrlEncoded(str.__add__(parse.quote(other), self), skip_encode=True)

def __mod__(self, fields):

"""Interpolation into ``UrlEncoded``s is disabled.

If you try to write ``UrlEncoded("%s") % "abc", will get a

``TypeError``.

"""

raise TypeError("Cannot interpolate into a UrlEncoded object.")

def __repr__(self):

return f"UrlEncoded({parse.unquote(str(self))!r})"

@contextmanager

def _handle_auth_error(msg):

"""Handle re-raising HTTP authentication errors as something clearer.

If an ``HTTPError`` is raised with status 401 (access denied) in

the body of this context manager, re-raise it as an

``AuthenticationError`` instead, with *msg* as its message.

This function adds no round trips to the server.

:param msg: The message to be raised in ``AuthenticationError``.

:type msg: ``str``

**Example**::

with _handle_auth_error("Your login failed."):

... # make an HTTP request

"""

try:

yield

except HTTPError as he:

if he.status == 401:

raise AuthenticationError(msg, he)

else:

raise

def _authentication(request_fun):

"""Decorator to handle autologin and authentication errors.

*request_fun* is a function taking no arguments that needs to

be run with this ``Context`` logged into Splunk.

``_authentication``'s behavior depends on whether the

``autologin`` field of ``Context`` is set to ``True`` or

``False``. If it's ``False``, then ``_authentication``

aborts if the ``Context`` is not logged in, and raises an

``AuthenticationError`` if an ``HTTPError`` of status 401 is

raised in *request_fun*. If it's ``True``, then

``_authentication`` will try at all sensible places to

log in before issuing the request.

If ``autologin`` is ``False``, ``_authentication`` makes

one roundtrip to the server if the ``Context`` is logged in,

or zero if it is not. If ``autologin`` is ``True``, it's less

deterministic, and may make at most three roundtrips (though

that would be a truly pathological case).

:param request_fun: A function of no arguments encapsulating

the request to make to the server.

**Example**::

import splunklib.binding as binding

c = binding.connect(..., autologin=True)

c.logout()

def f():

c.get("/services")

return 42

print(_authentication(f))

"""

@wraps(request_fun)

def wrapper(self, *args, **kwargs):

if self.token is _NoAuthenticationToken and not self.has_cookies():

# Not yet logged in.

if self.autologin and self.username and self.password:

# This will throw an uncaught

# AuthenticationError if it fails.

self.login()

else:

# Try the request anyway without authentication.

# Most requests will fail. Some will succeed, such as

# 'GET server/info'.

with _handle_auth_error("Request aborted: not logged in."):

return request_fun(self, *args, **kwargs)

try:

# Issue the request

return request_fun(self, *args, **kwargs)

except HTTPError as he:

if he.status == 401 and self.autologin:

# Authentication failed. Try logging in, and then

# rerunning the request. If either step fails, throw

# an AuthenticationError and give up.

with _handle_auth_error("Autologin failed."):

self.login()

with _handle_auth_error(

"Authentication Failed! If session token is used, it seems to have been expired."

):

return request_fun(self, *args, **kwargs)

elif he.status == 401 and not self.autologin:

raise AuthenticationError("Request failed: Session is not logged in.", he)

else:

raise

return wrapper

def _authority(scheme=DEFAULT_SCHEME, host=DEFAULT_HOST, port=DEFAULT_PORT):

"""Construct a URL authority from the given *scheme*, *host*, and *port*.

Named in accordance with RFC2396_, which defines URLs as::

<scheme>://<authority><path>?<query>

.. _RFC2396: http://www.ietf.org/rfc/rfc2396.txt

So ``https://localhost:8000/a/b/b?boris=hilda`` would be parsed as::

scheme := https

authority := localhost:8000

path := /a/b/c

query := boris=hilda

:param scheme: URL scheme (the default is "https")

:type scheme: "http" or "https"

:param host: The host name (the default is "localhost")

:type host: string

:param port: The port number (the default is 8089)

:type port: integer

:return: The URL authority.

:rtype: UrlEncoded (subclass of ``str``)

**Example**::

_authority() == "https://localhost:8089"

_authority(host="splunk.utopia.net") == "https://splunk.utopia.net:8089"

_authority(host="2001:0db8:85a3:0000:0000:8a2e:0370:7334") == \

"https://[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:8089"

_authority(scheme="http", host="splunk.utopia.net", port="471") == \

"http://splunk.utopia.net:471"

"""

# check if host is an IPv6 address and not enclosed in [ ]

if ":" in host and not (host.startswith("[") and host.endswith("]")):

# IPv6 addresses must be enclosed in [ ] in order to be well

# formed.

host = "[" + host + "]"

return UrlEncoded(f"{scheme}://{host}:{port}", skip_encode=True)

# kwargs: sharing, owner, app

def namespace(sharing=None, owner=None, app=None, **kwargs):

"""This function constructs a Splunk namespace.

Every Splunk resource belongs to a namespace. The namespace is specified by

the pair of values ``owner`` and ``app`` and is governed by a ``sharing`` mode.

The possible values for ``sharing`` are: "user", "app", "global" and "system",

which map to the following combinations of ``owner`` and ``app`` values:

"user" => {owner}, {app}

"app" => nobody, {app}

"global" => nobody, {app}

"system" => nobody, system

"nobody" is a special user name that basically means no user, and "system"

is the name reserved for system resources.

"-" is a wildcard that can be used for both ``owner`` and ``app`` values and

refers to all users and all apps, respectively.

In general, when you specify a namespace you can specify any combination of

these three values and the library will reconcile the triple, overriding the

provided values as appropriate.

Finally, if no namespacing is specified the library will make use of the

``/services`` branch of the REST API, which provides a namespaced view of

Splunk resources equivelent to using ``owner={currentUser}`` and

``app={defaultApp}``.

The ``namespace`` function returns a representation of the namespace from

reconciling the values you provide. It ignores any keyword arguments other

than ``owner``, ``app``, and ``sharing``, so you can provide ``dicts`` of

configuration information without first having to extract individual keys.

:param sharing: The sharing mode (the default is "user").

:type sharing: "system", "global", "app", or "user"

:param owner: The owner context (the default is "None").

:type owner: ``string``

:param app: The app context (the default is "None").

:type app: ``string``

:returns: A :class:`splunklib.data.Record` containing the reconciled

namespace.

**Example**::

import splunklib.binding as binding

n = binding.namespace(sharing="user", owner="boris", app="search")

n = binding.namespace(sharing="global", app="search")

"""

if sharing in ["system"]:

return record({"sharing": sharing, "owner": "nobody", "app": "system"})

if sharing in ["global", "app"]:

return record({"sharing": sharing, "owner": "nobody", "app": app})

if sharing in ["user", None]:

return record({"sharing": sharing, "owner": owner, "app": app})

raise ValueError("Invalid value for argument: 'sharing'")

class Context:

"""This class represents a context that encapsulates a splunkd connection.

The ``Context`` class encapsulates the details of HTTP requests,

authentication, a default namespace, and URL prefixes to simplify access to

the REST API.

After creating a ``Context`` object, you must call its :meth:`login`

method before you can issue requests to splunkd. Or, use the :func:`connect`

function to create an already-authenticated ``Context`` object. You can

provide a session token explicitly (the same token can be shared by multiple

``Context`` objects) to provide authentication.

:param host: The host name (the default is "localhost").

:type host: ``string``

:param port: The port number (the default is 8089).

:type port: ``integer``

:param scheme: The scheme for accessing the service (the default is "https").

:type scheme: "https" or "http"

:param verify: Enable (True) or disable (False) SSL verification for https connections.

:type verify: ``Boolean``

:param self_signed_certificate: Specifies if self signed certificate is used

:type self_signed_certificate: ``Boolean``

:param `key_file`: Path to a PEM-encoded private key.

:type key_file: ``string``

:param `cert_file`: Path to a PEM-encoded X509 certificate chain.

:type cert_file: ``string``

:param `context`: Custom SSLContext used with the HTTPSConnection, requires verify=True.

:type context: ``SSLContext``

:param sharing: The sharing mode for the namespace (the default is "user").

:type sharing: "global", "system", "app", or "user"

:param owner: The owner context of the namespace (optional, the default is "None").

:type owner: ``string``

:param app: The app context of the namespace (optional, the default is "None").

:type app: ``string``

:param token: A session token. When provided, you don't need to call :meth:`login`.

:type token: ``string``

:param cookie: A session cookie. When provided, you don't need to call :meth:`login`.

This parameter is only supported for Splunk 6.2+.

:type cookie: ``string``

:param username: The Splunk account username, which is used to

authenticate the Splunk instance.

:type username: ``string``

:param password: The password for the Splunk account.

:type password: ``string``

:param splunkToken: Splunk authentication token

:type splunkToken: ``string``

:param headers: List of extra HTTP headers to send (optional).

:type headers: ``list`` of 2-tuples.

:param retries: Number of retries for each HTTP connection (optional, the default is 0).

NOTE: THIS MAY INCREASE THE NUMBER OF ROUNDTRIP CONNECTIONS

TO THE SPLUNK SERVER AND BLOCK THE CURRENT THREAD WHILE RETRYING.

:type retries: ``int``

:param retryDelay: How long to wait between connection attempts if `retries` > 0 (optional, defaults to 10s).

:type retryDelay: ``int`` (in seconds)

:param handler: The HTTP request handler (optional).

:returns: A ``Context`` instance.

**Example**::

import splunklib.binding as binding

c = binding.Context(username="boris", password="natasha", ...)

c.login()

# Or equivalently

c = binding.connect(username="boris", password="natasha")

# Or if you already have a session token

c = binding.Context(token="atg232342aa34324a")

# Or if you already have a valid cookie

c = binding.Context(cookie="splunkd_8089=...")

"""

def __init__(self, handler=None, **kwargs):

self.http = HttpLib(

handler,

kwargs.get("verify", False),

key_file=kwargs.get("key_file"),

cert_file=kwargs.get("cert_file"),

context=kwargs.get("context"),

# Default to False for backward compat

retries=kwargs.get("retries", 0),

retryDelay=kwargs.get("retryDelay", 10),

)

self.token = kwargs.get("token", _NoAuthenticationToken)

if self.token is None: # In case someone explicitly passes token=None

self.token = _NoAuthenticationToken

self.scheme = kwargs.get("scheme", DEFAULT_SCHEME)

self.host = kwargs.get("host", DEFAULT_HOST)

self.port = int(kwargs.get("port", DEFAULT_PORT))

self.authority = _authority(self.scheme, self.host, self.port)

self.namespace = namespace(**kwargs)

self.username = kwargs.get("username", "")

self.password = kwargs.get("password", "")

self.basic = kwargs.get("basic", False)

self.bearerToken = kwargs.get("splunkToken", "")

self.autologin = kwargs.get("autologin", False)

self.additional_headers = kwargs.get("headers", [])

self._self_signed_certificate = kwargs.get("self_signed_certificate", True)

# Store any cookies in the self.http._cookies dict

if "cookie" in kwargs and kwargs["cookie"] not in [

None,

_NoAuthenticationToken,

]:

_parse_cookies(kwargs["cookie"], self.http._cookies)

def get_cookies(self):

"""Gets the dictionary of cookies from the ``HttpLib`` member of this instance.

:return: Dictionary of cookies stored on the ``self.http``.

:rtype: ``dict``

"""

return self.http._cookies

def has_cookies(self):

"""Returns true if the ``HttpLib`` member of this instance has auth token stored.

:return: ``True`` if there is auth token present, else ``False``

:rtype: ``bool``

"""

auth_token_key = "splunkd_"

return any(auth_token_key in key for key in self.get_cookies().keys())

# Shared per-context request headers

@property

def _auth_headers(self):

"""Headers required to authenticate a request.

Assumes your ``Context`` already has a authentication token or

cookie, either provided explicitly or obtained by logging

into the Splunk instance.

:returns: A list of 2-tuples containing key and value

"""

header = []

if self.has_cookies():

return [("Cookie", _make_cookie_header(list(self.get_cookies().items())))]

elif self.basic and (self.username and self.password):

token = f"Basic {b64encode(('%s:%s' % (self.username, self.password)).encode('utf-8')).decode('ascii')}"

elif self.bearerToken:

token = f"Bearer {self.bearerToken}"

elif self.token is _NoAuthenticationToken:

token = []

else:

# Ensure the token is properly formatted

if self.token.startswith("Splunk "):

token = self.token

else:

token = f"Splunk {self.token}"

if token:

header.append(("Authorization", token))

if self.get_cookies():

header.append(("Cookie", _make_cookie_header(list(self.get_cookies().items()))))

return header

def connect(self):

"""Returns an open connection (socket) to the Splunk instance.

This method is used for writing bulk events to an index or similar tasks

where the overhead of opening a connection multiple times would be

prohibitive.

:returns: A socket.

**Example**::

import splunklib.binding as binding

c = binding.connect(...)

socket = c.connect()

socket.write("POST %s HTTP/1.1\\r\\n" % "some/path/to/post/to")

socket.write("Host: %s:%s\\r\\n" % (c.host, c.port))

socket.write("Accept-Encoding: identity\\r\\n")

socket.write("Authorization: %s\\r\\n" % c.token)

socket.write("X-Splunk-Input-Mode: Streaming\\r\\n")

socket.write("\\r\\n")

"""

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

if self.scheme == "https":

context = ssl.create_default_context()

context.options |= ssl.OP_NO_TLSv1 | ssl.OP_NO_TLSv1_1

context.check_hostname = not self._self_signed_certificate

context.verify_mode = (

ssl.CERT_NONE if self._self_signed_certificate else ssl.CERT_REQUIRED

)

sock = context.wrap_socket(sock, server_hostname=self.host)

sock.connect((socket.gethostbyname(self.host), self.port))

return sock

@_authentication

@_log_duration

def delete(self, path_segment, owner=None, app=None, sharing=None, **query):

"""Performs a DELETE operation at the REST path segment with the given

namespace and query.

This method is named to match the HTTP method. ``delete`` makes at least

one round trip to the server, one additional round trip for each 303

status returned, and at most two additional round trips if

the ``autologin`` field of :func:`connect` is set to ``True``.

If *owner*, *app*, and *sharing* are omitted, this method uses the

default :class:`Context` namespace. All other keyword arguments are

included in the URL as query parameters.

:raises AuthenticationError: Raised when the ``Context`` object is not

logged in.

:raises HTTPError: Raised when an error occurred in a GET operation from

*path_segment*.

:param path_segment: A REST path segment.

:type path_segment: ``string``

:param owner: The owner context of the namespace (optional).

:type owner: ``string``

:param app: The app context of the namespace (optional).

:type app: ``string``

:param sharing: The sharing mode of the namespace (optional).

:type sharing: ``string``

:param query: All other keyword arguments, which are used as query

parameters.

:type query: ``string``

:return: The response from the server.

:rtype: ``dict`` with keys ``body``, ``headers``, ``reason``,

and ``status``

**Example**::

c = binding.connect(...)

c.delete('saved/searches/boris') == \\

{'body': ...a response reader object...,

'headers': [('content-length', '1786'),

('expires', 'Fri, 30 Oct 1998 00:00:00 GMT'),

('server', 'Splunkd'),

('connection', 'close'),

('cache-control', 'no-store, max-age=0, must-revalidate, no-cache'),

('date', 'Fri, 11 May 2012 16:53:06 GMT'),

('content-type', 'text/xml; charset=utf-8')],

'reason': 'OK',

'status': 200}

c.delete('nonexistant/path') # raises HTTPError

c.logout()

c.delete('apps/local') # raises AuthenticationError

"""

path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)

logger.debug("DELETE request to %s (body: %s)", path, mask_sensitive_data(query))

response = self.http.delete(path, self._auth_headers, **query)

return response

@_authentication

@_log_duration

def get(self, path_segment, owner=None, app=None, headers=None, sharing=None, **query):

"""Performs a GET operation from the REST path segment with the given

namespace and query.

This method is named to match the HTTP method. ``get`` makes at least

one round trip to the server, one additional round trip for each 303

status returned, and at most two additional round trips if

the ``autologin`` field of :func:`connect` is set to ``True``.

If *owner*, *app*, and *sharing* are omitted, this method uses the

default :class:`Context` namespace. All other keyword arguments are

included in the URL as query parameters.

:raises AuthenticationError: Raised when the ``Context`` object is not

logged in.

:raises HTTPError: Raised when an error occurred in a GET operation from

*path_segment*.

:param path_segment: A REST path segment.

:type path_segment: ``string``

:param owner: The owner context of the namespace (optional).

:type owner: ``string``

:param app: The app context of the namespace (optional).

:type app: ``string``

:param headers: List of extra HTTP headers to send (optional).

:type headers: ``list`` of 2-tuples.

:param sharing: The sharing mode of the namespace (optional).

:type sharing: ``string``

:param query: All other keyword arguments, which are used as query

parameters.

:type query: ``string``

:return: The response from the server.

:rtype: ``dict`` with keys ``body``, ``headers``, ``reason``,

and ``status``

**Example**::

c = binding.connect(...)

c.get('apps/local') == \\

{'body': ...a response reader object...,

'headers': [('content-length', '26208'),

('expires', 'Fri, 30 Oct 1998 00:00:00 GMT'),

('server', 'Splunkd'),

('connection', 'close'),

('cache-control', 'no-store, max-age=0, must-revalidate, no-cache'),

('date', 'Fri, 11 May 2012 16:30:35 GMT'),

('content-type', 'text/xml; charset=utf-8')],

'reason': 'OK',

'status': 200}

c.get('nonexistant/path') # raises HTTPError

c.logout()

c.get('apps/local') # raises AuthenticationError

"""

if headers is None:

headers = []

path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)

logger.debug("GET request to %s (body: %s)", path, mask_sensitive_data(query))

all_headers = headers + self.additional_headers + self._auth_headers

response = self.http.get(path, all_headers, **query)

return response

@_authentication

@_log_duration

def post(self, path_segment, owner=None, app=None, sharing=None, headers=None, **query):

"""Performs a POST operation from the REST path segment with the given

namespace and query.

This method is named to match the HTTP method. ``post`` makes at least

one round trip to the server, one additional round trip for each 303

status returned, and at most two additional round trips if

the ``autologin`` field of :func:`connect` is set to ``True``.

If *owner*, *app*, and *sharing* are omitted, this method uses the

default :class:`Context` namespace. All other keyword arguments are

included in the URL as query parameters.

Some of Splunk's endpoints, such as ``receivers/simple`` and

``receivers/stream``, require unstructured data in the POST body

and all metadata passed as GET-style arguments. If you provide

a ``body`` argument to ``post``, it will be used as the POST

body, and all other keyword arguments will be passed as

GET-style arguments in the URL.

:raises AuthenticationError: Raised when the ``Context`` object is not

logged in.

:raises HTTPError: Raised when an error occurred in a GET operation from

*path_segment*.

:param path_segment: A REST path segment.

:type path_segment: ``string``

:param owner: The owner context of the namespace (optional).

:type owner: ``string``

:param app: The app context of the namespace (optional).

:type app: ``string``

:param sharing: The sharing mode of the namespace (optional).

:type sharing: ``string``

:param headers: List of extra HTTP headers to send (optional).

:type headers: ``list`` of 2-tuples.

:param query: All other keyword arguments, which are used as query

parameters.

:param body: Parameters to be used in the post body. If specified,

any parameters in the query will be applied to the URL instead of

the body. If a dict is supplied, the key-value pairs will be form

encoded. If a string is supplied, the body will be passed through

in the request unchanged.

:type body: ``dict`` or ``str``

:return: The response from the server.

:rtype: ``dict`` with keys ``body``, ``headers``, ``reason``,

and ``status``

**Example**::

c = binding.connect(...)

c.post('saved/searches', name='boris',

search='search * earliest=-1m | head 1') == \\

{'body': ...a response reader object...,

'headers': [('content-length', '10455'),

('expires', 'Fri, 30 Oct 1998 00:00:00 GMT'),

('server', 'Splunkd'),

('connection', 'close'),

('cache-control', 'no-store, max-age=0, must-revalidate, no-cache'),

('date', 'Fri, 11 May 2012 16:46:06 GMT'),

('content-type', 'text/xml; charset=utf-8')],

'reason': 'Created',

'status': 201}

c.post('nonexistant/path') # raises HTTPError

c.logout()

# raises AuthenticationError:

c.post('saved/searches', name='boris',

search='search * earliest=-1m | head 1')

"""

if headers is None:

headers = []

path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)

logger.debug("POST request to %s (body: %s)", path, mask_sensitive_data(query))

all_headers = headers + self.additional_headers + self._auth_headers

response = self.http.post(path, all_headers, **query)

return response

@_authentication

@_log_duration

def put(

self,

path_segment,

owner=None,

app=None,

sharing=None,

headers=None,

**query,

):

"""Performs a PUT operation from the REST path segment with the given object,

namespace and query.

This method is named to match the HTTP method. ``put`` makes at least

one round trip to the server, one additional round trip for each 303

status returned, and at most two additional round trips if

the ``autologin`` field of :func:`connect` is set to ``True``.

If *owner*, *app*, and *sharing* are omitted, this method uses the

default :class:`Context` namespace. All other keyword arguments are

included in the URL as query parameters.

If you provide a ``body`` argument to ``put``, it will be used as the PUT body,

and all other keyword arguments will be passed as GET-style arguments in the URL.

:raises AuthenticationError: Raised when the ``Context`` object is not

logged in.

:raises HTTPError: Raised when an error occurred in a PUT operation from

*path_segment*.

:param path_segment: A REST path segment.

:type path_segment: ``string``

:param owner: The owner context of the namespace (optional).

:type owner: ``string``

:param app: The app context of the namespace (optional).

:type app: ``string``

:param sharing: The sharing mode of the namespace (optional).

:type sharing: ``string``

:param headers: List of extra HTTP headers to send (optional).

:type headers: ``list`` of 2-tuples.

:param query: All other keyword arguments, which are used as query

parameters.

:param body: Parameters to be used in the put body. If specified,

any parameters in the query will be applied to the URL instead of

the body. If a dict is supplied, the key-value pairs will be form

encoded. If a string is supplied, the body will be passed through

in the request unchanged.

:type body: ``dict`` or ``str``

:return: The response from the server.

:rtype: ``dict`` with keys ``body``, ``headers``, ``reason``,

and ``status``

**Example**::

c = binding.connect(...)

# Call an HTTP endpoint, exposed as Custom Rest Endpoint in a Splunk App.

# PUT /servicesNS/-/app_name/custom_rest_endpoint

c.put(

app="app_name",

path_segment="custom_rest_endpoint",

body=json.dumps({"key": "val"}),

headers=[("Content-Type", "application/json")],

)

"""

if headers is None:

headers = []

path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)

logger.debug("PUT request to %s (body: %s)", path, mask_sensitive_data(query))

all_headers = headers + self.additional_headers + self._auth_headers

response = self.http.put(path, all_headers, **query)

return response

@_authentication

@_log_duration

def patch(

self,

path_segment,

owner=None,

app=None,

sharing=None,

headers=None,

**query,

):

"""Performs a PATCH operation from the REST path segment with the given object,

namespace and query.

This method is named to match the HTTP method. ``patch`` makes at least

one round trip to the server, one additional round trip for each 303

status returned, and at most two additional round trips if

the ``autologin`` field of :func:`connect` is set to ``True``.

If *owner*, *app*, and *sharing* are omitted, this method uses the

default :class:`Context` namespace. All other keyword arguments are

included in the URL as query parameters.

If you provide a ``body`` argument to ``patch``, it will be used as the PATCH body,

and all other keyword arguments will be passed as GET-style arguments in the URL.

:raises AuthenticationError: Raised when the ``Context`` object is not

logged in.

:raises HTTPError: Raised when an error occurred in a PATCH operation from

*path_segment*.

:param path_segment: A REST path segment.

:type path_segment: ``string``

:param owner: The owner context of the namespace (optional).

:type owner: ``string``

:param app: The app context of the namespace (optional).

:type app: ``string``

:param sharing: The sharing mode of the namespace (optional).

:type sharing: ``string``

:param headers: List of extra HTTP headers to send (optional).

:type headers: ``list`` of 2-tuples.

:param query: All other keyword arguments, which are used as query

parameters.

:param body: Parameters to be used in the patch body. If specified,

any parameters in the query will be applied to the URL instead of

the body. If a dict is supplied, the key-value pairs will be form

encoded. If a string is supplied, the body will be passed through

in the request unchanged.

:type body: ``dict`` or ``str``

:return: The response from the server.

:rtype: ``dict`` with keys ``body``, ``headers``, ``reason``,

and ``status``

**Example**::

c = binding.connect(...)

# Call an HTTP endpoint, exposed as Custom Rest Endpoint in a Splunk App.

# PATCH /servicesNS/-/app_name/custom_rest_endpoint

c.patch(

app="app_name",

path_segment="custom_rest_endpoint",

body=json.dumps({"key": "val"}),

headers=[("Content-Type", "application/json")],

)

"""

if headers is None:

headers = []

path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)

logger.debug("PATCH request to %s (body: %s)", path, mask_sensitive_data(query))