charmlibs-pathops 0.0.0__py3-none-any.whl

charmlibs/pathops/_errors.py

@@ -0,0 +1,120 @@
+# Copyright 2025 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Methods for matching Python Exceptions to Pebble Errors and creating Exception objects."""
+
+from __future__ import annotations
+
+import errno
+import os
+from typing import NoReturn
+
+from ops import pebble
+
+
+def raise_if_matches_directory_not_empty(error: pebble.Error, msg: str) -> None:
+    if (
+        isinstance(error, pebble.PathError)
+        and error.kind == 'generic-file-error'
+        and 'directory not empty' in error.message
+    ):
+        raise OSError(errno.ENOTEMPTY, os.strerror(errno.ENOTEMPTY), msg) from error
+
+
+def raise_file_exists(msg: str, from_: BaseException | None = None) -> NoReturn:
+    e = FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), msg)
+    raise e from from_
+
+
+def raise_if_matches_file_exists(error: pebble.Error, msg: str) -> None:
+    if (
+        isinstance(error, pebble.PathError)
+        and error.kind == 'generic-file-error'
+        and 'file exists' in error.message
+    ):
+        raise_file_exists(msg, from_=error)
+
+
+def raise_file_not_found(msg: str, from_: BaseException | None = None) -> NoReturn:
+    # pebble will return this error when trying to read_{text,bytes} a socket
+    # pathlib raises OSError(errno.ENXIO, os.strerror(errno.ENXIO), path) in this case
+    # displaying as "OSError: [Errno 6] No such device or address: '/path'"
+    # since FileNotFoundError is a subtype of OSError, and this case should be rare
+    # it seems sensible to just raise FileNotFoundError here, without checking
+    # if the file in question is a socket
+    raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), msg) from from_
+
+
+def raise_if_matches_file_not_found(error: pebble.Error, msg: str) -> None:
+    if (isinstance(error, pebble.APIError) and error.code == 404) or (
+        isinstance(error, pebble.PathError) and error.kind == 'not-found'
+    ):
+        raise_file_not_found(msg, from_=error)
+
+
+def raise_is_a_directory(msg: str, from_: BaseException | None = None) -> None:
+    raise IsADirectoryError(errno.EISDIR, os.strerror(errno.EISDIR), msg) from from_
+
+
+def raise_if_matches_is_a_directory(error: pebble.Error, msg: str) -> None:
+    if (
+        isinstance(error, pebble.PathError)
+        and error.kind == 'generic-file-error'
+        and 'can only read a regular file' in error.message
+    ):
+        raise_is_a_directory(msg, from_=error)
+
+
+def raise_if_matches_lookup(error: pebble.Error, msg: str) -> None:
+    if (
+        isinstance(error, pebble.PathError)
+        and error.kind == 'generic-file-error'
+        and 'cannot look up user and group' in error.message
+    ):
+        raise LookupError(msg) from error
+
+
+def matches_not_a_directory(error: pebble.Error) -> bool:
+    return (
+        isinstance(error, pebble.APIError)
+        and error.code == 400
+        and 'not a directory' in error.message
+    ) or (
+        isinstance(error, pebble.PathError)
+        and error.kind == 'generic-file-error'
+        and 'not a directory' in error.message
+    )
+
+
+def raise_not_a_directory(msg: str, from_: BaseException | None = None) -> NoReturn:
+    raise NotADirectoryError(errno.ENOTDIR, os.strerror(errno.ENOTDIR), msg) from from_
+
+
+def raise_if_matches_not_a_directory(error: pebble.Error, msg: str) -> None:
+    if matches_not_a_directory(error):
+        raise_not_a_directory(msg, from_=error)
+
+
+def raise_if_matches_permission(error: pebble.Error, msg: str) -> None:
+    if isinstance(error, pebble.PathError) and error.kind == 'permission-denied':
+        raise PermissionError(errno.EPERM, os.strerror(errno.EPERM), msg) from error
+
+
+def raise_if_matches_too_many_levels_of_symlinks(error: pebble.Error, msg: str) -> None:
+    if (
+        isinstance(error, pebble.APIError)
+        and error.code == 400
+        and 'too many levels of symbolic links' in error.message
+    ):
+        raise OSError(errno.ELOOP, os.strerror(errno.ELOOP), msg) from error

charmlibs/pathops/_fileinfo.py

@@ -0,0 +1,97 @@
+# Copyright 2024 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Utilities for creating and working with :class:`ops.pebble.FileInfo` objects."""
+
+from __future__ import annotations
+
+import datetime
+import grp
+import pwd
+import stat
+import typing
+
+from ops import pebble
+
+from . import _errors
+
+if typing.TYPE_CHECKING:
+    import pathlib
+
+    from ._container_path import ContainerPath
+
+
+_FT_MAP: dict[int, pebble.FileType] = {
+    stat.S_IFREG: pebble.FileType.FILE,
+    stat.S_IFDIR: pebble.FileType.DIRECTORY,
+    stat.S_IFLNK: pebble.FileType.SYMLINK,
+    stat.S_IFSOCK: pebble.FileType.SOCKET,
+    stat.S_IFIFO: pebble.FileType.NAMED_PIPE,
+    stat.S_IFBLK: pebble.FileType.DEVICE,  # block device
+    stat.S_IFCHR: pebble.FileType.DEVICE,  # character device
+}
+
+
+def from_container_path(path: ContainerPath, follow_symlinks: bool = True) -> pebble.FileInfo:
+    if follow_symlinks:
+        return _get_fileinfo_directly(path)
+    return _get_fileinfo_from_parent(path)
+
+
+def _get_fileinfo_directly(path: ContainerPath) -> pebble.FileInfo:
+    try:
+        info_list = path._container.list_files(path._path, itself=True)
+    except (pebble.APIError, pebble.PathError) as e:
+        msg = repr(path)
+        _errors.raise_if_matches_file_not_found(e, msg=msg)
+        _errors.raise_if_matches_not_a_directory(e, msg=msg)
+        _errors.raise_if_matches_permission(e, msg=msg)
+        _errors.raise_if_matches_too_many_levels_of_symlinks(e, msg=msg)
+        raise
+    assert len(info_list) == 1, 'ops.Container.list_files with itself=True returns 1 item'
+    return info_list[0]
+
+
+def _get_fileinfo_from_parent(path: ContainerPath) -> pebble.FileInfo:
+    try:
+        info_list = path._container.list_files(path._path.parent, pattern=path.name)
+    except (pebble.APIError, pebble.PathError) as e:
+        msg = repr(path)
+        _errors.raise_if_matches_file_not_found(e, msg=msg)
+        _errors.raise_if_matches_permission(e, msg=msg)
+        raise
+    if not info_list:
+        _errors.raise_file_not_found(repr(path))
+    assert len(info_list) == 1, 'ops.Container.list_files with non-* pattern should return 1 item'
+    return info_list[0]
+
+
+def from_pathlib_path(path: pathlib.Path, follow_symlinks: bool = True) -> pebble.FileInfo:
+    stat_result = path.stat() if follow_symlinks else path.lstat()
+    utcoffset = datetime.datetime.now().astimezone().utcoffset()
+    timezone = datetime.timezone(utcoffset) if utcoffset is not None else datetime.timezone.utc
+    filetype = _FT_MAP.get(stat.S_IFMT(stat_result.st_mode), pebble.FileType.UNKNOWN)
+    size = stat_result.st_size if filetype is pebble.FileType.FILE else None
+    return pebble.FileInfo(
+        path=str(path),
+        name=path.name,
+        type=filetype,
+        size=size,
+        permissions=stat.S_IMODE(stat_result.st_mode),
+        last_modified=datetime.datetime.fromtimestamp(int(stat_result.st_mtime), tz=timezone),
+        user_id=stat_result.st_uid,
+        user=pwd.getpwuid(stat_result.st_uid).pw_name,
+        group_id=stat_result.st_gid,
+        group=grp.getgrgid(stat_result.st_gid).gr_name,
+    )

charmlibs/pathops/_functions.py

@@ -0,0 +1,104 @@
+# Copyright 2024 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Public helper functions exported by this package."""
+
+from __future__ import annotations
+
+import pathlib
+import typing
+
+from . import _constants, _fileinfo
+from ._container_path import ContainerPath
+from ._local_path import LocalPath
+
+if typing.TYPE_CHECKING:
+    import os
+    from typing import BinaryIO, TextIO
+
+    from ops import pebble
+    from typing_extensions import TypeIs
+
+    from ._types import PathProtocol
+
+
+def ensure_contents(
+    path: str | os.PathLike[str] | PathProtocol,
+    source: bytes | str | BinaryIO | TextIO,
+    *,
+    mode: int = _constants.DEFAULT_WRITE_MODE,
+    user: str | None = None,
+    group: str | None = None,
+) -> bool:
+    """Ensure ``source`` can be read from ``path``. Return True if any changes were made.
+
+    Ensure that ``path`` exists, contains ``source``, has the correct permissions (``mode``),
+    and has the correct file ownership (``user`` and ``group``).
+
+    Args:
+        path: A local or remote filesystem path.
+        source: The desired contents in ``str`` or ``bytes`` form, or an object with a ``.read()``
+            method which returns a ``str`` or ``bytes`` object.
+        mode: The desired file permissions.
+        user: The desired file owner, or ``None`` to not change the owner.
+        group: The desired group, or ``None`` to not change the group.
+
+    Returns:
+        ``True`` if any changes were made, including permissions or ownership, otherwise ``False``.
+
+    Raises:
+        LookupError: if the user or group is unknown.
+        NotADirectoryError: if the parent exists as a non-directory file.
+        PermissionError: if the user does not have permissions for the operation.
+        :class:`PebbleConnectionError`: if the remote Pebble client cannot be reached.
+    """
+    if _is_str_pathlike(path):
+        path = LocalPath(path)
+    source = _as_bytes(source)
+    try:
+        info = _get_fileinfo(path)
+    except FileNotFoundError:
+        pass  # file doesn't exist, so writing is required
+    else:  # check if metadata and contents already match
+        if (
+            (info.permissions == mode)
+            and (user is None or info.user == user)
+            and (group is None or info.group == group)
+            and (path.read_bytes() == source)
+        ):
+            return False  # everything matches, so writing is not required
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(source, mode=mode, user=user, group=group)
+    return True
+
+
+def _is_str_pathlike(obj: object) -> TypeIs[str | os.PathLike[str]]:
+    return isinstance(obj, str) or hasattr(obj, '__fspath__')
+
+
+def _get_fileinfo(
+    path: str | os.PathLike[str] | PathProtocol, follow_symlinks: bool = True
+) -> pebble.FileInfo:
+    if isinstance(path, ContainerPath):
+        return _fileinfo.from_container_path(path, follow_symlinks=follow_symlinks)
+    assert _is_str_pathlike(path)
+    return _fileinfo.from_pathlib_path(pathlib.Path(path), follow_symlinks=follow_symlinks)
+
+
+def _as_bytes(source: bytes | str | BinaryIO | TextIO) -> bytes:
+    if isinstance(source, bytes):
+        return source
+    if isinstance(source, str):
+        return source.encode()
+    return _as_bytes(source.read())

charmlibs/pathops/_local_path.py

@@ -0,0 +1,224 @@
+# Copyright 2024 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Implementation of LocalPath class."""
+
+from __future__ import annotations
+
+import grp
+import pathlib
+import pwd
+import shutil
+import typing
+
+from . import _constants
+
+if typing.TYPE_CHECKING:
+    from typing_extensions import Buffer
+
+
+class LocalPath(pathlib.PosixPath):
+    r""":class:`pathlib.PosixPath` subclass with extended file-creation method arguments.
+
+    .. note::
+        The :meth:`write_bytes`, :meth:`write_text`, and :meth:`mkdir` methods are extended with
+        file permission and ownership arguments, for compatibility with :class:`PathProtocol`.
+
+    Args:
+        \*parts: :class:`str` or :class:`os.PathLike`. ``LocalPath`` takes no keyword arguments.
+
+    ::
+
+        LocalPath(pathlib.Path('/foo'))
+        LocalPath('/', 'foo')
+    """
+
+    def write_bytes(
+        self,
+        data: Buffer,
+        *,
+        mode: int | None = None,
+        user: str | None = None,
+        group: str | None = None,
+    ) -> int:
+        """Write the provided data to the corresponding local filesystem path.
+
+        Compared to :meth:`pathlib.Path.write_bytes`, this method adds ``mode``, ``user``
+        and ``group`` args. These are used to set the permissions and ownership of the file.
+
+        Args:
+            data: The bytes to write, typically a :class:`bytes` object, but may also be a
+                :class:`bytearray` or :class:`memoryview`.
+            mode: The permissions to set on the file. Defaults to 0o644 (-rw-r--r--) for new files.
+                If the file already exists, its permissions will be changed, using
+                :meth:`pathlib.PosixPath.chmod`, unless ``mode`` is ``None`` (default).
+            user: The name of the user to set for the file using :func:`shutil.chown`.
+                Validated to be an existing user before writing.
+                If the file already exists, its user and group will be changed,
+                unless ``user`` is ``None`` (default).
+            group: The name of the group to set for the file using :func:`shutil.chown`.
+                Validated to be an existing group before writing.
+                If the file already exists, its group will be changed,
+                unless ``user`` and ``group`` are ``None`` (default).
+
+        Returns:
+            The number of bytes written.
+
+        Raises:
+            FileNotFoundError: if the parent directory does not exist.
+            LookupError: if the user or group is unknown.
+            NotADirectoryError: if the parent exists as a non-directory file.
+            PermissionError: if the local user does not have permissions for the operation.
+        """
+        _validate_user_and_group(user=user, group=group)
+        if mode is None:
+            # create the file with Pebble's default write mode if it doesn't exist
+            # doesn't change the mode if the file already exists
+            self.touch(mode=_constants.DEFAULT_WRITE_MODE)
+        bytes_written = super().write_bytes(data)
+        _chown_if_needed(self, user=user, group=group)
+        if mode is not None:
+            # explicitly set the mode if the user requested it
+            self.chmod(mode)
+        return bytes_written
+
+    def write_text(
+        self,
+        data: str,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+        *,
+        mode: int | None = None,
+        user: str | None = None,
+        group: str | None = None,
+    ) -> int:
+        r"""Write the provided string to the corresponding local filesystem path.
+
+        Compared to :meth:`pathlib.Path.write_bytes`, this method adds ``mode``, ``user``
+        and ``group`` args. These are used to set the permissions and ownership of the file.
+
+        .. warning::
+            :class:`ContainerPath` and :class:`PathProtocol` do not support the ``encoding``,
+            ``errors``, and ``newline`` arguments of :meth:`pathlib.Path.write_text`.
+            For :class:`ContainerPath` compatible code, do not use these arguments.
+            They are provided to allow :class:`LocalPath` to be used as a drop-in
+            replacement for :class:`pathlib.Path` if needed.
+
+        Args:
+            data: The string to write. Newlines are not modified on writing.
+            encoding: The encoding to use when writing the data, defaults to 'UTF-8'.
+            errors: 'strict' to raise any encoding errors, 'ignore' to ignore them.
+                Defaults to 'strict'.
+            newline: If ``None``, ``''``, or ``'\n'``, then '\n' will be written as is.
+                This is the default behaviour. If ``newline`` is ``'\r'`` or ``'\r\n'``,
+                then ``'\n'`` will be replaced with ``newline`` in memory before writing.
+            mode: The permissions to set on the file. Defaults to 0o644 (-rw-r--r--) for new files.
+                If the file already exists, its permissions will be changed, using
+                :meth:`pathlib.PosixPath.chmod`, unless ``mode`` is ``None`` (default).
+            user: The name of the user to set for the file using :func:`shutil.chown`.
+                Validated to be an existing user before writing.
+                If the file already exists, its user and group will be changed,
+                unless ``user`` is ``None`` (default).
+            group: The name of the group to set for the file using :func:`shutil.chown`.
+                Validated to be an existing group before writing.
+                If the file already exists, its group will be changed,
+                unless ``user`` and ``group`` are ``None`` (default).
+
+        Returns:
+            The number of bytes written.
+
+        Raises:
+            FileNotFoundError: if the parent directory does not exist.
+            LookupError: if the user or group is unknown.
+            NotADirectoryError: if the parent exists as a non-directory file.
+            PermissionError: if the local user does not have permissions for the operation.
+            ValueError: if ``newline`` is any value other than those documented above.
+        """
+        _validate_user_and_group(user=user, group=group)
+        if newline in ('\r', '\r\n'):
+            data = data.replace('\n', newline)
+        elif newline not in ('', '\n', None):
+            raise ValueError(f'illegal newline value: {newline!r}')
+        if mode is None:
+            # create the file with Pebble's default write mode
+            self.touch(mode=_constants.DEFAULT_WRITE_MODE)
+        bytes_written = super().write_text(data, encoding=encoding, errors=errors)
+        _chown_if_needed(self, user=user, group=group)
+        if mode is not None:
+            # explicitly set the mode if the user requested it
+            self.chmod(mode)
+        return bytes_written
+
+    def mkdir(
+        self,
+        mode: int = _constants.DEFAULT_MKDIR_MODE,
+        parents: bool = False,
+        exist_ok: bool = False,
+        *,
+        user: str | None = None,
+        group: str | None = None,
+    ) -> None:
+        """Create a new directory at the corresponding local filesystem path.
+
+        Compared to :meth:`pathlib.Path.mkdir`, this method adds ``user`` and ``group`` args.
+        These are used to set the ownership of the created directory. Any created parents
+        will not have their ownership set.
+
+        Args:
+            mode: The permissions to set on the created directory. Any parents created will have
+                their permissions set to the default value of 0o755 (drwxr-xr-x).
+                The permissions are not changed if the directory already exists.
+            parents: Whether to create any missing parent directories as well. If ``False``
+                (default) and a parent directory does not exist, a :class:`FileNotFound` error will
+                be raised.
+            exist_ok: Whether to raise an error if the directory already exists.
+                If ``False`` (default) and the directory already exists,
+                a :class:`FileExistsError` will be raised.
+            user: The name of the user to set for the directory using :func:`shutil.chown`.
+                Validated to be an existing user before writing.
+                The user and group are not changed if the directory already exists.
+            group: The name of the group to set for the directory using :func:`shutil.chown`.
+                Validated to be an existing group before writing.
+                The user and group are not changed if the directory already exists.
+
+        Raises:
+            FileExistsError: if the directory already exists and ``exist_ok`` is ``False``.
+            FileNotFoundError: if the parent directory does not exist and ``parents`` is ``False``.
+            LookupError: if the user or group is unknown.
+            NotADirectoryError: if the parent exists as a non-directory file.
+            PermissionError: if the local user does not have permissions for the operation.
+        """
+        _validate_user_and_group(user=user, group=group)
+        already_exists = self.exists()
+        super().mkdir(mode=mode, parents=parents, exist_ok=exist_ok)
+        if not already_exists:
+            _chown_if_needed(self, user=user, group=group)
+
+
+def _validate_user_and_group(user: str | None, group: str | None):
+    if user is not None:
+        pwd.getpwnam(user)
+    if group is not None:
+        grp.getgrnam(group)
+
+
+def _chown_if_needed(path: pathlib.Path, user: str | int | None, group: str | int | None) -> None:
+    if user is not None:
+        if group is None:  # use the user's group, following Pebble
+            info = pwd.getpwnam(user) if isinstance(user, str) else pwd.getpwuid(user)
+            group = info.pw_gid
+        shutil.chown(path, user=user, group=group)
+    elif group is not None:
+        shutil.chown(path, group=group)