🎯 The Problem

Every Python developer faces this:

import pandas as pd

df = pd.read_csv('data.csv')
result = df.groupby('category').agg(???)  # What parameters does agg() take?

Your choices:

• ❌ Stop coding, open browser, search "pandas agg", lose focus
• ❌ Try to remember from memory (hint: you won't)
• ❌ Spend 30 seconds guessing with autocomplete
• ✅ Hover over agg() in Python Hover — documentation appears instantly

Context matters. You're not hovering over a generic function—you're hovering over a specific method on a Pandas DataFrame. Python Hover understands that and shows you exactly what you need.

✨ The Solution: Python Hover

A documentation engine that works like your brain. Intelligent, contextual, offline-first.

✨ What Makes Python Hover Special

🎯 Universal Python Support

• 300+ Built-in Constructs — Complete coverage of Python's standard library
• 19+ Pre-Configured Libraries — NumPy, Pandas, FastAPI, Django, PyTorch, Flask, Matplotlib, and more
• 🚀 Auto-Discovery for ANY Library — Works with scikit-learn, TensorFlow, requests, beautifulsoup4, and thousands more!
• Smart Context Detection — Automatically determines if you're working with strings, lists, dicts, DataFrames, or custom objects
• Dynamic Type Resolution — Intelligently identifies which library a class belongs to without hardcoding

💡 Instant Access to Information

• Practical, Copyable Examples — Real code you can use immediately
• Rich Sphinx Documentation — Beautiful formatting with parameters, return types, and examples
• Offline Support — Aggressive caching for blazing-fast offline access
• Zero Configuration — Works instantly after installation

🎨 Beautiful & Customizable

• Clean, Modern Interface — Easy to read, aesthetically pleasing
• Fully Themeable — Customize colors, fonts, and styles to match your setup
• Version-Aware — Shows the exact documentation for your installed library versions

� Quick Start

Installation

1. Install from Marketplace Open VS Code → Extensions (Ctrl+Shift+X) → Search "Python Hover" → Install

   Or click here to install

2. Open any Python file

3. Hover over any code — That's it! 🎉

No configuration, no setup, no hassle. It just works.

📚 Coverage

Built-in Python

Pre-Configured Libraries

🔍 Auto-Discovery Magic

Python Hover automatically discovers documentation for ANY library with Sphinx/ReadTheDocs documentation:

import plotly  # Auto-discovered!
import dask    # Auto-discovered!
import spacy   # Auto-discovered!
import httpx   # Auto-discovered!

# Hover over any of their methods — instant documentation!

How it works:

1. Detects your imports automatically
2. Checks PyPI for documentation URLs
3. Fetches Sphinx inventory files
4. Caches everything for offline use
5. Shows rich documentation on hover

No configuration needed — it's completely automatic! 🪄

🎯 Key Features

🧠 Smart Context Detection

Python Hover understands your code context:

import pandas as pd

df = pd.DataFrame({'A': [1, 2, 3]})
df.head()  # Shows DataFrame.head() documentation, NOT generic object

result = "hello world"
result.upper()  # Shows str.upper() documentation

my_list = [1, 2, 3]
my_list.append(4)  # Shows list.append() documentation

Before v0.5.1: Might show "object.head()" Now: Correctly shows "DataFrame.head()" with full pandas documentation! ✨

🎨 Rich Documentation Display

• 📦 Summary boxes with clear descriptions
• 📝 Parameter details with type annotations
• ↩️ Return types clearly highlighted
• ⚠️ Exceptions that might be raised
• 📊 Examples with expected outputs
• 🏷️ Version info (added/changed/deprecated)
• 🔗 Links to full documentation

⚡ Performance

• < 10ms for cached lookups
• < 100ms for first-time fetches
• Offline-first architecture
• Intelligent caching (24 hours for libraries)
• Early exit optimization in dynamic resolution

🛠️ Developer Experience

• Zero configuration — works immediately
• No API keys required
• No external dependencies — everything bundled
• Works offline after initial cache
• Lightweight — minimal impact on VS Code performance
• Highly customizable — extensive settings for power users

🎨 Customization

Settings

Access settings via: Preferences > Settings > Extensions > Python Hover

{
  // Display settings
  "python-hover.fontSize": 14,
  "python-hover.fontFamily": "Consolas, 'Courier New', monospace",
  "python-hover.maxSnippetLines": 20,

  // Feature toggles
  "python-hover.enableExamples": true,
  "python-hover.enableVersionInfo": true,
  "python-hover.enableLinks": true,

  // Library configuration
  "python-hover.customLibraries": {
    "mylib": {
      "inventoryUrl": "https://mylib.readthedocs.io/en/latest/objects.inv",
      "docBaseUrl": "https://mylib.readthedocs.io/en/latest"
    }
  }
}

Custom Libraries

Add your own libraries with Sphinx documentation:

1. Find your library's objects.inv URL (usually on ReadTheDocs)
2. Add to settings:

{
  "python-hover.customLibraries": {
    "your-library": {
      "inventoryUrl": "https://your-library.readthedocs.io/en/stable/objects.inv",
      "docBaseUrl": "https://your-library.readthedocs.io/en/stable"
    }
  }
}

3. Done! Hover over your library's code to see documentation.

📖 Full custom library guide

💼 Perfect For

🆕 Python Beginners

Learn by example with comprehensive, easy-to-understand documentation right where you code.

👨‍💻 Professional Developers

Save time by eliminating constant tab-switching to documentation websites.

👨‍🏫 Educators & Students

Teach and learn Python with instant access to documentation and examples.

🔬 Data Scientists

Quick reference for NumPy, Pandas, scikit-learn, and other data science libraries.

🌐 Web Developers

Instant docs for Django, Flask, FastAPI, and all web development tools.

🤖 ML Engineers

Rapid access to PyTorch, TensorFlow, and machine learning library documentation.

🔥 What's New in v0.5.1

� Dynamic Library Resolution

• Works with ANY library automatically — no more hardcoded mappings!
• Intelligently determines which library a class belongs to
• Scales infinitely with your project's dependencies
• Handles pandas, numpy, sklearn, tensorflow, and custom libraries seamlessly

�️ Robust Error Handling

• Gracefully handles libraries with missing or invalid documentation
• No more crashes from malformed inventory files
• Silently skips problematic libraries and continues working
• Better logging for troubleshooting

� Enhanced Context Detection

• Fixed "object.method" issue — now shows correct qualified names
• Better type detection from code assignments
• Improved handling of inline comments
• More accurate method-to-type resolution

✨ Visual Improvements

• Enhanced Sphinx documentation parsing
• Better formatting for parameters and return types
• Version metadata display (added/changed/deprecated)
• Cleaner, more readable hover content

See full changelog

🤝 Contributing

Contributions are welcome! Whether it's bug reports, feature requests, or code contributions.

• Found a bug? Open an issue
• Have an idea? Start a discussion
• Want to contribute code? Read the contributing guide

📝 Troubleshooting

Hover not showing?

1. Ensure Python extension is installed — Python Hover requires the official Python extension
2. Check file is saved — Hover works best on saved files
3. Verify Python environment — Make sure a Python interpreter is selected

Library documentation not appearing?

1. Check library is imported — Python Hover detects imported libraries
2. Try reloading VS Code — Ctrl+Shift+P → "Developer: Reload Window"
3. Check Output panel — View → Output → Select "Python Hover" for debug logs
4. Ensure library has Sphinx docs — Most popular libraries do

Custom library not working?

1. Verify inventory URL — Try opening the URL in a browser
2. Check JSON syntax — Ensure settings JSON is valid
3. See custom library guide — Detailed instructions here

Still having issues? Open an issue with:

• VS Code version
• Python version
• Extension version
• Output panel logs

📊 Stats

• 🐍 300+ Python constructs covered
• 📚 19+ pre-configured libraries
• 🔍 1000s of libraries via auto-discovery
• ⚡ < 10ms cached lookup time
• 📦 1.07 MB bundle size
• ⭐ Loved by thousands of developers

� License

MIT License - see LICENSE file for details.

🌟 Show Your Support

If Python Hover saves you time and makes you more productive:

1. ⭐ Star the repository on GitHub
2. ⭐ Rate it 5-stars on the marketplace
3. ☕ Buy me a coffee to support development
4. � Share it with your team and the Python community!

Every bit of support helps keep this extension free and actively maintained! ❤️

🧪 Testing

Run fast unit tests (no VS Code needed):

npm run test:unit

Watch mode for rapid iteration:

npm run test:unit:watch

Full integration tests (spins up VS Code test host):

npm test

Notes:

• Unit tests stub the VS Code API and run in Node for speed.
• Integration tests validate activation, hover performance, and inventory resolution end-to-end.

Snapshot hover tests (real content)

Want to see the exact Markdown users see in the hover? Run the snapshot suite to generate reviewable artifacts:

npm run test:snapshots

What this does:

• Spins up the full VS Code test host and forces the real hover pipeline (no test shortcuts)
• Captures the actual Markdown from dozens of representative hovers
• Writes files to artifacts/hover-snapshots/*.md for hands-on review

Tips:

• Open a few files like artifacts/hover-snapshots/builtin-range.md or artifacts/hover-snapshots/keyword-for.md to inspect content
• Add new cases in src/test/suite/hoverSnapshots.test.ts to expand coverage
• Snapshot mode skips strict perf checks to keep runs stable and focused on content