Coverage for ipalib/crud : 90%
Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
|
# Authors: # Jason Gerard DeRose <jderose@redhat.com> # # Copyright (C) 2008 Red Hat # see file 'COPYING' for use and warranty information # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>.
Base classes for standard CRUD operations.
These base classes are for `Method` plugins that provide standard Create, Retrieve, Updated, and Delete operations (CRUD) for their corresponding `Object` plugin. In particuar, these base classes provide logic to automatically create the plugin args and options by inspecting the params on their corresponding `Object` plugin. This provides a single point of definition for LDAP attributes and enforces a simple, consistent API for CRUD operations.
For example, say we want CRUD operations on a hypothetical "user" entry. First we need an `Object` plugin:
>>> from ipalib import Object, Str >>> class user(Object): ... takes_params = ( ... Str('login', primary_key=True), ... Str('first'), ... Str('last'), ... Str('ipauniqueid', flags=['no_create', 'no_update']), ... ) ...
Next we need `Create`, `Retrieve`, `Updated`, and `Delete` plugins, and optionally a `Search` plugin. For brevity, we'll just define `Create` and `Retrieve` plugins:
>>> from ipalib import crud >>> class user_add(crud.Create): ... pass ... >>> class user_show(crud.Retrieve): ... pass ...
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.finalize()
First, notice that our ``user`` `Object` has the params we defined with the ``takes_params`` tuple:
>>> list(api.Object.user.params) ['login', 'first', 'last', 'ipauniqueid'] >>> api.Object.user.params.login Str('login', primary_key=True)
Although we defined neither ``takes_args`` nor ``takes_options`` for our ``user_add`` plugin, the `Create` base class automatically generated them for us:
>>> list(api.Command.user_add.args) ['login'] >>> list(api.Command.user_add.options) ['first', 'last', 'all', 'raw', 'version']
Notice that ``'ipauniqueid'`` isn't included in the options for our ``user_add`` plugin. This is because of the ``'no_create'`` flag we used when defining the ``ipauniqueid`` param. Often times there are LDAP attributes that are automatically created by the server and therefor should not be supplied as an option to the `Create` plugin. Often these same attributes shouldn't be update-able either, in which case you can also supply the ``'no_update'`` flag, as we did with our ``ipauniqueid`` param. Lastly, you can also use the ``'no_search'`` flag for attributes that shouldn't be search-able (because, for example, the attribute isn't indexed).
As with our ``user_add` plugin, we defined neither ``takes_args`` nor ``takes_options`` for our ``user_show`` plugin; instead the `Retrieve` base class created them for us:
>>> list(api.Command.user_show.args) ['login'] >>> list(api.Command.user_show.options) ['all', 'raw', 'version']
As you can see, `Retrieve` plugins take a single argument (the primary key) and no options. If needed, you can still specify options for your `Retrieve` plugin with a ``takes_options`` tuple.
Flags like ``'no_create'`` remove LDAP attributes from those that can be supplied as *input* to a `Method`, but they don't effect the attributes that can be returned as *output*. Regardless of what flags have been used, the output entry (or list of entries) can contain all the attributes defined on the `Object` plugin (in our case, the above ``user.params``).
For example, compare ``user.params`` with ``user_add.output_params`` and ``user_show.output_params``:
>>> list(api.Object.user.params) ['login', 'first', 'last', 'ipauniqueid'] >>> list(api.Command.user_add.output_params) ['login', 'first', 'last', 'ipauniqueid'] >>> list(api.Command.user_show.output_params) ['login', 'first', 'last', 'ipauniqueid']
Note that the above are all equal. """
""" Create a new entry. """
for option in super(Create, self).get_options(): yield option attribute=attribute, query=False, required=False, autofill=False, alwaysask=True ) else:
""" Base class for `Retrieve`, `Update`, and `Delete`. """
# Don't enforce rules on the primary key so we can reference # any stored entry, legal or not
""" Retrieve an entry by its primary key. """
""" Update one or more attributes on an entry. """
for option in super(Update, self).get_options(): yield option # Required options turn into non-required, since not specifying # them means that they are not changed. # However, they cannot be empty (i.e. explicitly set to None). yield option.clone( attribute=attribute, query=False, required=False, autofill=False, alwaysask=True, flags=new_flags, ) attribute=attribute, required=True, alwaysask=False, flags=new_flags, ) else: autofill=False, flags=new_flags, )
""" Delete one or more entries. """
""" Retrieve all entries that match a given search criteria. """
for option in super(Search, self).get_options(): yield option yield option.clone( attribute=attribute, query=True, required=False, autofill=False, alwaysask=True ) option.name, parameters.Bool, attribute=attribute, query=True, required=False, autofill=False ) else: attribute=attribute, query=True, required=False, autofill=False )
""" Base class defining generic CRUD backend API. """
""" Create a new entry.
This method should take key word arguments representing the attributes the created entry will have.
If this methods constructs the primary_key internally, it should raise an exception if the primary_key was passed. Likewise, if this method requires the primary_key to be passed in from the caller, it should raise an exception if the primary key was *not* passed.
This method should return a dict of the exact entry as it was created in the backing store, including any automatically created attributes. """
""" Retrieve an existing entry.
This method should take a two arguments: the primary_key of the entry in question and a list of the attributes to be retrieved. If the list of attributes is None then all non-operational attributes will be returned.
If such an entry exists, this method should return a dict representing that entry. If no such entry exists, this method should return None. """
""" Update an existing entry.
This method should take one required argument, the primary_key of the entry to modify, plus optional keyword arguments for each of the attributes being updated.
This method should return a dict representing the entry as it now exists in the backing store. If no such entry exists, this method should return None. """
""" Delete an existing entry.
This method should take one required argument, the primary_key of the entry to delete. """
""" Return entries matching specific criteria.
This method should take keyword arguments representing the search criteria. If a key is the name of an entry attribute, the value should be treated as a filter on that attribute. The meaning of keys outside this namespace is left to the implementation.
This method should return and iterable containing the matched entries, where each entry is a dict. If no entries are matched, this method should return an empty iterable. """ |