summaryrefslogtreecommitdiffstats
path: root/ipalib/output.py
blob: 19dd9adadeb8521caf9f0dc52981ce57a7f0c8b6 (plain)
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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
# 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.
"""
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:
            if not isinstance(type, tuple):
                type = (type,)
            self.type = type
        if doc is not None:
            self.doc = doc
        self.flags = flags
        lock(self)

    def __repr__(self):
        return '%s(%s)' % (
            self.__class__.__name__,
            ', '.join(self.__repr_iter())
        )

    def __repr_iter(self):
        yield repr(self.name)
        for key in ('type', 'doc', 'flags'):
            value = self.__dict__.get(key)
            if not value:
                continue
            if isinstance(value, tuple):
                value = repr(list(value))
            else:
                value = repr(value)
            yield '%s=%s' % (key, value)


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

simple_value = (
    summary,
    Output('result', bool, _('True means the operation was successful')),
    Output('value', unicode, flags=['no_display']),
)