Add mas module for installing applications via the Mac App Store (#19768)
* Add `mas` module for installing applications via the Mac App Store Currently, only the `install` command is available, and you must provide IDs when installing applications. * mas module: Update metadata Brings the metadata in line with the current style. * mas module: General refactor, support more states - `check_mode` is now fully supported - Support for states `absent` and `latest` (using `mas uninstall` and `mas upgrade`) - Support for a list of apps to manage - Remove return value as other packaging modules don’t support it either - Return msg with details on the changes on success - Code was refactored to be easier to read and maintain * mas module: Add upgrade_all option * mas module: Fix linting errors * mas module: Implement review feedback Co-authored-by: Lukas Bestle <account-github@lukasbestle.com>
This commit is contained in:
Michael Heap
GitHub
parent
807f4ea658
commit
a43f76cbf9
1 changed files with 290 additions and 0 deletions
290
lib/ansible/modules/packaging/os/mas.py
Normal file
290
lib/ansible/modules/packaging/os/mas.py
Normal file
|
|
@ -0,0 +1,290 @@
|
|||
#!/usr/bin/python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
# Copyright: (c) 2020, Lukas Bestle <project-ansible@lukasbestle.com>
|
||||
# Copyright: (c) 2017, Michael Heap <m@michaelheap.com>
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
ANSIBLE_METADATA = {'metadata_version': '1.1',
|
||||
'status': ['preview'],
|
||||
'supported_by': 'community'}
|
||||
|
||||
DOCUMENTATION = '''
|
||||
module: mas
|
||||
short_description: Manage Mac App Store applications with mas-cli
|
||||
description:
|
||||
- Installs, uninstalls and updates macOS applications from the Mac App Store using the C(mas-cli).
|
||||
version_added: "2.10"
|
||||
author:
|
||||
- Michael Heap (@mheap)
|
||||
- Lukas Bestle (@lukasbestle)
|
||||
options:
|
||||
id:
|
||||
description:
|
||||
- The Mac App Store identifier of the app(s) you want to manage.
|
||||
- This can be found by running C(mas search APP_NAME) on your machine.
|
||||
type: list
|
||||
elements: int
|
||||
state:
|
||||
description:
|
||||
- Desired state of the app installation.
|
||||
- The C(absent) value requires root permissions, also see the examples.
|
||||
type: str
|
||||
choices:
|
||||
- absent
|
||||
- latest
|
||||
- present
|
||||
default: present
|
||||
upgrade_all:
|
||||
description:
|
||||
- Upgrade all installed Mac App Store apps.
|
||||
type: bool
|
||||
default: "no"
|
||||
aliases: ["upgrade"]
|
||||
requirements:
|
||||
- macOS 10.11+
|
||||
- "mas-cli (U(https://github.com/mas-cli/mas)) 1.5.0+ available as C(mas) in the bin path"
|
||||
- The Apple ID to use already needs to be signed in to the Mac App Store (check with C(mas account)).
|
||||
notes:
|
||||
- This module supports C(check_mode).
|
||||
'''
|
||||
|
||||
EXAMPLES = '''
|
||||
- name: Install Keynote
|
||||
mas:
|
||||
id: 409183694
|
||||
state: present
|
||||
|
||||
- name: Install a list of apps
|
||||
mas:
|
||||
id:
|
||||
- 409183694 # Keynote
|
||||
- 413857545 # Divvy
|
||||
state: present
|
||||
|
||||
- name: Ensure the latest Keynote version is installed
|
||||
mas:
|
||||
id: 409183694
|
||||
state: latest
|
||||
|
||||
- name: Upgrade all installed Mac App Store apps
|
||||
mas:
|
||||
upgrade_all: yes
|
||||
|
||||
- name: Install specific apps and also upgrade all others
|
||||
mas:
|
||||
id:
|
||||
- 409183694 # Keynote
|
||||
- 413857545 # Divvy
|
||||
state: present
|
||||
upgrade_all: yes
|
||||
|
||||
- name: Uninstall Divvy
|
||||
mas:
|
||||
id: 413857545
|
||||
state: absent
|
||||
become: yes # Uninstallation requires root permissions
|
||||
'''
|
||||
|
||||
RETURN = r''' # '''
|
||||
|
||||
from ansible.module_utils.basic import AnsibleModule
|
||||
from ansible.module_utils._text import to_native
|
||||
from distutils.version import StrictVersion
|
||||
import os
|
||||
|
||||
|
||||
class Mas(object):
|
||||
|
||||
def __init__(self, module):
|
||||
self.module = module
|
||||
|
||||
# Initialize data properties
|
||||
self.mas_path = self.module.get_bin_path('mas')
|
||||
self._checked_signin = False
|
||||
self._installed = None # Populated only if needed
|
||||
self._outdated = None # Populated only if needed
|
||||
self.count_install = 0
|
||||
self.count_upgrade = 0
|
||||
self.count_uninstall = 0
|
||||
self.result = {
|
||||
'changed': False
|
||||
}
|
||||
|
||||
self.check_mas_tool()
|
||||
|
||||
def app_command(self, command, id):
|
||||
''' Runs a `mas` command on a given app; command can be 'install', 'upgrade' or 'uninstall' '''
|
||||
|
||||
if not self.module.check_mode:
|
||||
if command != 'uninstall':
|
||||
self.check_signin()
|
||||
|
||||
rc, out, err = self.run([command, str(id)])
|
||||
if rc != 0:
|
||||
self.module.fail_json(
|
||||
msg="Error running command '{0}' on app '{1}': {2}".format(command, str(id), out.rstrip())
|
||||
)
|
||||
|
||||
# No error or dry run
|
||||
self.__dict__['count_' + command] += 1
|
||||
|
||||
def check_mas_tool(self):
|
||||
''' Verifies that the `mas` tool is available in a recent version '''
|
||||
|
||||
# Is the `mas` tool available at all?
|
||||
if not self.mas_path:
|
||||
self.module.fail_json(msg='Required `mas` tool is not installed')
|
||||
|
||||
# Is the version recent enough?
|
||||
rc, out, err = self.run(['version'])
|
||||
if rc != 0 or not out.strip() or StrictVersion(out.strip()) < StrictVersion('1.5.0'):
|
||||
self.module.fail_json(msg='`mas` tool in version 1.5.0+ needed, got ' + out.strip())
|
||||
|
||||
def check_signin(self):
|
||||
''' Verifies that the user is signed in to the Mac App Store '''
|
||||
|
||||
# Only check this once per execution
|
||||
if self._checked_signin:
|
||||
return
|
||||
|
||||
rc, out, err = self.run(['account'])
|
||||
if out.split("\n", 1)[0].rstrip() == 'Not signed in':
|
||||
self.module.fail_json(msg='You must be signed in to the Mac App Store')
|
||||
|
||||
self._checked_signin = True
|
||||
|
||||
def exit(self):
|
||||
''' Exit with the data we have collected over time '''
|
||||
|
||||
msgs = []
|
||||
if self.count_install > 0:
|
||||
msgs.append('Installed {0} app(s)'.format(self.count_install))
|
||||
if self.count_upgrade > 0:
|
||||
msgs.append('Upgraded {0} app(s)'.format(self.count_upgrade))
|
||||
if self.count_uninstall > 0:
|
||||
msgs.append('Uninstalled {0} app(s)'.format(self.count_uninstall))
|
||||
|
||||
if msgs:
|
||||
self.result['changed'] = True
|
||||
self.result['msg'] = ', '.join(msgs)
|
||||
|
||||
self.module.exit_json(**self.result)
|
||||
|
||||
def get_current_state(self, command):
|
||||
''' Returns the list of all app IDs; command can either be 'list' or 'outdated' '''
|
||||
|
||||
rc, raw_apps, err = self.run([command])
|
||||
rows = raw_apps.split("\n")
|
||||
apps = []
|
||||
for r in rows:
|
||||
# Format: "123456789 App Name"
|
||||
r = r.split(' ', 1)
|
||||
if len(r) == 2:
|
||||
apps.append(int(r[0]))
|
||||
|
||||
return apps
|
||||
|
||||
def installed(self):
|
||||
''' Returns the list of installed apps '''
|
||||
|
||||
# Populate cache if not already done
|
||||
if self._installed is None:
|
||||
self._installed = self.get_current_state('list')
|
||||
|
||||
return self._installed
|
||||
|
||||
def is_installed(self, id):
|
||||
''' Checks whether the given app is installed '''
|
||||
|
||||
return int(id) in self.installed()
|
||||
|
||||
def is_outdated(self, id):
|
||||
''' Checks whether the given app is installed, but outdated '''
|
||||
|
||||
return int(id) in self.outdated()
|
||||
|
||||
def outdated(self):
|
||||
''' Returns the list of installed, but outdated apps '''
|
||||
|
||||
# Populate cache if not already done
|
||||
if self._outdated is None:
|
||||
self._outdated = self.get_current_state('outdated')
|
||||
|
||||
return self._outdated
|
||||
|
||||
def run(self, cmd):
|
||||
''' Runs a command of the `mas` tool '''
|
||||
|
||||
cmd.insert(0, self.mas_path)
|
||||
return self.module.run_command(cmd, False)
|
||||
|
||||
def upgrade_all(self):
|
||||
''' Upgrades all installed apps and sets the correct result data '''
|
||||
|
||||
outdated = self.outdated()
|
||||
|
||||
if not self.module.check_mode:
|
||||
self.check_signin()
|
||||
|
||||
rc, out, err = self.run(['upgrade'])
|
||||
if rc != 0:
|
||||
self.module.fail_json(msg='Could not upgrade all apps: ' + out.rstrip())
|
||||
|
||||
self.count_upgrade += len(outdated)
|
||||
|
||||
|
||||
def main():
|
||||
module = AnsibleModule(
|
||||
argument_spec=dict(
|
||||
id=dict(type='list', elements='int'),
|
||||
state=dict(type='str', default='present', choices=['absent', 'latest', 'present']),
|
||||
upgrade_all=dict(type='bool', default=False, aliases=['upgrade']),
|
||||
),
|
||||
supports_check_mode=True
|
||||
)
|
||||
mas = Mas(module)
|
||||
|
||||
if module.params['id']:
|
||||
apps = module.params['id']
|
||||
else:
|
||||
apps = []
|
||||
|
||||
state = module.params['state']
|
||||
upgrade = module.params['upgrade_all']
|
||||
|
||||
# Run operations on the given app IDs
|
||||
for app in sorted(set(apps)):
|
||||
if state == 'present':
|
||||
if not mas.is_installed(app):
|
||||
mas.app_command('install', app)
|
||||
|
||||
elif state == 'absent':
|
||||
if mas.is_installed(app):
|
||||
# Ensure we are root
|
||||
if os.getuid() != 0:
|
||||
module.fail_json(msg="Uninstalling apps requires root permissions ('become: yes')")
|
||||
|
||||
mas.app_command('uninstall', app)
|
||||
|
||||
elif state == 'latest':
|
||||
if not mas.is_installed(app):
|
||||
mas.app_command('install', app)
|
||||
elif mas.is_outdated(app):
|
||||
mas.app_command('upgrade', app)
|
||||
|
||||
# Upgrade all apps if requested
|
||||
mas._outdated = None # Clear cache
|
||||
if upgrade and mas.outdated():
|
||||
mas.upgrade_all()
|
||||
|
||||
# Exit with the collected data
|
||||
mas.exit()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Loading…
Reference in a new issue