Package: pysen
pysenInstallPyPIIf you have no preference of linter versions (recommended for newbies)pipinstall"pysen[lint]"Install pysen with your choice of linter versionspipinstallpysen
pipinstallblack==21.10b0flake8==4.0.1isort==5.10.1mypy==0.910Other installation examples# pipenvpipenvinstall--dev"pysen[lint]==0.10.5"# poetrypoetryadd-Dpysen==0.10.5-ElintQuickstart: Set up linters using pysenPut the following pysen configuration to eitherpysen.tomlorpyproject.tomlof your python package:[tool.pysen]version="0.10"[tool.pysen.lint]enable_black=trueenable_flake8=trueenable_isort=trueenable_mypy=truemypy_preset="strict"line_length=88py_version="py37"[[tool.pysen.lint.mypy_targets]]paths=["."]then, execute the following command:$pysenrunlint
$pysenrunformat# corrects errors with compatible commands (black, isort)That's it!
pysen, or more accurately pysen tasks that support the specified linters, generate setting files for black, isort, mypy, and flake8
and run them with the appropriate configuration.
For more details about the configuration items that you can write in a config file, please refer topysen/pyproject_model.py.You can also add custom setup commands to your Python package by adding the following lines to itssetup.py:importpysensetup=pysen.setup_from_pyproject(__file__)$pythonsetup.pylintWe also provide a Python interface for customizing our configuration and extending pysen.
For more details, please refer to the following two examples:Example configuration from Python:examples/advanced_example/config.pyExample plugin for pysen:examples/plugin_example/plugin.pyFrequently Asked QuestionsQ. How do I usemypy >= 0.800?A. SeeInstall pysen with your choice of linter versionsQ. mypy reports the errorSource file found twice under different module names.A. Addtool.pysen.lint.mypy_targetssection(s) so file names are unique in each section.Q. How do I change specific settings for linter X?A. We prioritize convention over configuration. However you can always create your own plugin. See:Create a plugin to customize pysenQ. pysen seems to ignore some files.A. pysen only checks files that are tracked in git. Trygit adding the file under question.
You can also disable this behavior by setting the environment variablePYSEN_IGNORE_GIT=1.Q. How do I run only [flake8|black|isort|mypy]?A. Try the--enableand--disableoptions, for example,pysen --enable flake --enable black run lint.Q. Files without filename extensions are not checked.A. Explicitly add those files under the include section intool.pysen.lint.source.Q. How do I add additional settings to mypyproject.toml, e.g.,pydantic-mypy?A. Addsettings_dir="."under the[tool.pysen-cli]section.What is pysen?pysen aims to provide a unified platform to configure and run day-to-day development tools.
We envision the following scenarios in the future:You open any project andpysen run lint,pysen run formatwill check and format the entire codebaseStandardized coding styles are setup with a few lines in a single config filepysen centralizes the code and knowledge related to development tools that teams have accumulated, most notably for python linters.
You can make tasks that can be executed from bothsetup.pyand our command-line tool.
We currently provide tasks that manage setting files for the following tools:lintersflake8isortmypyblackutilities(planned) protocWhat isn't pysen?pysen is not a linting tool per se. Rather,pysen run lintorchestrates multiple python linting tools by automatically setting up their configurations from a more abstract setting for pysen.pysen does not manage your dependencies and packages. We recommend using package managers such aspipenvorpoetryto lock your dependency versions,including the versions for the linting tools that pysen coordinates(i.e., isort, mypy, flake8, black). Theconfirmedversions for these tools can be found in theextra_requires/lintsection in pysen'ssetup.py, although higher versions may work. You shouldnotrely onpip install pysen[lint]to control the versions of your linting tools.pysen is not limited to linting purposes or python. See theplugin sectionfor details.How it works: Settings file directoryUnder the hood, whenever you run pysen, it generates the setting files as ephemeral temporary files to be used by linters.
You may want to keep those setting files on your disk, e.g. when you want to use them for your editor.
If that is the case, run the following command to generate the setting files to your directory of choice:$pysengenerate[out_dir]You can specify the settings directory that pysen uses when youpysen run.
To do so add the following section to your config:[tool.pysen-cli]settings_dir="path/to/generate/settings"When you specify a directory that already contains some configurations, pysen merges the contents. The resulting behavior may differ from when you don't specifysettings_dir.Also keep in mind that this option is honored only when you use pysen through its CLI. When using pre-commit or setuptools you need to specifysettings_diras arguments.Tips: IDE / Text editor integrationvimYou can add errors that pysen reports to your quickfix window by::cex system("pysen run_files lint --error-format gnu ".expand('%:p'))Another way is to set pysen tomakeprg:set makeprg=pysen\ run_files\ --error-format\ gnu\ lint\ %Then running:makewill populate your quickfix window with errors.
This also works withvim-dispatchas long as you invoke:Makeinstead of:Dispatch(forthis reason)The result will look like the following:A third party plugin is also available.pysen.vimEmacsRefer to theCompilation mode.
The following is an example hook for python.(add-hook 'python-mode-hook
    (lambda ()
        (set (make-local-variable 'compile-command)
            (concat "pysen run_files lint --error-format gnu  " buffer-file-name))))VSCodeAthird party pluginis available.Note that this may report duplicate errors if you have configured linters likeflake8directly through your VSCode python extension.Configure pysenWe provide two methods to write configuration for pysen.One is the[tool.pysen.lint]section in the config.
It is the most simple way to configure pysen, but the settings we provide are limited.The other method is to write a python script that configures pysen directly.
If you want to customize configuration files that pysen generates, command-line arguments that pysen takes, or whatever actions pysen performs, we recommend you use this method.
For more examples, please refer topysen/examples.Configuration modelPlease refer topysen/pyproject_model.pyfor the latest model.Here is an example of a basic configuration:[tool.pysen]version="0.10"[tool.pysen.lint]enable_black=trueenable_flake8=trueenable_isort=trueenable_mypy=truemypy_preset="strict"line_length=88py_version="py37"isort_known_third_party=["numpy"]isort_known_first_party=["pysen"]mypy_ignore_packages=["pysen.generated.*"]mypy_path=["stubs"][[tool.pysen.lint.mypy_targets]]paths=[".","tests/"][tool.pysen.lint.source]includes=["."]include_globs=["**/*.template"]excludes=["third_party/"]exclude_globs=["**/*_grpc.py"][tool.pysen.lint.mypy_modules."pysen.scripts"]preset="entry"[tool.pysen.lint.mypy_modules."numpy"]ignore_errors=truepysen looks for a configuration file in the following order:pysen.tomlwith atool.pysensectionpyproject.tomlwith atool.pysensectionCreate a plugin to customize pysenWe provide a plugin interface for customizing our tool support, setting files management, setup commands and so on.
For more details, please refer topysen/examples/plugin_example.Developmentpipenvis required for managing our development environment.# setup your environment$pipenvsync# activate the environment$pipenvshellUpdate dependencies inPipfile.lock$pipenvlock--preRun all tests$pipenvruntoxmypy presetsThe mypy presetstrictaims to make life easier for developers using the following packages:OpenCVPyTorchscikit-learnWe recommend developers mitigate some rules from thevery strictpreset to avoid some hassles.
If you use these packages with thestrictpreset and still have inconveniences, please let us know.ContributingOur main priority is to fulfil the demands from projects within Preferred Networks.
Therefore, we must assess whether each feature/pull request is in the best interest of our projects.
In principle, we are open to minor things like the following:Issues that report bugsSmall PRs that fix typos or minor glitchesAs for new features or major feature enhancements,
the core developers will determine whether the proposed idea is in line with the
goals and concepts ofpysenfor each case.
When in doubt, don't hesitate to open an Issue first.