Merge pull request #660 from jack-w-shaw/JUJU-796_use_relate

[JUJU-796] Add relate method and deprecate add-relation

#### Description

This is to follow the pattern we are following going ahead with Juju.
change the name of add-relation to relate, but keep add-relation, which
calls relate for backwards compatibility

This method should then be removed at the next major version bump

See this PR for more details
juju/juju#13907

#### QA Steps

```sh
tox -e integration
tox -e unit
```

docs/narrative/application.rst

@@ -95,7 +95,7 @@ application. The `mysql_app` object is an instance of
 
 Adding and Removing Relations
 -----------------------------
-The :meth:`juju.application.Application.add_relation` method returns a
+The :meth:`juju.application.Application.relate` method returns a
 :class:`juju.relation.Relation` instance.
 
 .. code:: python
@@ -122,7 +122,7 @@ The :meth:`juju.application.Application.add_relation` method returns a
   )
 
   # Add the master-slave relation
-  relation = await mysql_master.add_relation(
+  relation = await mysql_master.relate(
       # Name of the relation on the local (mysql-master) side
       'master',
       # Name of the app:relation on the remote side

examples/crossmodel_relation.py

@@ -66,7 +66,7 @@ async def main():
             lambda: all(unit.agent_status == 'executing'
                         for unit in application_2.units))
 
-        await consuming_model.add_relation('wordpress', 'admin/test-cmr-1.mysql')
+        await consuming_model.relate('wordpress', 'admin/test-cmr-1.mysql')
 
         print('Exporting bundle')
         with tempfile.TemporaryDirectory() as dirpath:

examples/future.py

@@ -29,7 +29,7 @@ async def main():
         channel='stable',
         num_units=0,
     )
-    await model.add_relation(
+    await model.relate(
         'ubuntu',
         'nrpe',
     )

examples/relate.py

@@ -83,7 +83,7 @@ async def main():
             # subordinates must be deployed without units
             num_units=0,
         )
-        my_relation = await model.add_relation(
+        my_relation = await model.relate(
             'ubuntu',
             'nrpe',
         )

juju/application.py

@@ -107,6 +107,13 @@ def tag(self):
         return tag.application(self.name)
 
     async def add_relation(self, local_relation, remote_relation):
+        """
+        .. deprecated:: 2.9.9
+           Use ``relate()`` instead
+        """
+        return await self.relate(local_relation, remote_relation)
+
+    async def relate(self, local_relation, remote_relation):
         """Add a relation to another application.
 
         :param str local_relation: Name of relation on this application
@@ -117,7 +124,7 @@ async def add_relation(self, local_relation, remote_relation):
         if ':' not in local_relation:
             local_relation = '{}:{}'.format(self.name, local_relation)
 
-        return await self.model.add_relation(local_relation, remote_relation)
+        return await self.model.relate(local_relation, remote_relation)
 
     async def add_unit(self, count=1, to=None):
         """Add one or more units to this application.

juju/bundle.py

@@ -894,7 +894,7 @@ async def run(self, context):
             return existing[0]
 
         log.info('Relating %s <-> %s', ep1, ep2)
-        return await context.model.add_relation(ep1, ep2)
+        return await context.model.relate(ep1, ep2)
 
     def __str__(self):
         return "add relation {endpoint1} - {endpoint2}".format(endpoint1=self.endpoint1,

juju/model.py

@@ -1342,6 +1342,13 @@ async def add_machine(
         return await self._wait_for_new('machine', machine_id)
 
     async def add_relation(self, relation1, relation2):
+        """
+        .. deprecated:: 2.9.9
+           Use ``relate()`` instead
+        """
+        return await self.relate(relation1, relation2)
+
+    async def relate(self, relation1, relation2):
         """Add a relation between two applications.
 
         :param str relation1: '<application>[:<relation_name>]'

tests/integration/test_crossmodel.py

@@ -93,7 +93,7 @@ async def test_remove_saas(event_loop):
 
 @base.bootstrapped
 @pytest.mark.asyncio
-async def test_add_relation_with_offer(event_loop):
+async def test_relate_with_offer(event_loop):
     pytest.skip('Revise: intermittent problem with the remove_saas call')
     async with base.CleanModel() as model_1:
         application = await model_1.deploy(
@@ -123,7 +123,7 @@ async def test_add_relation_with_offer(event_loop):
                 lambda: all(unit.agent_status == 'idle'
                             for unit in application.units))
 
-            await model_2.add_relation("mediawiki:db", "admin/{}.mysql".format(model_1.info.name))
+            await model_2.relate("mediawiki:db", "admin/{}.mysql".format(model_1.info.name))
             status = await model_2.get_status()
             if 'mysql' not in status.remote_applications:
                 raise Exception("Expected mysql in saas")

tests/integration/test_model.py

@@ -556,7 +556,7 @@ async def mock_AddRelation(*args, **kwargs):
 
         with mock.patch.object(ApplicationFacade, 'from_connection',
                                return_value=mock_app_facade):
-            my_relation = await run_with_interrupt(model.add_relation(
+            my_relation = await run_with_interrupt(model.relate(
                 'ubuntu',
                 'nrpe',
             ), timeout)

tests/unit/test_bundle.py

@@ -559,7 +559,7 @@ async def test_run(self, event_loop):
         rel2 = mock.Mock(name="rel2", **{"matches.return_value": True})
 
         model = mock.Mock()
-        model.add_relation = base.AsyncMock(return_value=rel2)
+        model.relate = base.AsyncMock(return_value=rel2)
 
         context = mock.Mock()
         context.resolve_relation = mock.Mock(side_effect=['endpoint_1', 'endpoint_2'])
@@ -569,17 +569,17 @@ async def test_run(self, event_loop):
         result = await change.run(context)
         assert result is rel2
 
-        model.add_relation.assert_called_once()
-        model.add_relation.assert_called_with("endpoint_1", "endpoint_2")
+        model.relate.assert_called_once()
+        model.relate.assert_called_with("endpoint_1", "endpoint_2")
 
         # confirm that it's idempotent
         context.resolve_relation = mock.Mock(side_effect=['endpoint_1', 'endpoint_2'])
-        model.add_relation.reset_mock()
-        model.add_relation.return_value = None
+        model.relate.reset_mock()
+        model.relate.return_value = None
         model.relations = [rel1, rel2]
         result = await change.run(context)
         assert result is rel2
-        assert not model.add_relation.called
+        assert not model.relate.called
 
 
 class TestAddUnitChange(unittest.TestCase):