lintrunner 0.12.3__py3-none-win32.whl

lintrunner-0.12.3.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.1
+Name: lintrunner
+Version: 0.12.3
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+License-File: LICENSE
+Summary: A lint running tool and framework.
+Author: Michael Suo <suo@fb.com>
+Author-email: Michael Suo <suo@fb.com>
+License: BSD-3-Clause
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: repository, https://github.com/suo/lintrunner
+
+# Lintrunner
+
+## Overview
+`lintrunner` is a tool that runs linters. It is responsible for:
+- Deciding which files need to be linted.
+- Invoking linters according to a common protocol.
+- Gathering results and presenting them to users.
+
+The intention is to provide a universal way to configure and invoke linters,
+which is useful on large polyglot projects.
+
+The design of `lintrunner` is heavily inspired by `linttool`, a project that exists internally at Meta.
+
+## Installation
+```
+pip install lintrunner
+```
+
+## Usage
+First, you need to add a configuration file to your repo. See the [Linter
+configuration](#linter-configuration) section for more info.
+
+Then, simply run `lintrunner` to lint your changes!
+
+## How to control what paths to lint `lintrunner`
+When run with no arguments, `lintrunner` will check:
+- The files changed in the `HEAD` commit.
+- The files changed in the user’s working tree.
+
+It does *not* check:
+- Any files not tracked by `git`; `git add` them to lint them.
+
+There are multiple ways to customize how paths are checked:
+
+### Pass paths as positional arguments
+For example:
+```
+lintrunner foo.py bar.cpp
+```
+
+This naturally composes with `xargs`, for example the canonical way to check
+every path in the repo is:
+```
+git grep -Il . | xargs lintrunner
+```
+
+### `--configs`/ `--config`
+"Comma-separated paths to lintrunner configuration files.
+Multiple files are merged, with later definitions overriding earlier ones.
+ONLY THE FIRST is required to be present on your machine.
+Defaults to `lintrunner.toml, lintrunner.private.toml`. Extra configs like `lintrunner.private.toml`
+ are useful for combining project-wide and local configs."
+
+### `--paths-cmd`
+Some ways to invoke `xargs` will cause multiple `lintrunner` processes to be
+run, increasing lint time (especially on huge path sets). As an alternative that
+gives `lintrunner` control of parallelization, you can use `--paths-cmd`. If
+`--paths-cmd` is specified `lintrunner` will execute that command and consider
+each line of its `stdout` to be a file to lint.
+
+For example, the same command above would be:
+```
+lintrunner --paths-cmd='git grep -Il .'
+```
+
+### `--paths-file`
+If this is specified, `lintrunner` will read paths from the given file, one per
+line, and check those. This can be useful if you have some really complex logic
+to determine which paths to check.
+
+### `--revision`
+This value can be any `<tree-ish>` accepted by `git diff-tree`, like a commit
+hash or revspec. If this is specified, `lintrunner` will check:
+- All paths changed from `<tree-ish>` to `HEAD`
+- All paths changed in the user's working tree.
+
+### `--merge-base-with`
+Like `--revision`, except the revision is determined by computing the merge-base
+of `HEAD` and the provided `<tree-ish>`. This is useful for linting all commits
+in a specific pull request. For example, for a pull request targeting master,
+you can run:
+```
+lintrunner -m master
+```
+
+### `--all-files`
+This will run lint on all files specified in `.lintrunner.toml`.
+
+### `--only-lint-under-config-dir`
+If set, will only lint files under the directory where the configuration file is located and its subdirectories.
+
+## Linter configuration
+`lintrunner` knows which linters to run and how by looking at a configuration
+file, conventionally named `.lintrunner.toml`.
+
+Here is an example linter configuration:
+
+```toml
+merge_base_with = 'main'
+
+[[linter]]
+name = 'FLAKE8'
+include_patterns = [
+  'src/**/*.py',  # unix-style globs supported
+  'test/**/*.py',
+]
+exclude_patterns = ['src/my_bad_file.py']
+command = [
+  'python3',
+  'flake8_linter.py',
+  '—-',
+  # {{PATHSFILE}} gets rewritten to a tmpfile containing all paths to lint
+  '@{{PATHSFILE}}',
+]
+```
+
+A complete description of the configuration schema can be found
+[here](https://docs.rs/lintrunner/latest/lintrunner/lint_config/struct.LintConfig.html).
+
+## Linter protocol
+Most linters have their own output format and arguments. In order to impose
+consistency on linter invocation and outputs, `lintrunner` implements a protocol
+that it expects linters to fulfill. In most cases, a small script (called a
+*linter adapter*) is required to implement the protocol for a given external
+linter. You can see some example adapters in  `examples/` .
+
+### Invocation
+Linters will be invoked according to the `command` specified by their
+configuration. They will be called once per lint run.
+
+If a linter needs to know which paths to run on, it should take a
+`{{PATHSFILE}}` argument. During invocation, the string `{{PATHSFILE}}` will be
+replaced with the name of a temporary file containing which paths the linter
+should run on, one path per line.
+
+A common way to implement this in a linter adapter is to use `argparse`’s
+[`fromfile_prefix_chars`](https://docs.python.org/3/library/argparse.html#fromfile-prefix-chars)
+feature. In the Flake8 example above, we use `@` as the `fromfile_prefix_chars`
+argument, so `argparse` will automatically read the `{{PATHSFILE}}` and supply
+its contents as a list of arguments.
+
+### Output
+Any lint messages a linter would like to communicate the user must be
+represented as a `LintMessage`. The linter, must print `LintMessage`s  as [JSON
+Lines](https://jsonlines.org/) to `stdout`, one message per line. Output to
+`stderr` will be ignored.
+
+A complete description of the LintMessage schema can be found
+[here](https://docs.rs/lintrunner/latest/lintrunner/lint_message/struct.LintMessage.html).
+
+### Exiting
+Linters **should always exit with code 0**. This is true even if lint errors are
+reported; `lintrunner` itself will determine how to exit based on what linters
+report.
+
+To signal a general linter failure (which should ideally never happen!), linters
+can return a `LintMessage` with `path = None`.
+
+In the event a linter exits non-zero, it will be caught by `lintrunner`and
+presented as a “general linter failure” with stdout/stderr shown to the user.
+This should be considered a bug in the linter’s implementation of this protocol.
+
+## Tips for adopting `lintrunner` in a new project
+
+When adopting lintrunner in a previously un-linted project, it may generate a lot
+of lint messages. You can use the `--output oneline` option to make
+`lintrunner` display each lint message in its separate line to quickly navigate
+through them.
+
+Additionally, you can selectively run specific linters with the `--take` option,
+like `--take RUFF,CLANGFORMAT`, to focus on resolving specific lint errors, or
+use `--skip` to skip a long running linter like `MYPY`.
+
+## GitHub Action
+
+To use `lintrunner` in a GitHub workflow, you can consider [`lintrunner-action`](https://github.com/justinchuby/lintrunner-action).
+

lintrunner-0.12.3.dist-info/RECORD

@@ -0,0 +1,5 @@
+lintrunner-0.12.3.dist-info/METADATA,sha256=8OYY3bjPyffRYhZVghaSkPUTAl_7zQ7N5T3fFGTXoxA,7362
+lintrunner-0.12.3.dist-info/WHEEL,sha256=HkkIsZtA0sTBbF3mELGjXJRINSUxtPE9noW4nlG5fdg,91
+lintrunner-0.12.3.dist-info/license_files/LICENSE,sha256=FnG9-4L4fftD_u0xYbyexJ_u6D6lvW2qS9V7VpJLJ_I,1089
+lintrunner-0.12.3.data/scripts/lintrunner.exe,sha256=Dl3EMk7jDd9lCPEzCRmys7KAiQ2_ivf7Xij_glBhA1U,3592704
+lintrunner-0.12.3.dist-info/RECORD,,

lintrunner-0.12.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (0.12.20)
+Root-Is-Purelib: false
+Tag: py3-none-win32

lintrunner-0.12.3.dist-info/license_files/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Michael Suo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.