Page MenuHomePhabricator
Diviner libphutil Tech Docs ArcanistPyLintLinter

final class ArcanistPyLintLinter
libphutil Technical Documentation ()

Uses "PyLint" to detect various errors in Python code.

Tasks

Human Readable Information

Runtime State

Executing the Linter

  • public function willLintPaths($paths)
  • final public function lintPath($path)
  • public function didLintPaths($paths)
  • final protected function getExecutableCommand() — Get the composed executable command, including the interpreter and binary but without flags or paths. This can be used to execute `--version` commands.
  • final protected function getCommandFlags() — Get the composed flags for the executable, including both mandatory and configured flags.

Interpreters, Binaries and Flags

  • public function getDefaultBinary()
  • public function getInstallInstructions()
  • public function getUpgradeInstructions() — Return a human-readable string describing how to upgrade the linter.
  • public function shouldExpectCommandErrors()
  • protected function getMandatoryFlags()
  • protected function getDefaultFlags()
  • final public function setFlags($flags) — Override default flags with custom flags. If not overridden, flags provided by @{method:getDefaultFlags} are used.
  • final public function setVersionRequirement($version) — Set the binary's version requirement.
  • final public function getBinary() — Return the binary or script to execute. This method synthesizes defaults and configuration. You can override the binary with @{method:setBinary}.
  • final public function setBinary($bin) — Override the default binary with a new one.
  • public function shouldUseInterpreter() — Return true if this linter should use an interpreter (like "python" or "node") in addition to the script.
  • public function getDefaultInterpreter() — Return the default interpreter, like "python" or "node". This method is only invoked if @{method:shouldUseInterpreter} has been overridden to return `true`.
  • final public function getInterpreter() — Get the effective interpreter. This method synthesizes configuration and defaults.
  • final public function setInterpreter($interpreter) — Set the interpreter, overriding any default.

Parsing Linter Output

Other Methods

Methods

public function getInfoURI()

ArcanistLinter

Return an optional informative URI where humans can learn more about this linter.

For most linters, this should return a link to the project home page. This is shown on arc linters.

ArcanistPyLintLinter
This method is not documented.
Return
string|nullOptionally, return an informative URI.

public function getInfoDescription()

ArcanistLinter

Return a brief human-readable description of the linter.

These should be a line or two, and are shown on arc linters.

ArcanistPyLintLinter
This method is not documented.
Return
string|nullOptionally, return a brief human-readable description.

public function getAdditionalInformation()
Inherited

ArcanistLinter

Return arbitrary additional information.

Linters can use this method to provide arbitrary additional information to be included in the output of arc linters.

Return
map<string, string>A mapping of header to body content for the additional information sections.

public function getInfoName()

ArcanistLinter

Return a human-readable linter name.

These are used by arc linters, and can let you give a linter a more presentable name.

ArcanistPyLintLinter
This method is not documented.
Return
stringHuman-readable linter name.

final public function getActivePath()
Inherited

This method is not documented.
Return
wild

final public function setActivePath($path)
Inherited

This method is not documented.
Parameters
$path
Return
wild

final public function setEngine($engine)
Inherited

This method is not documented.
Parameters
ArcanistLintEngine$engine
Return
wild

final protected function getEngine()
Inherited

This method is not documented.
Return
wild

final public function setLinterID($id)
Inherited

ArcanistLinter

Set the internal ID for this linter.

This ID is assigned automatically by the ArcanistLintEngine.

Parameters
string$idUnique linter ID.
Return
this

final public function getLinterID()
Inherited

ArcanistLinter

Get the internal ID for this linter.

Retrieves an internal linter ID managed by the ArcanistLintEngine. This ID is a unique scalar which distinguishes linters in a list.

Return
stringUnique linter ID.

public function willLintPaths($paths)
Inherited

ArcanistLinter

Hook called before a list of paths are linted.

Parallelizable linters can start multiple requests in parallel here, to improve performance. They can implement didLintPaths() to collect results.

Linters which are not parallelizable should normally ignore this callback and implement lintPath() instead.

Parameters
list<string>$pathsA list of paths to be linted
Return
void

final public function lintPath($path)
Inherited

ArcanistLinter

Hook called for each path to be linted.

Linters which are not parallelizable can do work here.

Linters which are parallelizable may want to ignore this callback and implement willLintPaths() and didLintPaths() instead.

Parameters
string$pathPath to lint.
Return
void

public function didLintPaths($paths)
Inherited

ArcanistLinter

Hook called after a list of paths are linted.

Parallelizable linters can collect results here.

Linters which are not paralleizable should normally ignore this callback and implement lintPath() instead.

Parameters
list<string>$pathsA list of paths which were linted.
Return
void

public function getLinterPriority()
Inherited

This method is not documented.
Return
wild

public function setCustomSeverityMap($map)
Inherited

This method is not documented.
Parameters
array$map
Return
wild

public function addCustomSeverityMap($map)
Inherited

This method is not documented.
Parameters
array$map
Return
wild

public function setCustomSeverityRules($rules)
Inherited

This method is not documented.
Parameters
array$rules
Return
wild

final public function getProjectRoot()
Inherited

This method is not documented.
Return
wild

final public function getOtherLocation($offset, $path)
Inherited

This method is not documented.
Parameters
$offset
$path
Return
wild

final public function stopAllLinters()
Inherited

This method is not documented.
Return
wild

final public function didStopAllLinters()
Inherited

This method is not documented.
Return
wild

final public function addPath($path)
Inherited

This method is not documented.
Parameters
$path
Return
wild

final public function setPaths($paths)
Inherited

This method is not documented.
Parameters
array$paths
Return
wild

private function filterPaths($paths)
Inherited

ArcanistLinter

Filter out paths which this linter doesn't act on (for example, because they are binaries and the linter doesn't apply to binaries).

Parameters
list<string>$paths
Return
list<string>

final public function getPaths()
Inherited

This method is not documented.
Return
wild

final public function addData($path, $data)
Inherited

This method is not documented.
Parameters
$path
$data
Return
wild

final protected function getData($path)
Inherited

This method is not documented.
Parameters
$path
Return
wild

public function getCacheVersion()
Inherited

This method is not documented.
Return
wild

final public function getLintMessageFullCode($short_code)
Inherited

This method is not documented.
Parameters
$short_code
Return
wild

final public function getLintMessageSeverity($code)
Inherited

This method is not documented.
Parameters
$code
Return
wild

protected function getDefaultMessageSeverity($code)

This method is not documented.
Parameters
$code
Return
wild

final public function isMessageEnabled($code)
Inherited

This method is not documented.
Parameters
$code
Return
wild

final public function getLintMessageName($code)
Inherited

This method is not documented.
Parameters
$code
Return
wild

final protected function addLintMessage($message)
Inherited

This method is not documented.
Parameters
ArcanistLintMessage$message
Return
wild

final public function getLintMessages()
Inherited

This method is not documented.
Return
wild

final public function raiseLintAtLine($line, $char, $code, $description, $original, $replacement)
Inherited

This method is not documented.
Parameters
$line
$char
$code
$description
$original
$replacement
Return
wild

final public function raiseLintAtPath($code, $desc)
Inherited

This method is not documented.
Parameters
$code
$desc
Return
wild

final public function raiseLintAtOffset($offset, $code, $description, $original, $replacement)
Inherited

This method is not documented.
Parameters
$offset
$code
$description
$original
$replacement
Return
wild

public function canRun()
Inherited

This method is not documented.
Return
wild

public function getLinterName()

This method is not documented.
Return
wild

public function getVersion()

This method is not documented.
Return
wild

final protected function isCodeEnabled($code)
Inherited

This method is not documented.
Parameters
$code
Return
wild

public function getLintSeverityMap()
Inherited

This method is not documented.
Return
wild

public function getLintNameMap()
Inherited

This method is not documented.
Return
wild

public function getCacheGranularity()
Inherited

This method is not documented.
Return
wild

public function getLinterConfigurationName()

ArcanistLinter

If this linter is selectable via .arclint configuration files, return a short, human-readable name to identify it. For example, "jshint" or "pep8".

If you do not implement this method, the linter will not be selectable through .arclint files.

ArcanistPyLintLinter
This method is not documented.
Return
wild
This method is not documented.
Return
wild

public function setLinterConfigurationValue($key, $value)

This method is not documented.
Parameters
$key
$value
Return
wild

protected function canCustomizeLintSeverities()
Inherited

This method is not documented.
Return
wild

protected function shouldLintBinaryFiles()
Inherited

This method is not documented.
Return
wild

protected function shouldLintDeletedFiles()
Inherited

This method is not documented.
Return
wild

protected function shouldLintDirectories()
Inherited

This method is not documented.
Return
wild

protected function shouldLintSymbolicLinks()
Inherited

This method is not documented.
Return
wild

protected function getLintCodeFromLinterConfigurationKey($code)

ArcanistLinter

Map a configuration lint code to an arc lint code. Primarily, this is intended for validation, but can also be used to normalize case or otherwise be more permissive in accepted inputs.

If the code is not recognized, you should throw an exception.

ArcanistExternalLinter

Map a configuration lint code to an arc lint code. Primarily, this is intended for validation, but can also be used to normalize case or otherwise be more permissive in accepted inputs.

If the code is not recognized, you should throw an exception.

ArcanistPyLintLinter
This method is not documented.
Parameters
string$codeCode specified in configuration.
Return
stringNormalized code to use in severity map.

protected function buildFutures($paths)
Inherited

This method is not documented.
Parameters
array$paths
Return
wild

protected function resolveFuture($path, $future)
Inherited

This method is not documented.
Parameters
$path
Future$future
Return
wild

final protected function getFuturesLimit()
Inherited

This method is not documented.
Return
wild

protected function didResolveLinterFutures($futures)
Inherited

ArcanistFutureLinter

Hook for cleaning up resources.

This is invoked after a block of futures resolve, and allows linters to discard or clean up any shared resources they no longer need.

Parameters
map<string,$futuresFuture> Map of paths to resolved futures.
Return
void

public function getDefaultBinary()

ArcanistExternalLinter

Return the default binary name or binary path where the external linter lives. This can either be a binary name which is expected to be installed in PATH (like "jshint"), or a relative path from the project root (like "resources/support/bin/linter") or an absolute path.

If the binary needs an interpreter (like "python" or "node"), you should also override shouldUseInterpreter() and provide the interpreter in getDefaultInterpreter().

ArcanistPyLintLinter
This method is not documented.
Return
stringDefault binary to execute.

public function getInstallInstructions()

ArcanistExternalLinter

Return a human-readable string describing how to install the linter. This is normally something like "Install such-and-such by running `npm install -g such-and-such`.", but will differ from linter to linter.

ArcanistPyLintLinter
This method is not documented.
Return
stringHuman readable install instructions

public function getUpgradeInstructions()
Inherited

ArcanistExternalLinter

Return a human-readable string describing how to upgrade the linter.

Return
stringHuman readable upgrade instructions

public function shouldExpectCommandErrors()

ArcanistExternalLinter

Return true to continue when the external linter exits with an error code. By default, linters which exit with an error code are assumed to have failed. However, some linters exit with a specific code to indicate that lint messages were detected.

If the linter sometimes raises errors during normal operation, override this method and return true so execution continues when it exits with a nonzero status.

ArcanistPyLintLinter
This method is not documented.
Parameters
boolReturn true to continue on nonzero error code.
Return
wild

protected function getMandatoryFlags()

ArcanistExternalLinter

Provide mandatory, non-overridable flags to the linter. Generally these are format flags, like --format=xml, which must always be given for the output to be usable.

Flags which are not mandatory should be provided in getDefaultFlags() instead.

ArcanistPyLintLinter
This method is not documented.
Return
list<string>Mandatory flags, like `"--format=xml"`.

protected function getDefaultFlags()

ArcanistExternalLinter

Provide default, overridable flags to the linter. Generally these are configuration flags which affect behavior but aren't critical. Flags which are required should be provided in getMandatoryFlags() instead.

Default flags can be overridden with setFlags().

ArcanistPyLintLinter
This method is not documented.
Return
list<string>Overridable default flags.

final public function setFlags($flags)
Inherited

ArcanistExternalLinter

Override default flags with custom flags. If not overridden, flags provided by getDefaultFlags() are used.

Parameters
list<string>$flagsNew flags.
Return
this

final public function setVersionRequirement($version)
Inherited

ArcanistExternalLinter

Set the binary's version requirement.

Parameters
string$versionVersion requirement.
Return
this

final public function getBinary()
Inherited

ArcanistExternalLinter

Return the binary or script to execute. This method synthesizes defaults and configuration. You can override the binary with setBinary().

Return
stringBinary to execute.

final public function setBinary($bin)
Inherited

ArcanistExternalLinter

Override the default binary with a new one.

Parameters
string$binNew binary.
Return
this

public function shouldUseInterpreter()
Inherited

ArcanistExternalLinter

Return true if this linter should use an interpreter (like "python" or "node") in addition to the script.

After overriding this method to return true, override getDefaultInterpreter() to set a default.

Return
boolTrue to use an interpreter.

public function getDefaultInterpreter()
Inherited

ArcanistExternalLinter

Return the default interpreter, like "python" or "node". This method is only invoked if shouldUseInterpreter() has been overridden to return true.

Return
stringDefault interpreter.

final public function getInterpreter()
Inherited

ArcanistExternalLinter

Get the effective interpreter. This method synthesizes configuration and defaults.

Return
stringEffective interpreter.

final public function setInterpreter($interpreter)
Inherited

ArcanistExternalLinter

Set the interpreter, overriding any default.

Parameters
string$interpreterNew interpreter.
Return
this

protected function parseLinterOutput($path, $err, $stdout, $stderr)

ArcanistExternalLinter

Parse the output of the external lint program into objects of class ArcanistLintMessage which arc can consume. Generally, this means examining the output and converting each warning or error into a message.

If parsing fails, returning false will cause the caller to throw an appropriate exception. (You can also throw a more specific exception if you're able to detect a more specific condition.) Otherwise, return a list of messages.

ArcanistPyLintLinter
This method is not documented.
Parameters
string$pathPath to the file being linted.
int$errExit code of the linter.
string$stdoutStdout of the linter.
string$stderrStderr of the linter.
Return
list<ArcanistLintMessage>|falseList of lint messages, or false to indicate parser failure.

final public function checkBinaryConfiguration()
Inherited

ArcanistExternalLinter

Check that the binary and interpreter (if applicable) exist, and throw an exception with a message about how to install them if they do not.

Return
void

final protected function checkBinaryVersion($version)
Inherited

ArcanistExternalLinter

If a binary version requirement has been specified, compare the version of the configured binary to the required version, and if the binary's version is not supported, throw an exception.

Parameters
string$versionVersion string to check.
Return
void

final protected function getExecutableCommand()
Inherited

ArcanistExternalLinter

Get the composed executable command, including the interpreter and binary but without flags or paths. This can be used to execute --version commands.

Return
stringCommand to execute the raw linter.

final protected function getCommandFlags()
Inherited

ArcanistExternalLinter

Get the composed flags for the executable, including both mandatory and configured flags.

Return
list<string>Composed flags.

protected function getPathArgumentForLinterFuture($path)
Inherited

ArcanistExternalLinter

Prepare the path to be added to the command string.

This method is expected to return an already escaped string.

Parameters
string$pathPath to the file being linted
Return
stringThe command-ready file argument