{"id":20106178,"url":"https://github.com/himkt/pysen-docs","last_synced_at":"2026-06-07T03:33:16.620Z","repository":{"id":91120586,"uuid":"486461332","full_name":"himkt/pysen-docs","owner":"himkt","description":null,"archived":false,"fork":false,"pushed_at":"2022-05-15T10:08:34.000Z","size":6579,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-13T05:08:39.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/himkt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-28T05:42:19.000Z","updated_at":"2022-04-30T15:15:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"504377d2-2f96-4f89-afc4-604ba5ba5a8c","html_url":"https://github.com/himkt/pysen-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fpysen-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fpysen-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fpysen-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/himkt%2Fpysen-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/himkt","download_url":"https://codeload.github.com/himkt/pysen-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241549089,"owners_count":19980475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T17:49:17.929Z","updated_at":"2025-03-02T17:47:32.653Z","avatar_url":"https://github.com/himkt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pysen\n\n![](https://github.com/pfnet/pysen/blob/main/assets/imgs/pysen.gif?raw=true)\n\n## Install\n\n### PyPI\n\n#### If you have no preference of linter versions (recommended for newbies)\n\n```sh\npip install \"pysen[lint]\"\n```\n\n#### Install pysen with your choice of linter versions\n\n```sh\npip install pysen\npip install black==21.10b0 flake8==4.0.1 isort==5.10.1 mypy==0.910\n```\n\n### Other installation examples\n\n```sh\n# pipenv\npipenv install --dev \"pysen[lint]==0.10.2\"\n# poetry\npoetry add -D pysen==0.10.2 -E lint\n```\n\n## Quickstart: Set up linters using pysen\n\nPut the following pysen configuration to either `pysen.toml` or `pyproject.toml` of your python package:\n```toml\n[tool.pysen]\nversion = \"0.10\"\n\n[tool.pysen.lint]\nenable_black = true\nenable_flake8 = true\nenable_isort = true\nenable_mypy = true\nmypy_preset = \"strict\"\nline_length = 88\npy_version = \"py37\"\n[[tool.pysen.lint.mypy_targets]]\n  paths = [\".\"]\n```\n\nthen, execute the following command:\n```sh\n$ pysen run lint\n$ pysen run format  # corrects errors with compatible commands (black, isort)\n```\n\nThat's it!\npysen, or more accurately pysen tasks that support the specified linters, generate setting files for black, isort, mypy, and flake8\nand run them with the appropriate configuration.\nFor more details about the configuration items that you can write in a config file, please refer to `pysen/pyproject_model.py`.\n\nYou can also add custom setup commands to your Python package by adding the following lines to its `setup.py`:\n```py\nimport pysen\nsetup = pysen.setup_from_pyproject(__file__)\n```\n\n```sh\n$ python setup.py lint\n```\n\nWe also provide a Python interface for customizing our configuration and extending pysen.\nFor more details, please refer to the following two examples:\n- Example configuration from Python: `examples/advanced_example/config.py`\n- Example plugin for pysen: `examples/plugin_example/plugin.py`\n\n## Frequently Asked Questions\n\nQ. How do I use `mypy \u003e= 0.800`?  \nA. See [Install pysen with your choice of linter versions](#install-pysen-with-your-choice-of-linter-versions)\n\nQ. mypy reports the error `Source file found twice under different module names`.  \nA. Add `tool.pysen.lint.mypy_targets` section(s) so file names are unique in each section.\n\nQ. How do I change specific settings for linter X?  \nA. We prioritize convention over configuration. However you can always create your own plugin. See: [Create a plugin to customize pysen](#create-a-plugin-to-customize-pysen)\n\nQ. pysen seems to ignore some files.  \nA. pysen only checks files that are tracked in git. Try `git add`ing the file under question.\nYou can also disable this behavior by setting the environment variable `PYSEN_IGNORE_GIT=1`.\n\nQ. How do I run only [flake8|black|isort|mypy]?  \nA. Try the `--enable` and `--disable` options, for example, `pysen --enable flake --enable black run lint`.\n\nQ. Files without filename extensions are not checked.  \nA. Explicitly add those files under the include section in `tool.pysen.lint.source`.\n\nQ. How do I add additional settings to my `pyproject.toml`, e.g., [pydantic-mypy](https://pydantic-docs.helpmanual.io/mypy_plugin/#configuring-the-plugin)?  \nA. Add `settings_dir=\".\"` under the `[tool.pysen-cli]` section.\n\n## What is pysen?\n\npysen aims to provide a unified platform to configure and run day-to-day development tools.\nWe envision the following scenarios in the future:\n\n- You open any project and `pysen run lint`, `pysen run format` will check and format the entire codebase\n- Standardized coding styles are setup with a few lines in a single config file\n\npysen centralizes the code and knowledge related to development tools that teams have accumulated, most notably for python linters.\nYou can make tasks that can be executed from both `setup.py` and our command-line tool.\nWe currently provide tasks that manage setting files for the following tools:\n\n- linters\n  - flake8\n  - isort\n  - mypy\n  - black\n- utilities\n  - (planned) protoc\n\n## What isn't pysen?\n\n* pysen is not a linting tool per se. Rather, `pysen run lint` orchestrates multiple python linting tools by automatically setting up their configurations from a more abstract setting for pysen.\n* pysen does not manage your depedencies and packages. We recommend using package managers such as [pipenv](https://github.com/pypa/pipenv) or [poetry](https://python-poetry.org/) to lock your dependecy versions, **including the versions for the linting tools that pysen coordinates** (i.e., isort, mypy, flake8, black). The supported versions for these tools can be found in the `extra_requires/lint` section in pysen's [setup.py](https://github.com/pfnet/pysen/blob/main/setup.py). You should **not** rely on `pip install pysen[lint]` to control the versions of your linting tools.\n* pysen is not limited to linting purposes or python. See the [plugin section](README.md#create-a-plugin-to-customize-pysen) for details.\n\n## How it works: Settings file directory\n\nUnder the hood, whenever you run pysen, it generates the setting files as ephemeral temporary files to be used by linters.\nYou may want to keep those setting files on your disk, e.g. when you want to use them for your editor.\nIf that is the case, run the following command to generate the setting files to your directory of choice:\n\n```sh\n$ pysen generate [out_dir]\n```\n\nYou can specify the settings directory that pysen uses when you `pysen run`.\nTo do so add the following section to your config:\n\n```toml\n[tool.pysen-cli]\nsettings_dir = \"path/to/generate/settings\"\n```\n\nWhen you specify a directory that already contains some configurations, pysen merges the contents. The resulting behavior may differ from when you don't specify `settings_dir`.\n\nAlso 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 specify `settings_dir` as arguments.\n\n## Tips: IDE / Text editor integration\n\n### vim\n\nYou can add errors that pysen reports to your quickfix window by:\n\n```\n:cex system(\"pysen run_files lint --error-format gnu \".expand('%:p'))\n```\n\nAnother way is to set pysen to `makeprg`:\n\n```\nset makeprg=pysen\\ run_files\\ --error-format\\ gnu\\ lint\\ %\n```\n\nThen running `:make` will populate your quickfix window with errors.\nThis also works with [`vim-dispatch`](https://github.com/tpope/vim-dispatch) as long as you invoke `:Make` instead of `:Dispatch` (for [this reason](https://github.com/tpope/vim-dispatch/issues/41#issuecomment-20555488))\n\nThe result will look like the following:\n\n![pysen-vim](https://github.com/pfnet/pysen/blob/main/assets/imgs/pysen_vim.gif?raw=true)\n\nA third party plugin is also available.\n- [pysen.vim](https://github.com/bonprosoft/pysen.vim)\n\n### Emacs\n\nRefer to the [Compilation mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-Mode.html).\nThe following is an example hook for python.\n```el\n(add-hook 'python-mode-hook\n    (lambda ()\n        (set (make-local-variable 'compile-command)\n            (concat \"pysen run_files lint --error-format gnu  \" buffer-file-name))))\n```\n\n### VSCode\n\nA [third party plugin](https://marketplace.visualstudio.com/items?itemName=bonprosoft.pysen-vscode) is available.\n\nNote that this may report duplicate errors if you have configured linters like `flake8` directly through your VSCode python extension.\n\n## Configure pysen\n\nWe provide two methods to write configuration for pysen.\n\nOne is the `[tool.pysen.lint]` section in the config.\nIt is the most simple way to configure pysen, but the settings we provide are limited.\n\nThe other method is to write a python script that configures pysen directly.\nIf 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.\nFor more examples, please refer to `pysen/examples`.\n\n### Configuration model\n\nPlease refer to `pysen/pyproject_model.py` for the latest model.\n\nHere is an example of a basic configuration:\n```toml\n[tool.pysen]\nversion = \"0.10\"\n\n[tool.pysen.lint]\nenable_black = true\nenable_flake8 = true\nenable_isort = true\nenable_mypy = true\nmypy_preset = \"strict\"\nline_length = 88\npy_version = \"py37\"\nisort_known_third_party = [\"numpy\"]\nisort_known_first_party = [\"pysen\"]\nmypy_ignore_packages = [\"pysen.generated.*\"]\nmypy_path = [\"stubs\"]\n[[tool.pysen.lint.mypy_targets]]\n  paths = [\".\", \"tests/\"]\n\n[tool.pysen.lint.source]\n  includes = [\".\"]\n  include_globs = [\"**/*.template\"]\n  excludes = [\"third_party/\"]\n  exclude_globs = [\"**/*_grpc.py\"]\n\n[tool.pysen.lint.mypy_modules.\"pysen.scripts\"]\n  preset = \"entry\"\n\n[tool.pysen.lint.mypy_modules.\"numpy\"]\n  ignore_errors = true\n```\n\npysen looks for a configuration file in the following order:\n1. `pysen.toml` with a `tool.pysen` section\n2. `pyproject.toml` with a `tool.pysen` section\n\n### Create a plugin to customize pysen\n\nWe provide a plugin interface for customizing our tool support, setting files management, setup commands and so on.\nFor more details, please refer to `pysen/examples/plugin_example`.\n\n## Development\n\n`pipenv` is required for managing our development environment.\n```sh\n# setup your environment\n$ pipenv sync\n# activate the environment\n$ pipenv shell\n```\n\n- Update depedencies in `Pipfile.lock`\n```sh\n$ pipenv lock --pre\n```\n- Run all tests\n```sh\n$ pipenv run tox\n```\n\n## mypy presets\n\nThe mypy preset `strict` aims to make life easier for developers using the following packages:\n\n* OpenCV\n* PyTorch\n* scikit-learn\n\nWe recommend developers mitigate some rules from the `very strict` preset to avoid some hassles.\nIf you use these packages with the `strict` preset and still have inconveniences, please let us know.\n\n## Contributing\n\nOur main priority is to fulfil the demands from projects within Preferred Networks.\nTherefore, we must assess whether each feature/pull request is in the best interest of our projects.\nIn principle, we are open to minor things like the following:\n\n* Issues that report bugs\n* Small PRs that fix typos or minor glitches\n\nAs for new features or major feature enhancements,\nthe core developers will determine whether the proposed idea is in line with the\ngoals and concepts of `pysen` for each case.\nWhen in doubt, don't hesitate to open an Issue first.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhimkt%2Fpysen-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhimkt%2Fpysen-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhimkt%2Fpysen-docs/lists"}