diff options
author | Jan Cholasta <jcholast@redhat.com> | 2016-04-25 16:14:05 +0200 |
---|---|---|
committer | Jan Cholasta <jcholast@redhat.com> | 2016-05-25 16:06:26 +0200 |
commit | 15a4c0d2767c0a37d55463d4bba60442a83539bb (patch) | |
tree | 8de3382c3af1ae8bbfa419e81abad3b60294afde | |
parent | bed546ee8220992084520737320a646dc47ec1e3 (diff) | |
download | freeipa-15a4c0d2767c0a37d55463d4bba60442a83539bb.tar.gz freeipa-15a4c0d2767c0a37d55463d4bba60442a83539bb.tar.xz freeipa-15a4c0d2767c0a37d55463d4bba60442a83539bb.zip |
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>
-rw-r--r-- | ipalib/__init__.py | 36 | ||||
-rw-r--r-- | ipalib/crud.py | 6 | ||||
-rw-r--r-- | ipalib/frontend.py | 10 | ||||
-rw-r--r-- | ipaserver/advise/base.py | 7 | ||||
-rw-r--r-- | ipaserver/plugins/dogtag.py | 3 |
5 files changed, 31 insertions, 31 deletions
diff --git a/ipalib/__init__.py b/ipalib/__init__.py index 4bf4a8788..62860b348 100644 --- a/ipalib/__init__.py +++ b/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.register(command_1) ->>> api.register(command_2) +>>> api.add_plugin(meta_command) +>>> api.add_plugin(command_1) +>>> 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!'} diff --git a/ipalib/crud.py b/ipalib/crud.py index 4928c7f7d..eee32820d 100644 --- a/ipalib/crud.py +++ b/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.register(user_add) ->>> api.register(user_show) +>>> api.add_plugin(user) +>>> api.add_plugin(user_add) +>>> api.add_plugin(user_show) >>> api.finalize() First, notice that our ``user`` `Object` has the params we defined with the diff --git a/ipalib/frontend.py b/ipalib/frontend.py index adad3707d..d9bf3d6c7 100644 --- a/ipalib/frontend.py +++ b/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.register(user) + >>> api.add_plugin(user_add) + >>> 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'] diff --git a/ipaserver/advise/base.py b/ipaserver/advise/base.py index c80a13b6c..d083a3c50 100644 --- a/ipaserver/advise/base.py +++ b/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) """ diff --git a/ipaserver/plugins/dogtag.py b/ipaserver/plugins/dogtag.py index 935f9ba20..acec25982 100644 --- a/ipaserver/plugins/dogtag.py +++ b/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(...) |