summaryrefslogtreecommitdiffstats
path: root/ipalib/__init__.py
diff options
context:
space:
mode:
Diffstat (limited to 'ipalib/__init__.py')
-rw-r--r--ipalib/__init__.py66
1 files changed, 57 insertions, 9 deletions
diff --git a/ipalib/__init__.py b/ipalib/__init__.py
index ecb2d6331..86a0c2778 100644
--- a/ipalib/__init__.py
+++ b/ipalib/__init__.py
@@ -19,7 +19,7 @@
'''
-Package containing core library.
+Package containing the core library.
=============================
Tutorial for Plugin Authors
@@ -35,6 +35,54 @@ and `ipa_server.plugins` provide real-life examples of how to write good
plugins.
+----------------------------
+How this tutorial is written
+----------------------------
+
+The code examples in this tutorial are presented as if entered into a Python
+interactive interpreter session. As such, when you create a real plugin in
+a source file, a few details will be different (in addition to the fact that
+you will never include the ``>>>`` nor ``...`` at the beginning of each line
+of code).
+
+The tutorial examples all have this pattern:
+
+ ::
+
+ >>> from ipalib import Command, get_standard_api
+ >>> api = get_standard_api()
+ >>> class my_command(Command):
+ ... pass
+ ...
+ >>> api.register(my_command)
+ >>> api.finalize()
+
+We call `get_standard_api()` to get an *example* instance of `plugable.API`
+to work with. But a real plugin will use the standard *run-time* instance
+of `plugable.API`, which is available at ``ipalib.api``.
+
+A real plugin will have this pattern:
+
+ ::
+
+ from ipalib import Command, api
+
+ class my_command(Command):
+ pass
+ api.register(my_command)
+
+The differences are that in a real plugin you will use the standard
+``ipalib.api`` instance of `plugable.API` and that you will *not* call
+`plugable.API.finalize()`. When in doubt, look at some of the built-in
+plugins for guidance, like those in `ipalib.plugins`.
+
+If don't know what the Python *interactive interpreter* is, or are confused
+about what this *Python* is in the first place, then you probably should start
+with the Python tutorial:
+
+ http://docs.python.org/tutorial/index.html
+
+
------------------------------------
First steps: A simple command plugin
------------------------------------
@@ -67,7 +115,7 @@ instantiated nor the does the ``Command`` namespace yet exist. For example:
>>> hasattr(api, 'Command')
False
->>> api.finalize()
+>>> api.finalize() # plugable.API.finalize()
>>> hasattr(api.Command, 'my_command')
True
>>> api.Command.my_command.doc
@@ -561,7 +609,7 @@ terminal, like this:
::
- $ ./ipa console
+ $ ./ipa console
By default, ``in_server`` is False. If you want to start the console in a
server context (so that all the backend plugins are loaded), you can use the
@@ -569,41 +617,41 @@ server context (so that all the backend plugins are loaded), you can use the
::
- $ ./ipa -e in_server=True console
+ $ ./ipa -e in_server=True console
You can specify multiple environment variables by including the ``-e`` option
multiple times, like this:
::
- $ ./ipa -e in_server=True -e mode=dummy console
+ $ ./ipa -e in_server=True -e mode=dummy console
The space after the ``-e`` is optional. This is equivalent to the above command:
::
- $ ./ipa -ein_server=True -emode=dummy console
+ $ ./ipa -ein_server=True -emode=dummy console
The ``env`` command will print out the full environment in key=value pairs,
like this:
::
- $ ./ipa env
+ $ ./ipa env
If you use the ``--server`` option, it will forward the call to the server
over XML-RPC and print out what the environment is on the server, like this:
::
- $ ./ipa env --server
+ $ ./ipa env --server
The ``plugins`` command will show details of all the plugin that are loaded,
like this:
::
- $ ./ipa plugins
+ $ ./ipa plugins
-----------------------------------