lib: Add hierarchical FileType framework

Introduce FileType, a class consisting of a name and a parent property,
designed to make the information FileContext.stat() provides about a
path-addressable object richer.

A FileType property goes as ftype into the StatResult structure. Along with
it, this commit adds a central registry (FileTypes) where the type hierarchy
is kept, and additional parameters to put() and mkdir() to allow creating
typed FileContext objects.

Builtin types are:

  - FT_REG: A regular file, the default thing put() creates
  - FT_DIR: A directory, the default thing mkdir() creates
  - FT_TOP: The parent of the two
  - FT_COMPOUND: An FT_REG returning child entries from readdir()

Signed-off-by: Jan Lindemann <jan@janware.com>
Assisted-by: unsloth/Qwen3.8-27B-GGUF:Q4_K_M with pi.dev v1.0.1

src/python/jw/pkg/lib/FileContext.py

@@ -6,12 +6,14 @@ from enum import Enum, auto
 from functools import cached_property
 from typing import TYPE_CHECKING, Any, Iterable, override
 
+from .file_types import FT_DIR, FT_REG
 from .log import DEBUG, ERR, log
 from .ProcFilter import ProcPipeline
 from .Uri import Uri
 
 if TYPE_CHECKING:
     from .base import Result, StatResult
+    from .file_types import FileType
     from .ProcFilter import ProcFilter
 
 class FileContext(abc.ABC):
@@ -161,6 +163,7 @@ class FileContext(abc.ABC):
         group: str | None,
         mode: str | None,
         atomic: bool,
+        ftype: FileType,
     ) -> Result:
         raise NotImplementedError()
 
@@ -176,6 +179,7 @@ class FileContext(abc.ABC):
         group: str | None = None,
         mode: int | None = None,
         atomic: bool = False,
+        ftype: FileType = FT_REG,
     ) -> Result:
         mode_str = None if mode is None else oct(mode).replace('0o', '0')
         if self.__out_pipe is not None:
@@ -191,6 +195,7 @@ class FileContext(abc.ABC):
             group = group,
             mode = mode_str,
             atomic = atomic,
+            ftype = ftype,
         )
 
     async def _unlink(self, path: str) -> None:
@@ -217,11 +222,13 @@ class FileContext(abc.ABC):
     async def rename(self, src: str, dst: str) -> None:
         return await self._rename(src, dst)
 
-    async def _mkdir(self, path: str, mode: int) -> None:
+    async def _mkdir(self, path: str, mode: int, ftype: FileType) -> None:
         raise NotImplementedError(f'{self.log_name}: mkdir({path}) is not implemented')
 
-    async def mkdir(self, path: str, mode: int = 0o777) -> None:
-        return await self._mkdir(self._chroot(path), mode)
+    async def mkdir(
+        self, path: str, mode: int = 0o777, ftype: FileType = FT_DIR
+    ) -> None:
+        return await self._mkdir(self._chroot(path), mode, ftype)
 
     async def _mktemp(self, tmpl: str, directory: bool) -> str:
         raise NotImplementedError(