docs: move docs from juju.is

build/lib/juju/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2024 Canonical Ltd.
+# Licensed under the Apache V2, see LICENCE file for details.
+"""Python Library for Juju."""

build/lib/juju/access.py

@@ -0,0 +1,49 @@
+# Copyright 2023 Canonical Ltd.
+# Licensed under the Apache V2, see LICENCE file for details.
+
+from .errors import JujuNotValid
+
+# No permissions at all
+NO_ACCESS = ""
+
+# Model permissions
+
+READ_ACCESS = "read"
+WRITE_ACCESS = "write"
+CONSUME_ACCESS = "consume"
+ADMIN_ACCESS = "admin"
+MODEL_ACCESS_LEVELS = {READ_ACCESS, WRITE_ACCESS, CONSUME_ACCESS, ADMIN_ACCESS}
+
+# Controller permissions
+
+LOGIN_ACCESS = "login"
+ADD_MODEL_ACCESS = "add-model"
+SUPERUSER_ACCESS = "superuser"
+CONTROLLER_ACCESS_LEVELS = {LOGIN_ACCESS, ADD_MODEL_ACCESS, SUPERUSER_ACCESS}
+
+OFFER_ACCESS_LEVELS = {READ_ACCESS, CONSUME_ACCESS, ADMIN_ACCESS}
+
+ALL_ACCESS_LEVELS = MODEL_ACCESS_LEVELS.union(CONTROLLER_ACCESS_LEVELS)
+
+
+def validate_access_level(access):
+    if access not in ALL_ACCESS_LEVELS:
+        raise JujuNotValid("access level", access)
+
+
+def validate_offer_access(access):
+    validate_access_level()
+    if access not in OFFER_ACCESS_LEVELS:
+        raise JujuNotValid("offer access level", access)
+
+
+def validate_model_access(access):
+    validate_access_level(access)
+    if access not in MODEL_ACCESS_LEVELS:
+        raise JujuNotValid("model access level", access)
+
+
+def validate_controller_access(access):
+    validate_access_level(access)
+    if access not in CONTROLLER_ACCESS_LEVELS:
+        raise JujuNotValid("controller access level", access)

build/lib/juju/action.py

@@ -0,0 +1,24 @@
+# Copyright 2023 Canonical Ltd.
+# Licensed under the Apache V2, see LICENCE file for details.
+
+from . import model
+
+
+class Action(model.ModelEntity):
+    def __init__(self, entity_id, model, history_index=-1, connected=True):
+        super().__init__(entity_id, model, history_index, connected)
+        self.results = {}
+        self._status = self.data["status"]
+
+    @property
+    def status(self):
+        return self._status
+
+    async def fetch_output(self):
+        completed_action = await self.model._get_completed_action(self.id)
+        self.results = completed_action.output or {}
+        self._status = completed_action.status
+
+    async def wait(self):
+        self.results or await self.fetch_output()
+        return self

build/lib/juju/annotation.py

@@ -0,0 +1,12 @@
+# Copyright 2023 Canonical Ltd.
+# Licensed under the Apache V2, see LICENCE file for details.
+
+import logging
+
+from . import model
+
+log = logging.getLogger(__name__)
+
+
+class Annotation(model.ModelEntity):
+    pass

build/lib/juju/annotationhelper.py

@@ -0,0 +1,38 @@
+# Copyright 2023 Canonical Ltd.
+# Licensed under the Apache V2, see LICENCE file for details.
+
+import logging
+
+from .client import client
+from .errors import JujuError
+
+log = logging.getLogger(__name__)
+
+
+async def _get_annotations(entity_tag, connection):
+    """Get annotations for the specified entity
+
+    :return dict: The annotations for the entity
+    """
+    facade = client.AnnotationsFacade.from_connection(connection)
+    result = (await facade.Get(entities=[{"tag": entity_tag}])).results[0]
+    if result.error is not None:
+        raise JujuError(result.error)
+    return result.annotations
+
+
+async def _set_annotations(entity_tag, annotations, connection):
+    """Set annotations on the specified entity.
+
+    :param annotations map[string]string: the annotations as key/value
+        pairs.
+    """
+    # TODO: ensure annotations is dict with only string keys
+    # and values.
+    log.debug("Updating annotations on %s", entity_tag)
+    facade = client.AnnotationsFacade.from_connection(connection)
+    args = client.EntityAnnotations(
+        entity=entity_tag,
+        annotations=annotations,
+    )
+    return await facade.Set(annotations=[args])