Code Style and Linting

This skill covers code style checking and formatting workflows for the Semantic Link Labs project.

When to Use This Skill

Use this skill when you need to:

• Check code for style violations
• Format code with black
• Verify type correctness with mypy
• Fix linting errors before committing
• Ensure code follows project standards

Formatting Tools

Code Formatting with Black

The project uses black for code formatting.

Running Black

# Format all source files
black src/sempy_labs tests

# Check without modifying (dry run)
black --check src/sempy_labs tests

# Show diff of changes
black --diff src/sempy_labs tests

# Format specific file
black src/sempy_labs/_workspaces.py

Black Configuration

From pyproject.toml, max line length is configured via flake8 settings.

Style Checking with Flake8

Running Flake8

# Check all source files
flake8 src/sempy_labs tests

# Check specific file
flake8 src/sempy_labs/_helper_functions.py

# Show source code for each error
flake8 --show-source src/sempy_labs

# Show statistics summary
flake8 --statistics src/sempy_labs

Flake8 Configuration

From pyproject.toml:

[tool.flake8]
max-line-length = 200

Common Flake8 Errors

Type Checking with Mypy

Running Mypy

# Check all source files
mypy src/sempy_labs

# Check specific file
mypy src/sempy_labs/_workspaces.py

# Show error codes
mypy --show-error-codes src/sempy_labs

Mypy Configuration

From pyproject.toml:

[[tool.mypy.overrides]]
module = "sempy.*,Microsoft.*,System.*,anytree.*,synapse.ml.services.*,polib.*,jsonpath_ng.*,anywidget.*,sqlglot.*"
ignore_missing_imports = true

Common Mypy Errors

Adding Type Ignore Comments

When mypy raises false positives:

# Ignore specific error
result = some_function()  # type: ignore[return-value]

# Ignore all errors on line
result = some_function()  # type: ignore

Import Organization

Import Order

Organize imports in this order (with blank lines between groups):

1. Standard library imports
2. Third-party imports
3. Local application imports

Example Import Structure

# Standard library
import os
import json
from typing import Optional, List
from uuid import UUID

# Third-party
import pandas as pd
import requests

# Semantic Link (dependency)
import sempy.fabric as fabric
from sempy._utils._log import log

# Local imports
import sempy_labs._icons as icons
from sempy_labs._helper_functions import (
    resolve_workspace_id,
    _base_api,
)

Pre-Commit Style Checklist

Before committing code changes:

# Format code
black src/sempy_labs tests

# Check for style issues
flake8 src/sempy_labs tests

# Check types (optional)
mypy src/sempy_labs

# If any errors, fix and re-run

Common Style Fixes

Line Too Long

Break long lines using parentheses or backslash:

# Before
result = some_very_long_function_call(parameter1, parameter2, parameter3, parameter4, parameter5)

# After
result = some_very_long_function_call(
    parameter1,
    parameter2,
    parameter3,
    parameter4,
    parameter5
)

F-String Line Breaks

# Before
print(f"{icons.green_dot} The '{item_name}' {item_type} has been successfully created in the '{workspace_name}' workspace.")

# After (if too long)
print(
    f"{icons.green_dot} The '{item_name}' {item_type} has been successfully "
    f"created in the '{workspace_name}' workspace."
)

Dictionary Formatting

# Before
payload = {"displayName": name, "description": description, "definition": definition}

# After
payload = {
    "displayName": name,
    "description": description,
    "definition": definition,
}

IDE Integration

VS Code Settings

Recommended .vscode/settings.json:

{
    "python.formatting.provider": "black",
    "python.linting.flake8Enabled": true,
    "python.linting.mypyEnabled": true,
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter"
    }
}