spruce.py

#!/usr/local/autopkg/python
# -*- coding: utf-8 -*-

# Copyright (C) 2015-2018 Shea G Craig
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""Spruce is a tool to help you clean up your filthy JSS."""


import argparse
from collections import Counter, namedtuple
import datetime
from distutils.version import StrictVersion
from html.parser import HTMLParser
import os
import re
import subprocess
import sys
import textwrap
from xml.etree import ElementTree as ET

# pylint: disable=import-error
from Foundation import (
    NSData,
    NSPropertyListSerialization,
    NSPropertyListMutableContainersAndLeaves,
    NSPropertyListXMLFormat_v1_0,
)

sys.path.insert(0, "/Library/AutoPkg/JSSImporter")
import requests
import jss

# pylint: enable=import-error

# Ensure that python-jss dependency is at minimum version
try:
    from jss import __version__ as PYTHON_JSS_VERSION
except ImportError:
    PYTHON_JSS_VERSION = "0.0.0"


REQUIRED_PYTHON_JSS_VERSION = StrictVersion("2.1.0")


# Globals
# Edit these if you want to change their default values.
AUTOPKG_PREFERENCES = "~/Library/Preferences/com.github.autopkg.plist"
PYTHON_JSS_PREFERENCES = "~/Library/Preferences/com.github.sheagcraig.python-jss.plist"
DESCRIPTION = (
    "Spruce is a tool to help you clean up your filthy JSS."
    "\n\nUsing the various reporting options, you can see "
    "unused packages, printers, scripts,\ncomputer groups, "
    "extension attributes, configuration profiles, mobile "
    "device groups, and mobile\ndevice configuration "
    "profiles.\n\nReports are by default output to stdout, "
    "and may optionally be output as\nXML for later use in "
    "automated removal.\n\n"
    "Spruce uses configured AutoPkg/JSSImporter settings "
    "first. If those are\nmissing, Spruce falls back to "
    "python-jss settings.\n\nThe recommended workflow is to "
    "begin by running the reports you find\ninteresting. "
    "After becoming familiar with the scale of unused "
    "things,\nreports can be output with the -o/--ofile "
    "option. This file can then be\nedited down to include "
    "only those things which you wish to remove.\nFinally, "
    "pass this filename as an option to the --remove "
    "argument to\nremove the specified objects."
)


__version__ = "2.0.1"


class Error(Exception):
    """Module base exception."""

    pass


class PlistParseError(Error):
    """Error parsing a plist file."""

    pass


class PlistDataError(Error):
    """Data can not be serialized to plist."""

    pass


class PlistWriteError(Error):
    """Error writing a plist file."""

    pass


class Plist(dict):
    """Abbreviated plist representation (as a dict)."""

    def __init__(self, filename=None):
        """Init a Plist, optionally from parsing an existing file.

        Args:
            filename: String path to a plist file.
        """
        if filename:
            dict.__init__(self, self.read_file(filename))
        else:
            dict.__init__(self)
            self.new_plist()

    def read_file(self, path):
        """Replace internal XML dict with data from plist at path.

        Args:
            path: String path to a plist file.

        Raises:
            PlistParseError: Error in reading plist file.
        """
        # pylint: disable=unused-variable
        (
            info,
            pformat,
            error,
        ) = NSPropertyListSerialization.propertyListWithData_options_format_error_(
            NSData.dataWithContentsOfFile_(os.path.expanduser(path)),
            NSPropertyListMutableContainersAndLeaves,
            None,
            None,
        )
        # pylint: enable=unused-variable
        if info is None:
            if error is None:
                error = "Invalid plist file."
            raise PlistParseError("Can't read %s: %s" % (path, error))

        return info

    def write_plist(self, path):
        """Write plist to path.

        Args:
            path: String path to desired plist file.

        Raises:
            PlistDataError: There was an error in the data.
            PlistWriteError: Plist could not be written.
        """
        (
            plist_data,
            error,
        ) = NSPropertyListSerialization.dataWithPropertyList_format_options_error_(
            self, NSPropertyListXMLFormat_v1_0, 0, None
        )
        if plist_data is None:
            if error is None:
                error = "Failed to serialize data to plist."
            raise PlistDataError(error)
        else:
            if not plist_data.writeToFile_atomically_(os.path.expanduser(path), True):
                raise PlistWriteError("Failed writing data to %s" % path)

    def new_plist(self):
        """Generate a barebones recipe plist."""
        # Not implemented at this time.
        pass


class JSSConnection(object):
    """Class for providing a single JSS connection."""

    _jss_prefs = None
    _jss = None

    @classmethod
    def setup(cls, connection=None):
        """Set up the jss connection class variable.

        If no connection argument is provided, setup will use the
        standard JSSImporter preferences
        (com.github.autopkg).

        Args:
            connection: Dictionary with JSS connection info, keys:
                jss_prefs: String path to a preference file.
                url: Path with port to a JSS.
                user: API Username.
                password: API Password.
                repo_prefs: A list of dicts with repository names and
                    passwords. See JSSPrefs.
                ssl_verify: Boolean indicating whether to verify SSL
                    certificates.  Defaults to True.
                verbose: Boolean indicating the level of logging.
                    (Doesn't do much.)
                jss_migrated: Boolean indicating whether scripts have
                    been migrated to the database. Used for determining
                    copy_script type.
                suppress_warnings:
                    Turns off the urllib3 warnings. Remember, these
                    warnings are there for a reason! Use at your own
                    risk.
        """
        if not connection:
            connection = {"jss_prefs": jss.JSSPrefs()}
        cls._jss_prefs = connection
        # pylint: disable=not-a-mapping
        if isinstance(connection, jss.JSSPrefs):
            cls._jss = jss.JSS(jss_prefs=cls._jss_prefs)
        else:
            cls._jss = jss.JSS(**cls._jss_prefs)
        # pylint: enable=not-a-mapping

    @classmethod
    def get(cls):
        """Return the shared JSS object."""
        if not cls._jss:
            cls.setup()
        return cls._jss


class Result(object):
    """Encapsulates the metadata and results from a report."""

    def __init__(self, results, verbose, heading, description=""):
        """Init our data structure.

        Args:
            results: A set of strings of some JSSObject names.
            include_in_non_verbose: Bool whether or not report will be
                included in non-verbose output.
            heading: String heading summarizing the results.
            description: Longer string describing the meaning of the
                results.
        """
        self.results = results
        self.include_in_non_verbose = verbose
        self.heading = heading
        self.description = description

    def __len__(self):
        """Return the length of the results list."""
        return len(self.results)


class Report(object):
    """Represents a collection of Result objects."""

    def __init__(self, obj_type, results, heading, metadata):
        """Init our data structure.

        Args:
            obj_type: String object type name (as returned by
                device_type)
            results: A list of Result objects to include in the
                report.
            heading: String heading describing the report.
            metadata: Dictionary of other data you want to output.
                key: Heading name.
                val Another dictionary, with:
                    key: Subheading name.
                    val: String of data to print.
        """
        self.obj_type = obj_type
        self.results = results
        self.heading = heading
        self.metadata = metadata

    def get_result_by_name(self, name):
        """Return a result with argument name.

        Args:
            name: String name to find in results.

        Returns:
            A Result object or None.
        """
        found = None
        for result in self.results:
            if result.heading == name:
                found = result
                break
        return found


class AppStoreVersionParser(HTMLParser):
    """Subclasses HTMLParser to scrape current app version number."""

    def __init__(self):
        HTMLParser.__init__(self)
        self.version = "Version Not Found"
        self.in_version_span = False

    def reset(self):
        """Manage data state to know when we are in the version span."""
        HTMLParser.reset(self)
        self.in_version_span = False

    def handle_starttag(self, tag, attrs):
        """Override handling of tags to find version metadata."""
        # <span itemprop="softwareVersion">3.0.3
        attrs_dict = dict(attrs)
        if (
            tag == "span"
            and "itemprop" in attrs_dict
            and attrs_dict["itemprop"] == "softwareVersion"
        ):
            self.in_version_span = True

    def handle_data(self, data):
        if self.in_version_span:
            self.version = data
            self.in_version_span = False


def map_jssimporter_prefs(prefs):
    """Convert python-jss preferences to JSSImporter preferences."""
    connection = {}
    connection["url"] = prefs["JSS_URL"]
    connection["user"] = prefs["API_USERNAME"]
    connection["password"] = prefs["API_PASSWORD"]
    connection["ssl_verify"] = prefs.get("JSS_VERIFY_SSL", True)
    connection["suppress_warnings"] = prefs.get("JSS_SUPPRESS_WARNINGS", True)
    connection["jss_migrated"] = prefs.get("JSS_MIGRATED", True)
    connection["repo_prefs"] = prefs.get("JSS_REPOS")
    print("JSS: {}".format(connection["url"]))

    return connection


def build_container_report(containers_with_search_paths, jss_objects):
    """Report on the usage of objects contained in container objects.

    Find the used and unused jss_objects across a list of containing
    JSSContainerObjects.

    For example, Computers can have packages or scripts scoped to
    policies or configurations.

    Args:
        containers_with_search_paths: A list of 2-tuples of:
            ([list of JSSContainerObjects], xpath to search for
            contained objects)
        jss_objects: A list of JSSObject names to search for in
            the containers_with_search_paths.

    Returns:
        A Report object with results and "cruftiness" metadata
        added, but no heading.
    """
    used_object_sets = []
    for containers, search in containers_with_search_paths:
        search = "container.%s" % search.replace("/", ".")
        for container in containers:  # pylint: disable=unused-variable
            try:
                obj = eval(search)
                if obj is not None:
                    used_object_sets.append({(obj.id.text, obj.name.text)})
            except AttributeError:
                pass

    used = set()
    if used_object_sets:
        used = used_object_sets.pop()
    for used_object_set in used_object_sets:
        used = used.union(used_object_set)
    unused = set(jss_objects).difference(used)

    # Use the xpath's second to last part to determine object type.
    obj_type = (
        containers_with_search_paths[0][1].split("/")[-1].replace("_", " ").title()
    )

    all_result = Result(jss_objects, False, "All", "All %ss on the JSS." % obj_type)
    used_result = Result(used, False, "Used")
    unused_result = Result(unused, True, "Unused")
    report = Report(
        obj_type, [all_result, used_result, unused_result], "", {"Cruftiness": {}}
    )
    cruftiness = calculate_cruft(
        report.get_result_by_name("Unused").results,
        report.get_result_by_name("All").results,
    )
    cruft_strings = get_cruft_strings(cruftiness)

    report.metadata["Cruftiness"] = {"Unscoped %s Cruftiness" % obj_type: cruft_strings}

    return report


def build_device_report(check_in_period, devices):
    """Build a report of out-of-date or unresponsive devices.

    Finds the newest OS version and looks for devices which are out
    of date. (Builds a histogram of installed OS versions).

    Compiles a list of devices which have not checked in for
    'check_in_period' days.

    Finally, does a report on the hardware models present.

    Args:
        check_in_period: Integer number of days since last check-in to
            include in report. Defaults to 30.
        devices: List of all Computer or MobileDevice objects from the
            JSS. These lists can be subsetted to include only the
            sections needed for this report.

    Returns:
        A Report object.
    """
    check_in_period = validate_check_in_period(check_in_period)
    device_name = device_type(devices)
    report = Report(device_name, [], "%s Report" % device_name, {"Cruftiness": {}})

    # Out of Date results.
    out_of_date_results = get_out_of_date_devices(check_in_period, devices)
    report.results.append(out_of_date_results[0])
    report.metadata["Cruftiness"][
        "%ss Not Checked In Cruftiness" % device_name
    ] = out_of_date_results[1]

    # Orphaned device results.
    orphaned_device_results = get_orphaned_devices(devices)
    report.results.append(orphaned_device_results[0])
    report.metadata["Cruftiness"][
        "%ss With no Group Membership Cruftiness" % device_name
    ] = orphaned_device_results[1]

    # Version and model results.
    (
        report.metadata["Version Spread"],
        report.metadata["Hardware Model Spread"],
    ) = get_version_and_model_spread(devices)

    # All Devices
    all_devices = [(device.id, device.name) for device in devices]
    report.results.append(Result(all_devices, False, "All %ss" % device_name))

    return report


def get_out_of_date_devices(check_in_period, devices):
    """Produce a report on devices not checked in since check_in_period.

    Args:
        check_in_period: Number of days to consider out of date.
        devices: List of all Computer or MobileDevice objects on the
            JSS.

    Returns:
        Tuple of (Result object, cruftiness)
    """
    device_name = device_type(devices)
    strptime = datetime.datetime.strptime
    out_of_date = datetime.datetime.now() - datetime.timedelta(check_in_period)
    # Example computer contact time format: 2015-08-06 10:46:51
    # Example mobile device time format:Friday, August 07 2015 at 3:51 PM
    if isinstance(devices[0], jss.Computer):
        fmt_string = "%Y-%m-%d %H:%M:%S"
        check_in = "general/last_contact_time"
    else:
        fmt_string = "%A, %B %d %Y at %H:%M %p"
        check_in = "general/last_inventory_update"
    out_of_date_devices = []
    for device in devices:
        last_contact = device.findtext(check_in)
        # Fix incorrectly formatted Mobile Device times.
        if last_contact and isinstance(device, jss.MobileDevice):
            last_contact = hour_pad(last_contact)
        if not last_contact or (strptime(last_contact, fmt_string) < out_of_date):
            out_of_date_devices.append((device.id, device.name))

    description = (
        "This report collects %ss which have not checked in for "
        "more than %i days (%s) based on their %s property."
        % (device_name, check_in_period, out_of_date, check_in.split("/")[1])
    )
    out_of_date_report = Result(
        out_of_date_devices, True, "Out of Date %ss" % device_name, description
    )

    out_of_date_cruftiness = calculate_cruft(out_of_date_report.results, devices)
    cruftiness = get_cruft_strings(out_of_date_cruftiness)

    return (out_of_date_report, cruftiness)


def get_orphaned_devices(devices):
    """Generate Result of devices with no group memberships.

    Also, include a cruftiness result.

    Args:
        devices: List of all Computer or MobileDevice objects on the
            JSS.

    Returns:
        Tuple of (Result object, cruftiness)
    """
    device_name = device_type(devices)
    orphaned_devices = [
        (device.id, device.name)
        for device in devices
        if has_no_group_membership(device)
    ]
    description = (
        "This report collects %ss which do not belong to any "
        "static or smart groups." % device_name
    )
    orphan_report = Result(
        orphaned_devices,
        True,
        "%ss With no Group Membership" % device_name,
        description,
    )

    orphan_cruftiness = calculate_cruft(orphan_report.results, devices)
    cruftiness = get_cruft_strings(orphan_cruftiness)

    return (orphan_report, cruftiness)


def device_type(devices):
    """Return a string type name for a list of devices."""

    num_of_types = len({type(device) for device in devices})
    if num_of_types == 1:
        # print("TEST: device: %s" % type(devices[0]).__name__)
        return type(devices[0]).__name__
    elif num_of_types == 0:
        return None
    else:
        raise ValueError


def get_version_and_model_spread(devices):
    """Generate version spread metadata for device reports.

    Args:
        devices: List of all Computer or MobileDevice objects on the
            JSS.

    Returns:
        Dictionary appropriate for use in Report.metadata.
    """
    if isinstance(devices[0], jss.Computer):
        os_type_search = "hardware/os_name"
        os_type = "Mac OS X"
        os_version_search = "hardware/os_version"
        model_search = "hardware/model"
        model_identifier_search = "hardware/model_identifier"
    else:
        os_type_search = "general/os_type"
        os_type = "iOS"
        os_version_search = "general/os_version"
        model_search = "general/model"
        model_identifier_search = "general/model_identifier"
    versions, models = [], []

    for device in devices:
        if device.findtext(os_type_search) == os_type:
            versions.append(
                device.findtext(os_version_search) or "No Version Inventoried"
            )
            models.append(
                "%s / %s"
                % (
                    device.findtext(model_search) or "No Model",
                    device.findtext(model_identifier_search,) or "No Model Identifier",
                )
            )
    version_counts = Counter(versions)
    # Standardize version number format.
    version_counts = fix_version_counts(version_counts)
    model_counts = Counter(models)

    total = len(devices)

    # Report on OS version spread
    strings = sorted(get_histogram_strings(version_counts, padding=8))
    version_metadata = {"%s Version Histogram (%s)" % (os_type, total): strings}

    # Report on Model Spread
    # Compare on the model identifier since it is an easy numerical
    # sort.
    strings = sorted(get_histogram_strings(model_counts, padding=8), key=model_compare)
    model_metadata = {"Hardware Model Histogram (%s)" % total: strings}

    return (version_metadata, model_metadata)


def model_compare(histogram_string):
    """Return Model Identifier for use as key in sorted() function.

    Args:
        histogram_string: Histogram string comprising of Mac model, count and emoji e.g.
            iMac Intel (21.5-inch, Late 2013) / iMac14,1 (2): 🍕🍕🍕🍕🍕🍕

    Returns:
        Model Identifier e.g. iMac14,1
    """
    pattern = re.compile(r"(\D+\d+,\d+)")
    string_search = re.search(pattern, histogram_string)
    if string_search:
        return string_search.group(1)


def build_computers_report(check_in_period, **kwargs):
    """Build a report of out-of-date or unresponsive computers.

    Finds the newest OS version and looks for computers which are out
    of date. (Builds a histogram of installed OS versions).

    Also, compiles a list of computers which have not checked in for
    'check_in_period' days.

    Finally, does a report on the hardware models present.

    Args:
        check_in_period: Integer number of days since last check-in to
            include in report. Defaults to 30.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_computers = jss_connection.Computer(
        ["general", "hardware", "groups_accounts"]
    ).retrieve_all()

    if all_computers:
        report = build_device_report(check_in_period, all_computers)
        report.heading = "Computer Report"
    else:
        report = Report("Computer", [], "Computer Report", {})
    return report


def build_mobile_devices_report(check_in_period, **kwargs):
    """Build a report of out-of-date or unresponsive mobile devices.

    Finds the newest OS version and looks for devices which are out
    of date. (Builds a histogram of installed OS versions).

    Also, compiles a list of computers which have not checked in for
    'check_in_period' days.

    Finally, does a report on the hardware models present.

    Args:
        check_in_period: Integer number of days since last check-in to
            include in report. Defaults to 30.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    mobile_devices = jss_connection.MobileDevice(
        ["general", "mobile_device_groups", "mobiledevicegroups"]
    ).retrieve_all()

    if mobile_devices:
        report = build_device_report(check_in_period, mobile_devices)
        report.heading = "Mobile Device Report"
    else:
        report = Report("MobileDevice", [], "Mobile Device Report", {})

    return report


def validate_check_in_period(check_in_period):
    """Ensure check_in_period argument is correct.

    Args:
        check_in_period: Number of days to consider out of date.

    Returns:
        A valid int check-in-period number of days.
    """
    if not check_in_period:
        check_in_period = 30
    if not isinstance(check_in_period, int):
        try:
            check_in_period = int(check_in_period)
        except ValueError:
            print("Incorrect check-in period given. Setting to 30.")
            check_in_period = 30

    return check_in_period


def hour_pad(datetime_string):
    """Fix time strings' zero padding.

    JAMF's dates don't always properly zero pad the hour. Do so.

    Args:
        datetime_string: A time string as referenced in MobileDevice's
            last_inventory_time field.

    Returns:
        The string plus any zero padding required.
    """
    # Example mobile device time format:
    # Friday, August 07 2015 at 3:51 PM
    # Monday, February 10 2014 at 8:42 AM<
    components = datetime_string.split()
    if len(components[5]) == 1:
        components[5] = "0" + components[5]
    return " ".join(components)


def build_packages_report(**kwargs):
    """Report on package usage.

    Looks for packages which are not installed by any policies, patch policies or
    computer configurations.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()

    all_policies = jss_connection.Policy(
        ["general", "package_configuration", "packages"]
    ).retrieve_all()
    all_configs = jss_connection.ComputerConfiguration().retrieve_all()
    all_packages = [(pkg.id, pkg.name) for pkg in jss_connection.Package()]
    if not all_packages:
        report = Report("Package", [], "Package Usage Report", {})
    else:
        policy_xpath = "package_configuration/packages/package"
        # patch_policy_xpath = "package_configuration/packages/package"
        config_xpath = "packages/package"
        report = build_container_report(
            [(all_policies, policy_xpath), (all_configs, config_xpath)], all_packages
        )
        report.get_result_by_name("Used").description = (
            "All packages which are installed by policies or imaging " "configurations."
        )
        report.get_result_by_name("Unused").description = (
            "All packages which are not installed by any policies or imaging "
            "configurations."
        )

        report.heading = "Package Usage Report"

    return report


def build_printers_report(**kwargs):
    """Report on printer usage.

    Looks for printers which are not installed by any policies or
    computer configurations.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()

    all_policies = jss_connection.Policy(["general", "printers"]).retrieve_all()
    all_configs = jss_connection.ComputerConfiguration().retrieve_all()
    all_printers = [(printer.id, printer.name) for printer in jss_connection.Printer()]
    if not all_printers:
        report = Report("Printer", [], "Printer Usage Report", {})
    else:
        policy_xpath = "printers/printer"
        config_xpath = "printers/printer"
        report = build_container_report(
            [(all_policies, policy_xpath), (all_configs, config_xpath)], all_printers
        )
        report.get_result_by_name("Used").description = (
            "All printers which are installed by policies or imaging " "configurations."
        )
        report.get_result_by_name("Unused").description = (
            "All printers which are not installed by any policies or imaging "
            "configurations."
        )

        report.heading = "Printer Usage Report"

    return report


def build_scripts_report(**kwargs):
    """Report on script usage.

    Looks for scripts which are not executed by any policies or
    computer configurations.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_policies = jss_connection.Policy(["general", "scripts"]).retrieve_all()
    all_configs = jss_connection.ComputerConfiguration().retrieve_all()
    all_scripts = [(script.id, script.name) for script in jss_connection.Script()]
    if not all_scripts:
        report = Report("Script", [], "Script Usage Report", {})
    else:
        policy_xpath = "scripts/script"
        config_xpath = "scripts/script"
        report = build_container_report(
            [(all_policies, policy_xpath), (all_configs, config_xpath)], all_scripts
        )
        report.get_result_by_name("Used").description = (
            "All scripts which are installed by policies or imaging " "configurations."
        )
        report.get_result_by_name("Unused").description = (
            "All scripts which are not installed by any policies or imaging "
            "configurations."
        )

        report.heading = "Script Usage Report"

    return report


def build_group_report(container_searches, groups_names, full_groups):
    """Report on group usage.

    Looks for computer or mobile device groups with no members. This
    does not mean they neccessarily are in-need-of-deletion.

    Args:
        container_searches: List of tuples to be passed to
            build_container_report.
        groups: List of (id, name) tuples for all groups on the JSS.
        full_groups: List of full JSSObject data for groups.

    Returns:
        A Report object.
    """
    # Build results for groups which aren't scoped.
    report = build_container_report(container_searches, groups_names)

    # Here we do more work, since Smart Groups can nest other groups.
    # We want to remove any groups nested (at any level) within a group
    # that is used.

    # For convenience, pull out unused and used sets.
    unused_groups = report.get_result_by_name("Unused").results
    used_groups = report.get_result_by_name("Used").results
    used_full_group_objects = get_full_groups_from_names(used_groups, full_groups)
    full_used_nested_groups = get_nested_groups(used_full_group_objects, full_groups)
    used_nested_groups = get_names_from_full_objects(full_used_nested_groups)

    # Remove the nested groups from the unused list and add to the used.
    unused_groups.difference_update(used_nested_groups)
    # There's no harm in doing a union with the nested used groups vs.
    # adding _just_ the ones removed from unused_groups.
    used_groups.update(used_nested_groups)

    # Recalculate cruftiness
    unused_cruftiness = calculate_cruft(unused_groups, groups_names)
    obj_type = device_type(full_groups)
    report.metadata["Cruftiness"][
        "Unscoped %s Cruftiness" % obj_type
    ] = get_cruft_strings(unused_cruftiness)

    # Build Empty Groups Report.
    empty_groups = get_empty_groups(full_groups)
    report.results.append(empty_groups)

    # Calculate empty cruftiness.
    empty_cruftiness = calculate_cruft(empty_groups, groups_names)
    report.metadata["Cruftiness"]["Empty Group Cruftiness"] = get_cruft_strings(
        empty_cruftiness
    )

    # Build No Criteria Groups Report.
    no_criteria_groups = get_no_criteria_groups(full_groups)
    report.results.append(no_criteria_groups)

    # Calculate empty cruftiness.
    no_criteria_cruftiness = calculate_cruft(no_criteria_groups, groups_names)
    report.metadata["Cruftiness"]["No Criteria Group Cruftiness"] = get_cruft_strings(
        no_criteria_cruftiness
    )

    return report


def build_computer_groups_report(**kwargs):
    """Report on computer groups usage.

    Looks for computer groups with no members. This does not mean
    they neccessarily are in-need-of-deletion.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    group_list = jss_connection.ComputerGroup()
    if not group_list:
        return Report("ComputerGroup", [], "Computer Group Report", {})

    all_computer_groups = [(group.id, group.name) for group in group_list]
    full_groups = group_list.retrieve_all()

    # all_policies = jss_connection.Policy().retrieve_all(
    #     subset=[])
    all_policies = jss_connection.Policy(["general", "scope"]).retrieve_all()
    # all_configs = jss_connection.OSXConfigurationProfile().retrieve_all(
    #     subset=["general", "scope"])
    all_configs = jss_connection.OSXConfigurationProfile(
        ["general", "scope"]
    ).retrieve_all()

    # Account for fix in python-jss that isn't yet part of a release.
    if hasattr(jss_connection, "RestrictedSoftware"):
        all_restricted_software = jss_connection.RestrictedSoftware().retrieve_all()
    else:
        all_restricted_software = jss_connection.RestrictedSfotware().retrieve_all()

    scope_xpath = "scope/computer_groups/computer_group"
    scope_exclusions_xpath = "scope/exclusions/computer_groups/computer_group"

    # Build results for groups which aren't scoped.
    report = build_group_report(
        [
            (all_policies, scope_xpath),
            (all_policies, scope_exclusions_xpath),
            (all_configs, scope_xpath),
            (all_configs, scope_exclusions_xpath),
            (all_restricted_software, scope_xpath),
            (all_restricted_software, scope_exclusions_xpath),
        ],
        all_computer_groups,
        full_groups,
    )

    report.heading = "Computer Group Usage Report"
    report.get_result_by_name("Used").description = (
        "All groups which participate in scoping. Computer groups are "
        "considered to be in-use if they are designated in the scope or the "
        "exclusions of a policy or a configuration profile. This report "
        "includes all groups which are nested inside of smart groups using "
        "the 'member_of' criterion."
    )
    report.get_result_by_name("Unused").description = (
        "All groups which do not participate in scoping. Computer groups are "
        "considered to be in-use if they are designated in the scope or the "
        "exclusions of a policy or a configuration profile. This report "
        "includes all groups which are nested inside of smart groups using "
        "the 'member_of' criterion."
    )

    return report


def build_computer_ea_report(**kwargs):
    """Report on computer extension attributes usage.

    Looks for computer extension attributes not being used as criteria in any
    smart groups or advanced searches. This does not mean they neccessarily are in-need-of-deletion.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_eas = [(ea.id, ea.name) for ea in jss_connection.ComputerExtensionAttribute()]
    if not all_eas:
        return Report(
            "Computer Extension Attribute",
            [],
            "Computer Extension Attribute Usage Report",
            {},
        )
    all_eas_result = Result(all_eas, False, "All Computer Extension Attributes")

    # Build results for extension attributes which aren't used in criteria.
    all_groups = jss_connection.ComputerGroup().retrieve_all()
    all_advanced_computer_searches = jss_connection.AdvancedComputerSearch().retrieve_all()
    all_criteria = (all_groups + all_advanced_computer_searches)
    used_criteria = []

    # get fully unused
    for criteria in all_criteria:
        criteria_names = get_all_criteria_names(criteria)
        for criteria_name in criteria_names:
            if criteria_name not in used_criteria:
                used_criteria.append(criteria_name)

    unused_eas = [ea for ea in all_eas if ea[1] not in used_criteria]
    desc = "All extension attributes which are not used in computer groups, or any advanced searches"
    unused = Result(unused_eas, True, "Unused Computer Extension Attributes", desc)
    unused_cruftiness = calculate_cruft(unused_eas, all_eas)

    report = Report(
        "Computer Extension Attribute",
        [unused, all_eas_result],
        "Computer Extension Attribute Report",
        {"Cruftiness": {}},
    )
    report.metadata["Cruftiness"][
        "Unused Computer Extension Attribute Cruftiness"
    ] = get_cruft_strings(unused_cruftiness)

    return report


def get_all_criteria_names(group):
    """Get the names of any extension attribute criteria in a group, or an empty set.

    Args:
        group: A jss.ComputerGroup object to search for extension attributes.

    Returns:
        A tuple of the extension attribute criteria in the provided group.
        Returns an empty set if no extension attributes are present.
    """
    return (
        criterion.findtext("name")
        for criterion in group.findall("criteria/criterion")
        if criterion.findtext("search_type") != "member of"
    )


def build_device_groups_report(**kwargs):
    """Report on mobile device groups usage.

    Looks for mobile device groups with no members. This does not mean
    they neccessarily are in-need-of-deletion.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    group_list = jss_connection.MobileDeviceGroup()
    if not group_list:
        return Report("MobileDeviceGroup", [], "Mobile Device Group Report", {})

    all_mobile_device_groups = [(group.id, group.name) for group in group_list]
    full_groups = group_list.retrieve_all()

    all_configs = jss_connection.MobileDeviceConfigurationProfile(
        ["general", "scope"]
    ).retrieve_all()
    all_provisioning_profiles = jss_connection.MobileDeviceProvisioningProfile(
        ["general", "scope"]
    ).retrieve_all()
    all_apps = jss_connection.MobileDeviceApplication(
        ["general", "scope"]
    ).retrieve_all()
    all_ebooks = jss_connection.EBook(["general", "scope"]).retrieve_all()
    xpath = "scope/mobile_device_groups/mobile_device_group"
    exclusion_xpath = "scope/exclusions/mobile_device_groups/mobile_device_group"

    # Build results for groups which aren't scoped.
    report = build_group_report(
        [
            (all_configs, xpath),
            (all_configs, exclusion_xpath),
            (all_provisioning_profiles, xpath),
            (all_provisioning_profiles, exclusion_xpath),
            (all_apps, xpath),
            (all_apps, exclusion_xpath),
            (all_ebooks, xpath),
            (all_ebooks, exclusion_xpath),
        ],
        all_mobile_device_groups,
        full_groups,
    )
    report.heading = "Mobile Device Group Usage Report"
    report.get_result_by_name("Used").description = (
        "All groups which participate in scoping. Mobile device groups are "
        "considered to be in-use if they are designated in the scope or the "
        "exclusions of a configuration profile, provisioning profile, app, "
        "or ebook. This report includes all groups which are nested inside "
        "of smart groups using the 'member_of' criterion."
    )
    report.get_result_by_name("Unused").description = (
        "All groups which do not participate in scoping. Mobile device groups "
        "are considered to be in-use if they are designated in the scope or "
        "the exclusions of a configuration profile, provisioning profile, "
        "app, or ebook. This report includes all groups which are nested "
        "inside of smart groups using the 'member_of' criterion."
    )

    return report


def build_policies_report(**kwargs):
    """Report on policy usage.

    Looks for policies which are not scoped to anything or are disabled.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_policies = jss_connection.Policy(["general", "scope"]).retrieve_all()
    if not all_policies:
        return Report("Policy", [], "Policy Usage Report", {})

    all_policies_result = Result(
        [(policy.id, policy.name) for policy in all_policies], False, "All Policies"
    )
    unscoped_policies = [
        (policy.id, policy.name)
        for policy in all_policies
        if policy.findtext("scope/all_computers") == "false"
        and not policy.findall("scope/computers/computer")
        and not policy.findall("scope/computer_groups/computer_group")
        and not policy.findall("scope/buildings/building")
        and not policy.findall("scope/departments/department")
    ]
    desc = (
        "Policies which are not scoped to any computers, computer groups, "
        "buildings, departments, or to the all_computers meta-scope."
    )
    unscoped = Result(unscoped_policies, True, "Policies not Scoped", desc)
    unscoped_cruftiness = calculate_cruft(unscoped_policies, all_policies)

    disabled_policies = [
        (policy.id, policy.name)
        for policy in all_policies
        if policy.findtext("general/enabled") == "false"
    ]
    disabled = Result(
        disabled_policies,
        True,
        "Disabled Policies",
        "Policies which are currently disabled " "(Policy/General/Enabled toggle).",
    )
    disabled_cruftiness = calculate_cruft(disabled_policies, all_policies)

    report = Report(
        "Policy",
        [unscoped, disabled, all_policies_result],
        "Policy Report",
        {"Cruftiness": {}},
    )

    report.metadata["Cruftiness"]["Unscoped Policy Cruftiness"] = get_cruft_strings(
        unscoped_cruftiness
    )
    report.metadata["Cruftiness"]["Disabled Policy Cruftiness"] = get_cruft_strings(
        disabled_cruftiness
    )

    return report


def build_config_profiles_report(**kwargs):
    """Report on computer configuration profile usage.

    Looks for profiles which are not scoped to anything.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_configs = jss_connection.OSXConfigurationProfile(
        ["general", "scope"]
    ).retrieve_all()
    if not all_configs:
        return Report(
            "Computer Configuration Profile",
            [],
            "Computer Configuration Profile Report",
            {},
        )

    all_configs_result = Result(
        [(config.id, config.name) for config in all_configs],
        False,
        "All OSX Configuration " "Profiles",
    )

    unscoped_configs = [
        (config.id, config.name)
        for config in all_configs
        if config.findtext("scope/all_computers") == "false"
        and not config.findall("scope/computers/computer")
        and not config.findall("scope/computer_groups/" "computer_group")
        and not config.findall("scope/buildings/building")
        and not config.findall("scope/departments/department")
    ]
    desc = (
        "Computer configuration profiles which are not scoped to any "
        "computers, computer groups, buildings, departments, or to the "
        "all_computers meta-scope."
    )
    unscoped = Result(
        unscoped_configs, True, "Computer Configuration Profiles not Scoped", desc
    )
    unscoped_cruftiness = calculate_cruft(unscoped_configs, all_configs)
    report = Report(
        "Computer Configuration Profile",
        [unscoped, all_configs_result],
        "Computer Configuration Profile Report",
        {"Cruftiness": {}},
    )
    report.metadata["Cruftiness"]["Unscoped Profile Cruftiness"] = get_cruft_strings(
        unscoped_cruftiness
    )

    return report


def build_md_config_profiles_report(**kwargs):
    """Report on mobile device configuration profile usage.

    Looks for profiles which are not scoped to anything.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_configs = jss_connection.MobileDeviceConfigurationProfile(
        ["general", "scope"]
    ).retrieve_all()
    if not all_configs:
        return Report(
            "Mobile Device Configuration Profile",
            [],
            "Mobile Device Configuration Profile Report",
            {},
        )
    all_configs_result = Result(
        [(config.id, config.name) for config in all_configs],
        False,
        "All iOS Configuration " "Profiles",
    )
    unscoped_configs = [
        (config.id, config.name)
        for config in all_configs
        if config.findtext("scope/all_mobile_devices") == "false"
        and not config.findall("scope/mobile_devices/mobile_device")
        and not config.findall("scope/mobile_device_groups/mobile_device_group")
        and not config.findall("scope/jss_users/user")
        and not config.findall("scope/jss_user_groups/user_group")
        and not config.findall("scope/buildings/building")
        and not config.findall("scope/departments/department")
    ]
    desc = (
        "Mobile device configuration profiles which are not scoped to any "
        "devices, device groups, users, user groups, buildings, "
        "departments, or to the all_mobile_devices meta-scope."
    )
    unscoped = Result(
        unscoped_configs, True, "Mobile Device Configuration Profiles not Scoped", desc
    )
    unscoped_cruftiness = calculate_cruft(unscoped_configs, all_configs)
    report = Report(
        "Mobile Device Configuration Profile",
        [unscoped, all_configs_result],
        "Mobile Device Configuration Profile Report",
        {"Cruftiness": {}},
    )
    report.metadata["Cruftiness"]["Unscoped Profile Cruftiness"] = get_cruft_strings(
        unscoped_cruftiness
    )

    return report


def build_apps_report(**kwargs):
    """Report on out of date and unscoped mobile apps.

    Returns:
        A Report object.
    """
    # All report functions support kwargs to support a unified interface,
    # even if they don't use them.
    _ = kwargs
    jss_connection = JSSConnection.get()
    all_apps = jss_connection.MobileDeviceApplication(
        ["general", "scope"]
    ).retrieve_all()
    if not all_apps:
        return Report("Mobile Application", [], "Mobile Device Application Report", {})

    all_apps_result = Result(
        [(app.id, app.name) for app in all_apps],
        False,
        "All Mobile Device Applications",
    )
    # Find apps not scoped anywhere.
    unscoped_apps = [
        (app.id, app.name)
        for app in all_apps
        if app.findtext("scope/all_mobile_devices") == "false"
        and app.findtext("scope/all_jss_users") == "false"
        and not app.findall("scope/mobile_devices/mobile_device")
        and not app.findall("scope/mobile_device_groups/mobile_device_group")
        and app.findall("scope/jss_users/user")
        and not app.findall("scope/jss_user_groups/user_group")
        and not app.findall("scope/buildings/building")
        and not app.findall("scope/departments/department")
    ]
    desc = (
        "Mobile Applications which are not scoped to any "
        "devices, device groups, users, user groups, buildings, "
        "departments, or to the all_mobile_devices or all_jss_users "
        "meta-scopes."
    )
    unscoped = Result(
        unscoped_apps, True, "Mobile Device Applications not Scoped", desc
    )
    unscoped_cruftiness = calculate_cruft(unscoped_apps, all_apps)

    report = Report(
        "Mobile Application",
        [unscoped, all_apps_result],
        "Mobile Device Application Report",
        {"Cruftiness": {}},
    )
    report.metadata["Cruftiness"]["Unscoped App Cruftiness"] = get_cruft_strings(
        unscoped_cruftiness
    )

    # Find out-of-date and discontinued apps.
    out_of_date = {}
    discontinued = []
    # Start a requests session.
    session = requests.session()
    for app in all_apps:
        external_url = app.findtext("general/external_url")
        if external_url:
            page = session.get(external_url).text
            version_parser = AppStoreVersionParser()
            version_parser.feed(page)
            current_version = version_parser.version
            if app.findtext("general/version") != current_version:
                out_of_date[app.name] = (
                    app.findtext("general/version"),
                    current_version,
                )
            if current_version == "Version Not Found":
                discontinued.append((app.id, app.name))

    report.metadata["Out-of-Date Apps"] = {}
    report.metadata["Out-of-Date Apps"]["Out-of-Date Apps"] = get_out_of_date_strings(
        out_of_date
    )

    desc = (
        "Mobile applications which are no longer available from the Apple "
        " App Store."
    )
    discontinued_result = Result(discontinued, True, "Apps No Longer Available", desc)
    report.results.append(discontinued_result)

    out_of_date_cruftiness = calculate_cruft(out_of_date, all_apps)
    report.metadata["Cruftiness"]["Out-of-Date App Cruftiness"] = get_cruft_strings(
        out_of_date_cruftiness
    )

    discontinued_cruftiness = calculate_cruft(discontinued, all_apps)
    report.metadata["Cruftiness"]["Discontinued App Cruftiness"] = get_cruft_strings(
        discontinued_cruftiness
    )

    return report


def get_nested_groups(groups, full_groups):
    """Get all of the groups 'nested' in an iterable of groups.

    A smart group may include other groups with a Computer Group
    criterion. This function will find all of the groups nested within
    a provided iterable of jss.ComputerGroup objects (including nested
    groups that _also_ nest groups).

    Args:
        groups: An iterable of jss.ComputerGroup objects to search
            for nested groups within.
        full_groups: A list of all computer groups. This will hopefully
            be deprecated once a connection caching procedure is
            devised.

    Returns:
        A set of groups nested within the original groups argument.
    """
    results = set()
    for group in groups:
        # Get the names of any nested groups.
        nested_groups_names = get_nested_groups_names(group)
        if nested_groups_names:
            # Function needs full objects, and criteria only specify
            # the name, so we need to "convert" names to full objects.
            nested_groups = get_full_groups_from_names(nested_groups_names, full_groups)
            # Add the nested groups to the results.
            results.update(nested_groups)
            # Recursively look for any groups nested in the nested
            # groups.
            results.update(get_nested_groups(nested_groups, full_groups))

        # If no groups are nested, we are done.
    return results


def get_nested_groups_names(group):
    """Get the names of any nested groups in a group, or an empty set.

    Args:
        group: A jss.ComputerGroup object to search for nested groups.

    Returns:
        A tuple of the group names nested in the provided group.
        Returns an empty set if no nested groups are present.
    """
    # print(group.criteria.criterion)
    return_groups = []
    for criterion in group.findall("criteria/criterion"):
        try:
            criterion.name.text
            if (
                criterion.name.text in ("Computer Group", "Mobile Device Group")
                and criterion.search_type.text == "member of"
            ):
                return_groups.append(criterion.value.text)
        except AttributeError:
            # print(criterion)
            pass

    return return_groups

    # return (
    #     criterion.value.text
    #     for criterion in group.findall("criteria/criterion") if
    #     criterion.name.text in ("Computer Group", "Mobile Device Group")
    #     and criterion.search_type.text == "member of")

    # return (
    #     criterion.value
    #     for criterion in group.findall("criteria/criterion") if
    #     criterion.name in ("Computer Group", "Mobile Device Group")
    #     and criterion.search_type == "member of")


def get_full_groups_from_names(groups, full_groups):
    """Given a list a of group names, get the full objects.

    Args:
        groups: A list of names.
        full_groups: A list of all jss.ComputerGroup or
            jss.MobileDeviceGroup objects.

    Returns:
        A list of jss.ComputerGroup or jss.MobileDeviceGroup objects
        corresponding to the names given by the groups argument.
    """
    return_full_groups = []

    for full_group in full_groups:
        if full_group.is_smart is True:
            for group in groups:
                group_name = group[1]
                if full_group.name == group_name:
                    return_full_groups.append(full_group)
                    continue
    return return_full_groups

    # return [full_group for group in groups for full_group in
    #         full_groups if full_group.name == group[1]]


def get_names_from_full_objects(objects):
    """Return a list of object names provided list of full objects."""
    return [obj.name for obj in objects]


def get_empty_groups(full_groups):
    """Return all groups with no members as a Result.

    Args:
        full_groups: list of all groups from jss; i.e.
            jss_connection.ComputerGroup().retrieve_all()

    Returns:
        Result object.
    """
    if isinstance(full_groups[0], jss.ComputerGroup):
        obj_type = ("computers", "Computer")
    elif isinstance(full_groups[0], jss.MobileDeviceGroup):
        obj_type = ("mobile_devices", "Mobile Device")
    else:
        raise TypeError("Incorrect group type.")
    groups_with_no_members = {
        (group.id, group.name)
        for group in full_groups
        if group.findtext("%s/size" % obj_type[0]) == "0"
    }
    return Result(
        groups_with_no_members,
        True,
        "Empty %s Groups" % obj_type[1],
        "%s groups which have no members." % obj_type[1],
    )


def get_no_criteria_groups(full_groups):
    """Return a Result with all smart groups that have no criteria.

    Args:
        full_groups: list of all groups from jss; i.e.
            jss_connection.ComputerGroup().retrieve_all()

    Returns:
        Result object.
    """
    if isinstance(full_groups[0], jss.ComputerGroup):
        obj_type = ("computers", "Computer")
    elif isinstance(full_groups[0], jss.MobileDeviceGroup):
        obj_type = ("mobile_devices", "Mobile Device")
    else:
        raise TypeError("Incorrect group type.")
    groups_with_no_criteria = {
        (group.id, group.name)
        for group in full_groups
        if group.findtext("is_smart") == "true"
        and int(group.findtext("criteria/size")) == 0
    }
    return Result(
        groups_with_no_criteria,
        True,
        "No Criteria %s Groups" % obj_type[1],
        "%s groups which have no criteria." % obj_type[1],
    )


def has_no_group_membership(device):
    """Test whether a computer or mobile device belongs to any groups.

    This test does not count membership in the default smart groups:
        "All Managed Clients",
        "All Managed Servers",
        "All Managed iPads",
        "All Managed iPhones",
        "All Managed iPod touches"

    Args:
        device: A jss.Computer or jss.MobileDevice object.

    Returns:
        Bool.
    """
    excluded_groups = (
        "All Managed Clients",
        "All Managed Servers",
        "All Managed iPads",
        "All Managed iPhones",
        "All Managed iPod touches",
    )
    if isinstance(device, jss.Computer):
        xpath = "groups_accounts/computer_group_memberships/group"
        group_membership = [
            group.text
            for group in device.findall(xpath)
            if not group.text in excluded_groups
        ]
    elif isinstance(device, jss.MobileDevice):
        xpath = "mobile_device_groups/mobile_device_group"
        group_membership = [
            group.findtext("name")
            for group in device.findall(xpath)
            if not group.findtext("name") in excluded_groups
        ]
    else:
        raise TypeError

    if group_membership:
        result = False
    else:
        result = True

    return result


def calculate_cruft(dividend, divisor):
    """Zero-safe find percentage of a subgroup within a larger group."""
    if divisor:
        result = float(len(dividend)) / len(divisor)
    else:
        result = 0.0
    return result


def print_output(report, verbose=False):
    """Print report data.

    Args:
        reports: Report object.
        verbose: Bool, whether to print all results or just unused
            results.
    """

    # Handle command line arguments.
    parser = build_argparser()
    args = parser.parse_args()

    #  set emoji
    if not args.kawaii:
        SPRUCE = "*"
    elif sys.version_info[0] < 3:
        SPRUCE = "\xF0\x9F\x8C\xB2"
    else:
        SPRUCE = "\N{evergreen tree}"

    # Indent is a space and a spruce emoji wide (so 3).
    indent_size = 3 * " "
    forest_length = (64 - len(report.heading)) / 2
    print("%s  %s %s " % (SPRUCE, report.heading, SPRUCE * int(forest_length)))
    if not report.results:
        print("%s  No Results %s" % (SPRUCE, SPRUCE))
    else:
        for result in report.results:
            if not result.include_in_non_verbose and not verbose:
                continue
            else:
                print("\n%s  %s (%i)" % (SPRUCE, result.heading, len(result.results)))
                if result.description:
                    print(
                        textwrap.fill(
                            result.description,
                            initial_indent=indent_size,
                            subsequent_indent=indent_size,
                        )
                    )
                print("")
                for line in sorted(result.results, key=lambda s: s[1].upper().strip()):
                    if line[1].strip() == "":
                        text = "(***NO NAME: ID is %s***)" % line[0]
                    else:
                        text = line[1]
                    print("\t%s" % text)

        for heading, subsection in report.metadata.items():
            print("\n%s  %s %s" % (SPRUCE, heading, SPRUCE))
            for subheading, strings in subsection.items():
                print("%s  %s" % (SPRUCE, subheading))
                for line in strings:
                    print("\t%s" % line)


def get_cruftmoji(percentage):
    """Return one of 11 possible emojis depending on how crufty.

    Args:
        percentage: A float between 0 and 1.

    Returns:
        An emoji string.
    """

    # emoji are not handled the same in python2 and 3 so we need a different kind
    # of encoding for each.
    if sys.version_info[0] < 3:
        PIZZA = "\xf0\x9f\x8d\x95"
        ALIEN = "\xf0\x9f\x91\xbe"
        BEER = "\xf0\x9f\x8d\xbb"
        CROSSED_ARMS = "\xf0\x9f\x99\x8f"
        SNAKE = "\xf0\x9f\x90\x8d"
        PLANE = "\xe2\x9c\x88\xef\xb8\x8f"
        GUARD = "\xf0\x9f\x92\x82"
        GHOST = "\xf0\x9f\x91\xbb"
        BOMB = "\xf0\x9f\x92\xa3"
        POODLE = "\xf0\x9f\x90\xa9"
        WIND = "\xf0\x9f\x92\xa8"
        SKULL = "\xf0\x9f\x92\x80"
        VHS = "\xf0\x9f\x93\xbc"
        CACTUS = "\xf0\x9f\x8c\xb5"
        POO = "\xf0\x9f\x92\xa9"
    else:
        PIZZA = "\N{slice of pizza}"
        ALIEN = "\N{alien monster}"
        BEER = "\N{clinking beer mugs}"
        CROSSED_ARMS = "\N{person with folded hands}"
        SNAKE = "\N{snake}"
        PLANE = "\N{airplane}"
        GUARD = "\N{guardsman}"
        GHOST = "\N{ghost}"
        BOMB = "\N{bomb}"
        POODLE = "\N{poodle}"
        WIND = "\N{dash symbol}"
        SKULL = "\N{skull}"
        VHS = "\N{videocassette}"
        CACTUS = "\N{cactus}"
        POO = "\N{pile of poo}"

    # Handle command line arguments.
    parser = build_argparser()
    args = parser.parse_args()

    if not args.kawaii:
        level = [
            "Master",
            "Snakes on a Plane",
            "Furry Hat Pizza Party",
            "Ghost",
            "The Bomb",
            "Farting Poodle",
            "Skull",
            "Video Cassette",
            "Cactus",
            "Smiling Poo",
            "Three steaming piles of poo",
        ]
        return str(level[int(percentage * 10)])
    else:
        level = [
            # Master
            "%s %s %s %s %s %s %s"
            % (CROSSED_ARMS, BEER, PIZZA, ALIEN, PIZZA, BEER, CROSSED_ARMS),
            # Snakes on a Plane
            "%s %s %s" % (SNAKE, SNAKE, PLANE),
            # Furry Hat Pizza Party
            "%s %s %s" % (PIZZA, GUARD, PIZZA),
            GHOST,  # Ghost
            BOMB,  # The Bomb
            "%s %s" % (POODLE, WIND),  # Poodle Fart
            SKULL,  # Skull
            VHS,  # VHS Cassette
            CACTUS,  # Cactus
            POO,  # Smiling Poo
            "%s %s %s" % (POO, POO, POO),
        ]  # Smiling Poo (For 100%)
        if sys.version_info[0] < 3:
            return level[int(percentage * 10)].decode("utf-8")
        else:
            return str(level[int(percentage * 10)])


def get_cruft_strings(cruft):
    """Generate a list of strings for cruft reports."""
    # Handle command line arguments.
    parser = build_argparser()
    args = parser.parse_args()

    if args.kawaii:
        return ["{:.2%}".format(cruft), "Rank: %s" % get_cruftmoji(cruft)]
    else:
        return ["{:.2%}".format(cruft)]


def get_terminal_size():
    """Get the size of the terminal window."""
    rows, columns = subprocess.check_output(["stty", "size"]).split()
    return (int(rows), int(columns))


def fix_version_counts(version_counts):
    """Fix too short version names by appending a '.0'.

    Args:
        version_counts: Dict of key: version name val: Count of clients.

    Returns:
        The updated version_counts dict.
    """
    result = {}
    ignored = ("", "No Version Inventoried")
    for version in version_counts:
        if version.count(".") < 2 and version not in ignored:
            updated_version = "%s.0" % version
        else:
            updated_version = version
        result[updated_version] = version_counts[version]

    return result


def get_histogram_strings(data, padding=0):
    """Generate a horizontal text histogram.

    Given a dictionary of items, generate a list of column aligned,
    padded strings.

    Args:
        data: Dict with
            key: string heading/name
            val: Float between 0 and 1 for histogram value.
        padding: int number of characters to subtract from max bar
            size. Defaults to zero. (If you intend on indenting, the
            indent level should be specified to make sure large bars
            don't overflow the length of the terminal.
        hist_char: Single character string to use as bar fill. Defaults
            to '#'.
    Returns:
        List of strings ready to print.
    """
    parser = build_argparser()
    args = parser.parse_args()

    if not args.kawaii:
        hist_char = "||"
    elif sys.version_info[0] < 3:
        hist_char = "\xf0\x9f\x8d\x95"
    else:
        hist_char = "\N{slice of pizza}"

    max_key_width = max([len(key) for key in data])
    max_val_width = max([len(str(val)) for val in list(data.values())])
    max_value = max(data.values())
    _, width = get_terminal_size()
    # Find the length we have left for the histogram bars.
    # Magic number 6 is the _():_ parts of the string, and the
    # guaranteed value of one that gets added.
    # all divided by 3 to take account of the extra width of a pizza slice
    histogram_width = (width - padding - max_key_width - max_val_width - 6) / 3
    result = []
    for key, val in data.items():
        preamble = "{:>{max_key}} ({:>{max_val}}): ".format(
            key, val, max_key=max_key_width, max_val=max_val_width
        )
        # percentage = float(val) / osx_clients
        percentage = float(val) / max_value
        histogram_bar = int(percentage * histogram_width + 1) * hist_char
        try:
            result.append((preamble + histogram_bar).decode("utf-8"))
        except AttributeError:
            result.append(preamble + histogram_bar)

    return result


def get_out_of_date_strings(data):
    """Build a list of strings for data with three items.

    Given a dictionary of items, generate a list of column aligned,
    padded strings.

    Args:
        data: Dict with
            key: string heading/name
            val: 2-Tuple of data to fill in string.

    Returns:
        List of strings ready to print.
    """
    result = []
    if data:
        max_key_width = max([len(key) for key in data])
        max_val1_width = max([len(str(val[0])) for val in list(data.values())])
        max_val2_width = max([len(str(val[1])) for val in list(data.values())])
        for key, val in data.items():
            output_string = (
                "{:>{max_key}} JSS Version:{:>{max_val1}} App "
                "Store Version: {:>{max_val2}}".format(
                    key,
                    val[0],
                    val[1],
                    max_key=max_key_width,
                    max_val1=max_val1_width,
                    max_val2=max_val2_width,
                )
            )
            result.append(output_string)
    return result


def add_output_metadata(root):
    """Build the main metadata and tags for an XML report.

    Args:
        root: Element to be used as the root for the report.
    """
    jss_connection = JSSConnection.get()
    report_date = ET.SubElement(root, "ReportDate")
    report_date.text = datetime.datetime.strftime(
        datetime.datetime.now(), "%Y%m%d-%H%M%S"
    )
    report_server = ET.SubElement(root, "Server")
    report_server.text = jss_connection.base_url
    api_user = ET.SubElement(root, "APIUser")
    api_user.text = jss_connection.user
    report_user = ET.SubElement(root, "LocalUser")
    report_user.text = os.getenv("USER")
    spruce_version = ET.SubElement(root, "SpruceVersion")
    spruce_version.text = __version__
    python_jss_version = ET.SubElement(root, "python-jssVersion")
    python_jss_version.text = jss.__version__
    removals = ET.SubElement(root, "Removals")
    removals.insert(0, ET.Comment("Move items to be removed here"))


def add_report_output(root, report):
    """Write the results to an xml file.

    Args:
        results: A Result object.
        ofile: String path to desired output filename.
    """
    report_element = ET.SubElement(root, tagify(report.heading))
    # Results
    for result in report.results:
        if not result.include_in_non_verbose:
            continue
        subreport_element = ET.SubElement(report_element, tagify(result.heading))
        subreport_element.attrib["length"] = str(len(result))
        desc = ET.SubElement(subreport_element, "Description")
        desc.text = result.description
        for id_, name in sorted(result.results, key=lambda x: x[1]):
            item = ET.SubElement(subreport_element, tagify(report.obj_type))
            item.text = name
            item.attrib["id"] = str(id_)

    # Metadata
    for metadata, val in report.metadata.items():
        metadata_element = ET.SubElement(report_element, tagify(metadata))
        # subreport_element.attrib["length"] = str(len(result))
        for submeta, submeta_val in val.items():
            item = ET.SubElement(metadata_element, tagify(submeta))
            for line in submeta_val:
                value = ET.SubElement(item, "Value")
                # value.text = line.encode("ascii", errors="replace").strip()
                value.text = line.strip()


def tagify(text):
    """Make a string appropriate for XML tag names."""
    if "(" in text:
        text = text.split("(")[0]
    return text.title().replace(" ", "")


def indent(elem, level=0, more_sibs=False):
    """Indent an xml element object to prepare for pretty printing.

    Method is internal to discourage indenting the self._root
    Element, thus potentially corrupting it.

    """
    i = "\n"
    pad = "    "
    if level:
        i += (level - 1) * pad
    num_kids = len(elem)
    if num_kids:
        if not elem.text or not elem.text.strip():
            elem.text = i + pad
            if level:
                elem.text += pad
        count = 0
        for kid in elem:
            if kid.tag == "data":
                kid.text = "*DATA*"
            indent(kid, level + 1, count < num_kids - 1)
            count += 1
        if not elem.tail or not elem.tail.strip():
            elem.tail = i
            if more_sibs:
                elem.tail += pad
    else:
        if level and (not elem.tail or not elem.tail.strip()):
            elem.tail = i
            if more_sibs:
                elem.tail += pad


def build_argparser():
    """Create our argument parser."""
    parser = argparse.ArgumentParser(
        description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    # Global Args
    phelp = (
        "Include a list of all objects and used objects in addition to "
        "unused objects in reports."
    )
    parser.add_argument("-v", "--verbose", help=phelp, action="store_true")
    phelp = "Show cute emoji in output and reports."
    parser.add_argument("--kawaii", help=phelp, action="store_true")
    phelp = (
        "For computer and mobile device reports, the number of "
        "days since the last check-in to consider device "
        "out-of-date."
    )
    parser.add_argument("--check_in_period", help=phelp)
    phelp = "Path to preference file."
    parser.add_argument("--prefs", help=phelp)
    # General Reporting Args
    general_group = parser.add_argument_group("General Reporting Arguments")
    phelp = (
        "Output results to OFILE, in plist format (also usable as "
        "input to the --remove option)."
    )
    general_group.add_argument("-o", "--ofile", help=phelp)
    phelp = "Generate all reports. With no other arguments, this is " "the default."
    general_group.add_argument("-a", "--all", help=phelp, action="store_true")

    # Computers
    group = parser.add_argument_group("Computer Reporting Arguments")
    phelp = "Generate computer report."
    group.add_argument("-c", "--computers", help=phelp, action="store_true")
    phelp = "Generate unused computer-groups report (Static and Smart)."
    group.add_argument("-g", "--computer_groups", help=phelp, action="store_true")
    phelp = "Generate unused computer extension attribute report."
    group.add_argument(
        "-e", "--computer_extension_attributes", help=phelp, action="store_true"
    )
    phelp = "Generate unused package report."
    group.add_argument("-p", "--packages", help=phelp, action="store_true")
    phelp = "Generate unused printer report."
    group.add_argument("--printers", help=phelp, action="store_true")
    phelp = "Generate unused script report."
    group.add_argument("-s", "--scripts", help=phelp, action="store_true")
    phelp = "Generate unused policy report."
    group.add_argument("-t", "--policies", help=phelp, action="store_true")
    phelp = "Generate unused computer configuration profile report."
    group.add_argument(
        "-u", "--computer_configuration_profiles", help=phelp, action="store_true"
    )

    # Mobile Devices
    md_group = parser.add_argument_group("Mobile Device Reporting Arguments")
    phelp = "Generate mobile device report."
    md_group.add_argument("-d", "--mobile_devices", help=phelp, action="store_true")
    phelp = "Generate unused mobile-device-groups report (Static and Smart)."
    md_group.add_argument(
        "-r", "--mobile_device_groups", help=phelp, action="store_true"
    )
    phelp = "Generate unused mobile-device-profiles report."
    md_group.add_argument(
        "-m", "--mobile_device_configuration_profiles", help=phelp, action="store_true"
    )
    phelp = "Generate out-of-date and unused mobile apps report."
    md_group.add_argument("-b", "--apps", help=phelp, action="store_true")

    # Removal Args
    removal_group = parser.add_argument_group("Removal Arguments")
    phelp = (
        "Remove all objects specified in supplied XML file REMOVE from "
        "the subelement 'Removals'. If this option is used, all "
        "reporting is skipped. The input file is most easily created by "
        "editing the results of a report done with the -o/--ofile "
        "option."
    )
    removal_group.add_argument("--remove", help=phelp)

    return parser


def run_reports(args):
    """Runs reports specified as commandline args to spruce.

    Runs each report specified as a commandline arguement, and outputs
    by default to stdout, or to a plist file specified with -o/--ofile.

    Shows report construction progress, and prints report after all
    data is crunched.

    Args:
        args: parsed argparser namespace object for spruce.
    """
    # Define the types of reports we can accept.
    # TODO: Roll this data structure into the Reports class.
    reports = {}
    reports["computers"] = {
        "heading": "Computer Report",
        "func": build_computers_report,
        "report": None,
    }
    reports["mobile_devices"] = {
        "heading": "Mobile Device Report",
        "func": build_mobile_devices_report,
        "report": None,
    }
    reports["computer_groups"] = {
        "heading": "Computer Groups Report",
        "func": build_computer_groups_report,
        "report": None,
    }
    reports["computer_extension_attributes"] = {
        "heading": "Computer Extension Attributes Report",
        "func": build_computer_ea_report,
        "report": None,
    }
    reports["packages"] = {
        "heading": "Package Report",
        "func": build_packages_report,
        "report": None,
    }
    reports["printers"] = {
        "heading": "Printers Report",
        "func": build_printers_report,
        "report": None,
    }
    reports["scripts"] = {
        "heading": "Scripts Report",
        "func": build_scripts_report,
        "report": None,
    }
    reports["policies"] = {
        "heading": "Policy Report",
        "func": build_policies_report,
        "report": None,
    }
    reports["computer_configuration_profiles"] = {
        "heading": "Computer Configuration Profile Report",
        "func": build_config_profiles_report,
        "report": None,
    }

    reports["mobile_device_configuration_profiles"] = {
        "heading": "Mobile Device Configuration Profile Report",
        "func": build_md_config_profiles_report,
        "report": None,
    }
    reports["mobile_device_groups"] = {
        "heading": "Mobile Device Group Report",
        "func": build_device_groups_report,
        "report": None,
    }
    reports["apps"] = {
        "heading": "Mobile Apps",
        "func": build_apps_report,
        "report": None,
    }

    args_dict = vars(args)
    # Build a list of report key names, requested by user, which are
    # tightly coupled, despite the smell, to arg names.
    requested_reports = [report for report in reports if args_dict[report]]

    # If either the --all option has been provided, OR none of the
    # other reports options have been specified, assume user wants all
    # reports (filtering out --remove is handled elsewhere).
    if args.all or not requested_reports:
        # Replace report list with all known report names.
        # TODO: THis is dumb... Just puts the name in so I can later
        # pull it again with dict.
        requested_reports = [report for report in reports]

    # Build the reports
    if not args.kawaii:
        SPRUCE = "*"
    elif sys.version_info[0] < 3:
        SPRUCE = "\xF0\x9F\x8C\xB2"
    else:
        SPRUCE = "\N{evergreen tree}"

    results = []
    for report_name in requested_reports:
        report_dict = reports[report_name]
        print("%s  Building: %s... %s" % (SPRUCE, report_dict["heading"], SPRUCE))
        func = reports[report_name]["func"]
        results.append(func(**args_dict))

    # Output the reports
    output_xml = ET.Element("SpruceReport")
    add_output_metadata(output_xml)

    for report in results:
        # Print output to stdout.
        if not args.ofile:
            print("")
            print_output(report, args.verbose)
        else:
            add_report_output(output_xml, report)

    if args.ofile:
        indent(output_xml)
        tree = ET.ElementTree(output_xml)
        # print(ET.tostring(output_xml, encoding="UTF-8"))
        try:
            tree.write(
                os.path.expanduser(args.ofile), encoding="UTF-8", xml_declaration=True
            )
            print("%s  Wrote output to %s" % (SPRUCE, args.ofile))
        except IOError:
            print("Error writing output to %s" % args.ofile)
            sys.exit(1)


def remove(removal_tree):
    """Remove desired objects from the JSS and distribution points.

    Given an XML file with subelement "Removals", remove each child
    object from the JSS. The child Element must have a tag name
    corresponding to the JSSObject class to delete (e.g. "Computer", or
    "Policy"), with an attribute of "id" containing the object's ID.

    The name is not used, as this is not always a guarantor of
    identity.

    Packages and Scripts (when applicable) will be removed from all
    distribution points and servers that support delete methods.

    Args:
        ElementTree instance with Element "Removals", as detailed
        above.
    """
    if not check_with_user():
        sys.exit(0)
    jss_connection = JSSConnection.get()
    # Tag map is a dictionary mapping our Element tags to JSS factory
    # methods.
    tag_map = {
        "Computer": jss_connection.Computer,
        "ComputerGroup": jss_connection.ComputerGroup,
        "Package": jss_connection.Package,
        "Printer": jss_connection.Printer,
        "Script": jss_connection.Script,
        "Policy": jss_connection.Policy,
        "ComputerConfigurationProfile": jss_connection.OSXConfigurationProfile,
        "MobileDevice": jss_connection.MobileDevice,
        "MobileDeviceGroup": jss_connection.MobileDeviceGroup,
        "MobileDeviceConfigurationProfile": jss_connection.MobileDeviceConfigurationProfile,
        "MobileApplication": jss_connection.MobileDeviceApplication,
    }

    root = removal_tree.getroot()
    removals = root.find("Removals")

    # JDS and CDP distribution points do not require files to be deleted
    # in addition to the objects being deleted (i.e. they handle it).
    # AFP/SMB DP's on the other hand do, so first test to see if any
    # File Share Distribution Points exist.
    if (
        hasattr(jss_connection.distribution_points, "dp_info")
        and jss_connection.distribution_points.dp_info
    ):

        # See if we are trying to delete any packages or scripts.
        # JSS's which have been migrated store their scripts in the
        # database, and thus do not need to have them deleted.
        needs_file_removal = ["Package"]
        # Assume that JSS has been migrated by now
        # if not jss_connection.jss_migrated:
        #     needs_file_removal.append("Script")

        file_type_removals = any(
            [removal.tag for removal in removals if removal.tag in needs_file_removal]
        )

        if file_type_removals:
            # Mount the shares now in preparation.
            jss_connection.distribution_points.mount()
    else:
        file_type_removals = False

    # Remove duplicate items.
    removals_set = ET.Element("Removals")
    for item in removals:
        if not item.attrib["id"] in [
            obj.get("id") for obj in removals_set.findall(item.tag)
        ]:
            removals_set.append(item)

    for item in removals_set:
        # Only try to delete members of the tag_map types.
        search_func = tag_map.get(item.tag)
        if not search_func:
            continue
        else:
            try:
                # Get the item from the JSS.
                obj = search_func(item.attrib["id"])
            except jss.GetError as error:
                # Object probably no longer exists.
                if hasattr(error, "status_code"):
                    print(
                        "%s object %s with ID %s is not available or does "
                        "not exist.\nStatus Code: %s\nError: %s"
                        % (
                            item.tag,
                            item.text,
                            item.attrib["id"],
                            error.status_code,
                            error.message,
                        )
                    )
                else:
                    print(
                        "%s object %s with ID %s is not available or does "
                        "not exist.\nError: %s"
                        % (item.tag, item.text, item.attrib["id"], error.message)
                    )
                continue

        # Try to delete the item.
        try:
            obj.delete()
            print("%s object %s: %s deleted." % (item.tag, obj.id, obj.name))
        except jss.DeleteError as error:
            print(
                "%s object %s with ID %s failed to delete.\n"
                "Status Code:%s Error: %s"
                % (
                    item.tag,
                    item.text,
                    item.attrib["id"],
                    error.status_code,
                    error.message,
                )
            )
            continue

        # If the item is a Package, or a Script on a non-migrated
        # JSS, delete the file from the distribution points.
        if file_type_removals and item.tag in needs_file_removal:
            # The name property of a script or package is called
            # "Display Name" in the gui, and it can differ from the
            # actual filename, so get the filename rather than use name.
            # However, if there is a DistributionServer type repo
            # configured, it tries to delete the db object, which needs
            # "name". Since this has already been done, it's going to
            # throw a GetError regardless. In the event that a user has
            # a Display Name that matches another package's filename, bad
            # things could happen!
            # Get filename, but fall back to name.
            filename = obj.findtext("filename", item.text)
            try:
                jss_connection.distribution_points.delete(filename)
                print("%s file %s deleted." % (item.tag, obj.name))
            except OSError as error:
                print(
                    "Unable to delete %s: %s with error: %s"
                    % (item.tag, filename, error)
                )
            except jss.GetError:
                # User has a DistributionServer of some kind and
                # A.) The db object has already been deleted above
                # and possibly also B.) The "Display Name" and
                # "Filename" do not match, and the GET is failing due
                # to no db objects named "Filename" existing.
                pass


def check_with_user():
    jss_connection = JSSConnection.get()
    response = input(
        "Are you sure you want to continue deleting objects "
        "from %s? (Y or N): " % jss_connection.base_url
    )
    if response.strip().upper() in ["Y", "YES"]:
        result = True
    else:
        result = False
    return result


def connect(args):
    """make the connection to the JSS"""
    # Allow override to prefs file
    if args.prefs:
        if os.path.exists(os.path.expanduser(args.prefs)):
            user_supplied_prefs = Plist(args.prefs)
            connection = map_jssimporter_prefs(user_supplied_prefs)
            print("Preferences used: %s" % args.prefs)
        else:
            sys.exit("Prefs file {} not found!".format(args.prefs))
    # Otherwise, get AutoPkg configuration settings for JSSImporter,
    # and barring that, get python-jss settings.
    elif os.path.exists(os.path.expanduser(AUTOPKG_PREFERENCES)):
        autopkg_env = Plist(AUTOPKG_PREFERENCES)
        connection = map_jssimporter_prefs(autopkg_env)
        print("Preferences used: %s" % AUTOPKG_PREFERENCES)
    else:
        try:
            connection = jss.JSSPrefs()
            print("Preferences used: %s" % PYTHON_JSS_PREFERENCES)
        except jss.exceptions.JSSPrefsMissingFileError:
            sys.exit("No python-jss or AutoPKG/JSSImporter configuration " "file!")
    JSSConnection.setup(connection)


def main():
    """Commandline processing."""
    # Ensure we have the right version of python-jss.
    python_jss_version = StrictVersion(PYTHON_JSS_VERSION)
    if python_jss_version < REQUIRED_PYTHON_JSS_VERSION:
        sys.exit(
            "Requires python-jss version: %s. Installed: %s\n"
            "Please update" % (REQUIRED_PYTHON_JSS_VERSION, python_jss_version)
        )

    # Handle command line arguments.
    parser = build_argparser()
    args = parser.parse_args()

    #  make the connection to the JSS
    connect(args)

    # Determine actions based on supplied arguments.

    # The remove argument is mutually exclusive with the others.
    if args.remove:
        removal_tree = ET.parse(os.path.expanduser(args.remove))
        remove(removal_tree)
    else:
        run_reports(args)


if __name__ == "__main__":
    main()