charmlibs-pathops 0.0.0__tar.gz → 1.0.0__tar.gz

charmlibs_pathops-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: charmlibs-pathops
+Version: 1.0.0
+Summary: A pathlib-like interface for Juju K8s charms to interact with files in their workload container.
+Author: The Charm Tech team at Canonical Ltd.
+Project-URL: Repository, https://github.com/canonical/charmtech-charmlibs
+Project-URL: Issues, https://github.com/canonical/charmtech-charmlibs/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: ops~=2.19
+
+# charmlibs-pathops
+
+`pathops` provides a `pathlib`-like interface for local filesystem and workload container paths for Juju Charms.
+
+To install, add `charmlibs-pathops` to your requirements. Then in your Python code, import as:
+
+```py
+from charmlibs import pathops
+```
+
+Check out the reference docs [here](https://canonical-charmlibs.readthedocs-hosted.com/reference/pathops/).
+
+# Getting started
+
+To get started, you can create an attribute `self.root` with the root directory for the local or remote paths you'll be working with.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        container = self.unit.get_container('container-name')
+        self.root = pathops.ContainerPath('/', container=container)
+
+# or
+
+class MachineCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        self.root = pathops.LocalPath('/')
+```
+
+You can then write code that could be used by either charm, using the `pathops.PathProtocol` type, which describes the operations supported by both local and container paths.
+
+```py
+CONFIG_FILE_LOCATION = '/foo/bar'
+CONFIG_FILE_CONTENTS = '...'
+
+def write_config_file(root: pathops.PathProtocol) -> None:
+    path = root / CONFIG_FILE_LOCATION
+    path.write_text(CONFIG_FILE_CONTENTS)
+```
+
+For a Kubernetes charm, this also allows you to use the same API to work with paths in the charm container or the workload container.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        self.charm_root = pathops.LocalPath('/')
+        container = self.unit.get_container('container-name')
+        self.workload_root = pathops.ContainerPath('/', container=container)
+        ...
+
+    def copy_config(self):
+        source = self.charm_root / 'foo/bar'
+        dest = self.workload_root / 'foo/bar/baz'
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(source.read_bytes())
+```
+
+`pathops` also provides a helper function for ensuring that a file is present with specified content, which returns whether changes were made.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    ...
+
+    def copy_config(self):
+        changed = pathops.ensure_contents(
+            path=self.workload_root / 'foo/bar/baz',
+            source=(self.charm_root / 'foo/bar').read_bytes(),
+        )
+        if changed:
+            # make the workload reload its configuration
+            ...
+```
+
+`pathops.PathProtocol` provides a subset of the `pathlib.Path` API. `PathProtocol` doesn't support relative paths, `open`, or manipulating hardlinks and symlinks.
+
+`pathops` doesn't provide a separate `chmod` method, as Pebble doesn't currently support this. Instead, `mkdir`, `write_bytes`, and `write_text` have arguments `mode`, `user`, and `group` to set directory or file permissions and ownership. `ensure_contents` also has these arguments.

charmlibs_pathops-1.0.0/README.md

@@ -0,0 +1,88 @@
+# charmlibs-pathops
+
+`pathops` provides a `pathlib`-like interface for local filesystem and workload container paths for Juju Charms.
+
+To install, add `charmlibs-pathops` to your requirements. Then in your Python code, import as:
+
+```py
+from charmlibs import pathops
+```
+
+Check out the reference docs [here](https://canonical-charmlibs.readthedocs-hosted.com/reference/pathops/).
+
+# Getting started
+
+To get started, you can create an attribute `self.root` with the root directory for the local or remote paths you'll be working with.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        container = self.unit.get_container('container-name')
+        self.root = pathops.ContainerPath('/', container=container)
+
+# or
+
+class MachineCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        self.root = pathops.LocalPath('/')
+```
+
+You can then write code that could be used by either charm, using the `pathops.PathProtocol` type, which describes the operations supported by both local and container paths.
+
+```py
+CONFIG_FILE_LOCATION = '/foo/bar'
+CONFIG_FILE_CONTENTS = '...'
+
+def write_config_file(root: pathops.PathProtocol) -> None:
+    path = root / CONFIG_FILE_LOCATION
+    path.write_text(CONFIG_FILE_CONTENTS)
+```
+
+For a Kubernetes charm, this also allows you to use the same API to work with paths in the charm container or the workload container.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        self.charm_root = pathops.LocalPath('/')
+        container = self.unit.get_container('container-name')
+        self.workload_root = pathops.ContainerPath('/', container=container)
+        ...
+
+    def copy_config(self):
+        source = self.charm_root / 'foo/bar'
+        dest = self.workload_root / 'foo/bar/baz'
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(source.read_bytes())
+```
+
+`pathops` also provides a helper function for ensuring that a file is present with specified content, which returns whether changes were made.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    ...
+
+    def copy_config(self):
+        changed = pathops.ensure_contents(
+            path=self.workload_root / 'foo/bar/baz',
+            source=(self.charm_root / 'foo/bar').read_bytes(),
+        )
+        if changed:
+            # make the workload reload its configuration
+            ...
+```
+
+`pathops.PathProtocol` provides a subset of the `pathlib.Path` API. `PathProtocol` doesn't support relative paths, `open`, or manipulating hardlinks and symlinks.
+
+`pathops` doesn't provide a separate `chmod` method, as Pebble doesn't currently support this. Instead, `mkdir`, `write_bytes`, and `write_text` have arguments `mode`, `user`, and `group` to set directory or file permissions and ownership. `ensure_contents` also has these arguments.

{charmlibs_pathops-0.0.0 → charmlibs_pathops-1.0.0}/pyproject.toml

@@ -11,7 +11,7 @@ classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Intended Audience :: Developers",
     "Operating System :: POSIX :: Linux",
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
 ]
 dynamic = ["version"]
 dependencies = [

charmlibs_pathops-1.0.0/src/charmlibs/pathops/_version.txt

@@ -0,0 +1 @@
+1.0.0

charmlibs_pathops-1.0.0/src/charmlibs_pathops.egg-info/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: charmlibs-pathops
+Version: 1.0.0
+Summary: A pathlib-like interface for Juju K8s charms to interact with files in their workload container.
+Author: The Charm Tech team at Canonical Ltd.
+Project-URL: Repository, https://github.com/canonical/charmtech-charmlibs
+Project-URL: Issues, https://github.com/canonical/charmtech-charmlibs/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: ops~=2.19
+
+# charmlibs-pathops
+
+`pathops` provides a `pathlib`-like interface for local filesystem and workload container paths for Juju Charms.
+
+To install, add `charmlibs-pathops` to your requirements. Then in your Python code, import as:
+
+```py
+from charmlibs import pathops
+```
+
+Check out the reference docs [here](https://canonical-charmlibs.readthedocs-hosted.com/reference/pathops/).
+
+# Getting started
+
+To get started, you can create an attribute `self.root` with the root directory for the local or remote paths you'll be working with.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        container = self.unit.get_container('container-name')
+        self.root = pathops.ContainerPath('/', container=container)
+
+# or
+
+class MachineCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        self.root = pathops.LocalPath('/')
+```
+
+You can then write code that could be used by either charm, using the `pathops.PathProtocol` type, which describes the operations supported by both local and container paths.
+
+```py
+CONFIG_FILE_LOCATION = '/foo/bar'
+CONFIG_FILE_CONTENTS = '...'
+
+def write_config_file(root: pathops.PathProtocol) -> None:
+    path = root / CONFIG_FILE_LOCATION
+    path.write_text(CONFIG_FILE_CONTENTS)
+```
+
+For a Kubernetes charm, this also allows you to use the same API to work with paths in the charm container or the workload container.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    def __init__(self, framework: ops.Framework):
+        super().__init__(framework)
+        self.charm_root = pathops.LocalPath('/')
+        container = self.unit.get_container('container-name')
+        self.workload_root = pathops.ContainerPath('/', container=container)
+        ...
+
+    def copy_config(self):
+        source = self.charm_root / 'foo/bar'
+        dest = self.workload_root / 'foo/bar/baz'
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(source.read_bytes())
+```
+
+`pathops` also provides a helper function for ensuring that a file is present with specified content, which returns whether changes were made.
+
+```py
+import ops
+from charmlibs import pathops
+
+class KubernetesCharm(ops.CharmBase):
+    ...
+
+    def copy_config(self):
+        changed = pathops.ensure_contents(
+            path=self.workload_root / 'foo/bar/baz',
+            source=(self.charm_root / 'foo/bar').read_bytes(),
+        )
+        if changed:
+            # make the workload reload its configuration
+            ...
+```
+
+`pathops.PathProtocol` provides a subset of the `pathlib.Path` API. `PathProtocol` doesn't support relative paths, `open`, or manipulating hardlinks and symlinks.
+
+`pathops` doesn't provide a separate `chmod` method, as Pebble doesn't currently support this. Instead, `mkdir`, `write_bytes`, and `write_text` have arguments `mode`, `user`, and `group` to set directory or file permissions and ownership. `ensure_contents` also has these arguments.

charmlibs_pathops-0.0.0/PKG-INFO

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: charmlibs-pathops
-Version: 0.0.0
-Summary: A pathlib-like interface for Juju K8s charms to interact with files in their workload container.
-Author: The Charm Tech team at Canonical Ltd.
-Project-URL: Repository, https://github.com/canonical/charmtech-charmlibs
-Project-URL: Issues, https://github.com/canonical/charmtech-charmlibs/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Development Status :: 4 - Beta
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: ops~=2.19
-
-# charmlibs-pathops
-
-`pathops` provides a `pathlib`-like interface for local filesystem and workload container paths for Juju Charms.
-
-To install, add `charmlibs-pathops` to your requirements. Then in your Python code, import as:
-
-```py
-from charmlibs import pathops
-```
-
-Check out the reference docs [here](https://canonical-charmlibs.readthedocs-hosted.com/reference/pathops/).

charmlibs_pathops-0.0.0/README.md

@@ -1,11 +0,0 @@
-# charmlibs-pathops
-
-`pathops` provides a `pathlib`-like interface for local filesystem and workload container paths for Juju Charms.
-
-To install, add `charmlibs-pathops` to your requirements. Then in your Python code, import as:
-
-```py
-from charmlibs import pathops
-```
-
-Check out the reference docs [here](https://canonical-charmlibs.readthedocs-hosted.com/reference/pathops/).

charmlibs_pathops-0.0.0/src/charmlibs/pathops/_version.txt

@@ -1 +0,0 @@
-0.0.0

charmlibs_pathops-0.0.0/src/charmlibs_pathops.egg-info/PKG-INFO

@@ -1,27 +0,0 @@
-Metadata-Version: 2.4
-Name: charmlibs-pathops
-Version: 0.0.0
-Summary: A pathlib-like interface for Juju K8s charms to interact with files in their workload container.
-Author: The Charm Tech team at Canonical Ltd.
-Project-URL: Repository, https://github.com/canonical/charmtech-charmlibs
-Project-URL: Issues, https://github.com/canonical/charmtech-charmlibs/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Development Status :: 4 - Beta
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: ops~=2.19
-
-# charmlibs-pathops
-
-`pathops` provides a `pathlib`-like interface for local filesystem and workload container paths for Juju Charms.
-
-To install, add `charmlibs-pathops` to your requirements. Then in your Python code, import as:
-
-```py
-from charmlibs import pathops
-```
-
-Check out the reference docs [here](https://canonical-charmlibs.readthedocs-hosted.com/reference/pathops/).