23886302068

Committed 02 Apr 2026 05:56AM UTC coverage: 82.885% (-0.08%) from 82.968%

Build # 23886302068

Build Type

push

github

Committed by

web-flow

Commit Message

Add --project-info (-i) CLI option for JSON project configuration dump [release] (#946)

## Summary

- Adds `pyb -i` / `pyb --project-info` that outputs the full project
configuration as pretty-printed JSON to stdout without running a build
- Runs plugin initializers to populate all properties but does not
execute any tasks or create build/test venvs
- Log messages go to stderr (via new `StdErrLogger` /
`ColoredStdErrLogger` classes) so stdout is always clean, parseable JSON
- Mutually exclusive with `-t`, `-T`, `--start-project`,
`--update-project`

### JSON output includes:
- Project metadata (name, version, authors, license, URLs, etc.)
- All build properties (built-in + plugin-defined, after initializers
run)
- Loaded plugins
- Runtime, build, plugin, and extras dependencies
- Available tasks with descriptions and dependency graphs
- Manifest files, package data, files to install

### Usage:
```bash
pyb -i 2>/dev/null | jq .project.name
pyb -i -E ci -P verbose=true 2>/dev/null | jq .properties
```

## Test plan

- [x] 678 unit tests pass (including new tests for option parsing,
stderr logging, serialization, JSON output)
- [x] 3 cram tests pass (help output updated, new project-info cram
test, existing no-build test)
- [x] `pyb -i | python -m json.tool` produces valid JSON
- [x] `pyb -i -X 2>log.txt` sends debug logs to stderr, JSON to stdout
- [x] `pyb -i -t` rejected as mutually exclusive

Coverage Stats

1426 of 1888 branches covered (75.53%)

Branch coverage included in aggregate %.

54 of 72 new or added lines in 1 file covered. (75.0%)

1 existing line in 1 file now uncovered.

5606 of 6596 relevant lines covered (84.99%)

33.05 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

76.74

/src/main/python/pybuilder/cli.py

#   -*- coding: utf-8 -*-
#
#   This file is part of PyBuilder
#
#   Copyright 2011-2020 PyBuilder Team
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

"""
    The PyBuilder cli module.
    Contains the PyBuilder command-line entrypoint.
"""

import datetime
import json
import optparse
import re
import sys
import traceback
from os.path import sep, normcase as nc

from pybuilder import __version__
from pybuilder import extern
from pybuilder.core import Logger
from pybuilder.errors import PyBuilderException
from pybuilder.execution import ExecutionManager
from pybuilder.python_utils import IS_WIN
from pybuilder.reactor import Reactor
from pybuilder.scaffolding import start_project, update_project
from pybuilder.terminal import (BOLD, BROWN, RED, GREEN, bold, styled_text,
                                fg, italic, print_text, print_text_line,
                                print_error, print_error_line, draw_line)
from pybuilder.utils import format_timestamp, get_dist_version_string

PROPERTY_OVERRIDE_PATTERN = re.compile(r'^[a-zA-Z0-9_]+=.*')
DEFAULT_LOG_TIME_FORMAT = '[%Y-%m-%d %H:%M:%S]'
_extern = extern


class CommandLineUsageException(PyBuilderException):
    def __init__(self, usage, message):
        super(CommandLineUsageException, self).__init__(message)
        self.usage = usage


class StdOutLogger(Logger):
    def _level_to_string(self, level):
        if Logger.DEBUG == level:
            return "[DEBUG]"
        if Logger.INFO == level:
            return "[INFO] "
        if Logger.WARN == level:
            return "[WARN] "
        return "[ERROR]"

    def _do_log(self, level, message, *arguments):
        formatted_message = self._format_message(message, *arguments)
        log_level = self._level_to_string(level)
        if self.log_time_format is not None:
            timestamp = datetime.datetime.now().strftime(self.log_time_format) + ' '
        else:
            timestamp = ''
        print_text_line("{0}{1} {2}".format(timestamp, log_level, formatted_message))


class ColoredStdOutLogger(StdOutLogger):
    def _level_to_string(self, level):
        if Logger.DEBUG == level:
            return italic("[DEBUG]")
        if Logger.INFO == level:
            return bold("[INFO] ")
        if Logger.WARN == level:
            return styled_text("[WARN] ", BOLD, fg(BROWN))
        return styled_text("[ERROR]", BOLD, fg(RED))


class StdErrLogger(StdOutLogger):
    def _do_log(self, level, message, *arguments):
        formatted_message = self._format_message(message, *arguments)
        log_level = self._level_to_string(level)
        if self.log_time_format is not None:
            timestamp = datetime.datetime.now().strftime(self.log_time_format) + ' '
        else:
            timestamp = ''
        print_error_line("{0}{1} {2}".format(timestamp, log_level, formatted_message))


class ColoredStdErrLogger(ColoredStdOutLogger, StdErrLogger):
    pass


def _log_time_format_argument__check_if_timestamp_passed(option, opt_str, value, parser):
    assert value is None
    value = DEFAULT_LOG_TIME_FORMAT

    for arg in parser.rargs:
        # stop on --foo like options
        if arg[:2] == "--" and len(arg) > 2:
            break
        # stop on -foo like options
        elif arg[:1] == "-" and len(arg) > 1:
            break
        else:
            value = arg.rstrip()
            del parser.rargs[0]
            break  # Only consume 1 argument

    setattr(parser.values, option.dest, value)


def parse_options(args):
    parser = optparse.OptionParser(usage="%prog [options] [+|^]task1 [[[+|^]task2] ...]",
                                   version="%prog " + __version__)

    def error(msg):
        raise CommandLineUsageException(
            parser.get_usage() + parser.format_option_help(), msg)

    parser.error = error

    list_tasks_option = parser.add_option("-t", "--list-tasks",
                                          action="store_true",
                                          dest="list_tasks",
                                          default=False,
                                          help="List all tasks that can be run in the current build configuration")

    list_plan_tasks_option = parser.add_option("-T", "--list-plan-tasks",
                                               action="store_true",
                                               dest="list_plan_tasks",
                                               default=False,
                                               help="List tasks that will be run with current execution plan")

    project_info_option = parser.add_option("-i", "--project-info",
                                            action="store_true",
                                            dest="project_info",
                                            default=False,
                                            help="Output project configuration as JSON")

    start_project_option = parser.add_option("--start-project",
                                             action="store_true",
                                             dest="start_project",
                                             default=False,
                                             help="Initialize build descriptors and Python project structure")

    update_project_option = parser.add_option("--update-project",
                                              action="store_true",
                                              dest="update_project",
                                              default=False,
                                              help="Update build descriptors and Python project structure")

    project_group = optparse.OptionGroup(
        parser, "Project Options", "Customizes the project to build.")

    project_group.add_option("-D", "--project-directory",
                             dest="project_directory",
                             help="Root directory to execute in",
                             metavar="<project directory>",
                             default=".")

    project_group.add_option("-O", "--offline",
                             dest="offline",
                             help="Attempt to execute the build without network connectivity (may cause build failure)",
                             default=False,
                             action="store_true")

    project_group.add_option("-E", "--environment",
                             dest="environments",
                             help="Activate the given environment for this build. Can be used multiple times",
                             metavar="<environment>",
                             action="append",
                             default=[])

    project_group.add_option("-P",
                             action="append",
                             dest="property_overrides",
                             default=[],
                             metavar="<property>=<value>",
                             help="Set/ override a property value")

    project_group.add_option("-x", "--exclude",
                             action="append",
                             dest="exclude_optional_tasks",
                             default=[],
                             metavar="<task>",
                             help="Exclude optional task dependencies")

    project_group.add_option("-o", "--exclude-all-optional",
                             action="store_true",
                             dest="exclude_all_optional",
                             default=False,
                             help="Exclude all optional task dependencies")

    project_group.add_option("--force-exclude",
                             action="append",
                             dest="exclude_tasks",
                             default=[],
                             metavar="<task>",
                             help="Exclude any task dependencies "
                                  "(dangerous, may break the build in unexpected ways)")

    project_group.add_option("--reset-plugins",
                             action="store_true",
                             dest="reset_plugins",
                             default=False,
                             help="Reset plugins directory prior to running the build")

    project_group.add_option("--no-venvs",
                             action="store_true",
                             dest="no_venvs",
                             default=False,
                             help="Disables the use of Python Virtual Environments")

    parser.add_option_group(project_group)

    output_group = optparse.OptionGroup(
        parser, "Output Options", "Modifies the messages printed during a build.")

    output_group.add_option("-X", "--debug",
                            action="store_true",
                            dest="debug",
                            default=False,
                            help="Print debug messages")

    output_group.add_option("-v", "--verbose",
                            action="store_true",
                            dest="verbose",
                            default=False,
                            help="Enable verbose output")

    output_group.add_option("-q", "--quiet",
                            action="store_true",
                            dest="quiet",
                            default=False,
                            help="Quiet mode; print only warnings and errors")

    output_group.add_option("-Q", "--very-quiet",
                            action="store_true",
                            dest="very_quiet",
                            default=False,
                            help="Very quiet mode; print only errors")

    output_group.add_option("-c", "--color",
                            action="store_true",
                            dest="force_color",
                            default=False,
                            help="Force colored output")

    output_group.add_option("-C", "--no-color",
                            action="store_true",
                            dest="no_color",
                            default=False,
                            help="Disable colored output")

    output_group.add_option("-f", "--log-time-format",
                            action='callback',
                            callback=_log_time_format_argument__check_if_timestamp_passed,
                            dest="log_time_format",
                            help="Define the format of timestamp in the log (default: no timestamps)",
                            default=None)

    parser.add_option_group(output_group)

    options, arguments = parser.parse_args(args=list(args))

    if options.list_tasks and options.list_plan_tasks:
        parser.error("%s and %s are mutually exclusive" % (list_tasks_option, list_plan_tasks_option))
    if options.project_info and (options.list_tasks or options.list_plan_tasks):
        parser.error("%s is mutually exclusive with %s and %s" % (
            project_info_option, list_tasks_option, list_plan_tasks_option))
    if options.project_info and (options.start_project or options.update_project):
        parser.error("%s is mutually exclusive with %s and %s" % (
            project_info_option, start_project_option, update_project_option))
    if options.start_project and options.update_project:
        parser.error("%s and %s are mutually exclusive" % (start_project_option, update_project_option))

    property_overrides = {}
    for pair in options.property_overrides:
        if not PROPERTY_OVERRIDE_PATTERN.match(pair):
            parser.error("%s is not a property definition." % pair)
        key, val = pair.split("=", 1)
        property_overrides[key] = val

    options.property_overrides = property_overrides

    if options.very_quiet:
        options.quiet = True

    return options, arguments


def init_reactor(logger):
    execution_manager = ExecutionManager(logger)
    reactor = Reactor(logger, execution_manager)
    return reactor


def should_colorize(options):
    return options.force_color or (sys.stdout.isatty() and not options.no_color)


def init_logger(options, use_stderr=False):
    threshold = Logger.INFO
    if options.debug:
        threshold = Logger.DEBUG
    elif options.quiet:
        threshold = Logger.WARN

    if not should_colorize(options):
        if use_stderr:
            logger = StdErrLogger(threshold, options.log_time_format)
        else:
            logger = StdOutLogger(threshold, options.log_time_format)
    else:
        if IS_WIN:
            import colorama
            colorama.init()
        if use_stderr:
            logger = ColoredStdErrLogger(threshold, options.log_time_format)
        else:
            logger = ColoredStdOutLogger(threshold, options.log_time_format)

    return logger


def print_build_summary(options, summary):
    print_text_line("Build Summary")
    print_text_line("%20s: %s" % ("Project", summary.project.name))
    print_text_line("%20s: %s%s" % ("Version", summary.project.version, get_dist_version_string(summary.project)))
    print_text_line("%20s: %s" % ("Base directory", summary.project.basedir))
    print_text_line("%20s: %s" %
                    ("Environments", ", ".join(options.environments)))

    task_summary = ""
    for task in summary.task_summaries:
        task_summary += " %s [%d ms]" % (task.task, task.execution_time)

    print_text_line("%20s:%s" % ("Tasks", task_summary))


def print_styled_text(text, options, *style_attributes):
    if should_colorize(options):
        add_trailing_nl = False
        if text[-1] == '\n':
            text = text[:-1]
            add_trailing_nl = True
        text = styled_text(text, *style_attributes)
        if add_trailing_nl:
            text += '\n'
    print_text(text)


def print_styled_text_line(text, options, *style_attributes):
    print_styled_text(text + "\n", options, *style_attributes)


def print_build_status(failure_message, options, successful):
    draw_line()
    if successful:
        print_styled_text_line("BUILD SUCCESSFUL", options, BOLD, fg(GREEN))
    else:
        print_styled_text_line(
            "BUILD FAILED - {0}".format(failure_message), options, BOLD, fg(RED))
    draw_line()


def print_elapsed_time_summary(start, end):
    time_needed = end - start
    millis = ((time_needed.days * 24 * 60 * 60) + time_needed.seconds) * 1000 + time_needed.microseconds / 1000
    print_text_line("Build finished at %s" % format_timestamp(end))
    print_text_line("Build took %d seconds (%d ms)" %
                    (time_needed.seconds, millis))


def print_summary(successful, summary, start, end, options, failure_message):
    print_build_status(failure_message, options, successful)

    if successful and summary:
        print_build_summary(options, summary)

    print_elapsed_time_summary(start, end)


def length_of_longest_string(list_of_strings):
    if len(list_of_strings) == 0:
        return 0

    result = 0
    for string in list_of_strings:
        length_of_string = len(string)
        if length_of_string > result:
            result = length_of_string

    return result


def task_description(task):
    return " ".join(task.description) or "<no description available>"


def print_task_list(tasks, quiet=False):
    if quiet:
        print_text_line("\n".join([task.name + ":" + task_description(task)
                                   for task in tasks]))
        return

    column_length = length_of_longest_string(
        list(map(lambda task: task.name, tasks)))
    column_length += 4

    for task in tasks:
        task_name = task.name.rjust(column_length)
        print_text_line("{0} - {1}".format(task_name, task_description(task)))

        if task.dependencies:
            whitespace = (column_length + 3) * " "
            depends_on_message = "depends on tasks: %s" % " ".join(
                [str(dependency) for dependency in task.dependencies])
            print_text_line(whitespace + depends_on_message)


def print_list_of_tasks(reactor, quiet=False):
    tasks = reactor.get_tasks()
    sorted_tasks = sorted(tasks)
    if not quiet:
        print_text_line('Tasks found for project "%s":' % reactor.project.name)
    print_task_list(sorted_tasks, quiet)


def print_plan_list_of_tasks(options, arguments, reactor, quiet=False):
    execution_plan = reactor.create_execution_plan(arguments, options.environments)
    if not quiet:
        print_text_line('Tasks that will be executed for project "%s":' % reactor.project.name)
    print_task_list(execution_plan, quiet)


def _serialize_dependency(dep):
    from pybuilder.core import RequirementsFile
    if isinstance(dep, RequirementsFile):
        return {
            "name": dep.name,
            "version": None,
            "declaration_only": dep.declaration_only,
            "type": "requirements_file"
        }
    return {
        "name": dep.name,
        "version": dep.version,
        "url": dep.url,
        "extras": dep.extras,
        "markers": dep.markers,
        "declaration_only": dep.declaration_only,
        "type": "dependency"
    }


def _safe_property_value(value):
    if value is None or isinstance(value, (bool, int, float, str)):
        return value
    if isinstance(value, (list, tuple)):
        return [_safe_property_value(v) for v in value]
    if isinstance(value, dict):
        return {str(k): _safe_property_value(v) for k, v in value.items()}
    if isinstance(value, set):
        return sorted([_safe_property_value(v) for v in value], key=str)
    return repr(value)


def _build_project_info(reactor):
    project = reactor.project

    def serialize_person(p):
        if isinstance(p, (dict, str)):
            return p
        result = {"name": p.name}
        if p.email:
            result["email"] = p.email
        if p.roles:
            result["roles"] = list(p.roles)
        return result

    def serialize_person_list(persons):
        return [serialize_person(p) for p in persons]

    tasks_info = []
    for task in sorted(reactor.get_tasks()):
        task_deps = []
        for dep in task.dependencies:
            task_deps.append({
                "name": str(dep.name),
                "optional": dep.optional
            })
        tasks_info.append({
            "name": task.name,
            "description": task_description(task),
            "dependencies": task_deps
        })

    return {
        "pybuilder_version": __version__,
        "project": {
            "name": project.name,
            "version": project.version,
            "dist_version": project.dist_version,
            "basedir": project.basedir,
            "summary": project.summary,
            "description": project.description,
            "author": project.author,
            "authors": serialize_person_list(project.authors),
            "maintainer": project.maintainer,
            "maintainers": serialize_person_list(project.maintainers),
            "license": project.license,
            "url": project.url,
            "urls": project.urls,
            "requires_python": project.requires_python,
            "default_task": project.default_task,
            "obsoletes": project.obsoletes,
            "explicit_namespaces": project.explicit_namespaces,
        },
        "environments": list(project.environments),
        "properties": {str(k): _safe_property_value(v) for k, v in sorted(project.properties.items())},
        "plugins": list(reactor.get_plugins()),
        "dependencies": {
            "runtime": [_serialize_dependency(d) for d in project.dependencies],
            "build": [_serialize_dependency(d) for d in project.build_dependencies],
            "plugin": [_serialize_dependency(d) for d in project.plugin_dependencies],
            "extras": {name: [_serialize_dependency(d) for d in deps]
                       for name, deps in project.extras_dependencies.items()}
        },
        "tasks": tasks_info,
        "manifest_included_files": project.manifest_included_files,
        "package_data": dict(project.package_data),
        "files_to_install": [[dest, files] for dest, files in project.files_to_install],
    }


def print_project_info(reactor, environments):
    reactor.project._environments = tuple(environments)
    reactor.execution_manager.execute_initializers(
        environments, logger=reactor.logger, project=reactor.project, reactor=reactor)

    info = _build_project_info(reactor)
    print_text_line(json.dumps(info, indent=2, default=str))


def get_failure_message():
    exc_type, exc_obj, exc_tb = sys.exc_info()

    filename = None
    lineno = None

    while exc_tb.tb_next:
        exc_tb = exc_tb.tb_next

    frame = exc_tb.tb_frame
    if hasattr(frame, "f_code"):
        code = frame.f_code
        filename = code.co_filename
        lineno = exc_tb.tb_lineno

        filename = nc(filename)
        for path in sys.path:
            path = nc(path)
            if filename.startswith(path) and len(filename) > len(path) and filename[len(path)] == sep:
                filename = filename[len(path) + 1:]
                break

    return "%s%s%s" % ("%s: " % exc_type.__name__ if not isinstance(exc_obj, PyBuilderException) else "",
                       exc_obj,
                       " (%s:%d)" % (filename, lineno) if filename else "")


def main(*args):
    if not args:
        args = sys.argv[1:]
    try:
        options, arguments = parse_options(args)
    except CommandLineUsageException as e:
        print_error_line("Usage error: %s\n" % e)
        print_error(e.usage)
        return 1

    start = datetime.datetime.now()

    logger = init_logger(options, use_stderr=options.project_info)
    reactor = init_reactor(logger)

    if options.start_project:
        return start_project()

    if options.update_project:
        return update_project()

    if options.project_info:
        try:
            reactor.prepare_build(property_overrides=options.property_overrides,
                                  project_directory=options.project_directory,
                                  exclude_optional_tasks=options.exclude_optional_tasks,
                                  exclude_tasks=options.exclude_tasks,
                                  exclude_all_optional=options.exclude_all_optional,
                                  offline=options.offline,
                                  no_venvs=options.no_venvs
                                  )
            print_project_info(reactor, options.environments)
            return 0
        except PyBuilderException:
            print_build_status(get_failure_message(), options, successful=False)
            return 1

    if options.list_tasks or options.list_plan_tasks:
        try:
            reactor.prepare_build(property_overrides=options.property_overrides,
                                  project_directory=options.project_directory,
                                  exclude_optional_tasks=options.exclude_optional_tasks,
                                  exclude_tasks=options.exclude_tasks,
                                  exclude_all_optional=options.exclude_all_optional,
                                  offline=options.offline,
                                  no_venvs=options.no_venvs
                                  )
            if options.list_tasks:
                print_list_of_tasks(reactor, quiet=options.very_quiet)

            if options.list_plan_tasks:
                print_plan_list_of_tasks(options, arguments, reactor, quiet=options.very_quiet)
            return 0
        except PyBuilderException:
            print_build_status(get_failure_message(), options, successful=False)
            return 1

    if not options.very_quiet:
        print_styled_text_line(
            "PyBuilder version {0}".format(__version__), options, BOLD)
        print_text_line("Build started at %s" % format_timestamp(start))
        draw_line()

    successful = True
    failure_message = None
    summary = None

    try:
        try:
            reactor.prepare_build(property_overrides=options.property_overrides,
                                  project_directory=options.project_directory,
                                  exclude_optional_tasks=options.exclude_optional_tasks,
                                  exclude_tasks=options.exclude_tasks,
                                  exclude_all_optional=options.exclude_all_optional,
                                  reset_plugins=options.reset_plugins,
                                  offline=options.offline,
                                  no_venvs=options.no_venvs
                                  )

            if options.verbose or options.debug:
                logger.debug("Verbose output enabled.\n")
                reactor.project.set_property("verbose", True)

            summary = reactor.build(
                environments=options.environments, tasks=arguments)

        except KeyboardInterrupt:
            raise PyBuilderException("Build aborted")

    except (Exception, SystemExit):
        successful = False
        failure_message = get_failure_message()
        if options.debug:
            traceback.print_exc(file=sys.stderr)

    finally:
        end = datetime.datetime.now()
        if not options.very_quiet:
            print_summary(
                successful, summary, start, end, options, failure_message)

    return 0 if successful else 1

pybuilder / pybuilder / 23886302068

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous