@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/python/P002-specify-file-encoding.md

@@ -0,0 +1,45 @@
+---
+title: Specify Encoding When Opening Files
+impact: MEDIUM
+impactDescription: Omitting encoding when opening text files causes silent failures on systems with non-UTF-8 locale, resulting in UnicodeDecodeError or garbled data in production.
+tags: python, encoding, files, portability, quality
+---
+
+## Specify Encoding When Opening Files
+
+When calling `open()` in text mode without an explicit `encoding` argument, Python uses the OS's default locale encoding. This is typically UTF-8 on Linux/macOS, but `cp1252` or similar on Windows. Code that works locally can silently fail or corrupt data in other environments.
+
+Always pass `encoding="utf-8"` (or whatever the file format requires) explicitly.
+
+**Incorrect:**
+```python
+# Relies on OS default — breaks on Windows or non-UTF-8 systems
+with open("data.txt") as f:
+    content = f.read()
+
+with open("output.csv", "w") as f:
+    f.write("café,prix\n")
+```
+
+**Correct:**
+```python
+with open("data.txt", encoding="utf-8") as f:
+    content = f.read()
+
+with open("output.csv", "w", encoding="utf-8") as f:
+    f.write("café,prix\n")
+
+# When reading binary, no encoding needed
+with open("image.png", "rb") as f:
+    data = f.read()
+```
+
+**Pathlib equivalent (also requires explicit encoding):**
+```python
+from pathlib import Path
+
+content = Path("data.txt").read_text(encoding="utf-8")
+Path("output.txt").write_text("hello", encoding="utf-8")
+```
+
+**Tools:** Ruff `W1514` / `PLW1514` (unspecified-encoding), Pylint `W1514`, flake8-bugbear

package/skill-assets/sunlint-code-quality/rules/python/P003-context-manager-for-resources.md

@@ -0,0 +1,54 @@
+---
+title: Use Context Manager for File and Resource Handling
+impact: MEDIUM
+impactDescription: Not using with statement for file/network/lock resources causes resource leaks when exceptions are raised, leading to open file handles, locked databases, and memory exhaustion.
+tags: python, resources, context-manager, files, quality
+---
+
+## Use Context Manager for File and Resource Handling
+
+Python's `with` statement (context manager protocol) guarantees that resources are released even when exceptions occur. Always use `with` when dealing with files, network connections, database cursors, threading locks, and any object that implements `__enter__`/`__exit__`.
+
+**Incorrect:**
+```python
+# File handle not closed if exception occurs
+f = open("data.txt", encoding="utf-8")
+content = f.read()  # If this raises, f.close() is never called
+f.close()
+
+# Lock never released if exception raised inside
+lock = threading.Lock()
+lock.acquire()
+do_work()  # Exception here leaves lock permanently acquired
+lock.release()
+```
+
+**Correct:**
+```python
+# File is always closed, even on exception
+with open("data.txt", encoding="utf-8") as f:
+    content = f.read()
+
+# Lock always released
+import threading
+
+lock = threading.Lock()
+with lock:
+    do_work()
+
+# Multiple context managers in one with
+with open("input.txt", encoding="utf-8") as fin, \
+     open("output.txt", "w", encoding="utf-8") as fout:
+    fout.write(fin.read())
+```
+
+**contextlib.suppress as context manager:**
+```python
+import contextlib
+
+# Instead of try/except/pass
+with contextlib.suppress(FileNotFoundError):
+    os.remove("temp.txt")
+```
+
+**Tools:** Ruff `SIM115` (open-file-with-context-handler), `R1732` (consider-using-with), Pylint, flake8-simplify

package/skill-assets/sunlint-code-quality/rules/python/P004-no-bare-except.md

@@ -0,0 +1,65 @@
+---
+title: Never Use Bare except Clause
+impact: HIGH
+impactDescription: A bare except catches SystemExit and KeyboardInterrupt, making programs impossible to interrupt and hiding unrelated errors that should propagate.
+tags: python, exceptions, error-handling, pitfalls, quality
+---
+
+## Never Use Bare except Clause
+
+A bare `except:` clause (with no exception type specified) catches **every** exception, including `SystemExit` (raised by `sys.exit()`), `KeyboardInterrupt` (Ctrl+C), and `GeneratorExit`. This prevents programs from being terminated normally, swallows programming errors, and makes debugging extremely difficult.
+
+Always specify the exception type(s) you intend to handle.
+
+**Incorrect:**
+```python
+# Catches SystemExit and KeyboardInterrupt — program cannot be stopped
+try:
+    process_data()
+except:
+    print("Something went wrong")
+
+# Also problematic: too broad
+try:
+    connect_to_db()
+except Exception:
+    pass  # silently ignores all errors including programming mistakes
+```
+
+**Correct:**
+```python
+# Catch only what you expect and can handle
+try:
+    process_data()
+except ValueError as e:
+    logger.warning("Invalid data: %s", e)
+except OSError as e:
+    logger.error("I/O error during processing: %s", e)
+
+# If you need a catch-all, at least log it and re-raise
+try:
+    connect_to_db()
+except Exception as e:
+    logger.error("Unexpected error connecting to DB: %s", e, exc_info=True)
+    raise
+
+# Correct way to suppress a specific expected error
+import contextlib
+
+with contextlib.suppress(FileNotFoundError):
+    os.remove("temp.txt")
+```
+
+**Exception hierarchy to catch:**
+```python
+# Prefer specific → broad order
+try:
+    result = int(user_input)
+except ValueError:
+    result = 0  # handle invalid literal
+except (TypeError, OverflowError) as e:
+    logger.warning("Type issue: %s", e)
+    result = 0
+```
+
+**Tools:** Ruff `E722` (bare-except), `W0702` in Pylint, `BLE001` (blind-except), flake8, pyflakes

package/skill-assets/sunlint-code-quality/rules/python/P005-use-isinstance.md

@@ -0,0 +1,60 @@
+---
+title: Use isinstance() Instead of type() for Type Checking
+impact: MEDIUM
+impactDescription: Using type() == for type checks breaks polymorphism and inheritance, rejecting valid subclass instances that should be accepted by the contract.
+tags: python, typing, isinstance, quality, oop
+---
+
+## Use isinstance() Instead of type() for Type Checking
+
+The `type(x) == SomeClass` pattern performs an exact type match and does not account for subclasses. This violates the Liskov Substitution Principle: code that accepts a `list` should also accept `UserList` or any other list subclass.
+
+Use `isinstance()` which checks the full MRO (method resolution order) and correctly handles subclasses and abstract base classes.
+
+**Incorrect:**
+```python
+def process(data):
+    if type(data) == list:    # rejects OrderedList, UserList, etc.
+        for item in data:
+            handle(item)
+    if type(data) == dict:    # rejects defaultdict, OrderedDict, etc.
+        process_mapping(data)
+
+def serialize(value):
+    if type(value) == str:    # rejects str subclasses
+        return value.encode("utf-8")
+```
+
+**Correct:**
+```python
+def process(data):
+    if isinstance(data, list):    # accepts all list subclasses
+        for item in data:
+            handle(item)
+    if isinstance(data, dict):    # accepts defaultdict, OrderedDict, etc.
+        process_mapping(data)
+
+def serialize(value):
+    if isinstance(value, str):
+        return value.encode("utf-8")
+
+# Use abstract base classes for duck typing
+from collections.abc import Mapping, Sequence
+
+def process_generic(data):
+    if isinstance(data, Sequence):  # list, tuple, str, UserList, etc.
+        for item in data:
+            handle(item)
+    if isinstance(data, Mapping):   # dict, defaultdict, ChainMap, etc.
+        process_mapping(data)
+```
+
+**Exception — when exact type match IS needed:**
+```python
+# Only use type() == when you explicitly want to exclude subclasses
+# e.g., in a serialization library distinguishing bool from int:
+if type(value) is bool:  # True/False, not int subclasses
+    return str(value).lower()
+```
+
+**Tools:** Ruff `E721` (type-comparison), Pylint `C0123` (unidiomatic-typecheck), mypy, pyright

package/skill-assets/sunlint-code-quality/rules/python/P006-timezone-aware-datetime.md

@@ -0,0 +1,58 @@
+---
+title: Always Use Timezone-Aware Datetimes
+impact: HIGH
+impactDescription: Naive datetimes (without tzinfo) cause silent bugs when comparing times across timezones, leading to incorrect scheduling, expiry calculations, and audit logs.
+tags: python, datetime, timezone, bugs, quality
+---
+
+## Always Use Timezone-Aware Datetimes
+
+Python's `datetime` objects can be *naive* (no timezone) or *aware* (with timezone). Mixing naive and aware datetimes raises a `TypeError`, but naive datetimes used consistently silently produce wrong results when code runs in different timezones (CI server vs production, container vs host).
+
+Always create timezone-aware datetimes by passing `tz` or `tzinfo`.
+
+**Incorrect:**
+```python
+from datetime import datetime
+
+# Naive datetimes — "now" means different things in Tokyo vs London
+created_at = datetime.now()
+expires_at = datetime.utcnow()  # UTC but naive — still dangerous
+
+# Comparing naive datetimes assumes both are in same timezone (often wrong)
+if datetime.now() > token_expiry:  # fails if token_expiry is aware
+    raise TokenExpiredError()
+```
+
+**Correct:**
+```python
+from datetime import datetime, timezone
+
+# Python 3.11+: use datetime.UTC constant
+now = datetime.now(tz=timezone.utc)
+
+# Python 3.9+: use zoneinfo for local zones
+from zoneinfo import ZoneInfo
+
+jst_now = datetime.now(tz=ZoneInfo("Asia/Tokyo"))
+utc_now = datetime.now(tz=timezone.utc)
+
+# django/pytz style (pre-3.9)
+import pytz
+
+utc_now = datetime.now(tz=pytz.utc)
+
+# Always compare aware with aware
+token_expiry: datetime  # must be aware
+if datetime.now(tz=timezone.utc) > token_expiry:
+    raise TokenExpiredError()
+```
+
+**Converting naive to aware (migration):**
+```python
+# Assume a legacy naive datetime is UTC — localize it explicitly
+naive_dt = datetime(2024, 1, 15, 10, 30)
+aware_dt = naive_dt.replace(tzinfo=timezone.utc)
+```
+
+**Tools:** Ruff `DTZ001`–`DTZ012` (flake8-datetimez), Pylint `W1502`, mypy with `--strict-optional`

package/skill-assets/sunlint-code-quality/rules/python/P007-use-pathlib.md

@@ -0,0 +1,62 @@
+---
+title: Use pathlib Instead of os.path for File Operations
+impact: MEDIUM
+impactDescription: os.path functions return plain strings that are easy to misuse; pathlib.Path provides an object-oriented, composable, and cross-platform API that eliminates common path manipulation bugs.
+tags: python, pathlib, os-path, files, quality, python3
+---
+
+## Use pathlib Instead of os.path for File Operations
+
+Python 3.4 introduced `pathlib.Path` as a modern, object-oriented replacement for `os.path`. Paths are represented as objects supporting `/` operator for joining, `.stem`, `.suffix`, `.parent` for decomposition, and `.read_text()` / `.write_text()` for content — with no risk of forgetting `os.path.join` and accidentally concatenating strings.
+
+**Incorrect:**
+```python
+import os
+
+# String concatenation — silent bugs on Windows with backslashes
+config_path = base_dir + "/config/" + "settings.json"
+
+# Verbose os.path usage
+import os.path
+
+full_path = os.path.join(base_dir, "config", "settings.json")
+file_name = os.path.basename(full_path)
+dir_name  = os.path.dirname(full_path)
+stem      = os.path.splitext(file_name)[0]
+ext       = os.path.splitext(file_name)[1]
+
+if os.path.exists(config_path):
+    with open(config_path, encoding="utf-8") as f:
+        content = f.read()
+
+os.makedirs(os.path.join(base_dir, "logs"), exist_ok=True)
+```
+
+**Correct:**
+```python
+from pathlib import Path
+
+base_dir = Path("/app")
+
+# / operator for joining — cross-platform and clear
+config_path = base_dir / "config" / "settings.json"
+
+# Readable decomposition
+file_name = config_path.name        # "settings.json"
+dir_name  = config_path.parent      # Path("/app/config")
+stem      = config_path.stem        # "settings"
+ext       = config_path.suffix      # ".json"
+
+# Built-in existence check and file reading
+if config_path.exists():
+    content = config_path.read_text(encoding="utf-8")
+
+# Directory creation
+(base_dir / "logs").mkdir(parents=True, exist_ok=True)
+
+# Glob for files
+for py_file in base_dir.rglob("*.py"):
+    print(py_file)
+```
+
+**Tools:** Ruff `PTH100`–`PTH208` (flake8-use-pathlib), pyupgrade, SonarQube Python rules

package/skill-assets/sunlint-code-quality/rules/python/P008-no-wildcard-import.md

@@ -0,0 +1,52 @@
+---
+title: Never Use Wildcard Imports
+impact: HIGH
+impactDescription: Wildcard imports pollute the namespace, make it impossible to trace where a name comes from, and can silently override existing names, causing hard-to-debug subtle bugs.
+tags: python, imports, namespace, quality, readability
+---
+
+## Never Use Wildcard Imports
+
+`from module import *` imports every public name from a module into the current namespace. This:
+- Makes it impossible to know where any name is defined without reading the imported module
+- Can silently override names from prior imports or `builtins`
+- Prevents static analysis tools from detecting undefined names
+- Breaks auto-complete and go-to-definition in IDEs
+
+The only acceptable use of `import *` is in a package's `__init__.py` to re-export a curated public API defined in `__all__`.
+
+**Incorrect:**
+```python
+from os.path import *      # which names are now in scope?
+from numpy import *        # overrides Python's built-in sum, any, all, etc.
+from models import *       # User? Order? both? neither?
+from utils import *
+
+# Now these silently shadow built-ins:
+result = sum([1, 2, 3])    # which sum? Python's or numpy's?
+```
+
+**Correct:**
+```python
+import os
+from os import path as osp                    # or use pathlib
+from pathlib import Path
+import numpy as np                            # conventional alias
+from models import User, Order, Product       # explicit names
+from utils import format_date, validate_email
+
+# Clear provenance for every name
+result = np.sum([1, 2, 3])
+full_path = Path("/data") / "file.txt"
+```
+
+**Acceptable use in `__init__.py`:**
+```python
+# package/__init__.py — re-export public API
+from .client import Client
+from .exceptions import APIError, RateLimitError
+
+__all__ = ["Client", "APIError", "RateLimitError"]
+```
+
+**Tools:** Ruff `F403` (undefined-local-with-import-star), `W0401` in Pylint (wildcard-import), flake8, isort

package/skill-assets/sunlint-code-quality/rules/python/P009-logging-lazy-format.md

@@ -0,0 +1,50 @@
+---
+title: Use Lazy Formatting in Logging Calls
+impact: MEDIUM
+impactDescription: Eager string interpolation in logging (f-strings or %) evaluates and allocates the string even when the log level is disabled, wasting CPU and memory in production.
+tags: python, logging, performance, quality
+---
+
+## Use Lazy Formatting in Logging Calls
+
+Python's `logging` module accepts a format string and arguments **separately**. The string interpolation only happens if the message will actually be emitted (i.e., the log level is enabled). Using f-strings or `%` interpolation beforehand evaluates the string unconditionally, even if `DEBUG` is disabled.
+
+**Incorrect:**
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+user_id = get_user_id()
+payload = serialize(data)
+
+# These always evaluate the f-string / % formatting, even if DEBUG is off
+logger.debug(f"Processing user {user_id} with payload {payload}")
+logger.info("Request from %s: %s" % (ip_address, request.path))
+logger.warning("Slow query: " + str(query_time) + "ms")
+```
+
+**Correct:**
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Formatting deferred — only if DEBUG is enabled
+logger.debug("Processing user %s with payload %s", user_id, payload)
+logger.info("Request from %s: %s", ip_address, request.path)
+logger.warning("Slow query: %sms", query_time)
+
+# For complex objects, use lazy repr via %r
+logger.debug("Event received: %r", event)
+
+# Exception info — use exc_info=True or logger.exception()
+try:
+    call_external_api()
+except requests.RequestException as e:
+    logger.error("External API failed for user %s: %s", user_id, e, exc_info=True)
+    # or equivalently inside an except block:
+    # logger.exception("External API failed for user %s", user_id)
+```
+
+**Tools:** Ruff `G004` (logging-f-string), `W1201` in Pylint (logging-not-lazy), `W1202` (logging-format-interpolation), `TRY400` (error-instead-of-exception), flake8-logging-format

package/skill-assets/sunlint-code-quality/rules/python/P010-exception-chaining.md

@@ -0,0 +1,57 @@
+---
+title: Use raise...from to Chain Exceptions
+impact: MEDIUM
+impactDescription: Rethrowing an exception without raise...from loses the original traceback, making it impossible to diagnose the root cause in production logs.
+tags: python, exceptions, error-handling, traceability, quality
+---
+
+## Use raise...from to Chain Exceptions
+
+When catching an exception and raising a different (or more specific) one, use `raise NewException("msg") from original_exception` to preserve the full causal chain. Without `from`, Python 3 still shows an implicit chain, but the context can be confusing. Using `from` makes the chain explicit and intentional.
+
+Using `raise ... from None` deliberately suppresses the original context when it adds no value to the end user.
+
+**Incorrect:**
+```python
+import json
+
+def load_config(path: str) -> dict:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except json.JSONDecodeError:
+        raise ValueError("Config file is malformed")  # original traceback lost
+
+def get_user(user_id: int) -> dict:
+    try:
+        return db.find_by_id(user_id)
+    except DatabaseError:
+        raise RuntimeError("Failed to fetch user")  # loses DB error context
+```
+
+**Correct:**
+```python
+import json
+
+def load_config(path: str) -> dict:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Config file '{path}' is malformed") from e  # chain preserved
+
+def get_user(user_id: int) -> dict:
+    try:
+        return db.find_by_id(user_id)
+    except DatabaseError as e:
+        raise UserNotFoundError(f"User {user_id} could not be fetched") from e
+
+# Suppress context intentionally (e.g., to hide internal DB details from callers)
+def validate_token(token: str) -> None:
+    try:
+        jwt.decode(token, SECRET)
+    except jwt.ExpiredSignatureError:
+        raise AuthenticationError("Token has expired") from None
+```
+
+**Tools:** Ruff `W0707` / `raise-missing-from`, `TRY200` (reraise-no-cause), `B904` (raise-without-from-inside-except), Pylint `W0707`, flake8-bugbear

package/skill-assets/sunlint-code-quality/rules/python/P011-subprocess-check.md

@@ -0,0 +1,59 @@
+---
+title: Pass Explicit check= to subprocess.run
+impact: HIGH
+impactDescription: subprocess.run silently ignores non-zero exit codes by default; a failed command goes undetected and subsequent code runs on corrupt or missing output.
+tags: python, subprocess, error-handling, quality, security
+---
+
+## Pass Explicit check= to subprocess.run
+
+`subprocess.run()` has `check=False` by default, meaning a command that exits with a non-zero status (indicating failure) does not raise an exception. Code that follows assumes success and may operate on missing or corrupt output without any error ever being raised.
+
+Always pass `check=True` unless you explicitly intend to handle failures yourself by inspecting `returncode`.
+
+**Incorrect:**
+```python
+import subprocess
+
+# Exit code ignored — if ffmpeg fails, output file doesn't exist
+subprocess.run(["ffmpeg", "-i", "input.mp4", "output.mp4"])
+
+# result.returncode is never checked
+result = subprocess.run(["git", "pull"])
+print("Done")  # runs even if git pull failed
+
+# capture_output=True but still no check
+result = subprocess.run(
+    ["python", "migrate.py"],
+    capture_output=True,
+    text=True,
+)
+apply_migrations()  # runs even if migrate.py failed
+```
+
+**Correct:**
+```python
+import subprocess
+
+# Raises CalledProcessError if command fails
+subprocess.run(
+    ["ffmpeg", "-i", "input.mp4", "output.mp4"],
+    check=True,
+)
+
+# Or capture output and check explicitly
+result = subprocess.run(
+    ["python", "migrate.py"],
+    capture_output=True,
+    text=True,
+    check=True,                  # raises on non-zero exit code
+)
+apply_migrations()  # only reached if migration succeeded
+
+# When you WANT to handle failures yourself — explicit intent:
+result = subprocess.run(["git", "pull"], check=False)
+if result.returncode != 0:
+    logger.warning("git pull failed with code %d", result.returncode)
+```
+
+**Tools:** Ruff `PLW1510` (subprocess-run-without-check), Pylint `W1510`, Bandit `S603`, flake8-bugbear

package/skill-assets/sunlint-code-quality/rules/python/P012-requests-timeout.md

@@ -0,0 +1,70 @@
+---
+title: Always Set timeout for HTTP Requests
+impact: HIGH
+impactDescription: HTTP requests without a timeout can hang indefinitely, exhausting thread pools and connection pools, causing cascading failures and outages in production services.
+tags: python, requests, http, reliability, quality
+---
+
+## Always Set timeout for HTTP Requests
+
+The `requests` library and similar HTTP clients have **no default timeout**. A single slow or unresponsive server can cause a thread to block indefinitely, exhausting thread pools and causing the entire service to become unresponsive. Always set an explicit `timeout` on every outbound HTTP call.
+
+**Incorrect:**
+```python
+import requests
+
+# Hangs forever if server is unresponsive
+response = requests.get("https://api.example.com/data")
+
+# Also no timeout
+session = requests.Session()
+response = session.post(
+    "https://api.example.com/webhook",
+    json=payload,
+)
+
+# httpx — same risk
+import httpx
+response = httpx.get("https://api.example.com/items")
+```
+
+**Correct:**
+```python
+import requests
+
+# Set both connect and read timeouts as a tuple
+response = requests.get(
+    "https://api.example.com/data",
+    timeout=(3.05, 27),   # (connect_timeout, read_timeout) in seconds
+)
+
+# Or a single value for both
+response = requests.post(
+    "https://api.example.com/webhook",
+    json=payload,
+    timeout=10,           # applies to both connect and read
+)
+response.raise_for_status()
+
+# httpx — also requires explicit timeout
+import httpx
+
+with httpx.Client(timeout=httpx.Timeout(connect=3.0, read=30.0)) as client:
+    response = client.get("https://api.example.com/items")
+```
+
+**Configure timeouts at the session level:**
+```python
+# Apply uniformly to all requests from the session
+session = requests.Session()
+adapter = requests.adapters.HTTPAdapter(max_retries=3)
+session.mount("https://", adapter)
+
+DEFAULT_TIMEOUT = (3.05, 27)
+
+def get_with_timeout(url: str, **kwargs) -> requests.Response:
+    kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+    return session.get(url, **kwargs)
+```
+
+**Tools:** Ruff `W3101` (missing-timeout), Pylint `W3101`, Bandit `S113`, flake8