revamping documentation
This commit is contained in:
@@ -1 +1,398 @@
|
||||
*This documentation is under development.*
|
||||
# PyCharm Troubleshooting Guide
|
||||
|
||||
Common PyCharm issues and their solutions for the development team.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Go to Declaration Not Working (Ctrl+B)](#go-to-declaration-not-working-ctrlb)
|
||||
- [Import Errors and Red Underlines](#import-errors-and-red-underlines)
|
||||
- [Python Interpreter Issues](#python-interpreter-issues)
|
||||
- [Debugging Not Working](#debugging-not-working)
|
||||
- [Performance Issues](#performance-issues)
|
||||
- [Git Integration Issues](#git-integration-issues)
|
||||
- [Database Tool Issues](#database-tool-issues)
|
||||
|
||||
---
|
||||
|
||||
## Go to Declaration Not Working (Ctrl+B)
|
||||
|
||||
### Problem
|
||||
|
||||
When you press **Ctrl+B** (or Cmd+B on Mac) on a function, class, or variable, PyCharm shows:
|
||||
- "Cannot find declaration to go to"
|
||||
- No navigation occurs
|
||||
- Imports are marked as unresolved even though code runs fine
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
from app.services.admin_audit_service import admin_audit_service
|
||||
|
||||
# Ctrl+B on get_audit_logs doesn't work
|
||||
logs = admin_audit_service.get_audit_logs(db, filters)
|
||||
```
|
||||
|
||||
### Solution 1: Configure Source Roots (Most Common Fix)
|
||||
|
||||
PyCharm needs to know your project structure:
|
||||
|
||||
1. **Mark project root as Sources Root:**
|
||||
- Right-click on project root folder (`letzshop-product-import`)
|
||||
- Select **"Mark Directory as"** → **"Sources Root"**
|
||||
- The folder icon should turn blue
|
||||
|
||||
2. **Via Project Structure settings:**
|
||||
- **File** → **Settings** (Ctrl+Alt+S)
|
||||
- Navigate to **Project: letzshop-product-import** → **Project Structure**
|
||||
- Select your project root directory
|
||||
- Click the **"Sources"** button at the top
|
||||
- Click **Apply** → **OK**
|
||||
|
||||
3. **Verify the change:**
|
||||
- Your project root should now have a blue folder icon
|
||||
- The `.idea` folder should show the source root is configured
|
||||
|
||||
### Solution 2: Verify Python Interpreter
|
||||
|
||||
Ensure PyCharm is using the correct virtual environment:
|
||||
|
||||
1. **Check current interpreter:**
|
||||
- **File** → **Settings** → **Project** → **Python Interpreter**
|
||||
- Should show: `/home/samir/PycharmProjects/letzshop-product-import/.venv/bin/python`
|
||||
|
||||
2. **If wrong interpreter:**
|
||||
- Click the gear icon → **Add**
|
||||
- Select **"Existing environment"**
|
||||
- Navigate to: `[PROJECT_ROOT]/.venv/bin/python`
|
||||
- Click **OK**
|
||||
|
||||
3. **Wait for indexing:**
|
||||
- Bottom right corner will show "Indexing..."
|
||||
- Wait for it to complete before testing
|
||||
|
||||
### Solution 3: Invalidate Caches
|
||||
|
||||
PyCharm's index might be corrupted:
|
||||
|
||||
1. **File** → **Invalidate Caches...**
|
||||
2. Select all checkboxes:
|
||||
- ✅ Invalidate and Restart
|
||||
- ✅ Clear file system cache and Local History
|
||||
- ✅ Clear downloaded shared indexes
|
||||
3. Click **"Invalidate and Restart"**
|
||||
4. **Wait 2-5 minutes** for re-indexing after restart
|
||||
|
||||
### Solution 4: Reimport Project
|
||||
|
||||
If nothing else works, rebuild the project structure:
|
||||
|
||||
1. **Close PyCharm**
|
||||
2. **Delete PyCharm's cache folder:**
|
||||
```bash
|
||||
rm -rf .idea/
|
||||
```
|
||||
3. **Reopen project in PyCharm:**
|
||||
- **File** → **Open**
|
||||
- Select project folder
|
||||
- Let PyCharm recreate `.idea/` folder
|
||||
4. **Reconfigure:**
|
||||
- Set Python interpreter
|
||||
- Mark source roots
|
||||
- Wait for indexing
|
||||
|
||||
### Solution 5: Check .idea/workspace.xml
|
||||
|
||||
Sometimes workspace configuration gets corrupted:
|
||||
|
||||
```bash
|
||||
# Close PyCharm first
|
||||
rm .idea/workspace.xml
|
||||
# Reopen PyCharm - it will regenerate this file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Import Errors and Red Underlines
|
||||
|
||||
### Problem
|
||||
|
||||
Imports show red underlines and errors like:
|
||||
- "Unresolved reference"
|
||||
- "No module named 'app'"
|
||||
- Code runs fine but PyCharm shows errors
|
||||
|
||||
### Solution
|
||||
|
||||
1. **Check Sources Root** (see above)
|
||||
|
||||
2. **Verify `__init__.py` files exist:**
|
||||
```bash
|
||||
# All package directories need __init__.py
|
||||
ls -la app/__init__.py
|
||||
ls -la app/services/__init__.py
|
||||
ls -la app/api/__init__.py
|
||||
```
|
||||
|
||||
3. **Add project root to PYTHONPATH:**
|
||||
- **File** → **Settings** → **Project** → **Project Structure**
|
||||
- Right-click project root → **"Mark as Sources Root"**
|
||||
|
||||
4. **Enable namespace packages** (if using PEP 420):
|
||||
- **File** → **Settings** → **Editor** → **Code Style** → **Python**
|
||||
- Check "Support namespace packages"
|
||||
|
||||
---
|
||||
|
||||
## Python Interpreter Issues
|
||||
|
||||
### Problem
|
||||
|
||||
- "No Python interpreter configured"
|
||||
- Wrong Python version
|
||||
- Missing packages even though they're installed
|
||||
|
||||
### Solution
|
||||
|
||||
1. **Verify virtual environment:**
|
||||
```bash
|
||||
# In terminal
|
||||
which python # Should show .venv/bin/python
|
||||
python --version # Should show Python 3.13.x
|
||||
```
|
||||
|
||||
2. **Configure in PyCharm:**
|
||||
- **File** → **Settings** → **Project** → **Python Interpreter**
|
||||
- Click gear icon → **Add**
|
||||
- Select **"Existing Environment"**
|
||||
- Choose: `[PROJECT_ROOT]/.venv/bin/python`
|
||||
|
||||
3. **Refresh interpreter packages:**
|
||||
- In Python Interpreter settings
|
||||
- Click refresh icon (⟳)
|
||||
- Wait for packages to reload
|
||||
|
||||
4. **Reinstall packages if needed:**
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-dev.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Debugging Not Working
|
||||
|
||||
### Problem
|
||||
|
||||
- Breakpoints are grayed out
|
||||
- Debugger doesn't stop at breakpoints
|
||||
- "Debugger is not attached"
|
||||
|
||||
### Solution 1: Check Run Configuration
|
||||
|
||||
1. **Edit configuration:**
|
||||
- Top right → Edit Configurations
|
||||
- Should use "Python" configuration type
|
||||
- Script path should point to your main file
|
||||
- Interpreter should be your virtual environment
|
||||
|
||||
2. **For FastAPI/Uvicorn:**
|
||||
- Module: `uvicorn`
|
||||
- Parameters: `main:app --reload`
|
||||
- Working directory: Project root
|
||||
|
||||
### Solution 2: Enable Gevent/Asyncio Support
|
||||
|
||||
For async code (FastAPI):
|
||||
|
||||
1. **File** → **Settings** → **Build, Execution, Deployment** → **Python Debugger**
|
||||
2. Check **"Gevent compatible"** or **"Asyncio compatible"**
|
||||
3. Restart debugger
|
||||
|
||||
### Solution 3: Check Breakpoint Settings
|
||||
|
||||
Right-click on breakpoint (red dot):
|
||||
- Ensure "Enabled" is checked
|
||||
- Check "Suspend" is set to "All"
|
||||
- Remove any conditions if not needed
|
||||
|
||||
---
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Problem
|
||||
|
||||
- PyCharm is slow or freezing
|
||||
- High CPU/memory usage
|
||||
- Indexing takes forever
|
||||
|
||||
### Solution 1: Exclude Unnecessary Directories
|
||||
|
||||
Exclude directories PyCharm doesn't need to index:
|
||||
|
||||
1. **File** → **Settings** → **Project** → **Project Structure**
|
||||
2. **Mark as "Excluded":**
|
||||
- `.venv` (if not already)
|
||||
- `node_modules`
|
||||
- `.pytest_cache`
|
||||
- `__pycache__`
|
||||
- `htmlcov`
|
||||
- `site` (mkdocs build output)
|
||||
|
||||
3. **Right-click these folders in Project view:**
|
||||
- **Mark Directory as** → **Excluded**
|
||||
|
||||
### Solution 2: Increase Memory
|
||||
|
||||
1. **Help** → **Change Memory Settings**
|
||||
2. Increase heap size to **2048 MB** or higher
|
||||
3. Restart PyCharm
|
||||
|
||||
### Solution 3: Disable Unused Plugins
|
||||
|
||||
1. **File** → **Settings** → **Plugins**
|
||||
2. Disable plugins you don't use
|
||||
3. Keep essential: Python, Git, Database, Markdown
|
||||
4. Restart PyCharm
|
||||
|
||||
### Solution 4: Pause Indexing
|
||||
|
||||
If you need to work immediately:
|
||||
|
||||
1. **File** → **Pause Indexing**
|
||||
2. Do your work
|
||||
3. **Resume Indexing** when convenient
|
||||
|
||||
---
|
||||
|
||||
## Git Integration Issues
|
||||
|
||||
### Problem
|
||||
|
||||
- Git operations fail
|
||||
- "Cannot run git" errors
|
||||
- Changes not detected
|
||||
|
||||
### Solution 1: Configure Git Executable
|
||||
|
||||
1. **File** → **Settings** → **Version Control** → **Git**
|
||||
2. **Path to Git executable:**
|
||||
- Linux/Mac: `/usr/bin/git`
|
||||
- Windows: `C:\Program Files\Git\bin\git.exe`
|
||||
3. Click **"Test"** to verify
|
||||
4. Click **OK**
|
||||
|
||||
### Solution 2: Check Git Root
|
||||
|
||||
1. **File** → **Settings** → **Version Control**
|
||||
2. Verify your project root is listed
|
||||
3. If missing, click **+** and add it
|
||||
|
||||
### Solution 3: Refresh VCS
|
||||
|
||||
1. **VCS** → **Refresh File Status**
|
||||
2. Or: **Git** → **Refresh**
|
||||
3. Or press: **Ctrl+F5**
|
||||
|
||||
---
|
||||
|
||||
## Database Tool Issues
|
||||
|
||||
### Problem
|
||||
|
||||
- Can't connect to PostgreSQL database
|
||||
- "Connection refused" errors
|
||||
- Tables not showing
|
||||
|
||||
### Solution 1: Verify Database Connection
|
||||
|
||||
1. **Database** tool window (usually right side)
|
||||
2. Click **+** → **Data Source** → **PostgreSQL**
|
||||
3. **Configure:**
|
||||
```
|
||||
Host: localhost
|
||||
Port: 5432
|
||||
Database: letzshop_db
|
||||
User: [from .env file]
|
||||
Password: [from .env file]
|
||||
```
|
||||
4. Click **"Test Connection"**
|
||||
5. Download drivers if prompted
|
||||
|
||||
### Solution 2: Check Database is Running
|
||||
|
||||
```bash
|
||||
# Check if PostgreSQL is running
|
||||
sudo systemctl status postgresql
|
||||
|
||||
# Start if not running
|
||||
sudo systemctl start postgresql
|
||||
```
|
||||
|
||||
### Solution 3: Verify .env Configuration
|
||||
|
||||
```bash
|
||||
# Check your .env file
|
||||
cat .env | grep DATABASE
|
||||
|
||||
# Should show something like:
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/letzshop_db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Checklist for New Developers
|
||||
|
||||
When setting up PyCharm for the first time:
|
||||
|
||||
- [ ] Clone repository
|
||||
- [ ] Create virtual environment: `python -m venv .venv`
|
||||
- [ ] Activate: `source .venv/bin/activate`
|
||||
- [ ] Install dependencies: `pip install -r requirements.txt`
|
||||
- [ ] Open project in PyCharm
|
||||
- [ ] Configure Python interpreter (`.venv/bin/python`)
|
||||
- [ ] Mark project root as Sources Root
|
||||
- [ ] Exclude `.venv`, `.pytest_cache`, `__pycache__` directories
|
||||
- [ ] Configure Git executable
|
||||
- [ ] Configure database connection
|
||||
- [ ] Wait for indexing to complete
|
||||
- [ ] Test: Ctrl+B on an import should work
|
||||
|
||||
---
|
||||
|
||||
## Still Having Issues?
|
||||
|
||||
### Check PyCharm Logs
|
||||
|
||||
1. **Help** → **Show Log in Explorer/Finder**
|
||||
2. Look for errors in `idea.log`
|
||||
3. Search for "ERROR" or "Exception"
|
||||
|
||||
### Enable Debug Logging
|
||||
|
||||
1. **Help** → **Diagnostic Tools** → **Debug Log Settings**
|
||||
2. Add: `#com.intellij.python`
|
||||
3. Reproduce the issue
|
||||
4. Check logs
|
||||
|
||||
### Report to Team
|
||||
|
||||
If the issue persists:
|
||||
|
||||
1. Screenshot the error
|
||||
2. Share PyCharm version: **Help** → **About**
|
||||
3. Share Python version: `python --version`
|
||||
4. Share OS: `uname -a` (Linux/Mac) or `ver` (Windows)
|
||||
5. Post in team chat with:
|
||||
- What you were trying to do
|
||||
- What error you got
|
||||
- What you've tried so far
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [PyCharm Make Configuration](pycharm-configuration-make.md) - Configure Make with virtual environment
|
||||
- [Contributing Guide](contributing.md) - Development workflow
|
||||
- [Database Migrations](database-migrations.md) - Working with Alembic
|
||||
|
||||
Reference in New Issue
Block a user