version 0.3.1

[PyX/mjg.git] / design / arg.tex

% $Header$
%
\documentclass{article}
\usepackage{pyx}
\begin{document}
\section*{Design rules for variable argument lists and dictionaries
of functions in \PyX}

In order to get an easy user interface, we should restrict ourselfs to
some well defined ways of handling function calls with variable
argument lists and dictionaries. This file tries to consider the
typical occurrences within \PyX{} and provides standard solutions for
them.

We describe two different kind of function calls with variable
argument lists and dictionaries. They are called
``\verb|arglist|-functions and arguments'' and
``\verb|argdict|-functions and arguments''. The distinction between
these two cases is given by the way the arguments are passed to the
function. In the following we will try to make out the difference in
the subject of the functions and arguments already.

Combinations of \verb|arglist|- and \verb|argdict|-type of arguments
should be avoided (although they are possible). The discussion here is
not restricted to standard function calls, but applies to class
methods and constructors as well.

\subsection*{\texttt{arglist}-type functions and arguments}

Somehow, this first case is the more specific to \PyX{} necessities than
the second one. Let's first consider an example:
\begin{verbatim}
class A:
    def __str__(self):
        return "<a>"

class B:
    def __str__(self):
        return "<b>"

def show(self, *args):
    for arg in args:
        print arg

show(A(), B())
\end{verbatim}

Although this is a rather trivial example, you can see, that the
arguments are collected in a list. This list is used to perform the
action ``show'' on its entries. The entries supply the needed
techniques to get showed -- thus \verb|show| itself doesn't need to
know any details about it.

A main feature is, that the classes \verb|A| and \verb|B| could have
some properties. Consider the following:
\begin{verbatim}
class A:
    def __init__(self, color):
        self.color = color
    def __str__(self):
        return "<a color=\"%s\">" % self.color
\end{verbatim}

Instead of the previous call \verb|show(A(), B())| we now have
to specify the color, e.g.
\verb|show(A("red"), B())|.\footnote{The constructor of class
\texttt{A} could have a default value for \texttt{color} (like
\texttt{color = "black"}), so that this default value could just be
omitted. You may keep this in mind, because it is a rather typical
construction. However, it is not used here, because it might raise
some confusion, because such default values belong to the
\texttt{argdict}-type of functions and arguments.}

To go further, we do modify the print routine in order to print some
text within the \verb|<...>|-tags. Suppose, the \verb|<...>|-tags can
be closed by \verb|</>| uniformly, then we could do:
\begin{verbatim}
def show(self, text, *args):
    for arg in args:
        print arg
    print text
    for arg in args:
        print "</>"
\end{verbatim}

Here we have introduced a standard parameter \verb|text|, which leads
to an example call like \verb|show("text", A("red"), B())|. The
instances of class \verb|A| and \verb|B| become a property of
\verb|text|.

By this construction you can do even more, actually.
Consider the following:
\begin{verbatim}
show(A("red"))
show("text1")
show("text2")
\end{verbatim}

Here, the same class previously used as an property for a single
call of \verb|show| becomes now an automatically chosen attribute for
all following calls of \verb|show|.\footnote{We should ensure, that
calls like \textbf{show(A("red"), B())} don't work at all. In the case
of PostScript it need to be considered anyway, because the first
parameter usually provides PostScript as well as a bounding box
information unless we do a property change as first and only
parameter.} When this flavor of the property arguments is undesirable
its use should just be prohibited.\footnote{like for the \TeX/\LaTeX{}
interface ???}

You may miss the correct handling of the closing tags \verb|</>| in
the last example, but that's a question about the output needed.
Indeed, for PostScript, this is not an issue.

To summarize the description above, typical design features of
\verb|arglist|-type functions and arguments are:
\begin{itemize}
\item[$+$]
properties can just implement what they want --- the evaluation by
function calls makes it most flexible
\item[$+$]
property implementations are small and well separated
\item[$+$]
properties can have additional functionality --- they may are
comparable, incrementable, etc.
\item[$+$]
organization of properties can be done within a class tree
\item[$-$]
classes are needed construct all the different properties which leads
to a bloat up in the namespaces
\end{itemize}

\subsection*{\texttt{argdict}-type functions and arguments}

Consider a class \verb|axis| used to handle axes of a graphs. Its
constructor might be defined as:
\begin{verbatim}
class axis:
    def __init__(self, min = None, max = None):
        self.min = min
        self.max = max
\end{verbatim}

There are two predefined arguments, \verb|min| and \verb|max|. The
user could just create an axis without passing values to these
parameters, which would lead to the usage of the predefined
values.\footnote{In this example the value \texttt{None} could mean,
that minimal and maximal values are unknown and should be
automatically estimated.}

We now derive this class in order to implement a new feature, namely
an axis title. This would look like:
\begin{verbatim}
class titleaxis(axis):
    def __init__(self, min = None, max = None, title = ""):
        axis.__init__(self, min = min, max = max)
        self.title = title
\end{verbatim}

That would do, but its ugly. Of course, we can easily change the
default values for min and max -- but hence we have always to recode
the default values. What happens, if somebody enhances the class
\verb|axis| later? Yes, we wouldn't be able to access those additional
parameters without modifying titleaxis too.

The solution would look like the following:
\begin{verbatim}
class axis:
    def __init__(self, min = None, max = None):
        self.min = min
        self.max = max

class titleaxis(axis):
    def __init__(self, title = "", **args):
        axis.__init__(self, **args)
        self.title = title
\end{verbatim}

It is intrinsic, that we do not see all parameters we can handle to
the constructor of \verb|titleaxis| at its definition. As far as
discussed up to this point, this seems to be the perfect solution. And
for \PyX we shouldn't go along the line discussed in the following.
Anyhow, I want to describe it here to make the clear statement of
avoiding sophisticated excesses, although they may look fascinating.
I will point out the problems arising by them.

A first idea you could think about is multiple inheritance. Lets
assume, there is the same class \verb|axis| like before. Additionally,
there might be a class \verb|title| handling titles for arbitrary
objects:

\begin{verbatim}
class title:
    def __init__(self, title = ""):
        self.title = title
\end{verbatim}

A combination of those classes is a bad idea, because again you have
to know about the parameters and it's defaults, if you do:
\begin{verbatim}
class titleaxis(axis, title):
    def __init__(self, min = None, max = None, title = ""):
        axis.__init__(self, min = min, max = max)
        title.__init__(self, title)
\end{verbatim}

There is another way, which is exactly a solution, I claim we should
avoid. The idea is to append a dictionary for additional parameters at
the base classes. The code would then look like:

\begin{verbatim}
class axis:
    def __init__(self, min = None, max = None, **args):
        self.min = min
        self.max = max

class title:
    def __init__(self, title = "", **args):
        self.title = title

class titleaxis(axis, title):
    def __init__(self, **args):
        axis.__init__(self, **args)
        title.__init__(self, **args)
\end{verbatim}

There are two things causing trouble here. First, we have to be sure
to have dictionaries for additional parameters at all base classes.
Secondly, and that's much more crucial, we do not get errors any more,
if we pass parameters which are not handled by any of the base
constructors we call. While we wanted to avoid knowing all parameters,
we're in troubles here. We could inspect the constructors we call
(using the inspect module) and find out if a parameter is never used,
but we shouldn't do that.

Another application is a parameter, which provides some solution for a
special task. Consider the non-trivial task of an automatic axis
partitioning, where there are different algorithms to provide it.
While it is wanted to keep this algorithm apart from other axis stuff,
the question arises, how to insert such an algorithm into an axis
class. Using a special routine, the user has to call in order to
insert an automatic axis partitioning is bad, because it would mean, the
user always has to call it (although some automatic default could be
implemented). Another option, multiple inheritance, leads to some
constrains as discussed before. It would also mean, the user can't
modify the default by just implementing another automatic axis
partitioning class, but additionally a new axis class derivation would
be needed. Naturally, an automatic axis partitioning would be just an
parameter of the constructor of the axis. It would look like:
\begin{verbatim}
class genpart:
    def __init__(self, opt = 5):
        self.opt = opt

class axis:
    def __init__(self, min = None, max = None, part = genpart(opt = 10)):
        self.min = min
        self.max = max
        self.part = part
\end{verbatim}

And actually, this should be the solution of choice. Similar to the
idea already discussed above, we could thought of a mechanism of
making the parameter \verb|opt| of the constructor of \verb|genpart|
directly available as a parameter of the constructor of \verb|axis|.
Instead of writing something like \verb|axis(part = genpart(opt = 15))| 
we could desire a syntax \verb|axis(opt = 15)|. While it is
again a charming idea, it finally would generate a lot of trouble.

To summarize the description above, typical design features of
\verb|argdict|-type functions and arguments are:
\begin{itemize}
\item[$+$]straight forward implementation of ``to be set'' parameters
with default values
\item[$-$]should not be combined with an tailing dictionary parameter
(e.g. \verb|**args| at the end of the argument list)
\item[$-$]multiple inheritance should allow only one parent with an
\verb|argdict|-type constructor
\item[$-$]modification of parameters of default values (e.g. class
instances) are a little bulky
\end{itemize}

\section*{Comments}

\begin{itemize}
\item In my opinion, it is still not entirely clear, how we
  distinguish the use of \verb|arglist| and \verb|argdict| type
  parameters. Specifically, I think that a combination of both may in
  some cases be desirable. Consider for instance in the \verb|axis|
  example the case, where one wants to specify additionally the font
  size of the title. Would this not justify the use of an
  \verb|arglist| type argument? 
\item Probably the distinction is already clear, if one draws the line
  between graphical properties (color, line/text style/width, etc.)
  and other things. But where exactly then do fit in transformations,
  clipping, arrows, \dots?
\item Maybe we should make \verb|arglist| type arguments the special
  case of \verb|argdict| arguments, namely \'a la 
\begin{verbatim}
class main:
    def show(self, style=(), *args):
        for arg in args + tuple(style):
            print arg

\end{verbatim}
We could even think of something like the following:
\begin{verbatim}
class main:
    def show(self, style=(), trafo=(), *args):
        for arg in args + tuple(style) + tuple(trafo):
            print arg

\end{verbatim}
or maybe better 
\begin{verbatim}
class main:
    def show(self, style=(), trafo=(), *args):
         for t in select_args(args, trafo, trafo.trafo):
            print t

\end{verbatim}
where \verb|select_arg(args, inst, _class)| is a helper routine, which
selects all instances of the class \verb|_class| out of the lists
\verb|args| and \verb|inst|, where in the latter one only instances of
\verb|_class| are allowed. Maybe, we could also convert \verb|args| in
advance to a list which can the modified in place by
\verb|select_args|, and all found instances of \verb|_class| can be deleted.

\end{itemize}

\end{document}