3

�d[e.1�@s�dZd
dl
mZ
d
dlmZ
d
dlmZ
d
dlmZ
d
dlmZ
Gdd�de�Z	Gd	d
�d
e�Z
Gdd�de
�ZGd
d�de
�ZGdd�de
�Z
Gdd�de�ZGdd�dej�ZdS)a�
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.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
``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.
�)
�Method)
�backend)
�
parameters)
�output)
�
_cs:eZ
dZd
ZejZdd�Z�f
dd�Z�f
dd�Z	�Z
S)�Createz
    Create a new entry.
    cKs&d
|
jkrd|d<|r"|
j
f|�
S|
S)NZoptional_createF�required)�flags�clone)�selfZparam�kw�r
�/usr/lib/python3.6/crud.pyZ__clone�s



zCreate.__clonec
#sD|jj
r|j|jj
d
d�V
x"tt|�j�D]}
|j|
�
V
q,WdS)NT)
�	attribute)�obj�primary_key�_Create__clone�superr�get_args)r�arg)
�	__class__r
rr�s



zCreate.get_argsc
#s�|jr*x"t
t|�j�D]}
|j|
�
V
qWx^|jj|j�
D]L}
d
|
jk}d|
jkrTq:d|
jkrv|
j	|ddddd�V
q:|j|
|d�V
q:W|js�x"t
t|�j�D]}
|j|
�
V
q�WdS)N�virtual_attributeZ	no_createZ
ask_createFT)r�queryr�autofill�	alwaysask)
r)
�extra_options_firstrr�get_optionsrr�params_minus�argsr	r
)r�optionr)
rr
rr�s
















zCreate.get_options)�__name__�
__module__�__qualname__�__doc__r�standard_entry�
has_outputrrr�
__classcell__r
r
)
rrr�s
rcs eZ
dZd
Z�f
dd�Z�ZS)�PKQueryz<
    Base class for `Retrieve`, `Update`, and `Delete`.
    c
#s>|jj
r|jj
jd
d
d�V
xtt|�j�D]
}
|
V
q,WdS)NT)rr)rrr
rr'r)rr)
rr
rr�s


zPKQuery.get_args)r r!r"r#rr&r
r
)
rrr'�sr'c
@seZ
dZd
ZejZdS)�Retrievez/
    Retrieve an entry by its primary key.
    N)r r!r"r#rr$r%r
r
r
rr(�sr(cs&eZ
dZd
ZejZ�f
dd�Z�ZS)�Updatez4
    Update one or more attributes on an entry.
    c
	#s�|jr$xt
t|�j�D]
}
|
V
qWx�|jj�D]�}
|
j}d
|
jk}|
jrV|jdg
�
}d|
jkrbq0d|
jkr�|
j	|dddd|d�V
q0d|
jkr�|
j	|dd|d	�V
q0|
j	|dd|d
�V
q0W|js�xt
t|�j�D]
}
|
V
q�WdS)NrZnonemptyZ	no_updateZ
ask_updateFT)rrrrrr	Z
req_update)rrrr	)rrrr	)
rrr)rrZparams_minus_pkr	r�unionr
)rrZ	new_flagsr)
rr
rr�s.























zUpdate.get_options)	r r!r"r#rr$r%rr&r
r
)
rrr)�sr)c
@seZ
dZd
ZejZdS)�Deletez%
    Delete one or more entries.
    N)r r!r"r#rZstandard_deleter%r
r
r
rr+�sr+cs2eZ
dZd
ZejZ�f
dd�Z�f
dd�Z�Z	S)�SearchzB
    Retrieve all entries that match a given search criteria.
    c
#s8tj
d
dtd�
d�V
xtt|�j�D]
}
|
V
q&WdS)Nz	criteria?Fz3A string searched in all relevant object attributes)Znoextrawhitespace�doc)rZStrrrr,r)rr)
rr
rr�s





zSearch.get_argsc
	#s�|jr$xt
t|�j�D]
}
|
V
qWx�|jj|j�
D]z}
d
|
jk}d|
jkrNq4d|
jkrp|
j|ddddd�V
q4t	|
t
j�r�|
j|
j
t
j|dddd�V
q4|
j|dddd�V
q4W|js�xt
t|�j�D]
}
|
V
q�WdS)NrZ	no_searchZ
ask_searchTF)rrrrr)rrrr)rrr,rrrrr	r
�
isinstancer�FlagZclone_retype�nameZBool)rrr)
rr
rr�s(




















zSearch.get_options)
r r!r"r#rZstandard_list_of_entriesr%rrr&r
r
)
rrr,�sr,c@s8eZ
dZd
Zdd�Zdd�Zdd�Zdd	�Zd
d�ZdS)
�CrudBackendz7
    Base class defining generic CRUD backend API.
    c
Kstd
|j
�
�
dS)aa
        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.
        z%s.create()N)�NotImplementedErrorr0)rrr
r
r�create
szCrudBackend.createcCstd
|j
�
�
dS)a�

        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.
        z
%s.retrieve()N)r2r0)rrZ
attributesr
r
r�retrieve,
s
zCrudBackend.retrievecKstd
|j
�
�
dS)a�

        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.
        z%s.update()N)r2r0)rrrr
r
r�update;
szCrudBackend.updatecCstd
|j
�
�
dS)z�
        Delete an existing entry.

        This method should take one required argument, the primary_key of the
        entry to delete.
        z%s.delete()N)r2r0)rrr
r
r�deleteI
szCrudBackend.deletec
Kstd
|j
�
�
dS)a!
        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.
        z%s.search()N)r2r0)rrr
r
r�searchR
s
zCrudBackend.searchN)	r r!r"r#r3r4r5r6r7r
r
r
rr1
s	r1N)r#Zipalib.frontendrZipalibrrrZipalib.textrrr'r(r)r+r,ZConnectibler1r
r
r
r�<module>xs



&()