Ruff linting

This includes updating the type hints to the Python 3.10 format. We can
use the new format and still maintain compatibility with Python 3.8 by
using a `__future__` import.

Author: avdstaaij

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 Compatible with GDMC-HTTP **>=1.6.0, <2.0.0** and Minecraft **1.21.4**.
 
+**Fixes:**
+- The re-exports in the `gdpc` top-level package are now formatted in a more standard way, which may prevent issues with static analysis tools when importing them.
+
 
 # 8.1.0
 

pyproject.toml

@@ -14,12 +14,77 @@ exclude = [
     "**/__pycache__",
     "**/site-packages/nbt/**",
 ]
-stubPath = "src/stubs"
-typeCheckingMode = "strict"
 ignore = [
     "**/site-packages/nbt/**",
 ]
+stubPath = "src/stubs"
+typeCheckingMode = "strict"
+reportUnusedImport = "warning"
 
 
 [tool.mypy]
 mypy_path = "src/stubs"
+
+
+[tool.ruff]
+target-version = "py38" # If we move the project setup from setup.py to pyproject.toml, replace this with project.requires-python. https://docs.astral.sh/ruff/settings/#target-version
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Reason for ignoring:
+    # DI: Disagree         - I disagree with this rule in nearly all cases.
+    # AL: Alternative      - The rule is incompatible with an alternative rule.
+    # TB: Too broad        - The rule is sometimes useful, but gives too many false positives.
+    # PA: Public API       - The fix may require changing a public API, making this rule unusable in many cases.
+    # HI: Hint             - The rule would be useful at hint-severity, if ruff supported that.
+    # PR: Project-specific - There is a project-specific reason to not use this rule.
+
+    # Mainly DI
+    "RUF010",  # explicit-f-string-type-conversion - DI - Explicit conversion is more readable. See also https://peps.python.org/pep-0498/#s-r-and-a-are-redundant
+
+    # Mainly AL
+    "D203",    # incorrect-blank-line-before-class - AL - Disabled in favor of D211.
+    "D213",    # multi-line-summary-second-line - AL - Disabled in favor of D212.
+
+    # Mainly TB
+    "ANN401",  # any-type - TB - Any can be useful for very generic interfaces or as an acceptable temporary solution.
+    "C90",     # mccabe - TB - May be hard to fix, and real issues can be spotted manually.
+    "D105",    # undocumented-magic-method - TB - Many magic methods are self-explanatory.
+    "D202",    # blank-line-after-function - TB - Adding a blank line can improve readability when the docstring is short.
+    "D204",    # incorrect-blank-line-after-class - TB - The blank line can be unnecessary for very short classes.
+    "D205",    # missing-blank-line-after-summary - TB - A single line is sometimes too limiting, and most tools can handle multiple lines.
+    "D209",    # new-line-after-last-paragraph - TB - It's a bit nasty, but breaking this rule can help compactify short docstrings.
+    "D301",    # escape-sequence-in-docstring - TB - It's a bit nasty, but breaking this rule with "\n" can help compactify short docstrings.
+    "D400",    # missing-trailing-period - TB - Other punctuation is also acceptable. We use D415 instead.
+    "D401",    # non-imperative-mood - TB - This is very controversial. I personally prefer the descriptive mood in most cases.
+    "D404",    # docstring-starts-with-this - TB - There are valid usages of "this", such as when referring to a method's object.
+    "E501",    # line-too-long - TB - Lines occasionally need to be longer, such as when a comment contains a long link.
+    "E701",    # multiple-statements - TB - Single-line if-statements can be more readable in certain scenarios.
+    "E741",    # ambiguous-variable-name - TB - "l" is often fine, and the others may occasionally be fine as well.
+    "FBT001",  # boolean-type-hint-positional-argument - TB, PA, and mostly redundant with FBT003.
+    "FBT002",  # boolean-default-value-positional-argument - TB, PA, and mostly redundant with FBT003.
+    "ISC003",  # explicit-string-concatenation - TB - In cases where some lines are literals and some expressions, it is clearer to use + everywhere.
+    "PERF203", # try-except-in-loop - TB - The try-except can often not be taken out of the loop.
+    "PLR091",  # too-many-* - TB, PA - Real issues can be spotted manually.
+    "PLR2004", # magic-value-comparison - TB - Although this rule is often right, there are also many cases where a constant is overkill.
+    "PLW2901", # redefined-loop-name - TB - Reuse of the loop variable can help keep names simple. This rule does have a strong case, though.
+    "PTH",     # flake8-use-pathlib - TB, HI - Old-style path manipulation is acceptable, and occasionally even more readable.
+    "S311",    # suspicious-non-cryptographic-random-usage - TB - Not all random usages are cryptographic.
+
+    # Mainly HI
+    "FIX",     # flake8-fixme - HI
+    "TD",      # flake8-todos - HI
+
+    # Mainly PR
+    "N802",    # invalid-function-name - PR, PA - For historical reasons, GDPC uses camelCase.
+    "N803",    # invalid-argument-name - PR, PA - for historical reasons, GDPC uses camelCase.
+    "N806",    # non-lowercase-variable-in-function - PR - For historical reasons, GDPC uses camelCase.
+    "N815",    # mixed-case-variable-in-class-scope - PR, PA - For historical reasons, GDPC uses camelCase.
+    "N816",    # mixed-case-variable-in-global-scope - PR, PA - For historical reasons, GDPC uses camelCase.
+    "PGH003",  # blanket-type-ignore - PR - GDPC uses blanket type ignores for pyright-strict-mode unknown-type errors when accessing NBT data.
+]
+
+[tool.ruff.lint.flake8-builtins]
+ignorelist = ["id"]

release-guide.md

@@ -8,7 +8,7 @@ Steps to make a release:
 	- In `__init__.py`, update `__version__` to the new version number.
 	- Change the "In development" header in the changelog to the new version number, and add a new "In development" section with only the compatibility line.
 	- If necessary, update the compatible GDMC-HTTP and Minecraft versions listed on the installation page of the docs and in the changelog.
-	- If necessary, update the minimum Python version listed on the installation page of the docs.
+	- If necessary, update the minimum Python version listed in setup.py, pyproject.toml, and on the installation page of the docs.
 	- Commit the changes above with the title "Updated version to X.X.X".
 	- Push changes to GitHub (things will be public from here).
 

setup.py

@@ -16,10 +16,11 @@ def get_metadata(name: str) -> str:
             # __{name}__ = "{value}"
             delim = '"' if '"' in line else "'"
             return line.split(delim)[1]
-    raise RuntimeError(f"Unable to find {dunderString} value.")
+    msg = f"Unable to find {dunderString} value."
+    raise RuntimeError(msg)
 
 
-with open("README.md", "r", encoding="utf-8") as readme:
+with open("README.md", encoding="utf-8") as readme:
     long_description = readme.read()
 
 
@@ -73,5 +74,5 @@ def get_metadata(name: str) -> str:
         "Chat about it on Discord":     "https://discord.gg/YwpPCRQWND",
         "Source":                       "https://github.com/avdstaaij/gdpc",
     },
-    zip_safe=False
+    zip_safe=False,
 )

src/gdpc/__init__.py

@@ -1,5 +1,4 @@
-"""
-GDPC top-level package.
+"""GDPC top-level package.
 
 Several important classes are re-exported here, so you can more easily import them.
 For example, you can use :python:`from gdpc import Editor` instead of :python:`from gdpc.editor import Editor`.
@@ -65,8 +64,9 @@
 __version__          = "8.1.0"
 
 
-from .vector_tools import Rect, Box # pyright: ignore [reportUnusedImport]
-from .transform import Transform # pyright: ignore [reportUnusedImport]
-from .block import Block # pyright: ignore [reportUnusedImport]
-from .world_slice import WorldSlice # pyright: ignore [reportUnusedImport]
-from .editor import Editor # pyright: ignore [reportUnusedImport]
+# ruff: noqa: I001
+from .vector_tools import Rect as Rect, Box as Box # noqa: PLC0414
+from .transform import Transform as Transform # noqa: PLC0414
+from .block import Block as Block # noqa: PLC0414
+from .world_slice import WorldSlice as WorldSlice # noqa: PLC0414
+from .editor import Editor as Editor # noqa: PLC0414

src/gdpc/block.py

@@ -1,16 +1,20 @@
 """Provides the :class:`.Block` class, which represents a Minecraft block."""
 
 
-from typing import Union, Optional, List, Dict, Sequence, cast
-from dataclasses import dataclass, field
+from __future__ import annotations
+
 from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Sequence, cast
 
-from pyglm.glm import bvec3
 from nbt import nbt
+from pyglm.glm import bvec3
 
-from .vector_tools import Vec3bLike
+from .block_state_tools import transformAxis, transformFacing, transformHalf, transformRotation
 from .nbt_tools import nbtToSnbt
-from .block_state_tools import transformAxis, transformFacing, transformRotation, transformHalf
+
+if TYPE_CHECKING:
+    from .vector_tools import Vec3bLike
 
 
 @dataclass
@@ -38,27 +42,29 @@ class Block:
     # TODO: Known orientation-related block states that are currently not supported:
     # - type="bottom"/"top" (e.g. slabs)  (note that slabs can also have type="double"!)
 
-    id:     Optional[str]  = "minecraft:stone" #: Block ID
-    states: Dict[str, str] = field(default_factory=dict) #: Block states
-    data:   Optional[str]  = None #: Block entity data
+    id:     str | None     = "minecraft:stone" #: Block ID
+    states: dict[str, str] = field(default_factory=lambda: cast("dict[str, str]", dict)) #: Block states
+    data:   str | None     = None #: Block entity data
 
     # We explicitly add this method instead of using @dataclass so that it looks better in the docs
     # and we can add a docstring.
     def __init__(
         self,
-        id: Optional[str] = "minecraft:stone", # pylint: disable=redefined-builtin
-        states: Optional[Dict[str, str]] = None,
-        data: Optional[str] = None
+        id: str | None = "minecraft:stone", # pylint: disable=redefined-builtin
+        states: dict[str, str] | None = None,
+        data: str | None = None,
     ) -> None:
         """Constructs a Block instance with the given properties."""
         self.id     = id
         self.states = states if states is not None else {}
         self.data   = data
 
 
-    def transform(self, rotation: int = 0, flip: Vec3bLike = bvec3()) -> None:
+    def transform(self, rotation: int = 0, flip: Vec3bLike | None = None) -> None:
         """Transforms this block.\n
         Flips first, rotates second."""
+        if flip is None:
+            flip = bvec3()
         axisState     = self.states.get("axis")
         facingState   = self.states.get("facing")
         rotationState = self.states.get("rotation")
@@ -69,9 +75,11 @@ def transform(self, rotation: int = 0, flip: Vec3bLike = bvec3()) -> None:
         if halfState     is not None: self.states["half"]     = transformHalf    (halfState,               flip)
 
 
-    def transformed(self, rotation: int = 0, flip: Vec3bLike = bvec3()) -> "Block":
+    def transformed(self, rotation: int = 0, flip: Vec3bLike | None = None) -> Block:
         """Returns a transformed copy of this block.\n
         Flips first, rotates second."""
+        if flip is None:
+            flip = bvec3()
         block = deepcopy(self)
         block.transform(rotation, flip)
         return block
@@ -84,12 +92,16 @@ def stateString(self) -> str:
 
 
     def __str__(self) -> str:
+        """Returns a string representation in the technical "block state" format.\n
+        For example: "minecraft:oak_log[axis=z]"\n
+        More info: https://minecraft.wiki/w/Argument_types#block_state."""
         if not self.id:
             return ""
         return self.id + self.stateString() + (self.data if self.data else "")
 
 
     def __repr__(self) -> str:
+        """Returns a string representation that is guaranteed to `eval()` to this Block."""
         # This is used for model dumping; it needs to return a string that eval()'s to this Block.
         # The default repr includes unnecessary default values, which make model dumps way larger
         # than they need to be.
@@ -102,13 +114,13 @@ def __repr__(self) -> str:
 
 
     @staticmethod
-    def fromBlockStateTag(blockStateTag: nbt.TAG_Compound, blockEntityTag: Optional[nbt.TAG_Compound] = None) -> "Block":
+    def fromBlockStateTag(blockStateTag: nbt.TAG_Compound, blockEntityTag: nbt.TAG_Compound | None = None) -> Block:
         """Parses a block state compound tag (as found in chunk palettes) into a Block.\n
         If ``blockEntityTag`` is provided, it is parsed into the Block's :attr:`.data` attribute."""
         block = Block(str(blockStateTag["Name"]))
 
         if "Properties" in blockStateTag:
-            for tag in cast(List[nbt.TAG_String], cast(nbt.TAG_Compound, blockStateTag["Properties"]).tags):
+            for tag in cast("list[nbt.TAG_String]", cast("nbt.TAG_Compound", blockStateTag["Properties"]).tags):
                 block.states[str(tag.name)] = str(tag.value)
 
         if blockEntityTag is not None:
@@ -121,9 +133,8 @@ def fromBlockStateTag(blockStateTag: nbt.TAG_Compound, blockEntityTag: Optional[
         return block
 
 
-def transformedBlockOrPalette(block: Union[Block, Sequence[Block]], rotation: int, flip: Vec3bLike) -> Union[Block, Sequence[Block]]:
+def transformedBlockOrPalette(block: Block | Sequence[Block], rotation: int, flip: Vec3bLike) -> Block | Sequence[Block]:
     """Convenience function that transforms a block or a palette of blocks."""
     if isinstance(block, Block):
         return block.transformed(rotation, flip)
-    else:
-        return [b.transformed(rotation, flip) for b in block]
+    return [b.transformed(rotation, flip) for b in block]

src/gdpc/block_state_tools.py

@@ -5,9 +5,14 @@
 """
 
 
-from pyglm.glm import ivec3, bvec3
+from __future__ import annotations
 
-from .vector_tools import Vec3iLike, Vec3bLike
+from typing import TYPE_CHECKING
+
+from pyglm.glm import bvec3, ivec3
+
+if TYPE_CHECKING:
+    from .vector_tools import Vec3bLike, Vec3iLike
 
 
 # ==================================================================================================
@@ -88,7 +93,8 @@ def vectorToAxis(vec: Vec3iLike) -> str:
     try:
         return __VECTOR_TO_AXIS[v]
     except KeyError as e:
-        raise ValueError("Exactly one vector component must be non-zero") from e
+        msg = "Exactly one vector component must be non-zero"
+        raise ValueError(msg) from e
 
 
 __AXIS_TO_VECTOR = {
@@ -123,7 +129,8 @@ def vectorToFacing(vec: Vec3iLike) -> str:
     try:
         return __VECTOR_TO_FACING[v]
     except KeyError as e:
-        raise ValueError("Exactly one vector component must be non-zero") from e
+        msg = "Exactly one vector component must be non-zero"
+        raise ValueError(msg) from e
 
 
 __FACING_TO_VECTOR = {
@@ -202,9 +209,11 @@ def flipFacing(facing: str, flip: Vec3bLike) -> str:
     return facing
 
 
-def transformFacing(facing: str, rotation: int = 0, flip: Vec3bLike = bvec3()) -> str:
+def transformFacing(facing: str, rotation: int = 0, flip: Vec3bLike | None = None) -> str:
     """Returns the transformed "facing" block state string.\n
     Flips first, rotates second."""
+    if flip is None:
+        flip = bvec3()
     return rotateFacing(flipFacing(facing, flip), rotation)
 
 
@@ -226,11 +235,13 @@ def invertFacing(facing: str) -> str:
 
 
 def rotateRotation(blockStateRotation: str, rotation: int) -> str:
-    """Returns the rotated "rotation" block state string.\n
+    """Returns the rotated "rotation" block state string.
+
     Yes, this name is confusing. ``blockStateRotation`` denotes a value of the "rotation" block
     state, as used by e.g. signs. ``rotation`` denotes a rotation as used by GDPC's transformation
     system, so one of {0,1,2,3}. This function name is consistent with the other block state
-    rotation functions."""
+    rotation functions.
+    """
     return str((int(blockStateRotation) + 4*rotation) % 16)
 
 
@@ -244,9 +255,11 @@ def flipRotation(rotation: str, flip: Vec3bLike) -> str:
     return str(rotationInt)
 
 
-def transformRotation(blockStateRotation: str, rotation: int = 0, flip: Vec3bLike = bvec3()) -> str:
+def transformRotation(blockStateRotation: str, rotation: int = 0, flip: Vec3bLike | None = None) -> str:
     """Returns the transformed "rotation" block state string.\n
     Flips first, rotates second."""
+    if flip is None:
+        flip = bvec3()
     return rotateRotation(flipRotation(blockStateRotation, flip), rotation)
 
 
@@ -274,6 +287,8 @@ def flipHalf(half: str, flip: Vec3bLike) -> str:
     return invertHalf(half) if flip[1] else half
 
 
-def transformHalf(half: str, flip: Vec3bLike = bvec3()) -> str:
+def transformHalf(half: str, flip: Vec3bLike | None = None) -> str:
     """Returns the transformed "half" block state string."""
+    if flip is None:
+        flip = bvec3()
     return flipHalf(half, flip)