1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
# Authors:
# Jason Gerard DeRose <jderose@redhat.com>
#
# Copyright (C) 2009 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/>.
"""
Simple description of return values.
"""
from inspect import getdoc
import six
from ipalib.plugable import ReadOnly, lock
from ipalib.capabilities import client_has_capability
from ipalib.text import _
if six.PY3:
unicode = str
class Output(ReadOnly):
"""
Simple description of a member in the return value ``dict``.
This class controls both the type of object being returned by
a command as well as how the output will be displayed.
For example, this class defines two return results: an entry
and a value.
>>> from ipalib import crud, output
>>> class user(crud.Update):
...
... has_output = (
... output.Entry('result'),
... output.value,
... )
The order of the values in has_output controls the order of output.
If you have values that you don't want to be printed then add
``'no_display'`` to flags.
The difference between ``'no_display'`` and ``'no_output'`` is
that ``'no_output'`` will prevent a Param value from being returned
at all. ``'no_display'`` will cause the API to return a value, it
simply won't be displayed to the user. This is so some things may
be returned that while not interesting to us, but may be to others.
>>> from ipalib import crud, output
>>> myvalue = output.Output('myvalue', unicode,
... 'Do not print this value', flags=['no_display'],
... )
>>> class user(crud.Update):
...
... has_output = (
... output.Entry('result'),
... myvalue,
... )
"""
type = None
validate = None
doc = None
flags = []
def __init__(self, name, type=None, doc=None, flags=[]):
self.name = name
if type is not None:
self.type = type
if doc is not None:
self.doc = doc
self.flags = flags
lock(self)
def __repr__(self):
return '%s(%r, %r, %r)' % (
self.__class__.__name__, self.name, self.type, self.doc,
)
class Entry(Output):
type = dict
doc = _('A dictionary representing an LDAP entry')
emsg = """%s.validate_output() => %s.validate():
output[%r][%d]: need a %r; got a %r: %r"""
class ListOfEntries(Output):
type = (list, tuple)
doc = _('A list of LDAP entries')
def validate(self, cmd, entries, version):
assert isinstance(entries, self.type)
for (i, entry) in enumerate(entries):
if not isinstance(entry, dict):
raise TypeError(emsg % (cmd.name, self.__class__.__name__,
self.name, i, dict, type(entry), entry)
)
class PrimaryKey(Output):
def validate(self, cmd, value, version):
if client_has_capability(version, 'primary_key_types'):
if hasattr(cmd, 'obj') and cmd.obj and cmd.obj.primary_key:
types = cmd.obj.primary_key.allowed_types
else:
types = (unicode,)
types = types + (type(None),)
else:
types = (unicode,)
if not isinstance(value, types):
raise TypeError(
"%s.validate_output() => %s.validate():\n"
" output[%r]: need %r; got %r: %r" % (
cmd.name, self.__class__.__name__, self.name,
types[0], type(value), value))
class ListOfPrimaryKeys(Output):
def validate(self, cmd, values, version):
if client_has_capability(version, 'primary_key_types'):
types = (tuple, list)
else:
types = (unicode,)
if not isinstance(values, types):
raise TypeError(
"%s.validate_output() => %s.validate():\n"
" output[%r]: need %r; got %r: %r" % (
cmd.name, self.__class__.__name__, self.name,
types[0], type(values), values))
if client_has_capability(version, 'primary_key_types'):
if hasattr(cmd, 'obj') and cmd.obj and cmd.obj.primary_key:
types = cmd.obj.primary_key.allowed_types
else:
types = (unicode,)
for (i, value) in enumerate(values):
if not isinstance(value, types):
raise TypeError(emsg % (
cmd.name, self.__class__.__name__, i, self.name,
types[0], type(value), value))
result = Output('result', doc=_('All commands should at least have a result'))
summary = Output('summary', (unicode, type(None)),
_('User-friendly description of action performed')
)
value = PrimaryKey('value', None,
_("The primary_key value of the entry, e.g. 'jdoe' for a user"),
flags=['no_display'],
)
standard = (summary, result)
standard_entry = (
summary,
Entry('result'),
value,
)
standard_list_of_entries = (
summary,
ListOfEntries('result'),
Output('count', int, _('Number of entries returned')),
Output('truncated', bool, _('True if not all results were returned')),
)
standard_delete = (
summary,
Output('result', dict, _('List of deletions that failed')),
value,
)
standard_multi_delete = (
summary,
Output('result', dict, _('List of deletions that failed')),
ListOfPrimaryKeys('value', flags=['no_display']),
)
standard_boolean = (
summary,
Output('result', bool, _('True means the operation was successful')),
value,
)
standard_value = standard_boolean
|
