dpcharmlibs-interfaces 1.0.0__tar.gz

dpcharmlibs_interfaces-1.0.0/.gitignore

@@ -0,0 +1,184 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+cos-tool*
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.coverage-*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+.report/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# PyPI configuration file
+.pypirc
+
+# packed charms
+.packed
+
+# temporary directory for packing charms
+.tmp
+
+# file for storing tests.
+.collected
+
+!**/charms/*/lib/

dpcharmlibs_interfaces-1.0.0/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 1.0.0 - 24 March 2026
+
+* Initial release of the library

dpcharmlibs_interfaces-1.0.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: dpcharmlibs-interfaces
+Version: 1.0.0
+Summary: The dpcharmlibs.interfaces package.
+Project-URL: Repository, https://github.com/canonical/data-platform-charmlibs
+Project-URL: Issues, https://github.com/canonical/data-platform-charmlibs/issues
+Author: The Data Platform team at Canonical Ltd.
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: ops<4,>=3
+Requires-Dist: pydantic<3,>=2.11
+Description-Content-Type: text/markdown
+
+# dpcharmlibs.interfaces: Library to manage the relation for the data-platform products
+
+The `interfaces` library.
+
+To install, add `dpcharmlibs-interfaces` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from dpcharmlibs import interfaces
+```
+
+## Abstract
+
+This V1 has been specified in
+<https://docs.google.com/document/d/1lnuonWnoQb36RWYwfHOBwU0VClLbawpTISXIC_yNKYo>,
+and should be backward compatible with v0 clients.
+
+This library contains the Requires and Provides classes for handling the relation
+between an application and multiple managed application supported by the data-team:
+MySQL, Postgresql, MongoDB, Redis, Kafka, and Karapace.
+
+## Components
+
+### Models
+
+This library exposes basic default models that can be used in most cases.
+If you need more complex models, you can subclass them.
+
+```python
+from dpcharmlibs.interfaces import RequirerCommonModel, ExtraSecretStr
+
+class ExtendedCommonModel(RequirerCommonModel):
+    operator_password: ExtraSecretStr
+```
+
+Secret groups are handled using annotated types.
+If you wish to add extra secret groups, please follow the following model.
+The string metadata represents the secret group name, and `OptionalSecretStr` is a TypeAlias for
+`SecretStr | None`. Finally, `SecretStr` represents a field validating the URI pattern `secret:.*`
+
+```python
+MyGroupSecretStr = Annotated[OptionalSecretStr, Field(exclude=True, default=None), "mygroup"]
+```
+
+Fields not specified as OptionalSecretStr and extended with a group name in the metadata will NOT
+get serialised.
+
+### Requirer Charm
+
+This library is a uniform interface to a selection of common database
+metadata, with added custom events that add convenience to database management,
+and methods to consume the application related data.
+
+```python
+from dpcharmlibs.interfaces import (
+    RequirerCommonModel,
+    RequirerDataContractV1,
+    ResourceCreatedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceProviderModel,
+    ResourceRequirerEventHandler,
+)
+
+class ClientCharm(CharmBase):
+    # Database charm that accepts connections from application charms.
+    def __init__(self, *args) -> None:
+        super().__init__(*args)
+
+        requests = [
+            RequirerCommonModel(
+                resource="clientdb",
+            ),
+            RequirerCommonModel(
+                resource="clientbis",
+            ),
+            RequirerCommonModel(
+                entity_type="USER",
+            )
+        ]
+        self.database = ResourceRequirerEventHandler(
+            self,"database", requests, response_model=ResourceProviderModel
+        )
+        self.framework.observe(self.database.on.resource_created, self._on_resource_created)
+        self.framework.observe(self.database.on.resource_entity_created, self._on_entity_created)
+
+    def _on_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Event triggered when a new database is created.
+        relation_id = event.relation.id
+        response = event.response # This is the response model
+
+        username = event.response.username
+        password = event.response.password
+        ...
+
+    def _on_entity_created(self, event: ResourceCreatedEvent) -> None:
+        # Event triggered when a new entity is created.
+        ...
+```
+
+Compared to V0, this library makes heavy use of pydantic models, and allows for
+multiple requests, specified as a list.
+On the Requirer side, each response will trigger one custom event for that response.
+This way, it allows for more strategic events to be emitted according to the request.
+
+As show above, the library provides some custom events to handle specific situations,
+which are listed below:
+
+- resource_created: event emitted when the requested database is created.
+- resource_entity_created: event emitted when the requested entity is created.
+- endpoints_changed: event emitted when the read/write endpoints of
+  the database have changed.
+- read_only_endpoints_changed: event emitted when the read-only endpoints of
+  the database have changed. Event is not triggered if read/write endpoints
+  changed too.
+
+If it is needed to connect multiple database clusters to the same relation endpoint
+the application charm can implement the same code as if it would connect to only
+one database cluster (like the above code example).
+
+To differentiate multiple clusters connected to the same relation endpoint
+the application charm can use the name of the remote application:
+
+```python
+def _on_resource_created(self, event: ResourceCreatedEvent) -> None:
+    # Get the remote app name of the cluster that triggered this event
+    cluster = event.relation.app.name
+```
+
+It is also possible to provide an alias for each different database cluster/relation.
+
+So, it is possible to differentiate the clusters in two ways.
+
+The first is to use the remote application name, with `event.relation.app.name`.
+
+The second way is to use different event handlers to handle each cluster events.
+
+The implementation would be something like the following code:
+
+```python
+from dpcharmlibs.interfaces import (
+    RequirerCommonModel,
+    RequirerDataContractV1,
+    ResourceCreatedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceProviderModel,
+    ResourceRequirerEventHandler,
+)
+
+class ApplicationCharm(CharmBase):
+    # Application charm that connects to database charms.
+
+    def __init__(self, *args):
+        super().__init__(*args)
+
+        requests = [
+            RequirerCommonModel(
+                resource="clientdb",
+            ),
+            RequirerCommonModel(
+                resource="clientbis",
+            ),
+        ]
+        # Define the cluster aliases and one handler for each cluster database
+        # created event.
+        self.database = ResourceRequirerEventHandler(
+            self,
+            relation_name="database"
+            relations_aliases = ["cluster1", "cluster2"],
+            requests=
+        )
+        self.framework.observe(
+            self.database.on.cluster1_resource_created, self._on_cluster1_resource_created
+        )
+        self.framework.observe(
+            self.database.on.cluster2_resource_created, self._on_cluster2_resource_created
+        )
+
+    def _on_cluster1_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Handle the created database on the cluster named cluster1
+
+        # Create configuration file for app
+        config_file = self._render_app_config_file(
+            event.response.username,
+            event.response.password,
+            event.response.endpoints,
+        )
+        ...
+
+    def _on_cluster2_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Handle the created database on the cluster named cluster2
+
+        # Create configuration file for app
+        config_file = self._render_app_config_file(
+            event.response.username,
+            event.response.password,
+            event.response.endpoints,
+        )
+        ...
+```
+
+### Provider Charm
+
+Following an example of using the ResourceRequestedEvent, in the context of the
+database charm code:
+
+```python
+from dpcharmlibs.interfaces import (
+    ResourceProviderEventHandler,
+    ResourceProviderModel,
+    ResourceRequestedEvent,
+    RequirerCommonModel,
+)
+
+class SampleCharm(CharmBase):
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        # Charm events defined in the database provides charm library.
+        self.provided_database = ResourceProviderEventHandler(
+            self, "database", RequirerCommonModel,
+        )
+        self.framework.observe(self.provided_database.on.resource_requested,
+            self._on_resource_requested)
+        # Database generic helper
+        self.database = DatabaseHelper()
+
+    def _on_resource_requested(self, event: ResourceRequestedEvent) -> None:
+        # Handle the event triggered by a new database requested in the relation
+        # Retrieve the database name using the charm library.
+        db_name = event.request.resource
+        # generate a new user credential
+        username = self.database.generate_user(event.request.request_id)
+        password = self.database.generate_password(event.request.request_id)
+        # set the credentials for the relation
+        response = ResourceProviderModel(
+            salt=event.request.salt,
+            request_id=event.request.request_id,
+            resource=db_name,
+            username=username,
+            password=password,
+            ...
+        )
+        self.provided_database.set_response(event.relation.id, response)
+```
+
+As shown above, the library provides a custom event (resource_requested) to handle
+the situation when an application charm requests a new database to be created.
+It's preferred to subscribe to this event instead of relation changed event to avoid
+creating a new database when other information other than a database name is
+exchanged in the relation databag.

dpcharmlibs_interfaces-1.0.0/README.md

@@ -0,0 +1,249 @@
+# dpcharmlibs.interfaces: Library to manage the relation for the data-platform products
+
+The `interfaces` library.
+
+To install, add `dpcharmlibs-interfaces` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from dpcharmlibs import interfaces
+```
+
+## Abstract
+
+This V1 has been specified in
+<https://docs.google.com/document/d/1lnuonWnoQb36RWYwfHOBwU0VClLbawpTISXIC_yNKYo>,
+and should be backward compatible with v0 clients.
+
+This library contains the Requires and Provides classes for handling the relation
+between an application and multiple managed application supported by the data-team:
+MySQL, Postgresql, MongoDB, Redis, Kafka, and Karapace.
+
+## Components
+
+### Models
+
+This library exposes basic default models that can be used in most cases.
+If you need more complex models, you can subclass them.
+
+```python
+from dpcharmlibs.interfaces import RequirerCommonModel, ExtraSecretStr
+
+class ExtendedCommonModel(RequirerCommonModel):
+    operator_password: ExtraSecretStr
+```
+
+Secret groups are handled using annotated types.
+If you wish to add extra secret groups, please follow the following model.
+The string metadata represents the secret group name, and `OptionalSecretStr` is a TypeAlias for
+`SecretStr | None`. Finally, `SecretStr` represents a field validating the URI pattern `secret:.*`
+
+```python
+MyGroupSecretStr = Annotated[OptionalSecretStr, Field(exclude=True, default=None), "mygroup"]
+```
+
+Fields not specified as OptionalSecretStr and extended with a group name in the metadata will NOT
+get serialised.
+
+### Requirer Charm
+
+This library is a uniform interface to a selection of common database
+metadata, with added custom events that add convenience to database management,
+and methods to consume the application related data.
+
+```python
+from dpcharmlibs.interfaces import (
+    RequirerCommonModel,
+    RequirerDataContractV1,
+    ResourceCreatedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceProviderModel,
+    ResourceRequirerEventHandler,
+)
+
+class ClientCharm(CharmBase):
+    # Database charm that accepts connections from application charms.
+    def __init__(self, *args) -> None:
+        super().__init__(*args)
+
+        requests = [
+            RequirerCommonModel(
+                resource="clientdb",
+            ),
+            RequirerCommonModel(
+                resource="clientbis",
+            ),
+            RequirerCommonModel(
+                entity_type="USER",
+            )
+        ]
+        self.database = ResourceRequirerEventHandler(
+            self,"database", requests, response_model=ResourceProviderModel
+        )
+        self.framework.observe(self.database.on.resource_created, self._on_resource_created)
+        self.framework.observe(self.database.on.resource_entity_created, self._on_entity_created)
+
+    def _on_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Event triggered when a new database is created.
+        relation_id = event.relation.id
+        response = event.response # This is the response model
+
+        username = event.response.username
+        password = event.response.password
+        ...
+
+    def _on_entity_created(self, event: ResourceCreatedEvent) -> None:
+        # Event triggered when a new entity is created.
+        ...
+```
+
+Compared to V0, this library makes heavy use of pydantic models, and allows for
+multiple requests, specified as a list.
+On the Requirer side, each response will trigger one custom event for that response.
+This way, it allows for more strategic events to be emitted according to the request.
+
+As show above, the library provides some custom events to handle specific situations,
+which are listed below:
+
+- resource_created: event emitted when the requested database is created.
+- resource_entity_created: event emitted when the requested entity is created.
+- endpoints_changed: event emitted when the read/write endpoints of
+  the database have changed.
+- read_only_endpoints_changed: event emitted when the read-only endpoints of
+  the database have changed. Event is not triggered if read/write endpoints
+  changed too.
+
+If it is needed to connect multiple database clusters to the same relation endpoint
+the application charm can implement the same code as if it would connect to only
+one database cluster (like the above code example).
+
+To differentiate multiple clusters connected to the same relation endpoint
+the application charm can use the name of the remote application:
+
+```python
+def _on_resource_created(self, event: ResourceCreatedEvent) -> None:
+    # Get the remote app name of the cluster that triggered this event
+    cluster = event.relation.app.name
+```
+
+It is also possible to provide an alias for each different database cluster/relation.
+
+So, it is possible to differentiate the clusters in two ways.
+
+The first is to use the remote application name, with `event.relation.app.name`.
+
+The second way is to use different event handlers to handle each cluster events.
+
+The implementation would be something like the following code:
+
+```python
+from dpcharmlibs.interfaces import (
+    RequirerCommonModel,
+    RequirerDataContractV1,
+    ResourceCreatedEvent,
+    ResourceEntityCreatedEvent,
+    ResourceProviderModel,
+    ResourceRequirerEventHandler,
+)
+
+class ApplicationCharm(CharmBase):
+    # Application charm that connects to database charms.
+
+    def __init__(self, *args):
+        super().__init__(*args)
+
+        requests = [
+            RequirerCommonModel(
+                resource="clientdb",
+            ),
+            RequirerCommonModel(
+                resource="clientbis",
+            ),
+        ]
+        # Define the cluster aliases and one handler for each cluster database
+        # created event.
+        self.database = ResourceRequirerEventHandler(
+            self,
+            relation_name="database"
+            relations_aliases = ["cluster1", "cluster2"],
+            requests=
+        )
+        self.framework.observe(
+            self.database.on.cluster1_resource_created, self._on_cluster1_resource_created
+        )
+        self.framework.observe(
+            self.database.on.cluster2_resource_created, self._on_cluster2_resource_created
+        )
+
+    def _on_cluster1_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Handle the created database on the cluster named cluster1
+
+        # Create configuration file for app
+        config_file = self._render_app_config_file(
+            event.response.username,
+            event.response.password,
+            event.response.endpoints,
+        )
+        ...
+
+    def _on_cluster2_resource_created(self, event: ResourceCreatedEvent) -> None:
+        # Handle the created database on the cluster named cluster2
+
+        # Create configuration file for app
+        config_file = self._render_app_config_file(
+            event.response.username,
+            event.response.password,
+            event.response.endpoints,
+        )
+        ...
+```
+
+### Provider Charm
+
+Following an example of using the ResourceRequestedEvent, in the context of the
+database charm code:
+
+```python
+from dpcharmlibs.interfaces import (
+    ResourceProviderEventHandler,
+    ResourceProviderModel,
+    ResourceRequestedEvent,
+    RequirerCommonModel,
+)
+
+class SampleCharm(CharmBase):
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        # Charm events defined in the database provides charm library.
+        self.provided_database = ResourceProviderEventHandler(
+            self, "database", RequirerCommonModel,
+        )
+        self.framework.observe(self.provided_database.on.resource_requested,
+            self._on_resource_requested)
+        # Database generic helper
+        self.database = DatabaseHelper()
+
+    def _on_resource_requested(self, event: ResourceRequestedEvent) -> None:
+        # Handle the event triggered by a new database requested in the relation
+        # Retrieve the database name using the charm library.
+        db_name = event.request.resource
+        # generate a new user credential
+        username = self.database.generate_user(event.request.request_id)
+        password = self.database.generate_password(event.request.request_id)
+        # set the credentials for the relation
+        response = ResourceProviderModel(
+            salt=event.request.salt,
+            request_id=event.request.request_id,
+            resource=db_name,
+            username=username,
+            password=password,
+            ...
+        )
+        self.provided_database.set_response(event.relation.id, response)
+```
+
+As shown above, the library provides a custom event (resource_requested) to handle
+the situation when an application charm requests a new database to be created.
+It's preferred to subscribe to this event instead of relation changed event to avoid
+creating a new database when other information other than a database name is
+exchanged in the relation databag.