code-style

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

Tool	Purpose	Configuration
black	Code formatting	pyproject.toml
flake8	Style checking	pyproject.toml
mypy	Type checking	pyproject.toml

---

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

Code	Description	Fix
E501	Line too long (>200 chars)	Break line or shorten code
F401	Imported but unused	Remove unused import
F841	Variable assigned but never used	Remove or use the variable
E302	Expected 2 blank lines	Add blank lines between functions
E303	Too many blank lines	Remove extra blank lines
W291	Trailing whitespace	Remove trailing spaces
E711	Comparison to None	Use is None instead of == None

---

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

Error	Description	Fix
Incompatible types	Type mismatch	Fix type annotation or value
Missing return statement	Function missing return	Add return statement
Argument has incompatible type	Wrong argument type	Pass correct type
has no attribute	Attribute doesn't exist	Check spelling or type

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"
    }
}