Skip to content

README.md

Latest commit

 

History

History
138 lines (102 loc) · 4.63 KB

README.md

File metadata and controls

138 lines (102 loc) · 4.63 KB

Python Module Completion for Zsh

A zsh plugin that provides intelligent tab completion for python -m commands with hierarchical module navigation and smart project detection.

asciicast

Features

  • Immediate Completion: Works with both python -m<TAB> and python -m <TAB>
  • Hierarchical Navigation: Navigate through nested modules with tab completion (e.g., my_package.submodule.deeper)
  • Smart Project Detection: Automatically detects Python projects via virtual environments, __init__.py files, and project configuration files
  • Cross-Platform: Works on Linux, macOS, and other Unix-like systems
  • Intelligent Filtering: Excludes virtual environments and build directories from completion
  • Smart Suffix Handling: Modules with submodules complete without space, final modules complete with space

Installation

Manual Installation

  1. Clone this repository:

    git clone https://github.com/UshioA/zsh-python-module-completion.git ~/.zsh/zsh-python-module-completion

  2. Add to your .zshrc:

    source ~/.zsh/zsh-python-module-completion/python-module-completion/python-module-completion.plugin.zsh

  3. Restart your shell or run exec zsh

Oh My Zsh

  1. Clone into Oh My Zsh custom plugins directory:

    git clone https://github.com/UshioA/zsh-python-module-completion.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-python-module-completion

  2. Add to your plugins in .zshrc:

    plugins=(... zsh-python-module-completion)

  3. Restart your shell

Zinit

Add to your .zshrc:

zinit light UshioA/zsh-python-module-completion

Antigen

Add to your .zshrc:

antigen bundle UshioA/zsh-python-module-completion

Zplug

Add to your .zshrc:

zplug "UshioA/zsh-python-module-completion"

Usage

In any Python project, use tab completion with python -m:

# Basic completion (both work)
python -m<TAB>           # Shows available top-level modules  
python -m <TAB>          # Shows available top-level modules

# Hierarchical navigation  
python -m mypackage<TAB>       # Completes to mypackage (no space if has submodules)
python -m mypackage.<TAB>      # Shows submodules in mypackage
python -m mypackage.sub<TAB>   # Completes to mypackage.sub
python -m mypackage.sub.<TAB>  # Shows modules in sub

Example

For a project structure like:

my_project/
├── my_module/
│   ├── __init__.py
│   ├── sub_module/
│   │   ├── __init__.py
│   │   └── deep_module.py
│   └── utils.py
└── setup.py

Tab completion works as:

  1. python -m <TAB> -> my_module
  2. python -m my_module<TAB> -> my_module (no space, has submodules)
  3. python -m my_module.<TAB> -> sub_module, utils
  4. python -m my_module.sub_module.<TAB> -> deep_module

Activation

Important: This plugin only activates when you create a .local_module_completion file in your Python project root. This ensures that zsh's default Python completion (including all command-line options and module completion) continues to work normally in directories without this marker file.

To enable local module completion for a project:

# In your project root directory
touch .local_module_completion

Completion Behavior

Without .local_module_completion file:

  • The plugin completely defers to zsh's built-in Python completion
  • python -<TAB> -> Shows all Python options (-c, -m, -V, etc.)
  • python -m <TAB> -> Shows installed packages from your Python environment
  • python <TAB> -> Shows Python files in current directory
  • All other completions work as normal

With .local_module_completion file:

  • python -<TAB> -> Shows all Python options (same as default)
  • python -m <TAB> -> Shows local project modules (custom behavior)
  • python <TAB> -> Shows files in current directory (same as default)
  • python -c <TAB> -> File completion (same as default)
  • python -m some.module.name <TAB> -> Show files in current directory (same as default)
  • All other completions fall back to default behavior

The plugin only customizes the module completion after -m when the marker file is present. All other completion scenarios use zsh's default Python completion.

Project Detection

When the .local_module_completion file is present, the plugin detects Python projects by looking for:

  • Virtual environments (venv, .venv, env, .env)
  • Python project files (pyproject.toml, setup.py, requirements.txt, Pipfile, poetry.lock)
  • Package directories (containing __init__.py)