newmount 0.1.0__py3-none-any.whl

newmount/__init__.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: 0BSD
+"""Python bindings for the Linux mount API.
+
+Two layers: the classic mount(2)/umount2(2) calls with helpers like
+bind() and tmpfs(), and the new mount API (kernel 5.2+) built on
+fsopen/fsconfig/fsmount/move_mount/open_tree/fspick/mount_setattr.
+"""
+
+from __future__ import annotations
+
+from . import flags as flags
+from .classic import (
+    bind,
+    make_private,
+    make_shared,
+    make_slave,
+    make_unbindable,
+    mount,
+    mount_proc,
+    tmpfs,
+    umount,
+    umount2,
+)
+from .errors import MountError, UnsupportedError
+from .flags import *  # noqa: F403 - re-export the constant namespace
+from .flags import __all__ as _flags_all
+from .fsapi import (
+    FsContext,
+    MountAttr,
+    MountFd,
+    Tree,
+    apply_attrs,
+    attach,
+    fsconfig,
+    fsmount,
+    fsopen,
+    fspick,
+    mount_setattr,
+    move_mount,
+    new_api_supported,
+    open_tree,
+    open_tree_clone,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FsContext",
+    "MountAttr",
+    "MountError",
+    "MountFd",
+    "Tree",
+    "UnsupportedError",
+    "__version__",
+    "apply_attrs",
+    "attach",
+    "bind",
+    "flags",
+    "fsconfig",
+    "fsmount",
+    "fsopen",
+    "fspick",
+    "make_private",
+    "make_shared",
+    "make_slave",
+    "make_unbindable",
+    "mount",
+    "mount_proc",
+    "mount_setattr",
+    "move_mount",
+    "new_api_supported",
+    "open_tree",
+    "open_tree_clone",
+    "tmpfs",
+    "umount",
+    "umount2",
+    *_flags_all,
+]

newmount/_syscall.py

@@ -0,0 +1,228 @@
+# SPDX-License-Identifier: 0BSD
+"""Raw ctypes bindings for the Linux mount syscalls.
+
+mount(2) and umount2(2) go through the libc wrappers. The new mount API
+(open_tree, move_mount, fsopen, fsconfig, fsmount, fspick, mount_setattr,
+all since kernel 5.2) goes through libc syscall(2) so no compiler or
+libmount is needed. Every mainline architecture uses the asm-generic
+numbers for these syscalls, verified against /usr/include/asm/unistd_64.h,
+/usr/include/asm/unistd_32.h and /usr/include/asm-generic/unistd.h. MIPS
+applies its ABI base offset instead.
+"""
+
+import ctypes
+import ctypes.util
+import errno
+import os
+import platform
+import sys
+from typing import NamedTuple, NoReturn
+
+from .errors import MountError, UnsupportedError
+
+
+class MountAttr(ctypes.Structure):
+    """struct mount_attr for mount_setattr(2), see /usr/include/linux/mount.h.
+
+    All four fields are u64, so the structure is 32 bytes on every ABI,
+    matching MOUNT_ATTR_SIZE_VER0.
+    """
+
+    _fields_ = [
+        ("attr_set", ctypes.c_uint64),
+        ("attr_clr", ctypes.c_uint64),
+        ("propagation", ctypes.c_uint64),
+        ("userns_fd", ctypes.c_uint64),
+    ]
+
+
+class _Numbers(NamedTuple):
+    """Per-architecture syscall numbers for the new mount API."""
+
+    open_tree: int
+    move_mount: int
+    fsopen: int
+    fsconfig: int
+    fsmount: int
+    fspick: int
+    mount_setattr: int
+
+
+# asm-generic numbering shared by x86_64, i386, aarch64, riscv and all
+# other modern ports
+_GENERIC = _Numbers(428, 429, 430, 431, 432, 433, 442)
+
+_GENERIC_MACHINES = frozenset(
+    {
+        "x86_64",
+        "amd64",
+        "i386",
+        "i486",
+        "i586",
+        "i686",
+        "x86",
+        "aarch64",
+        "arm64",
+        "riscv64",
+        "riscv32",
+        "loongarch64",
+        "s390x",
+        "s390",
+    }
+)
+
+_libc: ctypes.CDLL | None = None
+_numbers: _Numbers | None = None
+
+
+def _get_libc() -> ctypes.CDLL:
+    global _libc
+    if _libc is None:
+        if sys.platform != "linux":
+            raise UnsupportedError("newmount is only available on Linux")
+        name = ctypes.util.find_library("c")
+        _libc = ctypes.CDLL(name or None, use_errno=True)
+        _libc.syscall.restype = ctypes.c_long
+    return _libc
+
+
+def _syscall_numbers() -> _Numbers:
+    """Return the syscall numbers for this architecture."""
+    global _numbers
+    if _numbers is not None:
+        return _numbers
+    machine = platform.machine().lower()
+    if machine in ("mips64", "mips64el"):
+        base = 5000  # n64 ABI
+    elif machine in ("mips", "mipsel", "mips32"):
+        base = 4000  # o32 ABI
+    elif machine in _GENERIC_MACHINES or machine.startswith(("arm", "ppc", "powerpc")):
+        base = 0
+    else:
+        raise UnsupportedError(
+            f"no mount API syscall numbers for architecture {machine}"
+        )
+    _numbers = _Numbers(*(base + n for n in _GENERIC))
+    return _numbers
+
+
+def _raise_errno(err: int) -> NoReturn:
+    if err in (errno.ENOSYS, errno.EOPNOTSUPP):
+        raise UnsupportedError(err, os.strerror(err))
+    raise MountError(err, os.strerror(err))
+
+
+def _call(nr: int, *args: object) -> int:
+    ret = int(_get_libc().syscall(nr, *args))
+    if ret == -1:
+        _raise_errno(ctypes.get_errno())
+    return ret
+
+
+def mount(
+    source: bytes | None,
+    target: bytes,
+    fstype: bytes | None,
+    flags: int,
+    data: bytes | None,
+) -> None:
+    """mount(2) through the libc wrapper."""
+    ret = int(_get_libc().mount(source, target, fstype, ctypes.c_ulong(flags), data))
+    if ret == -1:
+        _raise_errno(ctypes.get_errno())
+
+
+def umount2(target: bytes, flags: int) -> None:
+    """umount2(2) through the libc wrapper."""
+    ret = int(_get_libc().umount2(target, ctypes.c_int(flags)))
+    if ret == -1:
+        _raise_errno(ctypes.get_errno())
+
+
+def fsopen(fstype: bytes, flags: int) -> int:
+    """fsopen(2): open a filesystem context, returns an fd."""
+    return int(_call(_syscall_numbers().fsopen, fstype, ctypes.c_uint(flags)))
+
+
+def fsconfig(
+    fd: int,
+    cmd: int,
+    key: bytes | None,
+    value: bytes | None,
+    aux: int,
+) -> None:
+    """fsconfig(2): pass one parameter or command to a context fd."""
+    _call(
+        _syscall_numbers().fsconfig,
+        ctypes.c_int(fd),
+        ctypes.c_uint(cmd),
+        key,
+        value,
+        ctypes.c_int(aux),
+    )
+
+
+def fsmount(fd: int, flags: int, attr_flags: int) -> int:
+    """fsmount(2): create a detached mount from a context, returns an fd."""
+    return int(
+        _call(
+            _syscall_numbers().fsmount,
+            ctypes.c_int(fd),
+            ctypes.c_uint(flags),
+            ctypes.c_uint(attr_flags),
+        )
+    )
+
+
+def open_tree(dfd: int, path: bytes, flags: int) -> int:
+    """open_tree(2): open or clone a mount tree, returns an fd."""
+    return int(
+        _call(
+            _syscall_numbers().open_tree,
+            ctypes.c_int(dfd),
+            path,
+            ctypes.c_uint(flags),
+        )
+    )
+
+
+def move_mount(
+    from_dfd: int,
+    from_path: bytes,
+    to_dfd: int,
+    to_path: bytes,
+    flags: int,
+) -> None:
+    """move_mount(2): attach or relocate a mount."""
+    _call(
+        _syscall_numbers().move_mount,
+        ctypes.c_int(from_dfd),
+        from_path,
+        ctypes.c_int(to_dfd),
+        to_path,
+        ctypes.c_uint(flags),
+    )
+
+
+def fspick(dfd: int, path: bytes, flags: int) -> int:
+    """fspick(2): reopen an existing mount for reconfiguration."""
+    return int(
+        _call(
+            _syscall_numbers().fspick,
+            ctypes.c_int(dfd),
+            path,
+            ctypes.c_uint(flags),
+        )
+    )
+
+
+def mount_setattr(dfd: int, path: bytes, flags: int, attr: MountAttr) -> None:
+    """mount_setattr(2): change attributes of a mount or mount tree."""
+    _call(
+        _syscall_numbers().mount_setattr,
+        ctypes.c_int(dfd),
+        path,
+        ctypes.c_uint(flags),
+        ctypes.byref(attr),
+        ctypes.c_size_t(ctypes.sizeof(attr)),
+    )

newmount/classic.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: 0BSD
+"""Helpers built on the classic mount(2) and umount2(2) calls."""
+
+from __future__ import annotations
+
+import os
+
+from . import _syscall
+from .flags import (
+    MS_BIND,
+    MS_NODEV,
+    MS_NOEXEC,
+    MS_NOSUID,
+    MS_PRIVATE,
+    MS_RDONLY,
+    MS_REC,
+    MS_REMOUNT,
+    MS_SHARED,
+    MS_SLAVE,
+    MS_UNBINDABLE,
+)
+
+__all__ = [
+    "bind",
+    "make_private",
+    "make_shared",
+    "make_slave",
+    "make_unbindable",
+    "mount",
+    "mount_proc",
+    "tmpfs",
+    "umount",
+    "umount2",
+]
+
+_Path = str | bytes | os.PathLike[str] | os.PathLike[bytes]
+
+
+def mount(
+    source: _Path | None,
+    target: _Path,
+    fstype: str | bytes | None,
+    flags: int = 0,
+    data: str | bytes | None = None,
+) -> None:
+    """Mount a filesystem with mount(2).
+
+    source and fstype may be None for operations that ignore them, such as
+    MS_REMOUNT and propagation changes. data is the filesystem specific
+    option string. Raises MountError on failure.
+    """
+    _syscall.mount(
+        None if source is None else os.fsencode(source),
+        os.fsencode(target),
+        None if fstype is None else os.fsencode(fstype),
+        flags,
+        None if data is None else os.fsencode(data),
+    )
+
+
+def umount2(target: _Path, flags: int = 0) -> None:
+    """Unmount with umount2(2); flags are MNT_* and UMOUNT_* bits."""
+    _syscall.umount2(os.fsencode(target), flags)
+
+
+def umount(target: _Path) -> None:
+    """Unmount a filesystem, equivalent to umount2(target, 0)."""
+    umount2(target, 0)
+
+
+def bind(
+    source: _Path,
+    target: _Path,
+    *,
+    recursive: bool = True,
+    readonly: bool = False,
+) -> None:
+    """Bind mount source onto target.
+
+    A bind mount cannot be created read-only in one call: the kernel
+    applies per-mount flags only at creation time. readonly first binds
+    and then remounts the new mount with MS_REMOUNT|MS_BIND|MS_RDONLY.
+    """
+    flags = MS_BIND | (MS_REC if recursive else 0)
+    mount(source, target, None, flags)
+    if readonly:
+        mount(source, target, None, flags | MS_REMOUNT | MS_RDONLY)
+
+
+def _propagation(target: _Path, flag: int, recursive: bool) -> None:
+    mount(None, target, None, flag | (MS_REC if recursive else 0))
+
+
+def make_private(target: _Path = "/", *, recursive: bool = True) -> None:
+    """Mark target (recursively by default) as private propagation."""
+    _propagation(target, MS_PRIVATE, recursive)
+
+
+def make_shared(target: _Path, *, recursive: bool = True) -> None:
+    """Mark target (recursively by default) as shared propagation."""
+    _propagation(target, MS_SHARED, recursive)
+
+
+def make_slave(target: _Path, *, recursive: bool = True) -> None:
+    """Mark target (recursively by default) as slave propagation."""
+    _propagation(target, MS_SLAVE, recursive)
+
+
+def make_unbindable(target: _Path, *, recursive: bool = True) -> None:
+    """Mark target (recursively by default) as unbindable."""
+    _propagation(target, MS_UNBINDABLE, recursive)
+
+
+def tmpfs(
+    target: _Path,
+    *,
+    size: int | str | None = None,
+    mode: int | str | None = None,
+    uid: int | None = None,
+    gid: int | None = None,
+    flags: int = 0,
+    source: str = "tmpfs",
+) -> None:
+    """Mount a tmpfs at target, building the option string from keywords.
+
+    size is a byte count or a string like "64m". mode is an int rendered
+    as octal or a string passed through unchanged. uid and gid are numeric
+    owner ids for the root inode.
+    """
+    options = []
+    if size is not None:
+        options.append(f"size={size}")
+    if mode is not None:
+        options.append(f"mode={mode:o}" if isinstance(mode, int) else f"mode={mode}")
+    if uid is not None:
+        options.append(f"uid={uid}")
+    if gid is not None:
+        options.append(f"gid={gid}")
+    mount(source, target, "tmpfs", flags, ",".join(options) or None)
+
+
+def mount_proc(target: _Path = "/proc") -> None:
+    """Mount a fresh procfs, usually inside a new pid+mount namespace."""
+    mount("proc", target, "proc", MS_NOSUID | MS_NOEXEC | MS_NODEV)

newmount/errors.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: 0BSD
+"""Exception types raised by newmount."""
+
+
+class MountError(OSError):
+    """A mount related syscall or operation failed."""
+
+
+class UnsupportedError(MountError):
+    """The running kernel or architecture lacks the requested feature."""

newmount/flags.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: 0BSD
+"""Constants for mount(2), umount2(2) and the new mount API.
+
+Values verified against /usr/include/sys/mount.h,
+/usr/include/linux/mount.h and the AT_* bits from
+/usr/include/bits/fcntl-linux.h.
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = [
+    "AT_EMPTY_PATH",
+    "AT_FDCWD",
+    "AT_NO_AUTOMOUNT",
+    "AT_RECURSIVE",
+    "AT_SYMLINK_FOLLOW",
+    "AT_SYMLINK_NOFOLLOW",
+    "FSCONFIG_CMD_CREATE",
+    "FSCONFIG_CMD_CREATE_EXCL",
+    "FSCONFIG_CMD_RECONFIGURE",
+    "FSCONFIG_SET_BINARY",
+    "FSCONFIG_SET_FD",
+    "FSCONFIG_SET_FLAG",
+    "FSCONFIG_SET_PATH",
+    "FSCONFIG_SET_PATH_EMPTY",
+    "FSCONFIG_SET_STRING",
+    "FSMOUNT_CLOEXEC",
+    "FSMOUNT_NAMESPACE",
+    "FSOPEN_CLOEXEC",
+    "FSPICK_CLOEXEC",
+    "FSPICK_EMPTY_PATH",
+    "FSPICK_NO_AUTOMOUNT",
+    "FSPICK_SYMLINK_NOFOLLOW",
+    "MNT_DETACH",
+    "MNT_EXPIRE",
+    "MNT_FORCE",
+    "MOUNT_ATTR_ATIME_SHIFT",
+    "MOUNT_ATTR_IDMAP",
+    "MOUNT_ATTR_NOATIME",
+    "MOUNT_ATTR_NODEV",
+    "MOUNT_ATTR_NODIRATIME",
+    "MOUNT_ATTR_NOEXEC",
+    "MOUNT_ATTR_NOSUID",
+    "MOUNT_ATTR_NOSYMFOLLOW",
+    "MOUNT_ATTR_RDONLY",
+    "MOUNT_ATTR_RELATIME",
+    "MOUNT_ATTR_SIZE_VER0",
+    "MOUNT_ATTR_STRICTATIME",
+    "MOUNT_ATTR__ATIME",
+    "MOVE_MOUNT_BENEATH",
+    "MOVE_MOUNT_F_AUTOMOUNTS",
+    "MOVE_MOUNT_F_EMPTY_PATH",
+    "MOVE_MOUNT_F_SYMLINKS",
+    "MOVE_MOUNT_SET_GROUP",
+    "MOVE_MOUNT_T_AUTOMOUNTS",
+    "MOVE_MOUNT_T_EMPTY_PATH",
+    "MOVE_MOUNT_T_SYMLINKS",
+    "MS_ACTIVE",
+    "MS_BIND",
+    "MS_BORN",
+    "MS_DIRSYNC",
+    "MS_I_VERSION",
+    "MS_KERNMOUNT",
+    "MS_LAZYTIME",
+    "MS_MANDLOCK",
+    "MS_MGC_MSK",
+    "MS_MGC_VAL",
+    "MS_MOVE",
+    "MS_NOATIME",
+    "MS_NODEV",
+    "MS_NODIRATIME",
+    "MS_NOEXEC",
+    "MS_NOSUID",
+    "MS_NOSYMFOLLOW",
+    "MS_NOUSER",
+    "MS_POSIXACL",
+    "MS_PRIVATE",
+    "MS_RDONLY",
+    "MS_REC",
+    "MS_RELATIME",
+    "MS_REMOUNT",
+    "MS_RMT_MASK",
+    "MS_SHARED",
+    "MS_SILENT",
+    "MS_SLAVE",
+    "MS_STRICTATIME",
+    "MS_SUBMOUNT",
+    "MS_SYNCHRONOUS",
+    "MS_UNBINDABLE",
+    "OPEN_TREE_CLOEXEC",
+    "OPEN_TREE_CLONE",
+    "OPEN_TREE_NAMESPACE",
+    "UMOUNT_NOFOLLOW",
+]
+
+# mount(2) rwflag bits, /usr/include/linux/mount.h
+MS_RDONLY = 1
+MS_NOSUID = 2
+MS_NODEV = 4
+MS_NOEXEC = 8
+MS_SYNCHRONOUS = 16
+MS_REMOUNT = 32
+MS_MANDLOCK = 64
+MS_DIRSYNC = 128
+MS_NOSYMFOLLOW = 256
+MS_NOATIME = 1024
+MS_NODIRATIME = 2048
+MS_BIND = 4096
+MS_MOVE = 8192
+MS_REC = 16384
+MS_SILENT = 32768  # MS_VERBOSE is deprecated, same bit
+MS_POSIXACL = 1 << 16
+MS_UNBINDABLE = 1 << 17
+MS_PRIVATE = 1 << 18
+MS_SLAVE = 1 << 19
+MS_SHARED = 1 << 20
+MS_RELATIME = 1 << 21
+MS_KERNMOUNT = 1 << 22
+MS_I_VERSION = 1 << 23
+MS_STRICTATIME = 1 << 24
+MS_LAZYTIME = 1 << 25
+
+# Internal kernel bits, listed for completeness
+MS_SUBMOUNT = 1 << 26
+MS_BORN = 1 << 29
+MS_ACTIVE = 1 << 30
+MS_NOUSER = 1 << 31
+
+# Bits changeable through MS_REMOUNT
+MS_RMT_MASK = MS_RDONLY | MS_SYNCHRONOUS | MS_MANDLOCK | MS_I_VERSION | MS_LAZYTIME
+
+# Legacy magic bits
+MS_MGC_VAL = 0xC0ED0000
+MS_MGC_MSK = 0xFFFF0000
+
+# umount2(2) flags
+MNT_FORCE = 1
+MNT_DETACH = 2
+MNT_EXPIRE = 4
+UMOUNT_NOFOLLOW = 8
+
+# AT_* bits shared by open_tree(2), mount_setattr(2) and friends
+AT_FDCWD = -100
+AT_SYMLINK_NOFOLLOW = 0x100
+AT_SYMLINK_FOLLOW = 0x400
+AT_NO_AUTOMOUNT = 0x800
+AT_EMPTY_PATH = 0x1000
+AT_RECURSIVE = 0x8000
+
+# open_tree(2) flags
+OPEN_TREE_CLONE = 1 << 0
+OPEN_TREE_NAMESPACE = 1 << 1
+OPEN_TREE_CLOEXEC = os.O_CLOEXEC
+
+# move_mount(2) flags
+MOVE_MOUNT_F_SYMLINKS = 0x00000001
+MOVE_MOUNT_F_AUTOMOUNTS = 0x00000002
+MOVE_MOUNT_F_EMPTY_PATH = 0x00000004
+MOVE_MOUNT_T_SYMLINKS = 0x00000010
+MOVE_MOUNT_T_AUTOMOUNTS = 0x00000020
+MOVE_MOUNT_T_EMPTY_PATH = 0x00000040
+MOVE_MOUNT_SET_GROUP = 0x00000100
+MOVE_MOUNT_BENEATH = 0x00000200
+
+# fsopen(2) flags
+FSOPEN_CLOEXEC = 0x00000001
+
+# fsmount(2) flags
+FSMOUNT_CLOEXEC = 0x00000001
+FSMOUNT_NAMESPACE = 0x00000002
+
+# fspick(2) flags
+FSPICK_CLOEXEC = 0x00000001
+FSPICK_SYMLINK_NOFOLLOW = 0x00000002
+FSPICK_NO_AUTOMOUNT = 0x00000004
+FSPICK_EMPTY_PATH = 0x00000008
+
+# fsconfig(2) commands, enum fsconfig_command in /usr/include/linux/mount.h
+FSCONFIG_SET_FLAG = 0
+FSCONFIG_SET_STRING = 1
+FSCONFIG_SET_BINARY = 2
+FSCONFIG_SET_PATH = 3
+FSCONFIG_SET_PATH_EMPTY = 4
+FSCONFIG_SET_FD = 5
+FSCONFIG_CMD_CREATE = 6
+FSCONFIG_CMD_RECONFIGURE = 7
+FSCONFIG_CMD_CREATE_EXCL = 8
+
+# MOUNT_ATTR_* bits for fsmount(2) and mount_setattr(2)
+MOUNT_ATTR_RDONLY = 0x00000001
+MOUNT_ATTR_NOSUID = 0x00000002
+MOUNT_ATTR_NODEV = 0x00000004
+MOUNT_ATTR_NOEXEC = 0x00000008
+MOUNT_ATTR__ATIME = 0x00000070  # mask covering the three atime bits
+MOUNT_ATTR_RELATIME = 0x00000000
+MOUNT_ATTR_NOATIME = 0x00000010
+MOUNT_ATTR_STRICTATIME = 0x00000020
+MOUNT_ATTR_NODIRATIME = 0x00000080
+MOUNT_ATTR_IDMAP = 0x00100000
+MOUNT_ATTR_NOSYMFOLLOW = 0x00200000
+
+# Bit position of the atime field inside MOUNT_ATTR__ATIME
+MOUNT_ATTR_ATIME_SHIFT = 4
+
+# sizeof first published struct mount_attr
+MOUNT_ATTR_SIZE_VER0 = 32

newmount/fsapi.py

@@ -0,0 +1,428 @@
+# SPDX-License-Identifier: 0BSD
+"""The new mount API (kernel 5.2+) plus ergonomic wrappers.
+
+The syscall layer builds a detached mount with fsopen/fsconfig/fsmount,
+attaches it with move_mount, clones an existing tree with open_tree,
+reopens a mount for reconfiguration with fspick and flips attributes in
+place with mount_setattr. All of it requires CAP_SYS_ADMIN in the user
+namespace owning the mount namespace; unprivileged callers get there
+through a user+mount namespace.
+
+Kernel reference:
+https://www.kernel.org/doc/html/latest/filesystems/mount_api.html
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import types
+from typing import TypeVar
+
+from . import _syscall
+from ._syscall import MountAttr
+from .errors import MountError, UnsupportedError
+from .flags import (
+    AT_EMPTY_PATH,
+    AT_FDCWD,
+    AT_RECURSIVE,
+    FSCONFIG_CMD_CREATE,
+    FSCONFIG_CMD_CREATE_EXCL,
+    FSCONFIG_CMD_RECONFIGURE,
+    FSCONFIG_SET_BINARY,
+    FSCONFIG_SET_FD,
+    FSCONFIG_SET_FLAG,
+    FSCONFIG_SET_PATH,
+    FSCONFIG_SET_PATH_EMPTY,
+    FSCONFIG_SET_STRING,
+    FSMOUNT_CLOEXEC,
+    FSOPEN_CLOEXEC,
+    FSPICK_CLOEXEC,
+    MOVE_MOUNT_F_EMPTY_PATH,
+    OPEN_TREE_CLOEXEC,
+    OPEN_TREE_CLONE,
+)
+
+__all__ = [
+    "FsContext",
+    "MountAttr",
+    "MountFd",
+    "Tree",
+    "apply_attrs",
+    "attach",
+    "fsconfig",
+    "fsmount",
+    "fsopen",
+    "fspick",
+    "mount_setattr",
+    "move_mount",
+    "new_api_supported",
+    "open_tree",
+    "open_tree_clone",
+]
+
+_Path = str | bytes | os.PathLike[str] | os.PathLike[bytes]
+
+_OwnedFdT = TypeVar("_OwnedFdT", bound="_OwnedFd")
+
+
+def fsopen(fstype: str | bytes, flags: int = FSOPEN_CLOEXEC) -> int:
+    """Open a filesystem configuration context, returns an fd."""
+    return _syscall.fsopen(os.fsencode(fstype), flags)
+
+
+def fsconfig(
+    fd: int,
+    cmd: int,
+    key: str | bytes | None = None,
+    value: str | bytes | None = None,
+    aux: int = 0,
+) -> None:
+    """Issue one fsconfig(2) command on a context fd.
+
+    cmd is an FSCONFIG_* constant. For SET_STRING and the SET_PATH family,
+    value is the option or path string and aux the dirfd (AT_FDCWD when
+    unset). For SET_BINARY, value is the blob and its length is passed as
+    aux. For SET_FD, pass the file descriptor as aux. The CMD_* actions
+    take neither key nor value.
+    """
+    k = None if key is None else os.fsencode(key)
+    if cmd == FSCONFIG_SET_BINARY:
+        if not isinstance(value, (bytes, bytearray, memoryview)):
+            raise TypeError("FSCONFIG_SET_BINARY requires a bytes value")
+        blob = bytes(value)
+        _syscall.fsconfig(fd, cmd, k, blob, len(blob))
+        return
+    v = None if value is None else os.fsencode(value)
+    _syscall.fsconfig(fd, cmd, k, v, aux)
+
+
+def fsmount(fd: int, flags: int = FSMOUNT_CLOEXEC, attr_flags: int = 0) -> int:
+    """Create a detached mount from a created context, returns an fd.
+
+    attr_flags are MOUNT_ATTR_* bits applied to the new mount.
+    """
+    return _syscall.fsmount(fd, flags, attr_flags)
+
+
+def open_tree(dfd: int, path: _Path, flags: int) -> int:
+    """open_tree(2): duplicate a mount or clone a tree, returns an fd."""
+    return _syscall.open_tree(dfd, os.fsencode(path), flags)
+
+
+def move_mount(
+    from_dfd: int,
+    from_path: _Path,
+    to_dfd: int,
+    to_path: _Path,
+    flags: int = 0,
+) -> None:
+    """move_mount(2): attach a detached mount or relocate an existing one.
+
+    Pass the mount fd as from_dfd with an empty from_path and
+    MOVE_MOUNT_F_EMPTY_PATH to attach it; see attach() for the shortcut.
+    """
+    _syscall.move_mount(
+        from_dfd,
+        os.fsencode(from_path),
+        to_dfd,
+        os.fsencode(to_path),
+        flags,
+    )
+
+
+def fspick(dfd: int, path: _Path, flags: int = FSPICK_CLOEXEC) -> int:
+    """fspick(2): reopen an existing mount as a configuration context."""
+    return _syscall.fspick(dfd, os.fsencode(path), flags)
+
+
+def mount_setattr(dfd: int, path: _Path, flags: int, attr: MountAttr) -> None:
+    """mount_setattr(2): change attributes of a mount or mount tree."""
+    _syscall.mount_setattr(dfd, os.fsencode(path), flags, attr)
+
+
+def attach(
+    fd: int,
+    target: _Path,
+    *,
+    dfd: int = AT_FDCWD,
+    flags: int = 0,
+) -> None:
+    """Attach a detached mount fd (fsmount/open_tree result) at target."""
+    move_mount(fd, "", dfd, target, MOVE_MOUNT_F_EMPTY_PATH | flags)
+
+
+def apply_attrs(
+    path: _Path,
+    *,
+    set: int = 0,  # noqa: A002 - matches the mount_attr field name
+    clear: int = 0,
+    propagation: int = 0,
+    userns_fd: int = 0,
+    recursive: bool = False,
+    dfd: int = AT_FDCWD,
+    flags: int = 0,
+) -> None:
+    """Change mount attributes in place via mount_setattr(2).
+
+    set and clear take MOUNT_ATTR_* bits; only one atime value may appear
+    in set. propagation takes MS_PRIVATE, MS_SHARED, MS_SLAVE or
+    MS_UNBINDABLE, or 0 to leave it unchanged. recursive applies the
+    change to the whole subtree beneath path.
+    """
+    attr = MountAttr(
+        attr_set=set,
+        attr_clr=clear,
+        propagation=propagation,
+        userns_fd=userns_fd,
+    )
+    if recursive:
+        flags |= AT_RECURSIVE
+    p = os.fsencode(path)
+    if not p:
+        flags |= AT_EMPTY_PATH
+    _syscall.mount_setattr(dfd, p, flags, attr)
+
+
+def new_api_supported() -> bool:
+    """Probe whether the kernel provides the new mount API.
+
+    fsopen(2) fails with EPERM without CAP_SYS_ADMIN and with ENODEV for
+    an unknown filesystem; both mean the API exists. ENOSYS maps to
+    UnsupportedError and means the kernel predates 5.2.
+    """
+    try:
+        fd = fsopen("proc", 0)
+    except UnsupportedError:
+        return False
+    except MountError:
+        return True
+    os.close(fd)
+    return True
+
+
+def open_tree_clone(
+    path: _Path,
+    *,
+    recursive: bool = True,
+    cloexec: bool = True,
+    dfd: int = AT_FDCWD,
+    flags: int = 0,
+) -> Tree:
+    """Clone the mount tree rooted at path into a detached Tree.
+
+    recursive passes AT_RECURSIVE so the whole subtree is cloned; with
+    recursive=False only the topmost mount is cloned. The clone is not
+    attached anywhere until Tree.attach() is called.
+    """
+    fl = OPEN_TREE_CLONE | flags
+    if cloexec:
+        fl |= OPEN_TREE_CLOEXEC
+    if recursive:
+        fl |= AT_RECURSIVE
+    return Tree(open_tree(dfd, path, fl))
+
+
+class _OwnedFd:
+    """Base for objects that own a kernel file descriptor."""
+
+    __slots__ = ("_fd",)
+
+    def __init__(self, fd: int) -> None:
+        self._fd = fd
+
+    @property
+    def closed(self) -> bool:
+        """Whether the file descriptor has been closed."""
+        return self._fd < 0
+
+    def fileno(self) -> int:
+        """Return the underlying file descriptor."""
+        if self._fd < 0:
+            raise ValueError("file descriptor is closed")
+        return self._fd
+
+    def close(self) -> None:
+        """Close the file descriptor. Safe to call twice."""
+        if self._fd >= 0:
+            os.close(self._fd)
+            self._fd = -1
+
+    def __copy__(self) -> _OwnedFd:
+        raise TypeError(
+            f"{type(self).__name__} cannot be copied; it owns a kernel file descriptor"
+        )
+
+    def __deepcopy__(self, memo: dict[int, object]) -> _OwnedFd:
+        raise TypeError(
+            f"{type(self).__name__} cannot be copied; it owns a kernel file descriptor"
+        )
+
+    def __repr__(self) -> str:
+        state = "closed" if self.closed else "open"
+        return f"{type(self).__name__}(fd={self._fd}, {state})"
+
+    def __enter__(self: _OwnedFdT) -> _OwnedFdT:
+        if self.closed:
+            raise RuntimeError(f"{type(self).__name__} is closed")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # __del__ must never raise
+        with contextlib.suppress(Exception):
+            self.close()
+
+
+class MountFd(_OwnedFd):
+    """A detached mount fd, the result of fsmount() or open_tree().
+
+    The mount is not part of the file hierarchy until attach() moves it
+    under a mountpoint. Use as a context manager or call close() to
+    release the fd.
+    """
+
+    __slots__ = ()
+
+    def attach(
+        self,
+        target: _Path,
+        *,
+        dfd: int = AT_FDCWD,
+        flags: int = 0,
+    ) -> None:
+        """Attach this detached mount at target via move_mount(2)."""
+        attach(self.fileno(), target, dfd=dfd, flags=flags)
+
+    def apply_attrs(
+        self,
+        *,
+        set: int = 0,  # noqa: A002 - matches the mount_attr field name
+        clear: int = 0,
+        propagation: int = 0,
+        userns_fd: int = 0,
+        recursive: bool = False,
+    ) -> None:
+        """Change attributes on this mount via mount_setattr(2)."""
+        apply_attrs(
+            "",
+            set=set,
+            clear=clear,
+            propagation=propagation,
+            userns_fd=userns_fd,
+            recursive=recursive,
+            dfd=self.fileno(),
+        )
+
+
+class Tree(MountFd):
+    """A detached clone of an existing mount tree (OPEN_TREE_CLONE)."""
+
+    __slots__ = ()
+
+
+class FsContext(_OwnedFd):
+    """Filesystem configuration context from fsopen(2) or fspick(2).
+
+    Configure parameters with set()/set_flag()/set_path(), then create()
+    to instantiate the superblock and mount() to obtain a detached
+    MountFd:
+
+        with FsContext("tmpfs") as ctx:
+            ctx.set("size", "16m")
+            ctx.create()
+            with ctx.mount() as mnt:
+                mnt.attach("/mnt/scratch")
+
+    FsContext.pick() reopens an existing mount so reconfigure() can change
+    its parameters.
+    """
+
+    __slots__ = ()
+
+    def __init__(self, fstype: str | bytes, flags: int = FSOPEN_CLOEXEC) -> None:
+        super().__init__(fsopen(fstype, flags))
+
+    @classmethod
+    def _adopt(cls, fd: int) -> FsContext:
+        self = cls.__new__(cls)
+        _OwnedFd.__init__(self, fd)
+        return self
+
+    @classmethod
+    def pick(
+        cls,
+        path: _Path,
+        *,
+        dfd: int = AT_FDCWD,
+        flags: int = FSPICK_CLOEXEC,
+    ) -> FsContext:
+        """Reopen the mount at path for reconfiguration via fspick(2)."""
+        return cls._adopt(fspick(dfd, path, flags))
+
+    def _config(
+        self,
+        cmd: int,
+        key: str | bytes | None = None,
+        value: str | bytes | None = None,
+        aux: int = 0,
+    ) -> None:
+        fsconfig(self.fileno(), cmd, key, value, aux)
+
+    def set_flag(self, key: str | bytes) -> None:
+        """Set a parameter that takes no value (FSCONFIG_SET_FLAG)."""
+        self._config(FSCONFIG_SET_FLAG, key)
+
+    def set(self, key: str | bytes, value: str | bytes | int) -> None:
+        """Set one parameter, dispatching on the value type.
+
+        str sends FSCONFIG_SET_STRING, bytes sends FSCONFIG_SET_BINARY and
+        int sends FSCONFIG_SET_FD with the value as the file descriptor.
+        Numeric filesystem options are passed as strings.
+        """
+        if isinstance(value, str):
+            self._config(FSCONFIG_SET_STRING, key, value)
+        elif isinstance(value, (bytes, bytearray, memoryview)):
+            self._config(FSCONFIG_SET_BINARY, key, bytes(value))
+        elif isinstance(value, int):
+            self._config(FSCONFIG_SET_FD, key, None, value)
+        else:
+            raise TypeError(f"unsupported fsconfig value type: {type(value)!r}")
+
+    def set_path(
+        self,
+        key: str | bytes,
+        path: _Path,
+        *,
+        dfd: int = AT_FDCWD,
+        allow_empty: bool = False,
+    ) -> None:
+        """Set a parameter that takes a path (FSCONFIG_SET_PATH)."""
+        cmd = FSCONFIG_SET_PATH_EMPTY if allow_empty else FSCONFIG_SET_PATH
+        self._config(cmd, key, os.fsencode(path), dfd)
+
+    def create(self, *, exclusive: bool = False) -> None:
+        """Instantiate the superblock (FSCONFIG_CMD_CREATE).
+
+        exclusive uses FSCONFIG_CMD_CREATE_EXCL to fail rather than reuse
+        an existing matching superblock.
+        """
+        self._config(FSCONFIG_CMD_CREATE_EXCL if exclusive else FSCONFIG_CMD_CREATE)
+
+    def reconfigure(self) -> None:
+        """Apply queued parameters to an existing superblock."""
+        self._config(FSCONFIG_CMD_RECONFIGURE)
+
+    def mount(self, attr_flags: int = 0, *, flags: int = FSMOUNT_CLOEXEC) -> MountFd:
+        """Create a detached mount from this context via fsmount(2).
+
+        attr_flags are MOUNT_ATTR_* bits applied to the new mount.
+        """
+        return MountFd(fsmount(self.fileno(), flags, attr_flags))

newmount-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: newmount
+Version: 0.1.0
+Summary: Python bindings for the Linux mount API
+Project-URL: Homepage, https://quad4.io
+Project-URL: Repository, https://github.com/Quad4-Software/newmount
+Project-URL: Issues, https://github.com/Quad4-Software/newmount/issues
+Project-URL: Changelog, https://github.com/Quad4-Software/newmount/blob/master/CHANGELOG.md
+Author: Quad4
+License-Expression: 0BSD
+License-File: LICENSE
+Keywords: filesystems,fsopen,linux,mount,namespaces
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# newmount
+
+[![CI](https://github.com/Quad4-Software/newmount/actions/workflows/ci.yml/badge.svg)](https://github.com/Quad4-Software/newmount/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/Quad4-Software/newmount/actions/workflows/codeql.yml/badge.svg)](https://github.com/Quad4-Software/newmount/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Quad4-Software/newmount/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Quad4-Software/newmount)
+[![PyPI](https://img.shields.io/pypi/v/newmount.svg)](https://pypi.org/project/newmount/)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue)](LICENSE)
+
+Dependency-free ctypes bindings for the Linux mount API: the classic
+mount(2)/umount2(2) calls, and the new mount API (kernel 5.2+) built on
+fsopen, fsconfig, fsmount, open_tree, move_mount, fspick and
+mount_setattr.
+
+Requires Python 3.10+ and Linux. Mounting needs CAP_SYS_ADMIN; an
+unprivileged process gets there inside a user+mount namespace
+(`unshare -Urm`).
+
+## Install
+
+    pip install newmount
+
+## Example: classic bind mount
+
+    import newmount
+
+    # bind recursively, then remount read-only
+    newmount.bind("/srv/data", "/mnt/data", readonly=True)
+
+## Example: clone, reconfigure and attach with the new API
+
+    import newmount
+
+    # clone the tree, flip the clone read-only, attach it
+    with newmount.open_tree_clone("/srv/data") as tree:
+        tree.apply_attrs(set=newmount.MOUNT_ATTR_RDONLY)
+        tree.attach("/mnt/data")
+
+    # or build a fresh filesystem from scratch
+    with newmount.FsContext("tmpfs") as ctx:
+        ctx.set("size", "16m")
+        ctx.create()
+        with ctx.mount() as mnt:
+            mnt.attach("/mnt/scratch")
+
+## Development
+
+    uv sync --group dev
+    make check
+
+License: 0BSD. Quad4 Software, https://quad4.io

newmount-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+newmount/__init__.py,sha256=a8D7d0RNHXcT_Sj9BPkdRIwV4p3CXK6pmPcEc-uzbjw,1478
+newmount/_syscall.py,sha256=toPaWfDsxEqBYcumZWOzAOc9iJ0a_YHnsPe9CBbTKqQ,5969
+newmount/classic.py,sha256=1KvlxiBWmVY699ImNnyN_dovM7Llyp4ZHrA0I9pxbSU,4047
+newmount/errors.py,sha256=ZM9_2PTG5mRbpYHzpyeqnsCMKFVEK_jvttKaNZmtkuA,270
+newmount/flags.py,sha256=tLIV6bNcWCdwR9LaWiahnQ6eqlqKM_RRck5gPiWj6mc,4930
+newmount/fsapi.py,sha256=vDw971UCmwf-wRhthu9gspcUZk5qoja0dXyeA4pna9w,12625
+newmount/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+newmount-0.1.0.dist-info/METADATA,sha256=4tr-hgWaFDq2jYuL6bba2iaVVNj3vKQBPiz3n2MQGu0,3022
+newmount-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+newmount-0.1.0.dist-info/licenses/LICENSE,sha256=3Hnwsz5EXuTC9iTlGjzA171dKQtIVsgjFoF5DEMRl48,633
+newmount-0.1.0.dist-info/RECORD,,

newmount-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

newmount-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026 Quad4
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.