Source Code for Module restxclient.restx_parameter

  1  """ 
  2  RESTx: Sane, simple and effective data publishing and integration.  
  3   
  4  Copyright (C) 2010   MuleSoft Inc.    http://www.mulesoft.com 
  5   
  6  This program is free software: you can redistribute it and/or modify  
  7  it under the terms of the GNU General Public License as published by  
  8  the Free Software Foundation, either version 3 of the License, or  
  9  (at your option) any later version.  
 10   
 11  This program is distributed in the hope that it will be useful,  
 12  but WITHOUT ANY WARRANTY; without even the implied warranty of  
 13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the  
 14  GNU General Public License for more details.  
 15   
 16  You should have received a copy of the GNU General Public License  
 17  along with this program.  If not, see <http://www.gnu.org/licenses/>.  
 18   
 19  """ 
 20   
 21  """ 
 22  Definition of the L{RestxParameter} class. 
 23   
 24  This object describes the properties of a paremeter. 
 25  Parameters are used in different contexts. 
 26   
 27      - A resource creation time parameter of a component. 
 28      - A parameter for a component service 
 29      - A parameter for a resource service (sub-resource) 
 30   
 31  """ 
 32   
 33  from restxclient.restx_client_exception import RestxClientException 
 34   
 35 -def _numstr_to_num(x): 
 36      """ 
 37      Translate a string to a numeric value. 
 38   
 39      This sort of translation function is necessary to be more 
 40      flexible in handling the type of input for parameter values. 
 41   
 42      @param x:    String representing a number or a number 
 43                   type. 
 44      @type x:     string or number type 
 45   
 46      @return:     Numeric value 
 47      @rtype:      Integer or Float 
 48   
 49      """ 
 50      if type(x) in [ int, float ]: 
 51          return x 
 52      try: 
 53          return int(x) 
 54      except: 
 55          return float(x) 
 56   
 57 -def _bool_convert(x): 
 58      """ 
 59      Translate a string to a boolean value. 
 60   
 61      This sort of translation function is necessary to be more 
 62      flexible in handling the type of input for parameter values. 
 63   
 64      Strings like 'y', 'yes', 'true', 't', '1' are interpreted 
 65      as True, all other strings are considered to mean False. 
 66   
 67      It works for upper and lower-case strings. 
 68   
 69      @param x:     String representation of a boolean value 
 70                    or a boolean. 
 71      @type x:      string or boolean 
 72   
 73      @return:      Boolean value. 
 74      @rtype:       boolean 
 75   
 76      """ 
 77      if type(x) is bool: 
 78          return x 
 79      if x.lower() in [ "y", "yes", "true", "t", "1" ]: 
 80          return True 
 81      else: 
 82          return False 
 83   
 84   
 85 -class RestxParameter(object): 
 86      """ 
 87      Represents a parameter for a RESTx resource or service. 
 88   
 89      This is a representation of the parameter's definition, not of the 
 90      parameter's value. 
 91   
 92      """ 
 93      # The keys to the parameter's meta data dictionary. 
 94      __DESC_KEY     = "desc" 
 95      __REQUIRED_KEY = "required" 
 96      __TYPE_KEY     = "type" 
 97      __DEFAULT_KEY  = "default" 
 98   
 99      __name         = None 
100      __desc         = None 
101      __required     = None 
102      __default_val  = None 
103      __type_str     = None 
104   
105      # All the known types identifiers for parameters 
106      __PARAM_STRING   = "string" 
107      __PARAM_PASSWORD = "password" 
108      __PARAM_BOOL     = "boolean" 
109      __PARAM_DATE     = "date" 
110      __PARAM_TIME     = "time" 
111      __PARAM_NUMBER   = "number" 
112      __PARAM_URI      = "uri" 
113   
114      # This table can convert strings for specific types to a proper object 
115      # of the indicated type. The type identifier can be used to look up 
116      # a tuple, which contains suitable types as well as a suitable 
117      # conversion function. 'None' for the function indicates that no conversion 
118      # is necessary, since the underlying type is a string. 
119      __TYPE_CONVERT = { 
120          __PARAM_STRING   : ([str, unicode], None),  
121          __PARAM_PASSWORD : ([str, unicode], None), 
122          __PARAM_BOOL     : ([str, unicode, bool], _bool_convert), 
123          __PARAM_DATE     : ([None], lambda x : date(*[ int(elem) for elem in x.split("-")])), 
124          __PARAM_TIME     : ([None], lambda x : time_class(*[ int(elem) for elem in x.split(":")])), 
125          __PARAM_NUMBER   : ([str, unicode, int, float], _numstr_to_num), 
126          __PARAM_URI      : ([str, unicode], None), 
127      } 
128   
129 -    def __str__(self): 
130          """ 
131          Return a string representation of this paramater. 
132   
133          """ 
134          return \ 
135  """RestxParameter '%s': 
136      Description:   %s 
137      Type:          %s 
138      Required:      %s 
139      Default val:   %s""" % (self.__name, self.__desc, self.__type_str, self.__required, self.__default_val) 
140   
141 -    def __init__(self, name, pdef): 
142          """ 
143          Create a new parameter definition representation in memory. 
144   
145          @param name:    Name of the parameter. 
146          @type name:     string 
147   
148          @param pdef:    Dictionary with parameter definition. This is the 
149                          dictionary returned by the server when describing 
150                          a parameter. 
151          @type pdef:     dict 
152   
153          """ 
154          try: 
155              self.__name         = name 
156              self.__desc         = pdef[self.__DESC_KEY] 
157              self.__required     = _bool_convert(pdef.get(self.__REQUIRED_KEY, "n")) 
158              self.__type_str     = pdef[self.__TYPE_KEY].lower() 
159   
160              if self.__type_str not in self.__TYPE_CONVERT: 
161                  raise RestxClientException(("Server error: Type '%s' specified for parameter '%s', which is " + 
162                                            "not supported by this client library.") % (self.__type_str, self.__name)) 
163   
164              if self.__DEFAULT_KEY in pdef: 
165                  # If a default value was specified, store it converted to 
166                  # to the proper type. 
167                  suitable_types, conversion_function = self.__TYPE_CONVERT[self.__type_str] 
168                  value_str                           = pdef[self.__DEFAULT_KEY] 
169                  if conversion_function: 
170                      self.__default_val = conversion_function(value_str) 
171                  else: 
172                      self.__default_val = value_str 
173              else: 
174                  if not self.__required: 
175                      raise RestxClientException("Server error: No default value specified for optional parameter '%s'." % self.__name) 
176   
177          except KeyError, e: 
178              raise RestxClientException("Server error: Expected key '%s' missing in definition of parameter '%s'." % (str(e), self.__name)) 
179   
180 -    def sanity_check(self, value): 
181          """ 
182          Check whether this is a valid value for this parameter. 
183   
184          Raises an exception if there's a problem. 
185   
186          @param value:      Some value object. 
187          @type value:       object 
188   
189          """ 
190          suitable_types, conversion_function = self.__TYPE_CONVERT[self.__type_str] 
191          if type(value) not in suitable_types: 
192              raise RestxClientException("Type '%s' is not suitable for parameter '%s'. Has to be one of '%s'." % (type(value), self.__name, suitable_types)) 
193   
194 -    def get_name(self): 
195          """ 
196          Return the name of the parameter. 
197   
198          @return:        Name of parameter. 
199          @rtype:         string 
200   
201          """ 
202          return self.__name 
203   
204 -    def get_description(self): 
205          """ 
206          Return the description of the parameter. 
207   
208          @return:        Description of parameter. 
209          @rtype:         string 
210   
211          """ 
212          return self.__desc 
213   
214 -    def get_parameter_type_str(self): 
215          """ 
216          Return the string representation of the type of this parameter. 
217   
218          @return:        String representation of parameter type. 
219          @rtype:         string 
220   
221          """ 
222          return self.__type_str 
223   
224 -    def get_default_value(self): 
225          """ 
226          Return the default value, if one was set. 
227   
228          @return:        The default value, or None. 
229          @rtype:         Whichever type the default value has. 
230   
231          """ 
232          return self.__default_val 
233   
234 -    def is_required(self): 
235          """ 
236          Indicate whether this is a required parameter. 
237   
238          @return:        Flag, which is True if required, False otherwise. 
239          @rtype:         boolean 
240   
241          """ 
242          return self.__required 
243   
244      # 
245      # Some properties for conevenience 
246      # 
247      name        = property(get_name, None) 
248      description = property(get_description, None) 
249      required    = property(is_required, None) 
250      type_str    = property(get_parameter_type_str, None) 
251