Base API Client#

class BaseAPIClient(max_concurrency: int = 5)[source]#

The BaseAPIClient class controls concurrency settings and secure connections for all API calls.

This class forms the backbone of Patcher’s ability to interact with external APIs. It manages the number of API requests that can be made simultaneously, ensuring the tool is both efficient and does not overload any servers.

Warning

Changing the max_concurrency value could lead to your Jamf server being unable to perform other basic tasks. It is strongly recommended to limit API call concurrency to no more than 5 connections. See Jamf Developer Guide for more information.

Parameters:

max_concurrency (int) – The maximum number of API requests that can be sent at once. Defaults to 5.

property concurrency: int#

Gets the current concurrency setting used by Patcher.

Returns:

The maximum number of concurrent API requests that can be made.

Return type:

int

set_concurrency(concurrency: int) → None[source]#

Sets the maximum concurrency level for API calls.

This method allows you to set the maximum number of concurrent API calls that can be made by the Jamf client. It is recommended to limit this value to 5 connections to avoid overloading the Jamf server.

Parameters:

concurrency (int) – The new maximum concurrency level.

Raises:

ValueError – If the concurrency level is less than 1.

Return type:

None

async execute(command: List[str]) → Dict | str | None[source]#

Asynchronously executes a shell command using subprocess and returns the output.

This method leverages asyncio to run a command in a new subprocess. If the command execution is unsuccessful (non-zero return code), an exception is raised.

Note

This method should be used for executing shell commands that are essential to the functionality of the API client, such as invoking cURL commands for API calls.

Parameters:

command (List[str]) – A list representing the command and its arguments to be executed in the shell.

Returns:

The standard output of the executed command decoded as a string, or None if there is an error.

Return type:

Optional[Union[Dict, str]]

Raises:

exceptions.ShellCommandError – If the command execution fails (returns a non-zero exit code).

async fetch_json(url: str, headers: Dict[str, str] | None = None, method: str = 'GET', data: Dict[str, str] | None = None) → Dict[source]#

Asynchronously fetches JSON data from the specified URL using a specified HTTP method.

Parameters:

  • url (str) – The URL to fetch data from.

  • headers (Optional[Dict[str, str]]) – Optional headers to include in the request.

  • method (str) – HTTP method to use (“GET” or “POST”). Defaults to “GET”.

  • data (Optional[Dict[str, str]]) – Optional form data to include for POST request.

Returns:

The fetched JSON data as a dictionary, or None if the request fails.

Return type:

Optional[Dict]

async fetch_batch(urls: List[str], headers: Dict[str, str] | None = None) → List[Dict | None][source]#

Fetches JSON data in batches to respect the concurrency limit. Data is fetched from each URL in the provided list, ensuring that no more than max_concurrency requests are sent concurrently.

Parameters:

  • urls (List[str]) – List of URLs to fetch data from.

  • headers (Optional[Dict[str, str]] = None)

Returns:

A list of JSON dictionaries or None for URLs that fail to retrieve data.

Return type:

List[Optional[Dict]]

async fetch_basic_token(username: str, password: str, jamf_url: str) → str | None[source]#

Asynchronously retrieves a bearer token using basic authentication.

This method is intended for initial setup to obtain client credentials for API clients and roles. It should not be used for regular token retrieval after setup.

Parameters:

  • username (str) – Username of admin Jamf Pro account for authentication. Not permanently stored, only used for initial token retrieval.

  • password (str) – Password of admin Jamf Pro account. Not permanently stored, only used for initial token retrieval.

  • jamf_url (str) – Jamf Server URL (same as server_url in patcher.models.jamf_client class).

Raises:

exceptions.TokenFetchError – If the call is unauthorized or unsuccessful.

Returns:

True if the basic token was successfully retrieved, False if unauthorized (e.g., due to SSO).

Return type:

bool

async create_roles(token: str, jamf_url: str) → bool[source]#

Creates the necessary API roles using the provided bearer token.

Parameters:

  • token (Optional[str]) – The bearer token to use for authentication. Defaults to the stored token if not provided.

  • jamf_url (str) – Jamf Server URL

Returns:

True if roles were successfully created, False otherwise.

Return type:

bool

async create_client(token: str, jamf_url: str) → Tuple[str, str] | None[source]#

Creates an API client and retrieves its client ID and client secret.

Parameters:

  • token (Optional[str]) – The bearer token to use for authentication. Defaults to the stored token if not provided.

  • jamf_url (str) – Jamf Server URL

Returns:

A tuple containing the client ID and client secret.

Return type:

Optional[Tuple[str, str]]