Source Code for Module httxlib.httxoptions

  1  #!/usr/bin/env python 
  2  # -*- coding: latin-1; py-indent-offset:4 -*- 
  3  ################################################################################ 
  4  #  
  5  # This file is part of HttxLib 
  6  # 
  7  # HttxLib is an HTTP(s) Python library suited multithreaded/multidomain 
  8  # applications 
  9  # 
 10  # Copyright (C) 2010-2011 Daniel Rodriguez (aka Daniel Rodriksson) 
 11  # Copyright (C) 2011 Sensible Odds Ltd 
 12  # 
 13  # You can learn more and contact the author at: 
 14  # 
 15  #    http://code.google.com/p/httxlib/ 
 16  # 
 17  # HttxLib is free software: you can redistribute it and/or modify 
 18  # it under the terms of the GNU General Public License as published by 
 19  # the Free Software Foundation, either version 3 of the License, or 
 20  # (at your option) any later version. 
 21  # 
 22  # HttxLib is distributed in the hope that it will be useful, 
 23  # but WITHOUT ANY WARRANTY; without even the implied warranty of 
 24  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
 25  # GNU General Public License for more details. 
 26  # 
 27  # You should have received a copy of the GNU General Public License 
 28  # along with HttxLib. If not, see <http://www.gnu.org/licenses/>. 
 29  # 
 30  ################################################################################ 
 31  ''' 
 32  Module that implements the domain wide options that connecting objects can share 
 33   
 34  A set of options apply to a HttxManager and all pending objects. 
 35   
 36  If a L{HttxManager} is cloned, it can be cloned sharing the options or not. If the options 
 37  are shared, so will be the cookies, compression schemes allowed, username and passwords, 
 38  certificate files. 
 39   
 40  If the options are not shared the new L{HttxManager} will be completely separate from 
 41  the original. 
 42   
 43  Since options can be directly instantiated by L{HttxNetLocation} and L{HttxConnection}, the 
 44  same logic applies on cloning 
 45   
 46  @var proxydefaults: If True try to automatically find and use the system 
 47                      (via environment variables, registry or others) defined proxies 
 48  @type proxydefault: bool (Default: False) 
 49  ''' 
 50   
 51  from copy import deepcopy 
 52   
 53  from httxauthcache import HttxAuthCache 
 54  from httxcertificates import HttxCertKeyManager, HttxCertReqManager, HttxCACertManager 
 55  from httxcookiejar import HttxCookieJar 
 56  from httxcompressionset import HttxCompressionSet 
 57  from httxobject import HttxObject 
 58  from httxpassmanager import HttxPassManager 
 59   
 60  proxydefaults = False 
 61   
 62   
 63 -class HttxOption(object): 
 64      ''' 
 65      A class representing an individual option. 
 66   
 67      The class is implemented as a descriptor. The class locks access 
 68      automatically on access (read/write) to the storage by using the 
 69      lock from the instance object accessing the option. 
 70   
 71      @ivar name: Name of the option 
 72      @type name: str 
 73      @ivar defvalue: Default value of the option 
 74      @type defvalue: Opaque type. Each option may have different types 
 75      @ivar storage: Actual storage for the option value(s) on a per 
 76                     instance (descriptor) basis 
 77      @type storage: dict 
 78      ''' 
 79   
 80      __slots__ = ['name', 'defvalue', 'storage', '__weakref__'] 
 81   
 82 -    def __init__(self, name, defvalue): 
 83          ''' 
 84          Constructor. 
 85          Initializes the member variables 
 86   
 87          @param name: Name of the option 
 88          @type name: str 
 89          @param defvalue: Default value of the option 
 90          @type defvalue: Opaque type. Each option may have different types 
 91          ''' 
 92          self.name = name 
 93          self.defvalue = defvalue 
 94          self.storage = dict() 
 95   
 96   
 97 -    def __get__(self, instance, owner): 
 98          ''' 
 99          Descriptor get 
100   
101          @param instance: instance that wants to access the storage 
102          @type instance: object instance 
103          @param owner: Not used but needed for descriptor implementation 
104          @type owner: Not used 
105          @return: the value of the requested option (the default value if 
106                   the option had not been set yet 
107          @rtype: Opaque type. Each option may have different types 
108          ''' 
109          with instance.lock: 
110              # XXX is deepcopy really needed? 
111              return self.storage.setdefault(instance, deepcopy(self.defvalue)) 
112   
113   
114 -    def __set__(self, instance, value): 
115          ''' 
116          Descriptor set 
117   
118          @param instance: instance that wants to access the storage 
119          @type instance: object instance 
120          @param value: Value to set 
121          @type value: Opaque type. Each option may have different types 
122          ''' 
123          with instance.lock: 
124              # XXX is deepcopy really needed? 
125              self.storage[instance] = deepcopy(value) 
126   
127   
128 -class HttxOptionsMeta(type): 
129      ''' 
130      Metaclass for L{HttxOptions} to initialize the list of options 
131      on instantiation 
132      ''' 
133   
134 -    def __new__(mcs, name, bases, dict): 
135          ''' 
136          On L{HttxOptions} instantiation the options present in the 
137          class variable I{defoptions} are added to the dictionary of the 
138          instance to start them with the default value 
139          ''' 
140          for defoption in dict['defoptions']: 
141              dict[defoption.name] = defoption 
142   
143          return type.__new__(mcs, name, bases, dict) 
144   
145   
146 -class HttxOptions(HttxObject): 
147      ''' 
148      Class implementing a set of options per domain to be held by HttxLib 
149      connecting objects like L{HttxManager}, L{HttxNetLocation} and L{HttxConnection} 
150   
151      @ivar defoptions: list of L{HttxOption} definitions 
152      @type defoptions: tuple 
153   
154        - timeout 
155          Default value: 15 seconds 
156          Timeout for network operations 
157   
158        - keepalive 
159          Default value: 90 seconds 
160          Timeout for HTTP keepalive 
161   
162        - connkeepalive 
163          Default value: True 
164          Timeout for HTTP Send the 'Connection: Keep-Alive' header 
165           
166        - httpsconnect 
167          Default value: True 
168          Use CONNECT for proxying HTTPS 
169   
170        - httpconnect 
171          Default value: False 
172          Use CONNECT for proxying HTTP 
173   
174        - sendfullurl 
175          Default value: False 
176          HTTP 1.1 allows this, but some servers may crash if they receive the full url 
177   
178        - proxy 
179          Default value: None 
180          A dictionary of scheme:url tuples can be set to use proxy servers 
181          scheme can be * for any scheme or have the http/https values 
182   
183        - compression 
184          Default value: False 
185          If True the body of a POST will be sent compressed. This is supported 
186          by very few servers 
187   
188        - compmethod 
189          Default value: HttxCompressionSet('gzip') 
190          Method to use when sending compressed requests 
191   
192        - decompression 
193          Default value: True 
194          Request compressed answers and decompress the body of an HTTP answer 
195   
196        - autodecompression 
197          Default value: True 
198          Even if compression was not requested, decompressed answers that 
199          contain a compressed body 
200   
201        - decompmethod 
202          Default value: HttxCompressionSet('gzip', 'deflate', 'bzip2') 
203          Methods to use when requesting compressed answers 
204   
205        - useragent 
206          Default value: '' 
207          Sets the user agent header value 
208   
209        - redirect 
210          Default value: True 
211          Allows or disallows redirection support 
212   
213        - externalredirect 
214          Default value: True 
215          Allows or disallows external redirection support 
216   
217        - maxredirect 
218          Default value: 3 
219          Maximum number of redirects to follow 
220   
221        - rfc2616postredir 
222          Default value: True 
223          If a redir after a post as specified in RFC 2616 should be followed 
224   
225        - cookies 
226          Default value: True 
227          Allows or disallows cookie support 
228   
229        - cookiejar 
230          Default value: HttxCookieJar 
231          For internal storage of cookies in a HttxOptions domain 
232   
233        - auth 
234          Default value: True 
235          Allows or disallows authentication support 
236   
237        - authuser 
238          Default value: True 
239          Allows or disallows www authentication support 
240   
241        - authproxy 
242          Default value: True 
243          Allows or disallows proxy authentication support 
244   
245        - authhandler 
246          Default value: None 
247          It can hold a reference to a function (or callable object) that accepts 
248          the following parameters: 
249   
250              - authhandler(authurl, authschemes, authcachedata) 
251                authurl is the url that generated the authorization request 
252                authschemes is a dictionary. The keys contain the names of the 
253                authentication schemes the server supports. Each value is a dictionary 
254                or paramaters (ex: realm='My AuthRealm', where realm is the key and 
255                'My AuthRealm' is the associated value) 
256   
257              - The function has to return a tuple: 
258                (authscheme, authanswer, authcachedata) If either authscheme or authanswer 
259                happen to be None then the handler cannot handle authentication) 
260    
261                authscheme contains the chosen scheme from the varios that may have 
262                been presented to the handler 
263   
264                authanswer contains the answer to the authentication challenge 
265   
266                authcachedata is a value that the handler may wish to store and will receive 
267                on next authentication challenges for the same url. If None is returned 
268                nothing will be stored 
269   
270        - passmanager 
271          Default value: HttxPassManager 
272          Internal storage of username/password credentials for realm and urls 
273   
274        - authcache 
275          Default value: HttxAuthCache 
276          Internal storage of authentication answers for reuse 
277   
278        - certkeyfile 
279          Default value: HttxCertKeyManager 
280          Internal storage of certificate/private key pair of path to files 
281          containing the certificates and private keys for client 
282          validation 
283          Being empty at the beginning, no files will be used in client validation 
284   
285        - certreq 
286          Default value: HttxCertReqManager 
287          Internal storage of requirement of validation for server certificates 
288          Being empty at the beginning, no validation will be performed 
289   
290        - cacert 
291          Default value: HttxCACertManager 
292          Internal storage of root (chain of) certificates(s) for server 
293          certificate validation. 
294          Being empty at the beginning, no validation can be performed 
295      ''' 
296   
297      defoptions = ( 
298          HttxOption('timeout', 15), 
299          HttxOption('keepalive', 90), 
300          HttxOption('connkeepalive', True), 
301          HttxOption('httpsconnect', True), 
302          HttxOption('httpconnect', False), 
303          HttxOption('sendfullurl', False), 
304          HttxOption('proxy', None), 
305          HttxOption('compression', False), 
306          HttxOption('compmethod', HttxCompressionSet('gzip')), 
307          HttxOption('decompression', True), 
308          HttxOption('autodecompression', True), 
309          HttxOption('decompmethods', HttxCompressionSet('gzip', 'deflate', 'bzip2')), 
310          HttxOption('useragent', ''), 
311          HttxOption('redirect', True), 
312          HttxOption('externalredirect', True), 
313          HttxOption('maxredirects', 3), 
314          HttxOption('rfc2616postredir', True), 
315          HttxOption('cookies', True), 
316          HttxOption('cookiejar', HttxCookieJar()), 
317          HttxOption('auth', True), 
318          HttxOption('authuser', True), 
319          HttxOption('authproxy', True), 
320          HttxOption('authhandler', None), 
321          HttxOption('passmanager', HttxPassManager()), 
322          HttxOption('authcache', HttxAuthCache()), 
323          HttxOption('certkeyfile', HttxCertKeyManager()), 
324          HttxOption('certreq', HttxCertReqManager()), 
325          HttxOption('cacert', HttxCACertManager()), 
326          ) 
327   
328      __metaclass__ = HttxOptionsMeta 
329   
330   
331 -    def __init__(self): 
332          ''' 
333          Constructor. It delegates construction to the base class 
334          L{HttxObject} 
335          ''' 
336          HttxObject.__init__(self) 
337   
338   
339 -    def __deepcopy__(self, memo): 
340          ''' 
341          Deepcopy support. 
342   
343          @param memo: standard __deepcopy__ parameter to avoid circular references 
344          @type memo: dict 
345          @return: a cloned object 
346          @rtype: L{HttxOptions} 
347          ''' 
348          clone = self.__class__() 
349   
350          # lock is un(deep)copyable 
351          # copy the attributes we want: options 
352          for defoption in self.defoptions: 
353              setattr(clone, defoption.name, deepcopy(getattr(self, defoption.name))) 
354   
355          return clone 
356   
357   
358 -    def clone(self): 
359          ''' 
360          Alias for deepcopy, for consistency with the rest of objects 
361   
362          @return: a cloned object 
363          @rtype: L{HttxOptions} 
364          ''' 
365          return deepcopy(self) 
366   
367   
368 -    def update(self, **kwargs): 
369          ''' 
370          Given a set of keyword arguments update the value of options 
371   
372          @param kwargs: keyword args 
373          @type kwargs: dict 
374          ''' 
375          for option in kwargs: 
376              if hasattr(self, option): 
377                  setattr(self, option, kwargs[option]) 
378