platforms.darwin

macOS platform implementation: system information, command support, defaults management, and launchd service management.

DarwinPlatformInfo

class DarwinPlatformInfo

Bases: object

macOS implementation of PlatformInfo.

Retrieves system information using macOS-specific binaries: - system_profiler for serial numbers - stat / id for console user details - id -F for user full names

invalid_users: ClassVar[tuple[str, ...]] = ('root', '', 'loginwindow', '_mbsetupuser')

get_serial_number() → str | None

Get serial number via system_profiler.

Returns:

Hardware serial number, or None on failure

Return type:

str | None

get_console_user() → tuple[str, int, Path] | None

Get the currently logged-in console user on macOS.

Uses stat -f%Su /dev/console to determine the console owner, then id -u for the UID, and constructs the home path under /Users/.

Returns:

Tuple of (username, uid, home_path), or None

Return type:

tuple[str, int, Path] | None

get_hostname() → str

Retrieve system hostname.

Returns:

System hostname

Return type:

str

get_user_full_name(username: str) → str | None

Get full name for a user via id -F (macOS-specific).

Parameters:

username (str) – Username to look up

Returns:

Full display name, or None on failure

Return type:

str | None

get_os_version_label() → str

Return macOS version label for logging.

Reads the marketing macOS productVersion (e.g. “15.4.1”, “26.4.1”) from platform.mac_ver(). platform.release() was used previously but returns the Darwin kernel version (e.g. “25.4.0” on macOS 26.4.1), which is not what users expect to see in logs.

Returns:

e.g. “macOS Version: 26.4.1”

Return type:

str

DarwinCommandSupport

class DarwinCommandSupport

Bases: object

macOS implementation of PlatformCommandSupport.

Uses launchctl asuser to run commands in the context of a logged-in user.

property min_user_uid: int

Minimum UID for non-system accounts on macOS (500).

Returns:

500

Return type:

int

run_as_user_command(command: list[str], username: str, uid: int) → list[str]

Wrap command with launchctl asuser for macOS.

Parameters:

• command (list[str]) – Original command arguments

• username (str) – Target username

• uid (int) – Target user UID

Returns:

Command prefixed with launchctl asuser + sudo -u

Return type:

list[str]

validate_user(username: str | None, uid: int | None) → bool

Validate user info for macOS.

Returns False if username/uid are missing, username has invalid characters, or UID is below the non-system threshold (500).

Parameters:

• username (str | None) – Username to validate

• uid (int | None) – User ID to validate

Returns:

True if valid

Return type:

bool

DarwinDefaults

class DarwinDefaults(runner: CommandRunner | None = None)

Bases: object

Read, write, and delete macOS user defaults (plist) values.

Wraps /usr/bin/defaults for non-raising plist operations: all methods return None or False on failure instead of raising.

Operations run in the calling process’s context by default (i.e. as root when the script is invoked under MDM). Pass a CommandRunner with a username/uid to allow per-call as_user=True reads/writes against the logged-in user’s domain.

Example:

>>> # Root context (or whoever the script runs as)
>>> defaults = DarwinDefaults()
>>> defaults.read("com.apple.SoftwareUpdate", "AutomaticCheckEnabled")
'1'

>>> # User context — pipe through a configured CommandRunner
>>> runner = CommandRunner(logger=logger, username="jappleseed", uid=501)
>>> defaults = DarwinDefaults(runner=runner)
>>> defaults.read("com.apple.dock", "orientation", as_user=True)
'bottom'
>>> defaults.write("com.apple.dock", "tilesize", "48", "-int", as_user=True)
True

Parameters:

runner (CommandRunner | None)

read(domain: str, key: str, *, as_user: bool = False) → str | None

Read a defaults value by domain and key.

Parameters:

• domain (str) – The plist domain (e.g., “com.apple.finder”)

• key (str) – The key to read

• as_user (bool) – If True, run via the configured CommandRunner’s run_as_user so the read targets the logged-in user’s domain.

Returns:

Value as string, or None if the key doesn’t exist

Return type:

str | None

write(domain: str, key: str, value: str, value_type: str = '-string', *, as_user: bool = False) → bool

Write a defaults value.

Parameters:

• domain (str) – The plist domain

• key (str) – The key to write

• value (str) – The value to set

• value_type (str) – defaults type flag (e.g., “-string”, “-int”, “-bool”, “-float”)

• as_user (bool) – If True, run as the configured user (see read).

Returns:

True if successful

Return type:

bool

delete(domain: str, key: str, *, as_user: bool = False) → bool

Delete a defaults key.

Parameters:

• domain (str) – The plist domain

• key (str) – The key to delete

• as_user (bool) – If True, run as the configured user (see read).

Returns:

True if deleted, False if missing or failed

Return type:

bool

DarwinServiceManager

class DarwinServiceManager

Bases: object

Manage launchd services on macOS.

Wraps /bin/launchctl for checking, loading, and unloading services. Targets use the launchctl domain-target format: system/com.example.daemon or gui/<uid>/com.example.agent.

Example:

>>> if DarwinServiceManager.is_loaded("system/com.example.daemon"):
...     DarwinServiceManager.bootout("system/com.example.daemon")

static is_loaded(target: str) → bool

Check if a launchd service is loaded.

Parameters:

target (str) – Service target (e.g., “system/com.example.daemon”)

Returns:

True if the service is loaded

Return type:

bool

static bootout(target: str) → bool

Unload a launchd service.

Parameters:

target (str) – Service target (e.g., “system/com.example.daemon”)

Returns:

True if successfully unloaded

Return type:

bool

static bootstrap(domain_target: str, plist_path: str) → bool

Load a launchd service from a plist.

Parameters:

• domain_target (str) – Domain target (e.g., “system” or “gui/501”)

• plist_path (str) – Path to the launchd plist file

Returns:

True if successfully loaded

Return type:

bool