Doc and typing updates

beet/contrib/auto_yaml.py

@@ -9,9 +9,10 @@
 ]
 
 
-from typing import Any, ClassVar, Tuple, Type
+from typing import Any, ClassVar
 
-from beet import Context, Drop, JsonFileBase, NamespaceFile, Pack, YamlFile
+from beet import Context, Drop, JsonFileBase, NamespaceFile, Pack, YamlFileBase
+from beet.library.base import Namespace
 
 
 def beet_default(ctx: Context):
@@ -48,19 +49,21 @@ def use_auto_yaml(pack: Pack[Any]):
 
 
 def create_namespace_handler(
-    file_type: Type[JsonFileBase[Any]],
-    namespace_scope: Tuple[str, ...],
+    file_type: type[NamespaceFile],
+    namespace_scope: tuple[str, ...],
     namespace_extension: str,
-) -> Type[NamespaceFile]:
+) -> type[NamespaceFile]:
     """Create handler that turns yaml namespace files into json."""
 
-    class AutoYamlNamespaceHandler(YamlFile):
-        scope: ClassVar[Tuple[str, ...]] = namespace_scope
-        extension: ClassVar[str] = namespace_extension
+    # Subclass check to get the currently unrepresentable type for a subclass of both a NamespaceFile and a JsonFileBase
+    if not issubclass(file_type, JsonFileBase):
+        raise TypeError()
 
-        model = file_type.model
+    class AutoYamlNamespaceHandler(YamlFileBase[Any], model=file_type.base_model):
+        scope: ClassVar[tuple[str, ...]] = namespace_scope
+        extension: ClassVar[str] = namespace_extension
 
-        def bind(self, pack: Any, path: str):
+        def bind(self, pack: Pack[Any], path: str):
             super().bind(pack, path)
             pack[file_type].merge({path: file_type(self.data, original=self.original)})
             raise Drop()
@@ -70,14 +73,12 @@ def bind(self, pack: Any, path: str):
 
 def create_extra_handler(
     filename: str,
-    file_type: Type[JsonFileBase[Any]],
-) -> Type[YamlFile]:
+    file_type: type[JsonFileBase[Any]],
+) -> type[YamlFileBase[Any]]:
     """Create handler that turns yaml extra files into json."""
 
-    class AutoYamlExtraHandler(YamlFile):
-        model = file_type.model
-
-        def bind(self, pack: Any, path: str):
+    class AutoYamlExtraHandler(YamlFileBase[Any], model=file_type.base_model):
+        def bind(self, pack: Pack[Any], path: str):
             super().bind(pack, path)
             pack.extra.merge({filename: file_type(self.data, original=self.original)})
             raise Drop()
@@ -87,14 +88,12 @@ def bind(self, pack: Any, path: str):
 
 def create_namespace_extra_handler(
     filename: str,
-    file_type: Type[JsonFileBase[Any]],
-) -> Type[YamlFile]:
+    file_type: type[JsonFileBase[Any]],
+) -> type[YamlFileBase[Any]]:
     """Create handler that turns yaml namespace extra files into json."""
 
-    class AutoYamlExtraHandler(YamlFile):
-        model = file_type.model
-
-        def bind(self, pack: Any, path: str):
+    class AutoYamlExtraHandler(YamlFileBase[Any], model=file_type.base_model):
+        def bind(self, pack: Pack[Namespace], path: str):
             super().bind(pack, path)
             namespace, _, path = path.partition(":")
             pack[namespace].extra.merge(

beet/contrib/autosave.py

@@ -8,15 +8,14 @@
 
 
 from dataclasses import dataclass, field
-from typing import List
 
 from beet import Context, PluginOptions, PluginSpec
 
 
 class AutosaveOptions(PluginOptions):
     link: bool = False
-    output_handlers: List[str] = []
-    link_handlers: List[str] = []
+    output_handlers: list[str] = []
+    link_handlers: list[str] = []
 
 
 @dataclass
@@ -25,8 +24,8 @@ class Autosave:
 
     ctx: Context
     link: bool = False
-    output_handlers: List[PluginSpec] = field(default_factory=list)
-    link_handlers: List[PluginSpec] = field(default_factory=list)
+    output_handlers: list[PluginSpec] = field(default_factory=list)
+    link_handlers: list[PluginSpec] = field(default_factory=list)
 
     def __post_init__(self):
         opts = self.ctx.validate("autosave", AutosaveOptions)

beet/contrib/babelbox.py

@@ -16,7 +16,7 @@
 from csv import Dialect, DictReader, Sniffer
 from glob import glob
 from pathlib import Path
-from typing import Dict, Optional, Type, Union
+from typing import Optional
 
 from beet import (
     Context,
@@ -28,7 +28,7 @@
 )
 from beet.core.utils import FileSystemPath
 
-DialectLike = Union[str, Dialect, Type[Dialect]]
+DialectLike = str | Dialect | type[Dialect]
 
 
 logger = logging.getLogger(__name__)
@@ -65,14 +65,14 @@ def load_languages(
     path: FileSystemPath,
     dialect: Optional[DialectLike] = None,
     prefix: str = "",
-) -> Dict[str, Language]:
+) -> dict[str, Language]:
     """Return a dictionnary mapping each column to a language file."""
     with open(path, newline="") as csv_file:
         if not dialect:
             dialect = Sniffer().sniff(csv_file.read(1024))
             csv_file.seek(0)
 
-        reader: DictReader[str] = DictReader(csv_file, dialect=dialect)
+        reader = DictReader(csv_file, dialect=dialect)
 
         key, *language_codes = reader.fieldnames or [""]
         languages = {code: Language() for code in language_codes}

beet/contrib/copy_files.py

@@ -13,7 +13,7 @@
 import os
 from glob import glob
 from pathlib import Path
-from typing import Dict, Iterator, Tuple, Type
+from typing import Iterator
 
 from beet import (
     BinaryFile,
@@ -23,7 +23,7 @@
     PackageablePath,
     PackFile,
     PluginOptions,
-    PngFile,
+    PngFileBase,
     TextFile,
     YamlFile,
     configurable,
@@ -32,9 +32,9 @@
 
 
 class CopyFilesOptions(PluginOptions):
-    resource_pack: Dict[str, ListOption[PackageablePath]] = {}
-    data_pack: Dict[str, ListOption[PackageablePath]] = {}
-    output: Dict[str, ListOption[PackageablePath]] = {}
+    resource_pack: dict[str, ListOption[PackageablePath]] = {}
+    data_pack: dict[str, ListOption[PackageablePath]] = {}
+    output: dict[str, ListOption[PackageablePath]] = {}
 
 
 def beet_default(ctx: Context):
@@ -59,9 +59,9 @@ def copy_files(ctx: Context, opts: CopyFilesOptions):
 
 
 def resolve_file_mapping(
-    mapping: Dict[str, ListOption[PackageablePath]],
+    mapping: dict[str, ListOption[PackageablePath]],
     directory: Path,
-) -> Iterator[Tuple[str, Path, Type[PackFile]]]:
+) -> Iterator[tuple[str, Path, type[PackFile]]]:
     """Expand glob patterns and guess the type of each file."""
     for key, value in mapping.items():
         entries = [
@@ -81,7 +81,7 @@ def resolve_file_mapping(
                 yield dst, entry, guess_file_type(entry)
 
 
-def guess_file_type(filename: FileSystemPath) -> Type[PackFile]:
+def guess_file_type(filename: FileSystemPath) -> type[PackFile]:
     """Helper to figure out the most appropriate file type depending on a filename."""
     filename = str(filename)
 
@@ -90,7 +90,7 @@ def guess_file_type(filename: FileSystemPath) -> Type[PackFile]:
     elif filename.endswith((".yml", ".yaml")):
         return YamlFile
     elif filename.endswith(".png"):
-        return PngFile
+        return PngFileBase
 
     mime_type, _ = mimetypes.guess_type(filename, strict=False)
     if mime_type and mime_type.startswith("text/"):

beet/contrib/dbg.py

@@ -13,7 +13,7 @@
 from dataclasses import dataclass, field
 from functools import cached_property
 from itertools import cycle
-from typing import Any, Dict, List, Tuple
+from typing import Any
 
 from jinja2.nodes import Node, Output, TemplateData
 
@@ -27,7 +27,7 @@ class DbgOptions(PluginOptions):
     enabled: bool = True
     level: str = "info"
 
-    level_config: List[Tuple[str, str]] = [
+    level_config: list[tuple[str, str]] = [
         ("critical", "dark_red"),
         ("error", "red"),
         ("warn", "yellow"),
@@ -74,7 +74,7 @@ def beet_default(ctx: Context):
     ctx.template.env.add_extension(DbgExtension)
 
 
-def get_padding(pixels: int) -> TextComponent:
+def get_padding(pixels: int) -> list[TextComponent]:
     """Generate a sequence of bold and normal spaces matching the given number of pixels."""
     if pixels < 12 and pixels not in [4, 5, 8, 9, 10]:
         raise ValueError(f"Invalid number of pixels {pixels}.")
@@ -108,11 +108,11 @@ def opts(self) -> DbgOptions:
         return self.ctx.validate("dbg", DbgOptions)
 
     @cached_property
-    def level_colors(self) -> Dict[str, str]:
+    def level_colors(self) -> dict[str, str]:
         return dict(self.opts.level_config)
 
     @cached_property
-    def level_ranks(self) -> Dict[str, int]:
+    def level_ranks(self) -> dict[str, int]:
         return {
             level: len(self.opts.level_config) - i
             for i, (level, _) in enumerate(self.opts.level_config)
@@ -131,7 +131,7 @@ def render_preview(self, path: str, lineno: int) -> TextComponent:
         ]
         number_width = max(len(n) for n in numbers)
 
-        output: List[TextComponent] = [""]
+        output: list[TextComponent] = [""]
 
         for number, line, color in zip(numbers, preview, cycle(["#dddddd", "gray"])):
             if len(line) > self.opts.preview_line_limit:

beet/contrib/extra_files.py

@@ -7,18 +7,16 @@
 ]
 
 
-from typing import List
-
 from beet import Context, PluginOptions, configurable
 
 from .copy_files import guess_file_type
 
 
 class ExtraFilesOptions(PluginOptions):
-    resource_pack: List[str] = []
-    data_pack: List[str] = []
-    resource_pack_namespace: List[str] = []
-    data_pack_namespace: List[str] = []
+    resource_pack: list[str] = []
+    data_pack: list[str] = []
+    resource_pack_namespace: list[str] = []
+    data_pack_namespace: list[str] = []
 
 
 def beet_default(ctx: Context):

beet/contrib/find_replace.py

@@ -12,17 +12,17 @@
 
 
 from dataclasses import dataclass
-from typing import Any, Callable, Generic, Sequence, Tuple, TypeVar, Union
+from typing import Any, Callable, Generic, Sequence, Union
 
 from pydantic import BaseModel
 
 from beet import (
     Context,
     DataPack,
     ListOption,
-    Pack,
     PackSelectOption,
     PackSelector,
+    PackType,
     PluginOptions,
     RegexOption,
     ResourcePack,
@@ -31,8 +31,6 @@
     configurable,
 )
 
-PackType = TypeVar("PackType", bound=Pack[Any])
-
 
 class TextSubstitutionOption(BaseModel):
     find: RegexOption
@@ -68,7 +66,7 @@ def compile(self, template: TemplateManager) -> Callable[[str], str]:
 
 
 class SubstitutionOption(BaseModel):
-    __root__: ListOption[Union[TextSubstitutionOption, RenderSubstitutionOption]]
+    __root__: ListOption[TextSubstitutionOption | RenderSubstitutionOption]
 
     def compile(self, template: TemplateManager) -> Callable[[str], str]:
         substitutions = [sub.compile(template) for sub in self.__root__.entries()]
@@ -81,15 +79,19 @@ def apply(value: str) -> str:
         return apply
 
 
+# Using Union because `|` doesn't support strings for forward reference
+SubstituteList = ListOption[Union[SubstitutionOption, "FindReplaceOptions"]]
+
+
 class FindReplaceOptions(PluginOptions):
     resource_pack: PackSelectOption = PackSelectOption()
     data_pack: PackSelectOption = PackSelectOption()
-    substitute: ListOption[Union[SubstitutionOption, "FindReplaceOptions"]]
+    substitute: SubstituteList
 
     def compile(
         self,
         template: TemplateManager,
-    ) -> Tuple["FindReplaceHandler[ResourcePack]", "FindReplaceHandler[DataPack]"]:
+    ) -> tuple["FindReplaceHandler[ResourcePack]", "FindReplaceHandler[DataPack]"]:
         substitute = [sub.compile(template) for sub in self.substitute.entries()]
         return (
             FindReplaceHandler(
@@ -103,7 +105,7 @@ def compile(
         )
 
 
-ListOption[Union[SubstitutionOption, "FindReplaceOptions"]].update_forward_refs()
+SubstituteList.update_forward_refs()
 
 
 @dataclass(frozen=True)

beet/contrib/format_json.py

@@ -8,16 +8,16 @@
 
 
 import json
-from typing import Any, Callable, Optional, Tuple, Union
+from typing import Any, Callable, Optional
 
 from beet import Context, JsonFileBase, PluginOptions, configurable
 
 
 class FormatJsonOptions(PluginOptions):
     ensure_ascii: bool = True
     allow_nan: bool = True
-    indent: Union[int, str, None] = 2
-    separators: Optional[Tuple[str, str]] = None
+    indent: Optional[int | str] = 2
+    separators: Optional[tuple[str, str]] = None
     sort_keys: bool = False
     final_newline: bool = True
 

beet/contrib/function_header.py

@@ -7,13 +7,13 @@
 ]
 
 
-from typing import List, Optional
+from typing import Optional
 
 from beet import Context, PluginOptions, configurable
 
 
 class FunctionHeaderOptions(PluginOptions):
-    match: List[str] = []
+    match: list[str] = []
     template: Optional[str] = "function_header.mcfunction"