Setup#

Setup State Manager#

class SetupStateManager(state_path: Path)[source]#

Manages reading, writing, and resetting the current setup stage.

This class is responsible for persisting setup progress to a JSON file, allowing the setup process to be resumed from the last known stage.

Parameters:

state_path (Path) – Filesystem path to the JSON file used to persist setup stage.

load_stage() → SetupStage[source]#

Loads the saved setup stage from disk. If the file does not exist or is invalid, defaults to NOT_STARTED.

Creates the stage file if it doesn’t already exist.

Returns:

The current saved setup stage.

Return type:

SetupStage

save_stage(stage: SetupStage) → None[source]#

Persists the provided setup stage to disk.

Creates the parent directory if it does not exist.

Parameters:

stage (SetupStage) – The setup stage to persist.

Return type:

None

destroy() → None[source]#

Deletes the persisted setup stage file if it exists.

Return type:

None

Setup Class#

class Setup(config: ConfigManager, ui_config: UIConfigManager, plist_manager: PropertyListManager)[source]#

Handles the initial setup process for the Patcher CLI tool.

This class guides users through configuring the necessary components to integrate with their Jamf environment. The setup includes creating API roles, clients, and configuring user interface settings for PDF reports.

Parameters:

  • config (ConfigManager) – Manages application configuration, including credential storage.

  • ui_config (UIConfigManager) – Handles UI-related configurations for the setup process.

  • plist_manager (PropertyListManager) – Handles read/write operations to project property list.

property completed: bool[source]#

Indicates whether the setup process has been completed.

Returns:

True if setup has been completed, False otherwise.

Return type:

bool

property stage: SetupStage[source]#

Returns the current SetupStage value used to determine setup state.

Returns:

The SetupStage value.

Return type:

SetupStage

prompt_credentials(setup_type: SetupType) → Dict[source]#

Prompt for credentials based on the credential type.

Parameters:

setup_type (SetupType) – The SetupType of credentials to prompt for.

Returns:

The credentials in dictionary form.

Return type:

Dict

validate_creds(creds: Dict, required_keys: Tuple[str, ...], setup_type: SetupType) → None[source]#

Validates all required keys are present in the credentials.

Parameters:

  • creds (Dict) – Credentials to validate

  • required_keys (Tuple [str, …]) – Keys required to be present in passed credentials.

  • setup_type (SetupType) – The SetupType to validate credentials against.

Raises:

SetupError – If any credentials are missing.

Return type:

None

prompt_installomator() → None[source]#

Prompts user to enable or disable Installomator support.

If enabled, assists in identifying PatchTitle objects with Installomator support, used during analyze commands.

Return type:

None

async get_token(setup_type: SetupType = SetupType.STANDARD, creds: Dict | None = None) → str | AccessToken[source]#

Fetches a Token (basic or AccessToken) depending on setup type (Standard or SSO).

Parameters:

  • setup_type (SetupType) – SetupType specified dictates which type of Token will be retrieved (basic or bearer).

  • creds (Optional [Dict]) – If SetupType is “Standard”, the user credentials needed to obtain a basic token.

Raises:

SetupError – If either type of Token could not be obtained.

Returns:

For SetupType.STANDARD, the basic token is returned. For SetupType.SSO, the AccessToken object is returned.

Return type:

Union [str, AccessToken]

async create_api_client(basic_token: str, jamf_url: str) → Tuple[str, str][source]#

Creates API Role and Client for standard setup types.

Parameters:

  • basic_token (str) – The basic token used for authorization in creating API Role and Client

  • jamf_url (str) – The Jamf Pro instance URL to create API Role and Clients in.

Raises:

SetupError – If either the API Role or API Client could not be created.

Returns:

The client ID and client secret of the created API Client and Role.

Return type:

Tuple [str, str]

async not_started(animator: Animation, setup_type: SetupType) → None[source]#

Handles the initial setup stage based on the selected setup type.

For STANDARD setup, prompts the user for username/password, creates a new API client, and saves credentials. For SSO, stores the provided client credentials.

Parameters:

  • animator (Animation) – The animation instance to update messages.

  • setup_type (SetupType) – The selected setup type (Standard or SSO).

Raises:

SetupError – If credentials are missing or a token cannot be obtained.

Return type:

None

async api_created(animator: Animation, _setup_type: SetupType) → None[source]#

Handles the stage after API credentials have been created or provided.

Attempts to fetch and persist an AccessToken using stored credentials.

Parameters:

  • animator (Animation) – The animation instance to update messages.

  • _setup_type (SetupType) – Placeholder to satisfy stage dispatch signature. Not used in this stage.

Raises:

SetupError – If an AccessToken cannot be retrieved

Return type:

None

async has_token(animator: Animation, _setup_type: SetupType) → None[source]#

Handles the stage after a token has been obtained.

Uses stored credentials and token to instantiate and store a JamfClient object.

Parameters:

  • animator (Animation) – The animation instance to update messages.

  • _setup_type (SetupType) – Placeholder to satisfy stage dispatch signature. Not used in this stage.

Return type:

None

async jamfclient_saved(animator: Animation, _setup_type: SetupType) → None[source]#

Final stage in setup: configures user interface settings and marks setup as complete.

Parameters:

  • animator (Animation) – The animation instance to update messages.

  • _setup_type (SetupType) – Placeholder to satisfy stage dispatch signature. Not used in this stage.

Return type:

None

async start(animator: Animation | None = None, fresh: bool = False) → None[source]#

Allows the user to choose between different setup methods (Standard or SSO).

An optional Animation object can be passed to update animation messages at runtime. Defaults to self.animator.

Options:

  • STANDARD prompts for basic credentials, obtains basic token, creates API integration, saves client credentials and obtains an AccessToken.

  • SSO prompts for existing API credentials, obtains AccessToken and saves credentials.

See also

For SSO users, reference our Handling SSO in Jamf Pro page for assistance creating an API integration.

Parameters:

  • animator (Optional [Animation]) – The animation instance to update messages. Defaults to self.animator.

  • fresh (bool) – If True, starts setup from scratch regardless of previous stage saved.

Raises:

SetupError – If a token could not be fetched, credentials are missing or setup could not be marked complete.

Return type:

None

reset_setup() → bool[source]#

Resets setup completion flag, removing the setup_completed key/value from the property list.

This effectively marks Setup completion as False and will re-trigger the setup assistant.

Warning!

The Jamf API will return a 400 response if API Roles/Clients exist already in the Jamf instance specified. It is important to remove the API Role and Client objects before re-running the Setup assistant.

Returns:

True if the Setup section in the property list file was removed.

Return type:

bool

Module Enums#

Setup Type#

class SetupType(*values)[source]#

Defines the method of setup used for configuring Patcher.

  • STANDARD: Prompts for Jamf Pro username/password and creates an API client.

  • SSO: Prompts for an existing API client ID and secret.

STANDARD = 'standard'#
SSO = 'sso'#

Setup Stage#

class SetupStage(*values)[source]#

Represents the sequential stages in the setup process.

Used to track progress and allow resuming setup from the last completed step.

NOT_STARTED = 'not_started'#
API_CREATED = 'api_created'#
HAS_TOKEN = 'has_token'#
JAMFCLIENT_SAVED = 'jamfclient_saved'#
COMPLETED = 'completed'#