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[source]#

Gets the current concurrency setting used by Patcher.

Returns:: The maximum number of concurrent API requests that can be made.
Return type:: int

async execute(command: List[str]) → Dict | str[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.
Return type:: Union [Dict | str]
Raises:: ShellCommandError – If the command execution fails (returns a non-zero exit code).

execute_sync(command: List[str]) → bytes | str[source]#

Identical to execute method, but does not leverage async functionality.

Method is primarily intended for UIConfigManager to ensure default font files are downloaded properly. See _download_font() for details.

Important

If used in separate context from downloading font files, output needs to be decoded from bytes:

b = BaseAPIClient()
result = b.execute_sync(["/usr/bin/curl", "-s", "-L", "https://ifconfig.co"])  # Returns <class 'bytes'>
decoded = result.decode().strip()  # Returns <class 'str'>

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.
Return type:: Union [Dict | str]
Raises:: 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, query_params: Dict[str, str] | None = None) → Dict[source]#

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

Parameters:

url (str) – The URL to fetch data from.
headers (Optional [Dict]) – Optional headers to include in the request. Defaults to self.headers.
method (str) – HTTP method to use (“GET” or “POST”). Defaults to “GET”.
data (Optional [Dict]) – Optional form data to include for POST request.
query_params (Optional [Dict]) – Additional query parameters to append to the URL. Defaults to None.

Returns:

The fetched JSON data as a dictionary.

Return type:

Dict

Raises:

APIResponseError – If the response payload is not valid JSON, or if command execution fails.

async fetch_batch(urls: List[str], headers: Dict[str, str] | None = None, query_params: Dict[str, str] | None = None) → List[Dict][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]) – Optional headers to include in the request. Defaults to self.headers via the fetch_json() method.
query_params (Optional [Dict]) – Additional query parameters to append to the URL. Defaults to None.

Returns:

A list of JSON dictionaries.

Return type:

List [Dict]

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

Asynchronously retrieves a basic 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 (See server).

Returns:

The BasicToken string.

Return type:

str

Raises:

APIResponseError – If the call is unauthorized or unsuccessful.

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

Creates the necessary API roles using the provided basic token.