API reference#

beet_default(
ctx: Context,
) → Any[source]#

Initializes the StewBeet package.

cli#

force_utf8_output() → None[source]#

Make stdout and stderr encode UTF-8 whatever the console’s code page is.

Windows consoles default to a legacy code page (cp1252 in Western locales)which cannot encode the emoji in the template list or the box-drawing characters in --help. Printing either raised UnicodeEncodeError and took the command down before it did anything, so stewbeet init failed on a first run. errors="replace" keeps a terminal that genuinely cannot render a glyph from crashing on it.

print_help() → None[source]#

Print the commands of stewbeet and of beet, with their options.

clean_project(
cfg: ProjectConfig,
) → None[source]#

Remove the beet cache, the build output, every __pycache__, the item renders and the debug definitions file.

run_beet(cfg: ProjectConfig) → None[source]#

Import the pipeline up front for readable errors, then hand the command line to beet.

silent#

telemetry#

Anonymous build telemetry: one counter increment per successful StewBeet build.

The whole feature lives in this file so anyone can read it in less than a minute and know exactly what leaves their machine: the StewBeet version, the full Python version (major.minor.micro), and how long the build took. Nothing identifies the project, the machine or the person, and nothing is stored between builds.

Set STEWBEET_TELEMETRY=0 to turn it off, every failure is swallowed: a build never fails, slows down or changes because of it.

Public page and aggregated numbers: https://stewbeet.paralya.fr/telemetry

ENDPOINT: str = 'https://stewbeet.paralya.fr/api/telemetry/build'[source]#

Where the event goes. The server keeps a daily counter and forgets everything else.

OPT_OUT_VARIABLE: str = 'STEWBEET_TELEMETRY'[source]#

Setting this to 0 (or false/no/off) disables telemetry entirely.

TIMEOUT_SECONDS: float = 2.0[source]#

Connect plus read budget. Short on purpose: an unreachable server must not hold a build open.

DISABLED_VALUES: frozenset[str] = frozenset({'0', 'false', 'no', 'off'})[source]#

Values of STEWBEET_TELEMETRY that mean “do not send anything”.

class Telemetry[source]#

Bases: object

The only entry point is Telemetry.record_build, called once a build has succeeded.

static is_enabled() → bool[source]#

Whether telemetry may be sent at all.

Returns:

True unless STEWBEET_TELEMETRY names one of the disabled values.

Return type:

bool

>>> os.environ[OPT_OUT_VARIABLE] = "0"
>>> Telemetry.is_enabled()
False
>>> os.environ[OPT_OUT_VARIABLE] = "1"
>>> Telemetry.is_enabled()
True
>>> del os.environ[OPT_OUT_VARIABLE]
>>> Telemetry.is_enabled()
True
static stewbeet_version() → str[source]#

Installed StewBeet version, or “unknown” when the package metadata is not there.

static payload(
duration_seconds: float,
) → JsonDict[source]#

The complete body of the request. These three keys are all there has ever been.

Parameters:

duration_seconds – How long the build took, in seconds.

Returns:

The documented fields, and nothing else.

Return type:

JsonDict

>>> sorted(Telemetry.payload(1.2345))
['duration_seconds', 'python_version', 'stewbeet_version']
>>> Telemetry.payload(1.2345)["duration_seconds"]
1.234
>>> Telemetry.payload(-1.0)["duration_seconds"]
0.0
static send(
payload: JsonDict,
) → None[source]#

POST one event and drop the answer, along with any error it took to get there.

Parameters:

payload – The body built by Telemetry.payload.

static record_build(
duration_seconds: float,
) → Thread | None[source]#

Report one successful build, on a thread so the terminal gets its prompt back immediately.

The thread is not a daemon, so the interpreter waits for it on the way out, and TIMEOUT_SECONDS bounds that wait. A delivery that blows up is never the build’s problem.

Returns:

The delivery thread, or None when telemetry is disabled.

utils#

get_project_config() → ProjectConfig[source]#

The beet configuration of the project the current directory belongs to, which becomes the current directory.

Raises:

AssertionError – When neither the current directory nor a parent holds a beet configuration.