👨‍💻 Exposed Functions

The venv-selector plugin exposes several Lua functions that you can use in your own configurations, keymaps, or other plugins. These functions provide programmatic access to the plugin's functionality.

📊 Information Functions

These functions return information about the current state without making changes.

🐍 require("venv-selector").python()

Returns the absolute path to the currently selected Python interpreter, or nil if no virtual environment is selected.

Return Type: string | nil

local python_path = require("venv-selector").python()
if python_path then
    print("Current Python: " .. python_path)
    -- Example: /home/user/.virtualenvs/myproject/bin/python
else
    print("No virtual environment selected")
end

Use Cases

• Checking if a venv is active before running Python commands
• Displaying current Python version in statusline
• Conditional logic based on Python interpreter availability

📁 require("venv-selector").venv()

Returns the absolute path to the root directory of the currently selected virtual environment, or nil if none is selected.

Return Type: string | nil

local venv_path = require("venv-selector").venv()
if venv_path then
    print("Current venv: " .. venv_path)
    -- Example: /home/user/.virtualenvs/myproject
else
    print("No virtual environment selected")
end

Difference from python()

While python() returns the path to the Python executable, venv() returns the root directory of the virtual environment itself.

🔍 require("venv-selector").source()

Returns the name of the search function that found the currently selected virtual environment.

Return Type: string | nil

local source = require("venv-selector").source()
if source then
    print("Found venv using: " .. source)
    -- Examples: "poetry", "conda", "venv", "pyenv"
end

Debugging

This is particularly useful for debugging why a specific virtual environment was selected, especially when you have multiple search functions configured.

🏢 require("venv-selector").workspace_paths()

Returns the workspace paths that your LSP is currently using.

Return Type: table

local paths = require("venv-selector").workspace_paths()
for i, path in ipairs(paths) do
    print("Workspace " .. i .. ": " .. path)
end

📂 require("venv-selector").cwd()

Returns the current working directory.

Return Type: string

local current_dir = require("venv-selector").cwd()
print("Working directory: " .. current_dir)

📄 require("venv-selector").file_dir()

Returns the directory of the currently opened file.

Return Type: string | nil

local file_directory = require("venv-selector").file_dir()
if file_directory then
    print("File directory: " .. file_directory)
else
    print("No file currently open")
end

⚡ Control Functions

These functions perform actions and modify the plugin's state.

❌ require("venv-selector").deactivate()

Deactivates the current virtual environment by removing it from the terminal PATH and unsetting environment variables.

Return Type: nil

-- Deactivate current virtual environment
require("venv-selector").deactivate()
print("Virtual environment deactivated")

Important

This only affects new terminal sessions. Existing terminals will retain their environment until restarted.

🛑 require("venv-selector").stop_lsp_servers()

Stops the LSP servers that are managed by the venv-selector plugin.

Return Type: nil

-- Stop LSP servers before switching environments
require("venv-selector").stop_lsp_servers()

When to Use

This is typically called internally when switching virtual environments, but you might need it for custom workflows or troubleshooting.

🎯 require("venv-selector").activate_from_path(python_path)

Activates a virtual environment using the provided Python interpreter path.

Parameters:

• python_path (string): Absolute path to a Python interpreter

Return Type: nil

-- Activate a specific virtual environment
local python_path = "/home/user/.virtualenvs/myproject/bin/python"
require("venv-selector").activate_from_path(python_path)

Use Cases

• Programmatically switching to a known virtual environment
• Integration with external tools or scripts
• Custom virtual environment selection logic

🛠️ Practical Examples

Custom Statusline Integration

Lualine

-- Add to your lualine configuration
require('lualine').setup({
  sections = {
    lualine_x = {
      function()
        local venv = require("venv-selector").venv()
        if venv then
          return "🐍 " .. vim.fn.fnamemodify(venv, ":t")
        end
        return ""
      end
    }
  }
})

Custom Function

-- Custom function to display Python info
function get_python_info()
  local python = require("venv-selector").python()
  local source = require("venv-selector").source()
  
  if python and source then
    local venv_name = vim.fn.fnamemodify(require("venv-selector").venv(), ":t")
    return string.format("🐍 %s (%s)", venv_name, source)
  end
  return "🐍 No venv"
end

Custom Keymaps with Function Integration

-- Create custom keymaps using exposed functions
vim.keymap.set("n", "<leader>vp", function()
  local python = require("venv-selector").python()
  if python then
    print("Current Python: " .. python)
  else
    print("No virtual environment selected")
    vim.cmd("VenvSelect")
  end
end, { desc = "Show current Python or select venv" })

vim.keymap.set("n", "<leader>vd", function()
  require("venv-selector").deactivate()
  print("Virtual environment deactivated")
end, { desc = "Deactivate virtual environment" })

Conditional Plugin Loading

-- Only load certain plugins if a Python venv is active
local function setup_python_tools()
  local python = require("venv-selector").python()
  if python then
    -- Setup Python-specific tools
    require("dap-python").setup(python)
    print("Python tools configured for: " .. python)
  end
end

-- Call after venv selection
vim.api.nvim_create_autocmd("User", {
  pattern = "VenvSelectSetup",
  callback = setup_python_tools,
})

Integration with Terminal Commands

-- Run Python commands with the selected interpreter
function run_python_file()
  local python = require("venv-selector").python()
  local file = vim.fn.expand("%:p")
  
  if python and vim.fn.filereadable(file) == 1 then
    vim.cmd("split | terminal " .. python .. " " .. file)
  else
    print("No Python interpreter selected or file not found")
  end
end

vim.keymap.set("n", "<leader>rp", run_python_file, { desc = "Run Python file" })

📋 Function Reference Summary

Function	Returns	Purpose
python()	string | nil	Current Python interpreter path
venv()	string | nil	Current virtual environment root path
source()	string | nil	Name of search function that found the venv
workspace_paths()	table	LSP workspace paths
cwd()	string	Current working directory
file_dir()	string | nil	Directory of current file
deactivate()	nil	Deactivate current virtual environment
stop_lsp_servers()	nil	Stop plugin-managed LSP servers
activate_from_path(path)	nil	Activate venv from Python path

Pro Tips

• Always check for nil return values before using paths
• These functions are perfect for creating custom workflows
• Use them in autocommands to react to virtual environment changes
• Combine multiple functions for rich status displays