FCI_WaterMaker_API/VSCODE_SETUP.md

VSCode Setup for Watermaker PLC API

This document explains how to use the VSCode configuration for development and debugging of the Watermaker PLC API project.

Prerequisites

1. Python Extension: Install the Python extension for VSCode
2. Virtual Environment: The project virtual environment should be created (see main README)

VSCode Configuration Files

The following VSCode configuration files have been created:

.vscode/settings.json

• Sets the Python interpreter to use the virtual environment (./venv/bin/python)
• Enables automatic virtual environment activation in terminals
• Configures linting with flake8
• Sets up code formatting with black
• Enables pytest for testing
• Configures file exclusions for better performance

.vscode/launch.json

Provides several debug configurations:

1. Python: Run Server - Debug the main server with --debug flag
2. Python: Run Server (Custom PLC) - Debug with custom PLC IP/port settings
3. Python: Current File - Debug the currently open Python file
4. Python: Pytest - Debug tests using pytest
5. Python: Attach to Remote - Attach to a remote debugging session

.vscode/tasks.json

Provides common development tasks:

1. Install Dependencies - Install packages from requirements.txt
2. Run Server - Start the server in debug mode
3. Run Tests - Execute all tests with pytest
4. Install Package in Dev Mode - Install the package in development mode
5. Activate Virtual Environment - Run the activation script

How to Use

1. Select Python Interpreter

• Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
• Type "Python: Select Interpreter"
• Choose the interpreter from ./venv/bin/python

2. Running and Debugging

• Press F5 to start debugging with the default configuration
• Or use Ctrl+Shift+D to open the Debug panel and select a configuration
• Set breakpoints by clicking in the left margin of code files

3. Running Tasks

• Press Ctrl+Shift+P and type "Tasks: Run Task"
• Select from the available tasks (Install Dependencies, Run Server, etc.)

4. Testing

• The Test Explorer should automatically discover tests in the tests/ directory
• Use the Test Explorer panel to run individual tests or all tests
• Or use the "Python: Pytest" debug configuration

5. Code Formatting and Linting

• Code will be automatically formatted with black on save
• Linting errors will be highlighted using flake8
• Use Ctrl+Shift+I to format the current file manually

Remote Debugging

For remote debugging scenarios:

1. Install debugpy in your remote environment:

   pip install debugpy
   

2. Add this to your remote code where you want to start debugging:

   import debugpy
   debugpy.listen(5678)
   debugpy.wait_for_client()
   

3. Use the "Python: Attach to Remote" configuration in VSCode

Terminal Integration

• New terminals will automatically activate the virtual environment
• The integrated terminal respects the virtual environment settings
• Use the "Activate Virtual Environment" task if needed

Troubleshooting

Python Interpreter Not Found

• Ensure the virtual environment exists: ls venv/bin/python
• Manually select the interpreter using the Command Palette

Tasks Not Working

• Ensure bash is available on your system
• Check that the virtual environment is properly created

Linting/Formatting Issues

• Ensure flake8 and black are installed: pip list | grep -E "(flake8|black)"
• Check the .flake8 and pyproject.toml configuration files

Tests Not Discovered

• Ensure pytest is installed: pip list | grep pytest
• Check that test files follow the naming convention (test_*.py)