jsonpickle/util.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # Copyright (C) 2008 John Paulett (john -at- 7oars.com)
   4 # All rights reserved.
   5 #
   6 # This software is licensed as described in the file COPYING, which
   7 # you should have received as part of this distribution.
   8
   9 """Helper functions for pickling and unpickling.  Most functions assist in
  10 determining the type of an object.
  11 """
  12 import time
  13 import types
  14 import datetime
  15
  16 COLLECTIONS = set, list, tuple
  17 PRIMITIVES = str, unicode, int, float, bool, long
  18 NEEDS_REPR = (datetime.datetime, datetime.time, datetime.date,
  19               datetime.timedelta)
  20
  21 def is_type(obj):
  22     """Returns True is obj is a reference to a type.
  23
  24     >>> is_type(1)
  25     False
  26
  27     >>> is_type(object)
  28     True
  29
  30     >>> class Klass: pass
  31     >>> is_type(Klass)
  32     True
  33     """
  34     return type(obj) is types.TypeType or repr(obj).startswith('<class')
  35
  36 def is_object(obj):
  37     """Returns True is obj is a reference to an object instance.
  38
  39     >>> is_object(1)
  40     True
  41
  42     >>> is_object(object())
  43     True
  44
  45     >>> is_object(lambda x: 1)
  46     False
  47     """
  48     return (isinstance(obj, object) and
  49             type(obj) is not types.TypeType and
  50             type(obj) is not types.FunctionType)
  51
  52 def is_primitive(obj):
  53     """Helper method to see if the object is a basic data type. Strings,
  54     integers, longs, floats, booleans, and None are considered primitive
  55     and will return True when passed into *is_primitive()*
  56
  57     >>> is_primitive(3)
  58     True
  59     >>> is_primitive([4,4])
  60     False
  61     """
  62     if obj is None:
  63         return True
  64     elif type(obj) in PRIMITIVES:
  65         return True
  66     return False
  67
  68 def is_dictionary(obj):
  69     """Helper method for testing if the object is a dictionary.
  70
  71     >>> is_dictionary({'key':'value'})
  72     True
  73     """
  74     return type(obj) is dict
  75
  76 def is_collection(obj):
  77     """Helper method to see if the object is a Python collection (list,
  78     set, or tuple).
  79     >>> is_collection([4])
  80     True
  81     """
  82     return type(obj) in COLLECTIONS
  83
  84 def is_list(obj):
  85     """Helper method to see if the object is a Python list.
  86
  87     >>> is_list([4])
  88     True
  89     """
  90     return type(obj) is list
  91
  92 def is_set(obj):
  93     """Helper method to see if the object is a Python set.
  94
  95     >>> is_set(set())
  96     True
  97     """
  98     return type(obj) is set
  99
 100 def is_tuple(obj):
 101     """Helper method to see if the object is a Python tuple.
 102
 103     >>> is_tuple((1,))
 104     True
 105     """
 106     return type(obj) is tuple
 107
 108 def is_dictionary_subclass(obj):
 109     """Returns True if *obj* is a subclass of the dict type. *obj* must be
 110     a subclass and not the actual builtin dict.
 111
 112     >>> class Temp(dict): pass
 113     >>> is_dictionary_subclass(Temp())
 114     True
 115     """
 116     return (hasattr(obj, '__class__') and
 117             issubclass(obj.__class__, dict) and not is_dictionary(obj))
 118
 119 def is_collection_subclass(obj):
 120     """Returns True if *obj* is a subclass of a collection type, such as list
 121     set, tuple, etc.. *obj* must be a subclass and not the actual builtin, such
 122     as list, set, tuple, etc..
 123
 124     >>> class Temp(list): pass
 125     >>> is_collection_subclass(Temp())
 126     True
 127     """
 128     #TODO add UserDict
 129     return issubclass(obj.__class__, COLLECTIONS) and not is_collection(obj)
 130
 131 def is_noncomplex(obj):
 132     """Returns True if *obj* is a special (weird) class, that is complex than
 133     primitive data types, but is not a full object. Including:
 134
 135         * :class:`~time.struct_time`
 136     """
 137     if type(obj) is time.struct_time:
 138         return True
 139     return False
 140
 141 def is_repr(obj):
 142     """Returns True if the *obj* must be encoded and decoded using the
 143     :func:`repr` function. Including:
 144
 145         * :class:`~datetime.datetime`
 146         * :class:`~datetime.date`
 147         * :class:`~datetime.time`
 148         * :class:`~datetime.timedelta`
 149     """
 150     return isinstance(obj, NEEDS_REPR)
 151
 152 def is_function(obj):
 153     """Returns true if passed a function
 154
 155     >>> is_function(lambda x: 1)
 156     True
 157
 158     >>> is_function(locals)
 159     True
 160
 161     >>> def method(): pass
 162     >>> is_function(method)
 163     True
 164
 165     >>> is_function(1)
 166     False
 167     """
 168     if type(obj) is types.FunctionType:
 169         return True
 170     if not is_object(obj):
 171         return False
 172     if not hasattr(obj, '__class__'):
 173         return False
 174     module = obj.__class__.__module__
 175     name = obj.__class__.__name__
 176     return (module == '__builtin__' and
 177             name in ('function', 'builtin_function_or_method'))