Shims

Workarounds for various gaps in the Python language and in its type annotations.

RelPathDirEntry

RelPathDirEntry(inner: DirEntry[str], base: Path, path: Path)

Wraps an os.DirEntry and alters its path attribute to be a Path object which provides the relative pathname from some base directory.

The base directory itself is accessible via the base attribute; this is guaranteed to be a resolved absolute path.

All other documented methods and properties of os.DirEntry are available with the same semantics as the original.

classproperty

classproperty(func: Callable[[type[T]], RT])

Bases: Generic[T, RT]

Decorator which converts a method into a class property; this ought to be spelled

class Thing:
     @property @classmethod
     def prop(cls):
         return "whatever"

but that doesn't work for reasons too tedious to get into (see https://github.com/python/cpython/issues/89519 for gory details) This is the recommended workaround. Note that only read-only properties can be supported (that's one of the tedious reasons).

close_or_forget

close_or_forget(resource: SC)

Bases: Generic[SC]

Context manager wrapper for any object with a close method, which conditionally closes that object on exit from the with-block.

On entry, returns self. The wrapped object can be accessed via the 'resource' property. On exit, the wrapped object's close method is called UNLESS the forget() method has been called to transfer ownership of the wrapped object to the caller.

forget

forget() -> SC

Shorthand: sets self.resource to None and then returns the old value of self.resource.

path_walk

path_walk(root: Path) -> Iterator[RelPathDirEntry]

A mash-up of os.scandir and Path.walk having the best properties of both (hopefully).

Yield RelPathDirEntry objects for each directory entry in the tree rooted at root. The base directory for each object will be root.

Does not follow symlinks within root under any circumstances; you get an entry object for the symlink itself and that's it.

The directory tree should not be modified while the walk is underway.