allow_new_attr to Struct. _ip.options now disallows attr creation

IPython/ipapi.py

@@ -1,330 +1,336 b''
 ''' IPython customization API
 
 Your one-stop module for configuring & extending ipython
 
 The API will probably break when ipython 1.0 is released, but so 
 will the other configuration method (rc files).
 
 All names prefixed by underscores are for internal use, not part 
 of the public api.
 
 Below is an example that you can just put to a module and import from ipython. 
 
 A good practice is to install the config script below as e.g. 
 
 ~/.ipython/my_private_conf.py
 
 And do 
 
 import_mod my_private_conf 
 
 in ~/.ipython/ipythonrc
 
 That way the module is imported at startup and you can have all your
 personal configuration (as opposed to boilerplate ipythonrc-PROFILENAME 
 stuff) in there. 
 
 -----------------------------------------------
 import IPython.ipapi
 ip = IPython.ipapi.get()
 
 def ankka_f(self, arg):
     print "Ankka",self,"says uppercase:",arg.upper()
 
 ip.expose_magic("ankka",ankka_f)
 
 ip.magic('alias sayhi echo "Testing, hi ok"')
 ip.magic('alias helloworld echo "Hello world"')
 ip.system('pwd')
 
 ip.ex('import re')
 ip.ex("""
 def funcci(a,b):
     print a+b
 print funcci(3,4)
 """)
 ip.ex("funcci(348,9)")
 
 def jed_editor(self,filename, linenum=None):
     print "Calling my own editor, jed ... via hook!"
     import os
     if linenum is None: linenum = 0
     os.system('jed +%d %s' % (linenum, filename))
     print "exiting jed"
 
 ip.set_hook('editor',jed_editor)
 
 o = ip.options
 o.autocall = 2  # FULL autocall mode
 
 print "done!"
 '''
 
 # stdlib imports
 import __builtin__
 import sys
 
 # our own
 from IPython.genutils import warn,error
  
 class TryNext(Exception):
     """Try next hook exception.
      
     Raise this in your hook function to indicate that the next hook handler
     should be used to handle the operation.  If you pass arguments to the
     constructor those arguments will be used by the next hook instead of the
     original ones.
     """
 
     def __init__(self, *args, **kwargs):
         self.args = args
         self.kwargs = kwargs
 
 # contains the most recently instantiated IPApi
 
 class IPythonNotRunning:
     """Dummy do-nothing class.
 
     Instances of this class return a dummy attribute on all accesses, which
     can be called and warns.  This makes it easier to write scripts which use
     the ipapi.get() object for informational purposes to operate both with and
     without ipython.  Obviously code which uses the ipython object for
     computations will not work, but this allows a wider range of code to
     transparently work whether ipython is being used or not."""
     
     def __str__(self):
         return "<IPythonNotRunning>"
 
     __repr__ = __str__
 
     def __getattr__(self,name):
         return self.dummy
 
     def dummy(self,*args,**kw):
         """Dummy function, which doesn't do anything but warn."""
         warn("IPython is not running, this is a dummy no-op function")
 
 _recent = None
 
 
 def get(allow_dummy=False):
     """Get an IPApi object.
 
     If allow_dummy is true, returns an instance of IPythonNotRunning 
     instead of None if not running under IPython.
 
     Running this should be the first thing you do when writing extensions that
     can be imported as normal modules. You can then direct all the
     configuration operations against the returned object.
     """
     global _recent
     if allow_dummy and not _recent:
         _recent = IPythonNotRunning()
     return _recent
 
 class IPApi:
     """ The actual API class for configuring IPython 
     
     You should do all of the IPython configuration by getting an IPApi object
     with IPython.ipapi.get() and using the attributes and methods of the
     returned object."""
     
     def __init__(self,ip):
         
         # All attributes exposed here are considered to be the public API of
         # IPython.  As needs dictate, some of these may be wrapped as
         # properties.
 
         self.magic = ip.ipmagic
         
         self.system = ip.ipsystem
         
         self.set_hook = ip.set_hook
         
         self.set_custom_exc = ip.set_custom_exc
 
         self.user_ns = ip.user_ns
 
         self.set_crash_handler = ip.set_crash_handler
 
         # Session-specific data store, which can be used to store
         # data that should persist through the ipython session.
         self.meta =  ip.meta
     
         # The ipython instance provided
         self.IP = ip
 
         global _recent
         _recent = self
 
     # Use a property for some things which are added to the instance very
     # late.  I don't have time right now to disentangle the initialization
     # order issues, so a property lets us delay item extraction while
     # providing a normal attribute API.
     def get_db(self):
         """A handle to persistent dict-like database (a PickleShareDB object)"""
         return self.IP.db
 
     db = property(get_db,None,None,get_db.__doc__)
 
     def get_options(self):
         """All configurable variables."""
+        
+        # catch typos by disabling new attribute creation. If new attr creation
+        # is in fact wanted (e.g. when exposing new options), do allow_new_attr(True) 
+        # for the received rc struct.
+        
+        self.IP.rc.allow_new_attr(False)
         return self.IP.rc
 
     options = property(get_options,None,None,get_options.__doc__)
     
     def expose_magic(self,magicname, func):
         ''' Expose own function as magic function for ipython 
     
         def foo_impl(self,parameter_s=''):
             """My very own magic!. (Use docstrings, IPython reads them)."""
             print 'Magic function. Passed parameter is between < >: <'+parameter_s+'>'
             print 'The self object is:',self
     
         ipapi.expose_magic("foo",foo_impl)
         '''
                 
         import new
         im = new.instancemethod(func,self.IP, self.IP.__class__)
         setattr(self.IP, "magic_" + magicname, im)
     
     def ex(self,cmd):
         """ Execute a normal python statement in user namespace """
         exec cmd in self.user_ns
     
     def ev(self,expr):
         """ Evaluate python expression expr in user namespace 
         
         Returns the result of evaluation"""
         return eval(expr,self.user_ns)
     
     def runlines(self,lines):
         """ Run the specified lines in interpreter, honoring ipython directives.
         
         This allows %magic and !shell escape notations.
         
         Takes either all lines in one string or list of lines.
         """
         if isinstance(lines,basestring):
             self.IP.runlines(lines)
         else:
             self.IP.runlines('\n'.join(lines))
 
     def to_user_ns(self,vars):
         """Inject a group of variables into the IPython user namespace.
 
         Inputs:
 
          - vars: string with variable names separated by whitespace
 
         This utility routine is meant to ease interactive debugging work,
         where you want to easily propagate some internal variable in your code
         up to the interactive namespace for further exploration.
 
         When you run code via %run, globals in your script become visible at
         the interactive prompt, but this doesn't happen for locals inside your
         own functions and methods.  Yet when debugging, it is common to want
         to explore some internal variables further at the interactive propmt.
 
         Examples:
 
         To use this, you first must obtain a handle on the ipython object as
         indicated above, via:
 
         import IPython.ipapi
         ip = IPython.ipapi.get()
 
         Once this is done, inside a routine foo() where you want to expose
         variables x and y, you do the following:
 
         def foo():
             ...
             x = your_computation()
             y = something_else()
             
             # This pushes x and y to the interactive prompt immediately, even
             # if this routine crashes on the next line after:
             ip.to_user_ns('x y')
             ...
             # return           
         
         If you need to rename variables, just use ip.user_ns with dict
         and update:
         
         # exposes variables 'foo' as 'x' and 'bar' as 'y' in IPython 
         # user namespace
         ip.user_ns.update(dict(x=foo,y=bar))    
         """
 
         # print 'vars given:',vars # dbg
         # Get the caller's frame to evaluate the given names in
         cf = sys._getframe(1)
         
         user_ns = self.user_ns
         
         for name in vars.split():
             try:
                 user_ns[name] = eval(name,cf.f_globals,cf.f_locals)
             except:
                 error('could not get var. %s from %s' %
                 (name,cf.f_code.co_name))
 
 def launch_new_instance(user_ns = None):
     """ Make and start a new ipython instance.
     
     This can be called even without having an already initialized 
     ipython session running.
     
     This is also used as the egg entry point for the 'ipython' script.
     
     """
     ses = make_session(user_ns)
     ses.mainloop()
 
 
 def make_user_ns(user_ns = None):
     """Return a valid user interactive namespace.
 
     This builds a dict with the minimal information needed to operate as a
     valid IPython user namespace, which you can pass to the various embedding
     classes in ipython.
     """
 
     if user_ns is None:
         # Set __name__ to __main__ to better match the behavior of the
         # normal interpreter.
         user_ns = {'__name__'     :'__main__',
                    '__builtins__' : __builtin__,
                    }
     else:
         user_ns.setdefault('__name__','__main__')
         user_ns.setdefault('__builtins__',__builtin__)
 
     return user_ns
 
 
 def make_user_global_ns(ns = None):
     """Return a valid user global namespace.
 
     Similar to make_user_ns(), but global namespaces are really only needed in
     embedded applications, where there is a distinction between the user's
     interactive namespace and the global one where ipython is running."""
 
     if ns is None: ns = {}
     return ns
 
 
 def make_session(user_ns = None):
     """Makes, but does not launch an IPython session.
     
     Later on you can call obj.mainloop() on the returned object.
 
     Inputs:
 
       - user_ns(None): a dict to be used as the user's namespace with initial
       data.
     
     WARNING: This should *not* be run when a session exists already."""
 
     import IPython
     return IPython.Shell.start(user_ns)

IPython/ipstruct.py

@@ -1,376 +1,393 b''
 # -*- coding: utf-8 -*-
 """Mimic C structs with lots of extra functionality.
 
-$Id: ipstruct.py 1005 2006-01-12 08:39:26Z fperez $"""
+$Id: ipstruct.py 1949 2006-11-28 19:12:15Z vivainio $"""
 
 #*****************************************************************************
 #       Copyright (C) 2001-2004 Fernando Perez <[e-mail]>
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
 #*****************************************************************************
 
 from IPython import Release
 __author__  = '%s <%s>' % Release.authors['Fernando']
 __license__ = Release.license
 
 __all__ = ['Struct']
 
 import types
 
 from IPython.genutils import list2dict2
 
 class Struct:
     """Class to mimic C structs but also provide convenient dictionary-like
     functionality.
 
     Instances can be initialized with a dictionary, a list of key=value pairs
     or both. If both are present, the dictionary must come first.
 
     Because Python classes provide direct assignment to their members, it's
     easy to overwrite normal methods (S.copy = 1 would destroy access to
     S.copy()). For this reason, all builtin method names are protected and
     can't be assigned to. An attempt to do s.copy=1 or s['copy']=1 will raise
     a KeyError exception. If you really want to, you can bypass this
     protection by directly assigning to __dict__: s.__dict__['copy']=1 will
     still work. Doing this will break functionality, though. As in most of
     Python, namespace protection is weakly enforced, so feel free to shoot
     yourself if you really want to.
 
     Note that this class uses more memory and is *much* slower than a regular
     dictionary, so be careful in situations where memory or performance are
     critical. But for day to day use it should behave fine. It is particularly
     convenient for storing configuration data in programs.
 
     +,+=,- and -= are implemented. +/+= do merges (non-destructive updates),
     -/-= remove keys from the original. See the method descripitions.
 
     This class allows a quick access syntax: both s.key and s['key'] are
     valid.  This syntax has a limitation: each 'key' has to be explicitly
     accessed by its original name. The normal s.key syntax doesn't provide
     access to the keys via variables whose values evaluate to the desired
     keys. An example should clarify this:
 
     Define a dictionary and initialize both with dict and k=v pairs:
     >>> d={'a':1,'b':2}
     >>> s=Struct(d,hi=10,ho=20)
     The return of __repr__ can be used to create a new instance:
     >>> s
     Struct({'ho': 20, 'b': 2, 'hi': 10, 'a': 1})
     __str__ (called by print) shows it's not quite a regular dictionary:
     >>> print s
     Struct {a: 1, b: 2, hi: 10, ho: 20}
     Access by explicitly named key with dot notation:
     >>> s.a
     1
     Or like a dictionary:
     >>> s['a']
     1
     If you want a variable to hold the key value, only dictionary access works:
     >>> key='hi'
     >>> s.key
     Traceback (most recent call last):
       File "<stdin>", line 1, in ?
     AttributeError: Struct instance has no attribute 'key'
     >>> s[key]
     10
 
     Another limitation of the s.key syntax (and Struct(key=val)
     initialization): keys can't be numbers. But numeric keys can be used and
     accessed using the dictionary syntax. Again, an example:
 
     This doesn't work:
     >>> s=Struct(4='hi')
     SyntaxError: keyword can't be an expression
     But this does:
     >>> s=Struct()
     >>> s[4]='hi'
     >>> s
     Struct({4: 'hi'})
     >>> s[4]
     'hi'
     """
 
     # Attributes to which __setitem__ and __setattr__ will block access.
     # Note: much of this will be moot in Python 2.2 and will be done in a much
     # cleaner way.
     __protected = ('copy dict dictcopy get has_attr has_key items keys '
                    'merge popitem setdefault update values '
                    '__make_dict __dict_invert ').split()
 
     def __init__(self,dict=None,**kw):
         """Initialize with a dictionary, another Struct, or by giving
         explicitly the list of attributes.
 
         Both can be used, but the dictionary must come first:
         Struct(dict), Struct(k1=v1,k2=v2) or Struct(dict,k1=v1,k2=v2).
         """
+        self.__dict__['__allownew'] = True
         if dict is None:
             dict = {}
         if isinstance(dict,Struct):
             dict = dict.dict()
         elif dict and  type(dict) is not types.DictType:
             raise TypeError,\
                   'Initialize with a dictionary or key=val pairs.'
         dict.update(kw)
         # do the updating by hand to guarantee that we go through the
         # safety-checked __setitem__
         for k,v in dict.items():
             self[k] = v
+        
 
     def __setitem__(self,key,value):
         """Used when struct[key] = val calls are made."""
         if key in Struct.__protected:
             raise KeyError,'Key '+`key`+' is a protected key of class Struct.'
+        if not self['__allownew'] and key not in self.__dict__:
+            raise KeyError(
+            "Can't create unknown attribute %s - Check for typos, or use allow_new_attr to create new attributes!" %
+            key)
+            
         self.__dict__[key] = value
 
     def __setattr__(self, key, value):
         """Used when struct.key = val calls are made."""
         self.__setitem__(key,value)
 
     def __str__(self):
         """Gets called by print."""
         
         return 'Struct('+str(self.__dict__)+')'
 
     def __repr__(self):
         """Gets called by repr.
         
         A Struct can be recreated with S_new=eval(repr(S_old))."""
         return 'Struct('+str(self.__dict__)+')'
 
     def __getitem__(self,key):
         """Allows struct[key] access."""
         return self.__dict__[key]
 
     def __contains__(self,key):
         """Allows use of the 'in' operator."""
         return self.__dict__.has_key(key)
 
     def __iadd__(self,other):
         """S += S2 is a shorthand for S.merge(S2)."""
         self.merge(other)
         return self
 
     def __add__(self,other):
         """S + S2 -> New Struct made form S and S.merge(S2)"""
         Sout = self.copy()
         Sout.merge(other)
         return Sout
 
     def __sub__(self,other):
         """Return S1-S2, where all keys in S2 have been deleted (if present)
         from S1."""
         Sout = self.copy()
         Sout -= other
         return Sout
 
     def __isub__(self,other):
         """Do in place S = S - S2, meaning all keys in S2 have been deleted
         (if present) from S1."""
 
         for k in other.keys():
             if self.has_key(k):
                 del self.__dict__[k]
 
     def __make_dict(self,__loc_data__,**kw):
         "Helper function for update and merge. Return a dict from data."
 
         if __loc_data__ == None:
             dict = {}
         elif type(__loc_data__) is types.DictType:
             dict = __loc_data__
         elif isinstance(__loc_data__,Struct):
             dict = __loc_data__.__dict__
         else:
             raise TypeError, 'Update with a dict, a Struct or key=val pairs.'
         if kw:
             dict.update(kw)
         return dict
 
     def __dict_invert(self,dict):
         """Helper function for merge. Takes a dictionary whose values are
         lists and returns a dict. with the elements of each list as keys and
         the original keys as values."""
 
         outdict = {}
         for k,lst in dict.items():
             if type(lst) is types.StringType:
                 lst = lst.split()
             for entry in lst:
                 outdict[entry] = k
         return outdict
 
     def clear(self):
         """Clear all attributes."""
         self.__dict__.clear()
 
     def copy(self):
         """Return a (shallow) copy of a Struct."""
         return Struct(self.__dict__.copy())
 
     def dict(self):
         """Return the Struct's dictionary."""
         return self.__dict__
 
     def dictcopy(self):
         """Return a (shallow) copy of the Struct's dictionary."""
         return self.__dict__.copy()
 
     def popitem(self):
         """S.popitem() -> (k, v), remove and return some (key, value) pair as
         a 2-tuple; but raise KeyError if S is empty."""
         return self.__dict__.popitem()
 
     def update(self,__loc_data__=None,**kw):
         """Update (merge) with data from another Struct or from a dictionary.
         Optionally, one or more key=value pairs can be given at the end for
         direct update."""
 
         # The funny name __loc_data__ is to prevent a common variable name which
         # could be a fieled of a Struct to collide with this parameter. The problem
         # would arise if the function is called with a keyword with this same name
         # that a user means to add as a Struct field.
         newdict = Struct.__make_dict(self,__loc_data__,**kw)
         for k,v in newdict.items():
             self[k] = v
 
     def merge(self,__loc_data__=None,__conflict_solve=None,**kw):
         """S.merge(data,conflict,k=v1,k=v2,...) -> merge data and k=v into S.
 
         This is similar to update(), but much more flexible.  First, a dict is
         made from data+key=value pairs. When merging this dict with the Struct
         S, the optional dictionary 'conflict' is used to decide what to do.
 
         If conflict is not given, the default behavior is to preserve any keys
         with their current value (the opposite of the update method's
         behavior).
 
         conflict is a dictionary of binary functions which will be used to
         solve key conflicts. It must have the following structure:
 
           conflict == { fn1 : [Skey1,Skey2,...], fn2 : [Skey3], etc }
 
         Values must be lists or whitespace separated strings which are
         automatically converted to lists of strings by calling string.split().
 
         Each key of conflict is a function which defines a policy for
         resolving conflicts when merging with the input data. Each fn must be
         a binary function which returns the desired outcome for a key
         conflict. These functions will be called as fn(old,new).
 
         An example is probably in order. Suppose you are merging the struct S
         with a dict D and the following conflict policy dict:
 
             S.merge(D,{fn1:['a','b',4], fn2:'key_c key_d'})
 
         If the key 'a' is found in both S and D, the merge method will call:
 
             S['a'] = fn1(S['a'],D['a'])
 
         As a convenience, merge() provides five (the most commonly needed)
         pre-defined policies: preserve, update, add, add_flip and add_s. The
         easiest explanation is their implementation:
 
           preserve = lambda old,new: old
           update   = lambda old,new: new
           add      = lambda old,new: old + new
           add_flip = lambda old,new: new + old  # note change of order!
           add_s    = lambda old,new: old + ' ' + new  # only works for strings!
 
         You can use those four words (as strings) as keys in conflict instead
         of defining them as functions, and the merge method will substitute
         the appropriate functions for you. That is, the call
 
           S.merge(D,{'preserve':'a b c','add':[4,5,'d'],my_function:[6]})
 
         will automatically substitute the functions preserve and add for the
         names 'preserve' and 'add' before making any function calls.
 
         For more complicated conflict resolution policies, you still need to
         construct your own functions. """
 
         data_dict = Struct.__make_dict(self,__loc_data__,**kw)
 
         # policies for conflict resolution: two argument functions which return
         # the value that will go in the new struct
         preserve = lambda old,new: old
         update   = lambda old,new: new
         add      = lambda old,new: old + new
         add_flip = lambda old,new: new + old  # note change of order!
         add_s    = lambda old,new: old + ' ' + new
 
         # default policy is to keep current keys when there's a conflict
         conflict_solve = list2dict2(self.keys(),default = preserve)
 
         # the conflict_solve dictionary is given by the user 'inverted': we
         # need a name-function mapping, it comes as a function -> names
         # dict. Make a local copy (b/c we'll make changes), replace user
         # strings for the three builtin policies and invert it.
         if __conflict_solve:
             inv_conflict_solve_user = __conflict_solve.copy()
             for name, func in [('preserve',preserve), ('update',update),
                                ('add',add), ('add_flip',add_flip), ('add_s',add_s)]:
                 if name in inv_conflict_solve_user.keys():
                     inv_conflict_solve_user[func] = inv_conflict_solve_user[name]
                     del inv_conflict_solve_user[name]
             conflict_solve.update(Struct.__dict_invert(self,inv_conflict_solve_user))
         #print 'merge. conflict_solve: '; pprint(conflict_solve) # dbg
         #print '*'*50,'in merger. conflict_solver:';  pprint(conflict_solve)
         for key in data_dict:
             if key not in self:
                 self[key] = data_dict[key]
             else:
                 self[key] = conflict_solve[key](self[key],data_dict[key])
 
     def has_key(self,key):
         """Like has_key() dictionary method."""
         return self.__dict__.has_key(key)
 
     def hasattr(self,key):
         """hasattr function available as a method.
 
         Implemented like has_key, to make sure that all available keys in the
         internal dictionary of the Struct appear also as attributes (even
         numeric keys)."""
         return self.__dict__.has_key(key)
 
     def items(self):
         """Return the items in the Struct's dictionary, in the same format
         as a call to {}.items()."""
         return self.__dict__.items()
 
     def keys(self):
         """Return the keys in the Struct's dictionary, in the same format
         as a call to {}.keys()."""
         return self.__dict__.keys()
 
     def values(self,keys=None):
         """Return the values in the Struct's dictionary, in the same format
         as a call to {}.values().
 
         Can be called with an optional argument keys, which must be a list or
         tuple of keys. In this case it returns only the values corresponding
         to those keys (allowing a form of 'slicing' for Structs)."""
         if not keys:
             return self.__dict__.values()
         else:
             ret=[]
             for k in keys:
                 ret.append(self[k])
             return ret
 
     def get(self,attr,val=None):
         """S.get(k[,d]) -> S[k] if S.has_key(k), else d.  d defaults to None."""
         try:
             return self[attr]
         except KeyError:
             return val
 
     def setdefault(self,attr,val=None):
         """S.setdefault(k[,d]) -> S.get(k,d), also set S[k]=d if not S.has_key(k)"""
         if not self.has_key(attr):
             self[attr] = val
         return self.get(attr,val)
+    
+    def allow_new_attr(self, allow = True):
+        """ Set whether new attributes can be created inside struct
+        
+        This can be used to catch typos by verifying that the attribute user tries to 
+        change already exists in this Struct.
+        """
+        self['__allownew'] = allow
+        
+        
 # end class Struct