Configuring NeoVim as a Python IDE (2023)

Theme

For years I used solarized dark mode for both Vim and NeoVim. Right now I'm using catppuccin. I really want to give rose-pine a try too. I also load devicons here as its used by many plugins.

{ "catppuccin/nvim", lazy = true, name = "catppuccin", priority=1000 },
{ "nvim-tree/nvim-web-devicons", lazy = true },

Here is a look at the catppuccin theme

Snippets

Next are Snippets. I use LuaSnip

{ "L3MON4D3/LuaSnip", event = "VeryLazy",
  config = function()
    require("luasnip.loaders.from_lua").load({paths = "./snippets"})
  end
},

LuaSnip supports a few different formats: SnipMate, VSCode or pure Lua. I've gone with pure Lua snippets which I put in the ./snippets folder.

I mainly use snippets for writing this blog which is in RST format. Here is an example

And here is the Lua snippet that I configured for that (s means add snippet, t stands for text node, i is an insert node where the user can edit the template)

local link = s({
  trig = "link",
  name = "Link",
  dscr = "Web link"
}, {
  t({"`"}),
  i(1, "Title"),
  t(" <"),
  i(2, "link"),
  t(">`_"),
  i(0)
})

Language Server Protocol

Now comes the big one: Language Server Protocol (LSP). As I wrote in the previous post, the LSP server will analyse our code. NeoVim will communicate with the LSP server to get autocomplete suggestions and code diagnostics. I am using pyright for the LSP server. This open source LSP server is developed by Microsoft. A closed source derivative is used in VS Code.

{ "neovim/nvim-lspconfig",
  dependencies = {
    "williamboman/mason.nvim",
    "williamboman/mason-lspconfig.nvim"
  },
  config = function()
    local capabilities = vim.lsp.protocol.make_client_capabilities()
    capabilities = require('cmp_nvim_lsp').default_capabilities(capabilities)

    require('mason').setup()
    local mason_lspconfig = require 'mason-lspconfig'
    mason_lspconfig.setup {
        ensure_installed = { "pyright" }
    }
    require("lspconfig").pyright.setup {
        capabilities = capabilities,
    }
  end
},

This part is a little complicated.

First, we are installing Mason. Mason allows us to install / uninstall / manage all our LSP servers from within NeoVim. So we don't need to install pyright separately on the terminal. Next we install nvim-lspconfig and its Mason interface mason-lspconfig.

After that we load cmp_nvim_lsp. This is our autocomplete plugin (more about it in the next section). We ask it what capabilities it requires from the LSP server. Then we tell Mason to make sure pyright is installed, and it gets started with the required list of capabilities.

Once set up, you will get LSP diagnostics in NeoVim

Autocomplete

Well, if you thought the LSP configuration was complicated, wait till we get to autocompletion. I am using hrsh7th/ncim-cmp as the autocomplete plugin. This plugin can autocomplete from many different sources. I have it configured to autocomplete from LSP (via cmp-nvim-lsp) as well as LuaSnip snippets (via cmp_luasnip).

{ "hrsh7th/nvim-cmp",
  dependencies = {
    "hrsh7th/cmp-nvim-lsp",
    "L3MON4D3/LuaSnip",
    "saadparwaiz1/cmp_luasnip"
  },
  config = function()
    local has_words_before = function()
      unpack = unpack or table.unpack
      local line, col = unpack(vim.api.nvim_win_get_cursor(0))
      return col ~= 0 and vim.api.nvim_buf_get_lines(0, line - 1, line, true)[1]:sub(col, col):match("%s") == nil
    end

    local cmp = require('cmp')
    local luasnip = require('luasnip')

    cmp.setup({
      snippet = {
        expand = function(args)
          luasnip.lsp_expand(args.body)
        end
      },
      completion = {
        autocomplete = false
      },
      mapping = cmp.mapping.preset.insert ({
        ["<Tab>"] = cmp.mapping(function(fallback)
          if cmp.visible() then
            cmp.select_next_item()
          elseif luasnip.expand_or_jumpable() then
            luasnip.expand_or_jump()
          elseif has_words_before() then
            cmp.complete()
          else
            fallback()
          end
        end, { "i", "s" }),
        ["<s-Tab>"] = cmp.mapping(function(fallback)
          if cmp.visible() then
            cmp.select_prev_item()
          elseif luasnip.jumpable(-1) then
            luasnip.jump(-1)
          else
            fallback()
          end
        end, { "i", "s" }),
        ["<c-e>"] = cmp.mapping.abort(),
        ["<CR>"] = cmp.mapping.confirm({ select=true }),
      }),
      sources = {
        { name = "nvim_lsp" },
        { name = "luasnip" },
      }
    })
  end
},

Most of this configuration is setting up the keys for autocomplete. I use TAB to trigger autocompletion. Since TAB is also a normal key used for indentation and moving between sections of a LuaSnip snippet, we need to write some code so it triggers correctly. Essentially, if you press TAB immediately after any text, the plugin will pop up the autocomplete menu. If the menu is already open, then it will cycle through the items in the autocomplete menu. Otherwise it will fall back to the default behaviour. Same for Shift-TAB in reverse order.

This is what it looks like in action

Treesitter

We configure Treesitter next. Treesitter is a fast, incremental code parser. It can parse the code as we type and give the results to NeoVim. NeoVim mainly uses it for syntax highlighting, though there are a few other use cases as well. The syntax highlighting is superior to the usual regex based highlighting. Treesitter can differentiate between a local and global variable for example, even though both have the same regex.

I have treesitter configured for a bunch of languages.

{ "nvim-treesitter/nvim-treesitter", version = false,
  build = function()
    require("nvim-treesitter.install").update({ with_sync = true })
  end,
  config = function()
    require("nvim-treesitter.configs").setup({
      ensure_installed = { "c", "lua", "vim", "vimdoc", "query", "python", "javascript" },
      auto_install = false,
      highlight = { enable = true, additional_vim_regex_highlighting = false },
      incremental_selection = {
        enable = true,
        keymaps = {
          init_selection = "<C-n>",
          node_incremental = "<C-n>",
          scope_incremental = "<C-s>",
          node_decremental = "<C-m>",
        }
      }
    })
  end
},

In addition, I have enabled incremental selection on Treesitter. Pressing Ctrl-n will select the innermost syntactical piece of code based on the cursor location. Press Ctrl-n again and it expands the selection to the next scope in the parse tree. Take a look

Here the cursor starts on the return word. Had the cursor beein inside the list comprehension, then it would have selected the list comprehension first, then the whole line and so on. This is such a great feature.

Telescope

The last of the big configurations is Telescope. Telescope is a fuzzy finder that can search for different things. You can search for files in the current project, switch between open buffers, search text within all the files, symbols in the document -- almost anything really. Check the docs for a full list of capabilities.

The two most common that I use are <leader>sf to fuzzy search and open file in project, and <leader><space> to swap between buffers.

{ "nvim-telescope/telescope.nvim", cmd = "Telescope", version = false,
  dependencies = { "nvim-lua/plenary.nvim" },
  keys = {
    { "<leader>sf", "<cmd>Telescope git_files<cr>", desc = "Find Files (root dir)" },
    { "<leader><space>", "<cmd>Telescope buffers<cr>", desc = "Find Buffers" },
    { "<leader>sg", "<cmd>Telescope live_grep<cr>", desc = "Search Project" },
    { "<leader>ss", "<cmd>Telescope lsp_document_symbols<cr>", desc = "Search Document Symbols" },
    { "<leader>sw", "<cmd>Telescope lsp_dynamic_workspace_symbols<cr>", desc = "Search Workspace Symbols" },
  },
  opts = {
    extensions = {
      fzf = {
        fuzzy = true,
        override_generic_sorter = true,
        override_file_sorter = true,
        case_mode = "smart_case"
      }
    }
  }
},
{ "nvim-telescope/telescope-fzf-native.nvim",
  build = "make",
  config = function()
    require('telescope').load_extension('fzf')
  end
},

Here is a screenshot using Telescope to fuzzy find a file in the project

Linting & Formatting

I use the null-ls to lint and reformat the file everytime I save it. I use ruff as the linter and Black for formatting Python code.

null-ls supports both, as well as many others.

{ "jose-elias-alvarez/null-ls.nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  config = function()
    local null_ls = require("null-ls")

    null_ls.setup({
      sources = {
        null_ls.builtins.diagnostics.ruff,
        null_ls.builtins.formatting.black,
      }
    })
  end
},

Terminal

Nothing much to say about this really. toggleterm.nvim will open the terminal when I press Ctrl-s. Most of the interesting terminal configuration happened earlier in the config. toggleterm is nice because it allows you to have multiple terminals open. Show / hide them all or show / hide a single one. Useful when you want to run a server on one terminal, hide it and open another terminal for running commands.

An interesting feature is you can select some code and send it to run on a terminal. So if you have a Python REPL session open in a terminal, you can select code in the buffer and have it run in the REPL.

{ "akinsho/toggleterm.nvim", event = "VeryLazy", version = "*",
  opts = {
    size = 10,
    open_mapping = "<c-s>",
  }
},

Other Editor Plugins

The rest of the file is standard editor configuration plugins. My configuration is

• lualine for the status line
• bufferline to display a list of open buffers
• mini.pairs for auto-closing quotes, brackets, etc
• mini.surround to surround text with a character, or remove/replace a surrounding
• indent-blankline to show indentation guides (super useful for Python coding)

One nice thing about bufferline is that it allows us to pin buffers, and close all unpinned buffers. Often I find myself working on one or two files, but I temporarily need to open many other files. You can pin the buffers you are working on and just close everything else when you are done.

You can also hook it up to LSP diagnostics, so it will show an icon if the file has any warnings or errors.