refex.cli

Command-line interface to Refex, and extension points to that interface.

This module allows you to define your own main() function by calling run_cli() with alternative arguments, which is a blunt and silly extension point to allow for users to extend the refex CLI with new features.

class RefexRunner(searcher, renderer=NOTHING, dry_run=True, show_diff=True, show_files=True, verbose=False, max_iterations=10)

The application logic of the refex CLI app.

This implementation should work for a normal unix-y filesystem. Subclasses can override methods to handle more exotic filesystems as needed.

All methods in this class and subclasses should be thread safe, since they may be executed in a multithreaded context from within the same instance of the class. NOTE: currently log_changes isn’t thread safe, that should be fixed or updated.

Subclasses should consider overriding the following methods:

It may be necessary to override get_matches(), but this seems unlikely.

read(path: str) → Optional[str]

Reads in a file and return the resulting content as unicode.

Since this is only called from the loop within rewrite_files(), non-fatal failures should return None.

Parameters

path – The path to the file.

Returns

An optional unicode string of the file content.

get_matches(contents, path)

Finds all refex matches in the file.

Parameters

  • contents – File contents to analyze.

  • path – The path to the above content.

Returns

A list of refex Match objects.

log_changes(content, matches, name, renderer)

Prints any changes, depending on the config.

rewrite_files(path_pairs)

Main access point for rewriting.

Parameters

path_pairs – A list of (read, write) filenames. For most users, if the list of files is files, rewrite_files(zip(files, files)) should work.

Returns

A JSON-serializable dict of filename to failure information. Only files that failed to load are in this dict.

run(runner: refex.cli.RefexRunner, files: Iterable[Union[str, Tuple[str, str]]], bug_report_url: str, version: str = '<unspecified>')

Performs console setup, and runs.

Parameters

  • runner – a RefexRunner.

  • files – the list of files to rewrite using runner. If the output file is different from the input file, a pair (input, output) may be passed instead of just inout.

  • bug_report_url – if a failure occurs, the URL to report bugs to.

  • version – The version to write to debug logs.

run_cli(argv, parser, get_runner, get_files, bug_report_url='https://github.com/ssbr/refex/issues/new/choose', version='<unspecified>')

Creates a runner from command-line arguments, and executes it.

Parameters

  • argv – argv

  • parser – An ArgumentParser.

  • get_runner – called with (parser, options) returns the runner to use.

  • get_files – called with (runner, options) returns the files to examine, as [(in_file, out_file), …] pairs.

  • bug_report_url – An URL to present to the user to report bugs. As the error dump includes source code, corporate organizations may wish to override this with an internal bug report link for triage.

  • version – The version number to use in bug report logs and –version

report_failures(failures, bug_report_url, version, verbose)

Reports RefexRunner.rewrite_files() failures, if any.

These are written to a debug log file (readable via the developer script rxerr_debug), and to stderr.

Parameters

  • failures – The return value of RefexRunner.rewrite_files().

  • bug_report_url – An URL to present to the user to report bugs.

  • version – The version number to write to debug logs.

  • verbose – If true, writes failures to stderr in addition to debug logs.

argument_parser(version)

Creates an argparse.ArgumentParser for the refex CLI.

runner_from_options(parser, options) → refex.cli.RefexRunner

Returns a runner based on CLI flags.

files_from_options(runner: refex.cli.RefexRunner, options) → Iterable[Tuple[str, str]]

Returns the list of files specified by the command line options.

main(argv=None, bug_report_url='https://github.com/ssbr/refex/issues/new/choose', version=None)

The refex main function.