Jobs

A pre-configured --jobs option to control parallel execution. Defaults to one fewer than available CPU cores, leaving one core free for the main process and system tasks.

The resolved value is stored in ctx.meta["click_extra.jobs"] for downstream code to consume. The option itself does not drive any concurrency: it only captures the user’s intent.

Usage

from click import command, echo, pass_context
from click_extra import jobs_option

@command
@jobs_option
@pass_context
def build(ctx):
    """Build the project."""
    jobs = ctx.meta["click_extra.jobs"]
    echo(f"Building with {jobs} parallel jobs.")

$ build --help
Usage: build [OPTIONS]

  Build the project.

Options:
  --jobs INTEGER  Number of parallel jobs. Defaults to one less than available
                  CPUs.  [default: 1]
  --help          Show this message and exit.

$ build --jobs 4
warning: Requested 4 jobs exceeds available CPU cores (1).
Building with 4 parallel jobs.

Warnings

When the requested value is below 1, it is clamped to 1 and a warning is logged. When it exceeds available CPU cores, a warning is logged but the value is honored.

click_extra.jobs API

        classDiagram
  ExtraOption <|-- JobsOption

Parallel job control utilities.

click_extra.jobs.CPU_COUNT = 1

Number of available CPU cores, or None if undetermined.

click_extra.jobs.DEFAULT_JOBS = 1

Default number of parallel jobs: one fewer than available cores.

Falls back to 1 on single-core machines or when the core count cannot be determined.

class click_extra.jobs.JobsOption(param_decls=None, default=1, expose_value=False, show_default=True, type=<class 'int'>, help='Number of parallel jobs. Defaults to one less than available CPUs.', **kwargs)[source]

Bases: ExtraOption

A pre-configured --jobs option to control parallel execution.

Defaults to one fewer than the number of available CPU cores, leaving one core free for the main process and system tasks.

The resolved value is stored in ctx.meta["click_extra.jobs"].

Warning

This option is a placeholder for future parallel execution utilities. It does not drive any concurrency by itself: downstream code must read ctx.meta["click_extra.jobs"] and act on it.

validate_jobs(ctx, param, value)[source]

Validate job count and store the effective value in context metadata.

Clamps values below 1 to 1 and warns when the requested count exceeds available CPU cores.

Return type:

None