Logging - `vcspull.log`¶

Log utilities for formatting CLI output in vcspull.

This module containers special formatters for processing the additional context information from libvcs.base.RepoLoggingAdapter.

Colorized formatters for generic logging inside the application is also provided.

vcspull.log.get_cli_logger_names(include_self=True) ¶ function[source]

Return logger names under vcspull.cli.

Parameters:: include_self (bool)
Return type:: list[str]

vcspull.log._libvcs_stream_level(verbosity) ¶ function[source]

Return the libvcs StreamHandler level for a given -v count.

Reporter expectation: at the default verbosity, libvcs’s chatty log.info("Updating to '%s'.") and log.debug("git_tag: ...") crumb lines should NOT print on the terminal – only WARNING+ does. -v lifts that to INFO; -vv to DEBUG. The debug log file (setup_file_logger) is always DEBUG regardless of this knob.

Parameters:: verbosity (int)
Return type:: int

vcspull.log.setup_logger(log=None, level='INFO', verbosity=0) ¶ function[source]

Configure the vcspull logging hierarchy once and reuse it everywhere.

The level argument governs the vcspull logger and its CLI submodules; existing callers and --log-level users see no change.

The verbosity argument (-v count from the sync subcommand) drives the libvcs StreamHandler level via _libvcs_stream_level(). Setting it as a per-handler filter – not a logger-level filter – is deliberate: setup_file_logger later raises both loggers to DEBUG so the debug file captures the full trace, and without per-handler levels on the StreamHandlers that bump would also open the terminal floodgate. See tests/test_log.py::test_setup_file_logger_does_not_open_stream_floodgate for the regression guard.

Parameters:

log (Logger | None)
level (Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'])
verbosity (int)

Return type:

None

class vcspull.log.LogFormatter ¶ class[source]

Bases: Formatter

Log formatting for vcspull.

__init__(color=True, **kwargs)
¶
method[source]

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

Parameters:

color (bool)
kwargs (Any)

Return type:

None

class vcspull.log.DebugLogFormatter ¶ class[source]

Bases: LogFormatter

Provides greater technical details than standard log Formatter.

class vcspull.log.RepoLogFormatter ¶ class[source]

Bases: LogFormatter

Log message for VCS repository.

class vcspull.log.SimpleLogFormatter ¶ class[source]

Bases: Formatter

Simple formatter that outputs only the message, like print().

class vcspull.log.RepoFilter ¶ class[source]

Bases: Filter

Only include repo logs for this type of record.

vcspull.log._DEBUG_FILE_FORMAT = '%(asctime)s.%(msecs)03d [%(levelname)s] %(name)s %(module)s:%(lineno)d -- %(message)s' ¶ data: Format string for the debug log file. Verbose enough to trace a hang: level, timestamp (to millisecond), logger, module:line, and the message.

vcspull.log.default_debug_log_path() ¶ function[source]

Return the path where vcspull writes its per-invocation debug log.

Mirrors the npm / pnpm convention of dropping a timestamped log file in the system temp directory on every run. The file is always created but its path is only surfaced to the user when something went wrong (failure or timeout), so clean runs stay quiet.

Logs land under a vcspull/ subdirectory of the system tempdir (e.g. /tmp/vcspull/debug-<ts>-<pid>.log) so the dir name in /tmp/ is self-describing instead of relying on a vcspull- file prefix that gets lost in a busy tempdir. Under pytest (PYTEST_CURRENT_TEST is set) the subdirectory is vcspull-test/ instead – an automatic safety net so tests that incidentally invoke this helper without redirecting TMPDIR can’t pollute the production log dir.

Examples

>>> path = default_debug_log_path()
>>> path.name.startswith("debug-")
True
>>> path.suffix
'.log'
>>> path.parent.name in {"vcspull", "vcspull-test"}
True
>>> path.parent.parent == pathlib.Path(tempfile.gettempdir())
True

Return type:: Path

vcspull.log.setup_file_logger(path, *, level=10) ¶ function[source]

Attach a file handler to the vcspull and libvcs loggers.

Unlike setup_logger(), this handler is not tied to stdout – it captures the full debug trace so a post-mortem (npm/pnpm/yarn style) has enough context to diagnose a timeout even when the CLI output was aggressively summarised.

Parameters:

path (pathlib.Path) – Destination file. Parent directories are created as needed. An existing file is appended to so a single session that sets up logging multiple times does not clobber earlier context.
level (int) – Threshold for the file handler. Defaults to logging.DEBUG because the file is consulted only when diagnosing a failure.

Return type:

FileHandler

vcspull.log.teardown_file_logger(handler) ¶ function[source]

Flush and detach handler from the vcspull/libvcs loggers.

Parameters:: handler (FileHandler)
Return type:: None

Logging - vcspull.log¶

Logging - `vcspull.log`¶