Skip to content

Development Setup Guide

Jump to bottom
Jahnvi Thakkar edited this page Nov 21, 2025 · 3 revisions

This mssql-python module helps developers set up their development environment for the mssql-python project with automatic code formatting and linting.

🚀 Quick Start (Recommended)

For VS Code users - Everything is automated!

  1. Clone the repository

    git clone https://github.com/microsoft/mssql-python.git
cd mssql-python

  2. Open in VS Code

    code .

  3. Install recommended extensions

    • A notification will appear: "This workspace has extension recommendations"
    • Click "Install All" or "Show Recommendations"
    • VS Code will automatically install all required formatters and linters

  4. Start coding!

    • All settings are pre-configured in .vscode/settings.json
    • Save any file (Ctrl+S) and it auto-formats automatically ✨
    • Linting runs in real-time

That's it! No manual configuration needed. The repository includes:

  • ✅ .vscode/extensions.json - Automatic extension recommendations
  • ✅ .vscode/settings.json - Pre-configured formatter and linter settings
  • ✅ .clang-format - C++ formatting rules
  • ✅ pyproject.toml & .flake8 - Python linting configuration

Table of Contents

📦 What's Included in This PR

This PR adds comprehensive auto-formatting and linting configuration to streamline development:

New Files Added

1. .vscode/extensions.json ⭐

Purpose: Automatically recommends required VS Code extensions

What it does:

  • When developers open this repository in VS Code, they see a notification
  • One click installs all necessary formatters and linters
  • Ensures everyone uses the same development tools

Extensions recommended:

  • Python: ms-python.python, ms-python.vscode-pylance, ms-python.black-formatter, ms-python.pylint, ms-python.flake8, ms-python.autopep8
  • C++: ms-vscode.cpptools, ms-vscode.cpptools-extension-pack, xaver.clang-format, mine.cpplint
  • Git (optional): github.vscode-pull-request-github, eamodio.gitlens

Developer experience:

📢 VS Code Notification: 
   "This workspace has extension recommendations. 
    Would you like to install them?"
    
    [Install All] [Show Recommendations] [Ignore]

2. .vscode/settings.json ⭐

Purpose: Pre-configured workspace settings for consistent formatting

What it configures:

  • ✅ Enables formatOnSave for all files
  • ✅ Sets Black as default Python formatter (100-char line length)
  • ✅ Sets clang-format as default C++ formatter (100-char line length)
  • ✅ Configures all linters (Pylint, Flake8, cpplint) with project rules
  • ✅ Enables Pylance type checking with inlay hints
  • ✅ Automatic import organization on save

Key settings:

{
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  },
  "[cpp]": {
    "editor.defaultFormatter": "xaver.clang-format",
    "editor.formatOnSave": true
  },
  "black-formatter.args": ["--line-length=100"],
  "cpplint.lineLength": 100
}

3. .clang-format

Purpose: C++ code formatting rules (enforced by clang-format)

Configuration:

  • Style: LLVM-based with Microsoft modifications
  • Line length: 100 characters
  • Indent: 4 spaces, no tabs
  • Comment spacing: Minimum 2 spaces before inline comments (cpplint compliant)
  • Pointer alignment: Left (int* ptr, not int *ptr)

4. pyproject.toml & .flake8

Purpose: Python linting and formatting configuration

Configuration:

  • Black line length: 100 characters
  • Flake8 ignores: E203, W503, E501, E722, F401, F841, W293, W291, F541, F811, E402, E711, E712, E721, F821
  • Pylint disabled rules: fixme, no-member, too-many-arguments, invalid-name, etc.

5. .github/workflows/lint-check.yml

Purpose: Automated CI/CD linting checks on every PR

What it checks:

  • ✅ Blocking (must pass): Black formatting for Python files
  • ℹ️ Informational (warnings only): Flake8, Pylint, clang-format, cpplint

Workflow triggers:

  • Pull requests to main or develop branches
  • Changes to .py, .cpp, .c, .h, .hpp files
  • Changes to config files (.flake8, pyproject.toml, .clang-format)

Modified Files

.gitignore

  • Updated to allow tracking of .vscode/extensions.json and .vscode/settings.json
  • While .vscode/* remains ignored, these specific config files are tracked using git add -f
  • This ensures shared configuration without tracking personal VS Code preferences

✨ Benefits for Developers

🚀 Zero Manual Setup

  • Clone repo → Open in VS Code → Click "Install" → Start coding
  • No need to configure formatters, linters, or settings manually
  • Works identically for all team members

📏 Consistent Code Style

  • Everyone uses the same formatters with identical settings
  • Auto-format on save prevents style debates in PRs
  • CI/CD enforces formatting standards automatically

🔍 Better Code Quality

  • Real-time linting feedback in Problems panel (Ctrl+Shift+M)
  • Type checking with Pylance inlay hints showing types inline
  • Automatic import organization keeps code clean

⚡ Faster Onboarding

  • New contributors get proper tooling immediately
  • Documentation explains what's configured and why
  • Troubleshooting guide for common issues

🎯 CI/CD Integration

  • Automated checks on every PR
  • Only Black formatting is blocking (easy to fix with Ctrl+S)
  • Other linting issues are informational

Quick Start

For VS Code users (Recommended):

  1. Clone the repository
  2. Open the project in VS Code
  3. When prompted, click "Install" to install recommended extensions
  4. Extensions and settings are automatically configured!
  5. Start coding - your code will auto-format on save 🎉

Prerequisites

Required Software

  1. Visual Studio Code (latest version)
  2. Python 3.8+ (Python 3.13+ recommended)
  3. clang-format (version 10+)
  4. Git (for version control)

Check Installations

# Check Python version
python --version

# Check clang-format
clang-format --version

# Check pip
python -m pip --version

VS Code Setup

Automatic Extension Installation

This repository includes .vscode/extensions.json which automatically recommends required extensions when you open the project.

What happens when you open the repo:

  1. VS Code detects .vscode/extensions.json
  2. A notification appears: "This workspace has extension recommendations. Would you like to install them?"
  3. Click "Install All" or "Show Recommendations"
  4. All necessary extensions will be installed automatically

Recommended Extensions

The following extensions will be automatically recommended:

Python Extensions (Microsoft Official)

  • Python (ms-python.python) - Core Python language support
  • Pylance (ms-python.vscode-pylance) - Fast Python language server
  • Black Formatter (ms-python.black-formatter) - Python code formatter
  • autopep8 (ms-python.autopep8) - Alternative Python formatter
  • Pylint (ms-python.pylint) - Python linter
  • Flake8 (ms-python.flake8) - Python style guide enforcement

C++ Extensions

  • C/C++ (ms-vscode.cpptools) - Microsoft's official C++ tools
  • C/C++ Extension Pack (ms-vscode.cpptools-extension-pack) - C++ tools bundle
  • Clang-Format (xaver.clang-format) - clang-format integration
  • cpplint (mine.cpplint) - Google C++ style guide checker

Git Tools (Optional but Recommended)

  • GitHub Pull Requests (github.vscode-pull-request-github) - GitHub PR integration
  • GitLens (eamodio.gitlens) - Advanced Git features

Manual Extension Installation

If you prefer to install extensions manually:

# Install all extensions at once
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension ms-python.black-formatter
code --install-extension ms-python.autopep8
code --install-extension ms-python.pylint
code --install-extension ms-python.flake8
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cpptools-extension-pack
code --install-extension xaver.clang-format
code --install-extension mine.cpplint
code --install-extension github.vscode-pull-request-github
code --install-extension eamodio.gitlens

Workspace Settings

This repository includes .vscode/settings.json with pre-configured settings for:

  • ✅ Auto-format on save
  • ✅ Correct formatter selection (Black for Python, clang-format for C++)
  • ✅ Linter configurations (line length, ignore rules)
  • ✅ Type checking with Pylance
  • ✅ Import organization

Key settings configured:

{
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  },
  "[cpp]": {
    "editor.defaultFormatter": "xaver.clang-format"
  },
  "black-formatter.args": ["--line-length=100"],
  "flake8.args": ["--max-line-length=100"],
  "cpplint.lineLength": 100
}

Python Package Dependencies

Install Required Packages

# Navigate to project root
cd mssql-python

# Install development dependencies
python -m pip install -r requirements.txt

# This includes:
# - black (code formatter)
# - flake8 (style checker)
# - pylint (linter)
# - autopep8 (formatter)
# - cpplint (C++ linter)
# - mypy (type checker)

Automatic Formatting

How It Works

Once you have the extensions installed and workspace settings loaded:

✅ Python Files (.py)

  • Formatter: Black (line length: 100)
  • Trigger: Automatic on save (Ctrl+S)
  • Import Organization: Automatically sorts imports
  • Manual Format: Shift+Alt+F

✅ C++ Files (.cpp, .c, .h, .hpp)

  • Formatter: clang-format (uses .clang-format config)
  • Trigger: Automatic on save (Ctrl+S)
  • Style Guide: Microsoft/LLVM style (100-char lines)
  • Comment Spacing: Minimum 2 spaces before inline comments
  • Manual Format: Shift+Alt+F

What Gets Formatted

File Type Extensions Formatter Line Length On Save
Python .py Black 100 chars ✅ Yes
C++ Source .cpp, .c clang-format 100 chars ✅ Yes
C++ Headers .h, .hpp clang-format 100 chars ✅ Yes

Configuration Files

The project includes the following configuration files:

  1. .vscode/settings.json - VS Code workspace settings (auto-format, linters)
  2. .vscode/extensions.json - Extension recommendations
  3. .clang-format - C++ formatting rules (LLVM-based, 100-char limit)
  4. pyproject.toml - Python tool configuration (Black, pylint)
  5. .flake8 - Python style guide settings

Linting Configuration

Python Linting

Enabled Linters:

  • Pylint: Code quality and error detection
  • Flake8: Style guide enforcement (PEP 8)
  • mypy: Static type checking (optional)

Configuration:

  • Line length: 100 characters (not 79)
  • Ignores: E203, W503 (conflicts with Black)
  • Custom rules in pyproject.toml and .flake8

Ignored Warnings:

# Common warnings that are ignored:
- E501 (line too long) - Black handles this
- E722 (bare except) - Sometimes necessary
- F401 (unused imports) - May be intentional
- E711/E712 (comparison to None/True/False)

View Linting Errors:

  1. Open the Problems panel: Ctrl+Shift+M
  2. See real-time linting feedback as you type

C++ Linting

Enabled Linter:

  • cpplint: Google C++ Style Guide checker

Configuration:

  • Line length: 100 characters
  • Filtered warnings:
    • -legal/copyright (no copyright headers required)
    • -build/include_subdir (flexible includes)
    • -build/c++11 (modern C++ features allowed)

Run Manually:

# Check a specific file
python -m cpplint --filter=-legal/copyright,-build/include_subdir,-build/c++11 --linelength=100 mssql_python\pybind\ddbc_bindings.cpp

# Check all C++ files
python -m cpplint --filter=-legal/copyright,-build/include_subdir,-build/c++11 --linelength=100 --recursive mssql_python\pybind

CI/CD Integration

GitHub Actions Workflow

This repository includes .github/workflows/lint-check.yml that automatically checks all PRs for linting issues.

What Gets Checked on Every PR:

✅ Required Checks (Must Pass):

  • Black formatting for Python files

ℹ️ Informational Checks (Won't Block PR):

  • Flake8 (Python style)
  • Pylint (Python code quality)
  • clang-format (C++ formatting)
  • cpplint (C++ style)

How It Works:

  1. PR is created or updated
  2. GitHub Actions runs linting checks
  3. Black formatting errors will block the PR
  4. Other linting issues are warnings only
  5. Review results in the "Checks" tab of your PR

Before Committing Code

Run these commands to ensure your PR will pass:

# Format Python files
black --line-length=100 mssql_python/ tests/

# Format C++ files
Get-ChildItem -Path mssql_python\pybind -Recurse -Include *.cpp,*.h,*.hpp | ForEach-Object { clang-format -i $_.FullName }

# Check Python linting
flake8 mssql_python/ tests/ --max-line-length=100

# Check C++ linting  
python -m cpplint --filter=-legal/copyright,-build/include_subdir,-build/c++11 --linelength=100 --recursive mssql_python\pybind

Or Simply:

  • Save all files in VS Code (Ctrl+S) - auto-formatting will fix most issues! ✨
  • Check the Problems panel (Ctrl+Shift+M) for remaining issues
  • Fix any remaining errors manually

Type Checking (Python)

Pylance Configuration

The workspace uses Pylance with type checking enabled:

  • Type Checking Mode: basic
  • Inlay Hints: Enabled for function returns, variables, and parameters
  • Auto-imports: Enabled for better productivity

View Type Information:

  • Hover over any variable/function to see type hints
  • Press Ctrl+Space for IntelliSense with type information
  • Inlay hints show return types and parameter types inline

Verification

Test Python Formatting

  1. Open any Python file (e.g., mssql_python/connection.py)
  2. Add some messy formatting (extra spaces, wrong indentation)
  3. Press Ctrl+S to save
  4. ✅ File should auto-format with proper spacing

Example:

# Before save (messy)
def    my_function(  x,y,z  ):
    return   x+y+z

# After save (formatted)
def my_function(x, y, z):
    return x + y + z

Test C++ Formatting

  1. Open any C++ file (e.g., mssql_python/pybind/ddbc_bindings.cpp)
  2. Add some messy formatting
  3. Press Ctrl+S to save
  4. ✅ File should auto-format with proper indentation and spacing

Example:

// Before save
int value = 42;// Comment too close

// After save
int value = 42;  // Comment with 2 spaces

Keyboard Shortcuts

Action Shortcut
Format Document Shift+Alt+F
Format Selection Ctrl+K Ctrl+F
Save (triggers format) Ctrl+S
Problems Panel Ctrl+Shift+M
Command Palette Ctrl+Shift+P
Extensions Panel Ctrl+Shift+X

Troubleshooting

Extensions Not Showing Up

Issue: No prompt to install recommended extensions

Solution:

  1. Open Extensions panel: Ctrl+Shift+X
  2. Click the "Show Recommended Extensions" button (filter icon with star)
  3. You'll see workspace recommendations at the top
  4. Click "Install Workspace Recommended Extensions"

Python Formatting Not Working

Issue: Black formatter doesn't run on save

Solution:

  1. Check Black is installed: python -m black --version
  2. Verify extension is installed: Check Extensions panel for "Black Formatter"
  3. Check Output panel: View → Output → Select "Black Formatter"
  4. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"

C++ Formatting Not Working

Issue: clang-format doesn't run on save

Solutions:

  1. Check clang-format installation:

    clang-format --version

  2. Verify extension is active:

    • Open Extensions (Ctrl+Shift+X)
    • Search for "Clang-Format"
    • Ensure xaver.clang-format is enabled

  3. Check formatter setting:

    • Open Command Palette (Ctrl+Shift+P)
    • Run "Preferences: Open Workspace Settings (JSON)"
    • Verify: "[cpp]": { "editor.defaultFormatter": "xaver.clang-format" }

  4. Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"

Settings Not Applied

Issue: Changes to .vscode/settings.json not taking effect

Solutions:

  1. Close and reopen VS Code completely
  2. Check for syntax errors in settings.json (use JSON validator)
  3. Check VS Code Output: View → Output → Select "Extension Host"
  4. Try: Ctrl+Shift+P → "Developer: Reload Window"

Linting Errors Not Showing

Issue: No linting errors in Problems panel

Solutions:

  1. Open Problems panel: Ctrl+Shift+M
  2. Check linters are installed: 
    python -m flake8 --version
python -m pylint --version
python -m cpplint --version
  3. Check Output panel for each linter: View → Output → Select linter
  4. Verify extensions are installed and enabled

Workspace Settings vs User Settings

Understanding the hierarchy:

  1. User Settings - Global settings for all projects
  2. Workspace Settings (.vscode/settings.json) - Override user settings for this project
  3. Folder Settings - Override workspace settings (if multi-root workspace)

The .vscode/settings.json in this repo will override your personal preferences only for this project.

Best Practices

Development Workflow

  1. Before Starting Work:

    • Pull latest changes from main
    • Ensure all extensions are installed
    • Verify auto-format works (test with Ctrl+S)

  2. While Coding:

    • Save frequently (Ctrl+S) - formatting happens automatically
    • Check Problems panel (Ctrl+Shift+M) for linting errors
    • Fix linting issues as you go

  3. Before Committing:

    • Save all files (formats everything)
    • Review Problems panel for any remaining issues
    • Run tests if applicable
    • Review git diff to see formatting changes

  4. Before Creating PR:

    • Ensure all files are saved and formatted
    • Check CI/CD workflow status
    • Fix any failing checks before requesting review

Code Review Tips

  • Formatting changes will appear in diffs - this is expected
  • Focus reviews on logic, not formatting (automation handles that)
  • If CI fails on Black formatting, simply save files and push again

Additional Resources

Documentation Links

Project-Specific Questions

  • Check existing issues in the project repository
  • Ask team lead or senior developers
  • Review code review feedback for formatting standards

Summary

✅ Automated Setup:

  • VS Code automatically prompts to install recommended extensions
  • Workspace settings are pre-configured
  • Just open the project and click "Install" - you're ready to code!

✅ Auto-formatting is configured for:

  • Python files (.py) - Black formatter, 100 char lines
  • C++ files (.cpp, .c, .h, .hpp) - clang-format, 100 char lines

✅ Linting is enabled for:

  • Python - Pylint + Flake8
  • C++ - cpplint (Google Style Guide)

✅ CI/CD checks:

  • Automated linting on every PR
  • Only Black formatting is blocking
  • Other checks are informational

✅ Type checking is enabled:

  • Python - Pylance with basic mode and inlay hints

Just save your files (Ctrl+S) and everything formats automatically! 🎉

Clone this wiki locally