NI Python Style Guide

Welcome to NI's internal and external Python conventions and enforcement tooling.

Written Conventions

Our written conventions can be found at https://ni.github.io/python-styleguide/.

Their source is in docs/Coding-Conventions.md.

NOTE: Using the GitHub Pages link is preferable to a GitHub /blob link.

Enforcement tooling

As a tool, ni-python-styleguide is installed like any other script:

pip install ni-python-styleguide

The script name nps is a short-name for ni-python-styleguide, and may be used in place of ni-python-styleguide in any CLI command.

Linting

To lint, just run the lint subcommand (from within the project root, or lower):

ni-python-styleguide lint
# or
ni-python-styleguide lint ./dir/
# or
nps lint module.py

The rules enforced are all rules documented in the written convention, which are marked as enforced.

Configuration

ni-python-styleguide aims to keep the configuration to a bare minimum (none wherever possible). However there are some situations you might need to configure the tool.

Fix

ni-python-styleguide has a subcommand fix which will run black and isort to apply basic formatting fixes.

When using the --aggressive option with fix, it will first run black and isort to fix what it can then add acknowledgements (# noqa) for any remaining linting errors that cannot be automatically fixed.

When using setup.py

If you're using setup.py, you'll need to set your app's import names for import sorting.

# pyproject.toml
[tool.ni-python-styleguide]
application-import-names = "<app_name>"

Formatting

ni-python-styleguide has a subcommand format which will run black and isort with the correct settings to match the linting expectations.

If you wish to be able to invoke black directly, you'll want to set the following to get black formatting as the styleguide expects.

# pyproject.toml
[tool.black]
line-length = 100

Editor Integration

Vim/Neovim

1. Install the ALE plugin. This is a popular asynchronous lint engine for Vim and Neovim and already does most of the heavy lifting for us. It supports many different ways to lint and fix code. Check out the documentation (:help ale) for more information.
2. Because ni-python-styleguide is a wrapper around flake8, you can add the following vim configuration lines to wherever you configure your vim project (you can do it in your init.vim or vimrc file, but then it will apply to all Python code you edit):

let g:ale_python_flake8_executable = 'ni-python-styleguide'
let g:ale_python_flake8_options = 'lint'
let g:ale_linters = {'python': ['flake8']}
let g:ale_python_black_executable = 'ni-python-styleguide'
let g:ale_python_black_options = 'fix'
let g:ale_fixers = {'python': ['isort', 'black']}

Note: You can set all of these with b: as well.

3. You can make ALE auto-fix issues, e.g., when hitting F8, or when saving:

let g:ale_fix_on_save = 1 " Fix on save
nmap <F8> <Plug>(ale_fix) " Fix on F8

Change all of these to your taste.

VSCode

One can configure VSCode either in the User 'settings.json' file, or in a local .vscode/settings.json.

1. Install the Python extension by Microsoft

2. Because ni-python-styleguide is a wrapper around flake8, you can add the following configuration to make it uses ni-python-styleguide's rules.

   If using Poetry:

   "flake8.path": [
         "poetry",
         "run",
         "ni-python-styleguide",
         "lint"
      ],
   

   If ni-python-styleguide is directly installed

   "flake8.path": [
         "ni-python-styleguide",
         "lint"
      ],
   

   (alternatively, tell flake8 to use the ni-python-styleguide config - although this method does not evaluate what the module's application-import-names are)

   "flake8.args": [
        "--config=.venv\\lib\\site-packages\\ni_python_styleguide\\config.ini"
   ],
   

3. Telling the formatter to use ni-python-styleguide's settings

   (telling VS Code to use black and telling black to use ni-python-styleguide's settings file)

   "[python]": {
        "editor.formatOnType": true,
        "editor.defaultFormatter": "ms-python.black-formatter"
    },
   "black-formatter.args": [
      "--config=.venv\\lib\\site-packages\\ni_python_styleguide\\config.toml"
   ],