charmlibs-pathops 0.0.0__py3-none-any.whl

charmlibs/pathops/__init__.py

@@ -0,0 +1,54 @@
+# 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.
+
+r""":mod:`pathlib`-like interface for local and :class:`ops.Container` filesystem paths.
+
+The ``pathops`` charm library provides:
+
+- :class:`PathProtocol`: defines the interface of methods common to both local and container paths.
+  Use this to type annotate code designed to work on both Kubernetes and machine charms.
+- :class:`ContainerPath`: the concrete implementation of the interface for remote paths in the
+  workload container of Kubernetes charms. Operations are implemented using the Pebble file API.
+- :class:`LocalPath`: the concrete implementation of the interface for local paths, which includes
+  both machine charms and the charm container of Kubernetes charms.
+- Top-level helper functions such as :func:`ensure_contents`, which operate on both container
+  and local paths.
+
+:class:`ContainerPath` methods that interact with the remote filesystem will raise a
+:class:`PebbleConnectionError` if the workload container isn't reachable.
+Methods designed to work with both local and container paths may handle this error internally,
+or they may leave handling connection errors to the caller, documenting this if so.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path as _Path  # for __version__
+
+from ops.pebble import ConnectionError as PebbleConnectionError
+
+from ._container_path import ContainerPath, RelativePathError
+from ._functions import ensure_contents
+from ._local_path import LocalPath
+from ._types import PathProtocol
+
+__all__ = (
+    'ContainerPath',
+    'LocalPath',
+    'PathProtocol',
+    'PebbleConnectionError',
+    'RelativePathError',
+    'ensure_contents',
+)
+
+__version__ = (_Path(__file__).parent / '_version.txt').read_text().strip()

charmlibs/pathops/_constants.py

@@ -0,0 +1,31 @@
+# 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.
+
+"""Magic numbers."""
+
+import stat
+
+DEFAULT_MKDIR_MODE = stat.S_IRWXU | stat.S_IRGRP | stat.S_IXGRP | stat.S_IROTH | stat.S_IXOTH
+"""Pebble's default of 0o755 (493) 'drwxr-xr-x'.
+
+Pathlib's default value is 0o777 (511) 'drwxrwxrwx'.
+"""
+assert DEFAULT_MKDIR_MODE == 0o755
+
+DEFAULT_WRITE_MODE = stat.S_IRUSR | stat.S_IWUSR | stat.S_IRGRP | stat.S_IROTH
+"""Pebble's default of 0o644 (420) '-rw-r--r--'.
+
+Pathlib's default value is 0o666 (438) '-rw-rw-rw-'.
+"""
+assert DEFAULT_WRITE_MODE == 0o644