Telemetry

A simple pre-configured --telemetry/--no-telemetry option flag, that is respecting the proposed DO_NOT_TRACK environment variable as a unified standard to opt-out of telemetry for TUI/console apps.

It does nothing else.

from click_extra import command, context, echo, pass_context, telemetry_option

@command
@telemetry_option
@pass_context
def orchard(ctx):
    """Count the apple trees."""
    echo(f"Telemetry: {context.get(ctx, context.TELEMETRY)}")

DO_NOT_TRACK precedence

A truthy DO_NOT_TRACK turns telemetry off. Most specific first:

1. --telemetry or --no-telemetry on the command line;

2. DO_NOT_TRACK in the environment;

3. <CLI>_TELEMETRY in the environment;

4. telemetry in the CLI’s configuration file;

5. the built-in default, off.

This ranks DO_NOT_TRACK above the variable of the option and above the configuration file, where the other machine-wide variables, like CLICK_EXTRA_THEME, rank below both. DO_NOT_TRACK is a consumer-protection opt-out: a user exports it once to refuse tracking from every tool, and a configuration file a project ships, or a variable a wrapper sets, must not opt that user back in. Only the command line, which the user types, outranks it:

$ orchard
Telemetry: False
$ orchard --telemetry
Telemetry: True

click_extra.telemetry API

        classDiagram
  ExtraOption <|-- TelemetryOption
    

Telemetry utilities.

class click_extra.telemetry.TelemetryOption(param_decls=None, *, default=False, expose_value=False, envvar=None, show_envvar=True, help='Collect telemetry and usage data.', **kwargs)

Bases: ExtraOption

A pre-configured --telemetry/--no-telemetry option flag.

Respects the proposed DO_NOT_TRACK environment variable as a unified standard to opt-out of telemetry for TUI/console apps: a truthy DO_NOT_TRACK forces telemetry off, overriding the user-defined environment variables, the auto-generated values, and configuration files. Only an explicit --telemetry on the command line outranks it.

The resolved value is stored in ctx.meta[click_extra.context.TELEMETRY].

See also

• A knowledge base of telemetry disabling configuration options.

• And another list of environment variable to disable telemetry in desktop apps.

set_telemetry(ctx, param, value)

Reconcile the flag with DO_NOT_TRACK and store the result on ctx.meta.

An explicit --telemetry/--no-telemetry on the command line wins. Otherwise a truthy DO_NOT_TRACK (bare presence, or any value not parseable as false, see parse_envvar_flag()) forces telemetry off. Read via click_extra.context.get(ctx, click_extra.context.TELEMETRY).

Important

DO_NOT_TRACK breaks the rule of the other machine-wide variables, which a configuration file and the option’s own variable outrank (see machine_envvars_apply()). It is a consumer-protection opt-out: a user exports it once to refuse tracking from every tool, and a configuration file a project ships, or a <CLI>_TELEMETRY variable a wrapper or a CI job sets, must not opt that user back in. Only the command line, which the user types, outranks it.

Note

DO_NOT_TRACK is read here rather than wired through the option’s envvar: Click’s environment plumbing feeds the raw value straight to the boolean flag, so DO_NOT_TRACK=1 would enable telemetry, inverting the convention. Reading it manually keeps the opt-out meaning, mirroring how ColorOption reads NO_COLOR and friends.

Return type:

None