lib/xsd/codegen

# 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; version 2 only
#
# 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, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

"""
Base classes for all front-end plugins.
"""

import re
import inspect
from base import lock, check_name, NameSpace
from plugable import Plugin
from parameters import create_param, parse_param_spec, Param, Str, Flag, Password
from util import make_repr
from output import Output, Entry, ListOfEntries
from text import _, ngettext

from errors import ZeroArgumentError, MaxArgumentError, OverlapError, RequiresRoot
from errors import InvocationError
from constants import TYPE_ERROR


RULE_FLAG = 'validation_rule'

def rule(obj):
    assert not hasattr(obj, RULE_FLAG)
    setattr(obj, RULE_FLAG, True)
    return obj

def is_rule(obj):
    return callable(obj) and getattr(obj, RULE_FLAG, False) is True


class HasParam(Plugin):
    """
    Base class for plugins that have `Param` `NameSpace` attributes.

    Subclasses of `HasParam` will on one or more attributes store `NameSpace`
    instances containing zero or more `Param` instances.  These parameters might
    describe, for example, the arguments and options a command takes, or the
    attributes an LDAP entry can include, or whatever else the subclass sees
    fit.

    Although the interface a subclass must implement is very simple, it must
    conform to a specific naming convention: if you want a namespace
    ``SubClass.foo``, you must define a ``Subclass.takes_foo`` attribute and a
    ``SubCLass.get_foo()`` method, and you may optionally define a
    ``SubClass.check_foo()`` method.


    A quick big-picture example
    ===========================

    Say you want the ``options`` instance attribute on your subclass to be a
    `Param` `NameSpace`... then according to the enforced naming convention,
    your subclass must define a ``takes_options`` attribute and a
    ``get_options()`` method.  For example:

    >>> from ipalib import Str, Int
    >>> class Example(HasParam):
    ...
    ...     options = None  # This will be replaced with your namespace
    ...
    ...     takes_options = (Str('one'), Int('two'))
    ...
    ...     def get_options(self):
    ...         return self._get_param_iterable('options')
    ...
    >>> eg = Example()

    The ``Example.takes_options`` attribute is a ``tuple`` defining the
    parameters you want your ``Example.options`` namespace to contain.  Your
    ``Example.takes_options`` attribute will be accessed via
    `HasParam._get_param_iterable()`, which, among other things, enforces the
    ``('takes_' + name)`` naming convention.  For example:

    >>> eg._get_param_iterable('options')
    (Str('one'), Int('two'))

    The ``Example.get_options()`` method simply returns
    ``Example.takes_options`` by calling `HasParam._get_param_iterable()`.  Your
    ``Example.get_options()`` method will be called via
    `HasParam._filter_param_by_context()`, which, among other things, enforces
    the ``('get_' + name)`` naming convention.  For example:

    >>> list(eg._filter_param_by_context('options'))
    [Str('one'), Int('two')]

    At this point, the ``eg.options`` instance attribute is still ``None``:

    >>> eg.options is None
    True

    `HasParam._create_param_namespace()` will create the ``eg.options``
    namespace from the parameters yielded by
    `HasParam._filter_param_by_context()`.  For example:

    >>> eg._create_param_namespace('options')
    >>> eg.options
    NameSpace(<2 members>, sort=False)
    >>> list(eg.options)  # Like dict.__iter__()
    ['one', 'two']

    Your subclass can optionally define a ``check_options()`` method to perform
    sanity checks.  If it exists, the ``check_options()`` method is called by
    `HasParam._create_param_namespace()` with a single value, the `NameSpace`
    instance it created.  For example:

    >>> class Example2(Example):
    ...
    ...     def check_options(self, namespace):
    ...         for param in namespace():  # Like dict.itervalues()
    ...             if param.name == 'three':
    ...                 raise ValueError("I dislike the param 'three'")
    ...         print '  ** Looks good! **'  # Note output below
    ...
    >>> eg = Example2()
    >>> eg._create_param_namespace('options')
      ** Looks good! **
    >>> eg.options
    NameSpace(<2 members>, sort=False)

    However, if we subclass again and add a `Param` named ``'three'``:

    >>> class Example3(Example2):
    ...
    ...     takes_options = (Str('one'), Int('two'), Str('three'))
    ...
    >>> eg = Example3()
    >>> eg._create_param_namespace('options')
    Traceback (most recent call last):
      ...
    ValueError: I dislike the param 'three'
    >>> eg.options is None  # eg.options was not set
    True


    The Devil and the details
    =========================

    In the above example, ``takes_options`` is a ``tuple``, but it can also be
    a param spec (see `create_param()`), or a callable that returns an iterable
    containing one or more param spec.  Regardless of how ``takes_options`` is
    defined, `HasParam._get_param_iterable()` will return a uniform iterable,
    conveniently hiding the details.

    The above example uses the simplest ``get_options()`` method possible, but
    you could instead implement a ``get_options()`` method that would, for
    example, produce (or withhold) certain parameters based on the whether
    certain plugins are loaded.

    Think of ``takes_options`` as declarative, a simple definition of *what*
    parameters should be included in the namespace.  You should only implement
    a ``takes_options()`` method if a `Param` must reference attributes on your
    plugin instance (for example, for validation rules); you should not use a
    ``takes_options()`` method to filter the parameters or add any other
    procedural behaviour.

    On the other hand, think of the ``get_options()`` method as imperative, a
    procedure for *how* the parameters should be created and filtered.  In the
    example above the *how* just returns the *what* unchanged, but arbitrary
    logic can be implemented in the ``get_options()`` method.  For example, you
    might filter certain parameters from ``takes_options`` base on some
    criteria, or you might insert additional parameters provided by other
    plugins.

    The typical use case for using ``get_options()`` this way is to procedurally
    generate the arguments and options for all the CRUD commands operating on a
    specific LDAP object: the `Object` plugin defines the possible LDAP entry
    attributes (as `Param`), and then the CRUD commands intelligently build
    their ``args`` and ``options`` namespaces based on which attribute is the
    primary key.  In this way new LDAP attributes (aka parameters) can be added
    to the single point of definition (the `Object` plugin), and all the
    corresponding CRUD commands pick up these new parameters without requiring
    modification.  For an example of how this is done, see the
    `ipalib.crud.Create` base class.

    However, there is one type of filtering you should not implement in your
    ``get_options()`` method, because it's already provided at a higher level:
    you should not filter parameters based on the value of ``api.env.context``
    nor (preferably) on any values in ``api.env``.
    `HasParam._filter_param_by_context()` already does this by calling
    `Param.use_in_context()` for each parameter.  Although the base
    `Param.use_in_context()` implementation makes a decision solely on the value
    of ``api.env.context``, subclasses can override this with implementations
    that consider arbitrary ``api.env`` values.
    """

    def _get_param_iterable(self, name, verb='takes'):
        """
        Return an iterable of params defined by the attribute named ``name``.

        A sequence of params can be defined one of three ways: as a ``tuple``;
        as a callable that returns an iterable; or as a param spec (a `Param` or
        ``str`` instance).  This method returns a uniform iterable regardless of
        how the param sequence was defined.

        For example, when defined with a tuple:

        >>> class ByTuple(HasParam):
        ...     takes_args = (Param('foo'), Param('bar'))
        ...
        >>> by_tuple = ByTuple()
        >>> list(by_tuple._get_param_iterable('args'))
        [Param('foo'), Param('bar')]

        Or you can define your param sequence with a callable when you need to
        reference attributes on your plugin instance (for validation rules,
        etc.).  For example:

        >>> class ByCallable(HasParam):
        ...     def takes_args(self):
        ...         yield Param('foo', self.validate_foo)
        ...         yield Param('bar', self.validate_bar)
        ...
        ...     def validate_foo(self, _, value, **kw):
        ...         if value != 'Foo':
        ...             return _("must be 'Foo'")
        ...
        ...     def validate_bar(self, _, value, **kw):
        ...         if value != 'Bar':
        ...             return _("must be 'Bar'")
        ...
        >>> by_callable = ByCallable()
        >>> list(by_callable._get_param_iterable('args'))
        [Param('foo', validate_foo), Param('bar', validate_bar)]

        Lastly, as a convenience for when a param sequence contains a single
        param, your defining attribute may a param spec (either a `Param`
        or an ``str`` instance).  For example:

        >>> class BySpec(HasParam):
        ...     takes_args = Param('foo')
        ...     takes_options = 'bar?'
        ...
        >>> by_spec = BySpec()
        >>> list(by_spec._get_param_iterable('args'))
        [Param('foo')]
        >>> list(by_spec._get_param_iterable('options'))
        ['bar?']

        For information on how an ``str`` param spec is interpreted, see the
        `create_param()` and `parse_param_spec()` functions in the
        `ipalib.parameters` module.

        Also see `HasParam._filter_param_by_context()`.
        """
        src_name = verb + '_' + name
        src = getattr(self, src_name, None)
        if type(src) is tuple:
            return src
        if isinstance(src, (Param, str)):
            return (src,)
        if callable(src):
            return src()
        if src is None:
            return tuple()
        raise TypeError(
            '%s.%s must be a tuple, callable, or spec; got %r' % (
                self.name, src_name, src
            )
        )

    def _filter_param_by_context(self, name, env=None):
        """
        Filter params on attribute named ``name`` by environment ``env``.

        For example:

        >>> from ipalib.config import Env
        >>> class Example(HasParam):
        ...
        ...     takes_args = (
        ...         Str('foo_only', include=['foo']),
        ...         Str('not_bar', exclude=['bar']),
        ...         'both',
        ...     )
        ...
        ...     def get_args(self):
        ...         return self._get_param_iterable('args')
        ...
        ...
        >>> eg = Example()
        >>> foo = Env(context='foo')
        >>> bar = Env(context='bar')
        >>> another = Env(context='another')
        >>> (foo.context, bar.context, another.context)
        ('foo', 'bar', 'another')
        >>> list(eg._filter_param_by_context('args', foo))
        [Str('foo_only', include=['foo']), Str('not_bar', exclude=['bar']), Str('both')]
        >>> list(eg._filter_param_by_context('args', bar))
        [Str('both')]
        >>> list(eg._filter_param_by_context('args', another))
        [Str('not_bar', exclude=['bar']), Str('both')]
        """
        env = getattr(self, 'env', env)
        get_name = 'get_' + name
        if not hasattr(self, get_name):
            raise NotImplementedError(
                '%s.%s()' % (self.name, get_name)
            )
        get = getattr(self, get_name)
        if not callable(get):
            raise TypeError(
                '%s.%s must be a callable; got %r' % (self.name, get_name, get)
            )
        for spec in get():
            param = create_param(spec)
            if env is None or param.use_in_context(env):
                yield param

    def _create_param_namespace(self, name, env=None):
        namespace = NameSpace(
            self._filter_param_by_context(name, env),
            sort=False
        )
        check = getattr(self, 'check_' + name, None)
        if callable(check):
            check(namespace)
        setattr(self, name, namespace)


class Command(HasParam):
    """
    A public IPA atomic operation.

    All plugins that subclass from `Command` will be automatically available
    as a CLI command and as an XML-RPC method.

    Plugins that subclass from Command are registered in the ``api.Command``
    namespace. For example:

    >>> from ipalib import create_api
    >>> api = create_api()
    >>> class my_command(Command):
    ...     pass
    ...
    >>> api.register(my_command)
    >>> api.finalize()
    >>> list(api.Command)
    ['my_command']
    >>> api.Command.my_command # doctest:+ELLIPSIS
    ipalib.frontend.my_command()
    """

    takes_options = tuple()
    takes_args = tuple()
    args = None
    options = None
    params = None
    output_for_cli = None
    obj = None

    use_output_validation = True
    output = None
    has_output = ('result',)
    output_params = None
    has_output_params = tuple()

    msg_summary = None
    msg_truncated = _('Results are truncated, try a more specific search')

    def __call__(self, *args, **options):
        """
        Perform validation and then execute the command.

        If not in a server context, the call will be forwarded over
        XML-RPC and the executed an the nearest IPA server.
        """
        params = self.args_options_2_params(*args, **options)
        self.debug(
            'raw: %s(%s)', self.name, ', '.join(self._repr_iter(**params))
        )
        params = self.normalize(**params)
        params = self.convert(**params)
        params.update(self.get_default(**params))
        self.info(
            '%s(%s)', self.name, ', '.join(self._repr_iter(**params))
        )
        self.validate(**params)
        (args, options) = self.params_2_args_options(**params)
        ret = self.run(*args, **options)
        if (
            isinstance(ret, dict)
            and 'summary' in self.output
            and 'summary' not in ret
        ):
            if self.msg_summary:
                ret['summary'] = self.msg_summary % ret
            else:
                ret['summary'] = None
        if self.use_output_validation and (self.output or ret is not None):
            self.validate_output(ret)
        return ret

    def soft_validate(self, values):
        errors = dict()
        for p in self.params():
            try:
                value = values.get(p.name)
                values[p.name] = p(value, **values)
            except InvocationError, e:
                errors[p.name] = str(e)
        return dict(
            values=values,
            errors=errors,
        )

    def _repr_iter(self, **params):
        """
        Iterate through ``repr()`` of *safe* values of args and options.

        This method uses `parameters.Param.safe_value()` to mask passwords when
        logging.  Logging the exact call is extremely useful, but we obviously
        don't want to log the cleartext password.

        For example:

        >>> class my_cmd(Command):
        ...     takes_args = ('login',)
        ...     takes_options=(Password('passwd'),)
        ...
        >>> c = my_cmd()
        >>> c.finalize()
        >>> list(c._repr_iter(login=u'Okay.', passwd=u'Private!'))
        ["u'Okay.'", "passwd=u'********'"]
        """
        for arg in self.args():
            value = params.get(arg.name, None)
            yield repr(arg.safe_value(value))
        for option in self.options():
            if option.name not in params:
                continue
            value = params[option.name]
            yield '%s=%r' % (option.name, option.safe_value(value))

    def args_options_2_params(self, *args, **options):
        """
        Merge (args, options) into params.
        """
        if self.max_args is not None and len(args) > self.max_args:
            if self.max_args == 0:
                raise ZeroArgumentError(name=self.name)
            raise MaxArgumentError(name=self.name, count=self.max_args)
        params = dict(self.__options_2_params(options))
        if len(args) > 0:
            arg_kw = dict(self.__args_2_params(args))
            intersection = set(arg_kw).intersection(params)
            if len(intersection) > 0:
                raise OverlapError(names=sorted(intersection))
            params.update(arg_kw)
        return params

    def __args_2_params(self, values):
        multivalue = False
        for (i, arg) in enumerate(self.args()):
            assert not multivalue
            if len(values) > i:
                if arg.multivalue:
                    multivalue = True
                    if len(values) == i + 1 and type(values[i]) in (list, tuple):
                        yield (arg.name, values[i])
                    else:
                        yield (arg.name, values[i:])
                else:
                    yield (arg.name, values[i])
            else:
                break

    def __options_2_params(self, options):
        for name in self.params:
            if name in options:
                yield (name, options[name])

    def args_options_2_entry(self, *args, **options):
        """
        Creates a LDAP entry from attributes in args and options.
        """
        kw = self.args_options_2_params(*args, **options)
        return dict(self.__attributes_2_entry(kw))

    def __convert_2_dict(self, attrs, append=True):
        """
        Convert a string in the form of name/value pairs into
        a dictionary. The incoming attribute may be a string or
        a list.

        Any attribute found that is also a param is silently dropped.

        append controls whether this returns a list of values or a single
        value.
        """
        newdict = {}
        if not type(attrs) in (list, tuple):
            attrs = [attrs]
        for a in attrs:
            m = re.match("\s*(.*?)\s*=\s*(.*?)\s*$", a)
            attr = str(m.group(1)).lower()
            value = m.group(2)
            if len(value) == 0:
                # None means "delete this attribute"
                value = None
            if attr not in self.params:
                if append and attr in newdict:
                    newdict[attr].append(value)
                else:
                    newdict[attr] = [value]
        return newdict

    def __attributes_2_entry(self, kw):
        for name in self.params:
            if self.params[name].attribute and name in kw:
                value = kw[name]
                if isinstance(value, tuple):
Mode	Name	Size
-rw-r--r--	classdef.rb	4393	log stats plain
-rw-r--r--	commentdef.rb	606	log stats plain
-rw-r--r--	gensupport.rb	2928	log stats plain
-rw-r--r--	methoddef.rb	1229	log stats plain
-rw-r--r--	moduledef.rb	4008	log stats plain