platform_json.py

#!/usr/bin/env python3
# Copyright 2020 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

"""Print one fully-calculated fw-testing-config to stdout.

This script takes one platform name (and optionally a model name) as inputs,
calculates the full config for that platform, and prints the results as
plaintext JSON.

The full config is calculated based on the fw-testing-configs inheritance
model.  Each platform config has an optional "parent" attribute. For each
config field, if the platform does not explicitly set a value for that field,
then the value is instead inherited from the parent config. This inheritance
can be recursive: the parent may have a parent, and so on. At the top of the
inheritance tree (when parent is None), any remaining fields inherit their
values from DEFAULTS. Also, if the platform has a "models" attribute matching
the passed-in model name, then its field-value pairs override everything else.
"""

import argparse
import collections
import json
import os
import re
import sys


# Regexes matching fields which describe config metadata: that is, they do not
# contain actual config information.  When calculating the final config, fields
# matching any of these regexes will be ignored.
META_FIELD_REGEXES = (
    re.compile(r'^models$'),
    re.compile(r'\.DOC$')
)


class PlatformNotFoundError(AttributeError):
    """Error class for when the requested platform name is not found."""
    pass


class FieldNotFoundError(AttributeError):
    """Error class for when the requested field name is not found."""


def parse_args(argv):
    """Determine input dir and output file from command-line args.

    Args:
        argv: List of command-line args, excluding the invoked script.
              Typically, this should be set to sys.argv[1:].

    Returns:
        An argparse.Namespace with the following attributes:
            condense_output: A bool determining whether to remove pretty
                whitespace from the script's final output.
            consolidated: The filepath to CONSOLIDATED.json
            field: If specified, then only this field's value will be printed.
            platform: The name of the board whose config should be calculated
            model: The name of the model for the board

    Raises:
        ValueError: If the passed-in platform name ends in '.json'
    """
    parser = argparse.ArgumentParser()
    parser.add_argument('platform',
                        help='The platform name to calculate a config for. '
                             'Should not include ".json" suffix.')
    parser.add_argument('-m', '--model', default=None,
                        help='The model name of the board. If not specified, '
                             'then no model overrides will be used.')
    parser.add_argument('-f', '--field', default=None,
                        help="If specified, only print this field's value.")
    parser.add_argument('-c', '--consolidated', default='CONSOLIDATED.json',
                        help='The filepath to CONSOLIDATED.json')
    parser.add_argument('--condense-output', action='store_true',
                        help='Print the output without pretty whitespace.')
    args = parser.parse_args(argv)
    return args


def calculate_field_value(consolidated_json, field, platform, model=None):
    """Calculate a platform's ultimate value for a single field.

    Args:
        consolidated_json: The key-value contents of CONSOLIDATED.json.
        field: The name of the JSON field to calculate.
        platform: The name of the platform to calculate for.  If the
            platform does not define the field, then recursively check its
            parent's config (or DEFAULTS).
        model: The name of the model to check overrides for.

    Raises:
        PlatformNotFoundError: If platform is not in consolidated_json.
    """
    if platform not in consolidated_json:
        raise PlatformNotFoundError(platform)

    # Model overrides are most important.
    # Not all models have config overrides, so it's OK for the model name not
    # to be present in models_json.
    models_json = consolidated_json[platform].get('models', {})
    if field in models_json.get(model, {}):
        return models_json[model][field]

    # Then check if the platform explicitly defines the value.
    if field in consolidated_json[platform]:
        return consolidated_json[platform][field]

    # Finally, inherit from the parent (or DEFAULTS).
    # The DEFAULTS config contains every field name, so this will terminate the
    # recursion.
    parent = consolidated_json[platform].get('parent', 'DEFAULTS')
    return calculate_field_value(consolidated_json, field, parent, model)


def load_consolidated_json(consolidated_fp):
    """Return the contents of consolidated_fp as a Python object."""
    if not os.path.isfile(consolidated_fp):
        raise FileNotFoundError(consolidated_fp)
    with open(consolidated_fp) as consolidated_file:
        return json.load(consolidated_file)


def calculate_config(platform, model, consolidated_json):
    """Calculate a platform's ultimate config values for all fields.

    Args:
        platform: The name of the platform to calculate values for.
        model: The name of the model to check for overrides.
    """
    final_json = collections.OrderedDict()
    for field in consolidated_json['DEFAULTS']:
        if any(regex.search(field) for regex in META_FIELD_REGEXES):
            continue
        value = calculate_field_value(consolidated_json, field, platform, model)
        final_json[field] = value
    return final_json


def main(argv):
    """
    Parse command-line args and print a JSON config to stdout.

    Args:
        argv: List of command-line args, excluding the invoked script.
              Typically, this should be set to sys.argv[1:].
    """
    args = parse_args(argv)
    consolidated_json = load_consolidated_json(args.consolidated)
    config_json = calculate_config(args.platform, args.model,
                                   consolidated_json)
    if args.field is None:
        # indent=None means no newlines/indents in stringified JSON.
        # indent=4 means 4-space indents.
        indent = None if args.condense_output else 4
        output = json.dumps(config_json, indent=indent)
    elif args.field not in config_json:
        raise FieldNotFoundError(args.field)
    else:
        output = config_json[args.field]
    print(output, end='' if args.condense_output else '\n')


if __name__ == '__main__':
    main(sys.argv[1:])