Client

exception APIException(...)

Raised when the API server indicates an error.

class Pagination(per_page=10, expand=False)

pagination settings for recources .search() and .iter() methods

expand: bool = False: if True the server will send additional properties for each resource

per_page: int = 10: number of returned objects per page request

class Client(url, *, http_auth=None, http_token=None, oauth2_token=None, additional_headers=())

The root class to interact with the REST API.

Almost every object keeps the initialized instance of Client as reference.

Example:

from zammadoo import Client

# basic authentication scheme
client = Client("https://myhost.com/api/v1/", http_auth=("<username>", "<mysecret>"))
# token based authentication
client = Client("https://myhost.com/api/v1/", http_token="<secret_token>")
# authenticate with bearer token (OAuth 2.0)
client = Client("https://myhost.com/api/v1/", oauth2_token="<secret_token>")

For authentication use either http_auth or http_token or oauth2_token.

Parameters:

url (str) – the zammad API url (e.g. https://myhost.com/api/v1)
http_auth (Tuple[str, str] | None) – username and password for HTTP Basic Authentication
http_token (str | None) – access token when using HTTP Token Authentication
oauth2_token (str | None) – access token when using OAuth 2 Authentication
additional_headers (Sequence[Tuple[str, str]]) – additional name, value pairs that will be appended to the requests header [(name, value), ...]

Raises:

ValueError if authentication settings are missing.

get(*args, params=None): shortcut for request() with parameter ("GET", *args, params)

delete(*args, json=None)

shortcut for request() with parameter ("DELETE", *args, json)

impersonation_of(user)

Temporarily perform requests on behalf of another user.

To be used as context manager:

with client.impersonation_of(1):
    print(client.users.me().id)  # output: 1

Parameters:: user (str | int) – user id or login_name

post(*args, json=None)

shortcut for request() with parameter ("POST", *args, json)

put(*args, json=None)

shortcut for request() with parameter ("PUT", *args, json)

request(method, *args, params=None, json=None, **kwargs)

Perform a request on the API URL.

Parameters:

method (str) – HTTP method: e.g. GET, POST, PUT, DELETE
args – endpoint specifiers
params (StringKeyMapping | None) – URL parameter (usually for GET)
json (StringKeyMapping | None) – data as dictionary (usually for POST or PUT)
kwargs – additional parameters passed to request()

Returns:

the server JSON response

Return type:

StringKeyDict

Raises:

APIException, requests.HTTPError

response(method, url, params=None, json=None, **kwargs)

Perform a request on the API URL.

Parameters:

method (str) – the HTTP method (e.g. GET, POST, PUT, DELETE)
url (str) – full resource URL
params (StringKeyMapping | None) – parameter that get urlencoded (usually for GET)
json (StringKeyMapping | None) – data as dictionary (usually for POST or PUT)
kwargs – additional parameters passed to request()

Return type:

requests.Response

property groups: Groups: Manages the /groups endpoint.

property notificatons: Notifications: Manages the /online_notifications endpoint.

property organizations: Organizations: Manages the /organizations endpoint.

pagination: Pagination: initial Pagination settings

property roles: Roles: Manages the /roles endpoint.

property server_version: str: the Zammad server version

session: Session: the requests Session instance

property tags: Tags: Manages the /tags, /tag_list, /tag_search endpoint.

property ticket_articles: Articles: Manages the /ticket_articles endpoint.

property ticket_priorities: Priorities: Manages the /ticket_priorities endpoint.

property ticket_states: States: Manages the /ticket_states endpoint.

property tickets: Tickets: Manages the /tickets endpoint.

property time_accountings: TimeAccountings: Manages the /time_accountings endpoint.

url: str: the clients API URL

property users: Users: Manages the /users endpoint.

property weburl: str