ipalib, ipaserver: fix incorrect API.register calls in docstrings

Use API.add_plugin to load specific plugins into API objects. Use Registry
to register plugins.

This fixes doctests.

https://fedorahosted.org/freeipa/ticket/4739
https://fedorahosted.org/freeipa/ticket/5115

Reviewed-By: David Kupka <dkupka@redhat.com>

ipalib/__init__.py

@@ -54,7 +54,7 @@ The tutorial examples all have this pattern:
         >>> class my_command(Command):
         ...     pass
         ...
-        >>> api.register(my_command)
+        >>> api.add_plugin(my_command)
         >>> api.finalize()
 
 In the tutorial we call `create_api()` to create an *example* instance
@@ -65,11 +65,13 @@ A real plugin will have this pattern:
 
     ::
 
-        from ipalib import Command, api
+        from ipalib import Command, Registry, api
 
+        register = Registry()
+
+        @register()
         class my_command(Command):
             pass
-        api.register(my_command)
 
 As seen above, also note that in a real plugin you will *not* call
 `plugable.API.finalize()`.  When in doubt, look at some of the built-in
@@ -104,7 +106,7 @@ thereof).  Here is our first example:
 >>> class my_command(Command): # Step 1, define class
 ...     """My example plugin."""
 ...
->>> api.register(my_command) # Step 2, register class
+>>> api.add_plugin(my_command) # Step 2, register class
 
 Notice that we are registering the ``my_command`` class itself, not an
 instance of ``my_command``.
@@ -138,7 +140,7 @@ implement a ``run()`` method, like this:
 ...         return dict(result='My run() method was called!')
 ...
 >>> api = create_api()
->>> api.register(my_command)
+>>> api.add_plugin(my_command)
 >>> api.finalize()
 >>> api.Command.my_command(version=u'2.47') # Call your command
 {'result': 'My run() method was called!'}
@@ -195,7 +197,7 @@ called:
 
 >>> api = create_api()
 >>> api.env.in_server = False # run() will dispatch to forward()
->>> api.register(my_command)
+>>> api.add_plugin(my_command)
 >>> api.finalize()
 >>> api.Command.my_command(version=u'2.47') # Call your command plugin
 {'result': 'forward(): in_server=False'}
@@ -205,7 +207,7 @@ On the other hand, if ``my_command`` is loaded in a *server* context,
 
 >>> api = create_api()
 >>> api.env.in_server = True # run() will dispatch to execute()
->>> api.register(my_command)
+>>> api.add_plugin(my_command)
 >>> api.finalize()
 >>> api.Command.my_command(version=u'2.47') # Call your command plugin
 {'result': 'execute(): in_server=True'}
@@ -261,7 +263,7 @@ Here is a simple example:
 ...         return 'Stuff got done.'
 ...
 >>> api = create_api()
->>> api.register(my_backend)
+>>> api.add_plugin(my_backend)
 >>> api.finalize()
 >>> api.Backend.my_backend.do_stuff()
 'Stuff got done.'
@@ -312,7 +314,7 @@ plugin:
 ...         """my_command.execute() calls this."""
 ...         return 'my_backend.do_stuff() indeed did do stuff!'
 ...
->>> api.register(my_backend)
+>>> api.add_plugin(my_backend)
 
 Second, we have our frontend plugin, the command:
 
@@ -323,7 +325,7 @@ Second, we have our frontend plugin, the command:
 ...         """Implemented against Backend.my_backend"""
 ...         return dict(result=self.Backend.my_backend.do_stuff())
 ...
->>> api.register(my_command)
+>>> api.add_plugin(my_command)
 
 Lastly, we call ``api.finalize()`` and see what happens when we call
 ``my_command()``:
@@ -349,7 +351,7 @@ example:
 ...     def forward(self, **options):
 ...         return dict(result='Just my_command.forward() getting called here.')
 ...
->>> api.register(my_command)
+>>> api.add_plugin(my_command)
 >>> api.finalize()
 
 Notice that the ``my_backend`` plugin has certainly not be registered:
@@ -391,9 +393,9 @@ several other commands in a single operation.  For example:
 ...     def execute(self, **options):
 ...         return dict(result='command_2.execute() called')
 ...
->>> api.register(meta_command)
+>>> api.add_plugin(meta_command)
->>> api.register(command_1)
+>>> api.add_plugin(command_1)
->>> api.register(command_2)
+>>> api.add_plugin(command_2)
 >>> api.finalize()
 >>> api.Command.meta_command(version=u'2.47')
 {'result': 'command_1.execute() called; command_2.execute() called.'}
@@ -428,7 +430,7 @@ For example:
 ...
 >>> api = create_api()
 >>> api.env.in_server = True
->>> api.register(nudge)
+>>> api.add_plugin(nudge)
 >>> api.finalize()
 >>> api.Command.nudge(u'Jason', version=u'2.47')
 {'result': u'Jason, go write more documentation!'}
@@ -616,7 +618,7 @@ For example, say we setup a command like this:
 ...
 >>> api = create_api()
 >>> api.bootstrap(in_server=True)  # We want to execute, not forward
->>> api.register(show_items)
+>>> api.add_plugin(show_items)
 >>> api.finalize()
 
 Normally when you invoke the ``ipa`` script, `cli.CLI.load_plugins()` will
@@ -758,7 +760,7 @@ For example:
 ...
 >>> api = create_api()
 >>> api.bootstrap(in_server=True, message='Hello, world!')
->>> api.register(motd)
+>>> api.add_plugin(motd)
 >>> api.finalize()
 >>> api.Command.motd(version=u'2.47')
 {'result': u'Hello, world!'}

ipalib/crud.py

@@ -56,9 +56,9 @@ Now we'll register the plugins and finalize the `plugable.API` instance:
 
 >>> from ipalib import create_api
 >>> api = create_api()
->>> api.register(user)
+>>> api.add_plugin(user)
->>> api.register(user_add)
+>>> api.add_plugin(user_add)
->>> api.register(user_show)
+>>> api.add_plugin(user_show)
 >>> api.finalize()
 
 First, notice that our ``user`` `Object` has the params we defined with the

ipalib/frontend.py

@@ -384,7 +384,7 @@ class Command(HasParam):
     >>> class my_command(Command):
     ...     pass
     ...
-    >>> api.register(my_command)
+    >>> api.add_plugin(my_command)
     >>> api.finalize()
     >>> list(api.Command)
     ['my_command']
@@ -1336,8 +1336,8 @@ class Method(Attribute, Command):
     >>> class user(Object):
     ...     pass
     ...
-    >>> api.register(user_add)
+    >>> api.add_plugin(user_add)
-    >>> api.register(user)
+    >>> api.add_plugin(user)
     >>> api.finalize()
 
     First, the ``user_add`` plugin can be accessed through the ``api.Method``
@@ -1404,11 +1404,11 @@ class Updater(Plugin):
     >>> class my(Object):
     ...     pass
     ...
-    >>> api.register(my)
+    >>> api.add_plugin(my)
     >>> class my_update(Updater):
     ...     pass
     ...
-    >>> api.register(my_update)
+    >>> api.add_plugin(my_update)
     >>> api.finalize()
     >>> list(api.Updater)
     ['my_update']

ipaserver/advise/base.py

@@ -39,6 +39,9 @@ The class can run any arbitrary code or IPA command via api.Command['command']()
 calls. It needs to override get_info() method, which returns the formatted
 advice string.
 
+Important! Do not forget to register the class to the API.
+
+>>> @register()
 >>> class sample_advice(Advice):
 >>>     description = 'Instructions for machine with SSSD 1.0 setup.'
 
@@ -69,10 +72,6 @@ As a result, you can redirect the advice's output directly to a script file.
 
 # ipa-advise sample-advice > script.sh
 # ./script.sh
-
-Important! Do not forget to register the class to the API.
-
->>> api.register(sample_advice)
 """
 
 

ipaserver/plugins/dogtag.py

@@ -1965,12 +1965,11 @@ class RestClient(Backend):
     This class is a context manager.  Authenticated calls must be
     executed in a ``with`` suite::
 
+        @register()
         class ra_certprofile(RestClient):
             path = 'profile'
             ...
 
-        api.register(ra_certprofile)
-
         with api.Backend.ra_certprofile as profile_api:
             # REST client is now logged in
             profile_api.create_profile(...)