Package pyxb
[hide private]
[frames] | no frames]

Source Code for Package pyxb

  1  # -*- coding: utf-8 -*- 
  2   
  3  """PyXB stands for Python U{W3C XML 
  4  Schema<http://www.w3.org/XML/Schema>} Bindings, and is pronounced 
  5  "pixbee".  It enables translation between XML instance documents and 
  6  Python objects following rules specified by an XML Schema document. 
  7   
  8  This is the top-level entrypoint to the PyXB system.  Importing this 
  9  gets you all the L{exceptions<pyxb.exceptions_.PyXBException>}, and 
 10  L{pyxb.namespace}.  For more functionality, delve into these 
 11  submodules: 
 12   
 13   - L{pyxb.xmlschema} Module holding the 
 14     L{structures<pyxb.xmlschema.structures>} that convert XMLSchema 
 15     from a DOM model to a Python class model based on the XMLSchema 
 16     components.  Use this when you need to operate on the component 
 17     model. 
 18   
 19   - L{pyxb.binding} Module used to generate the bindings and at runtime 
 20     to support the generated bindings.  Use this if you need to use the 
 21     binding model or content model. 
 22   
 23   - L{pyxb.utils} Common utilities used in parsing, generating, and 
 24     executing.  The submodules must be imported separately. 
 25   
 26  """ 
 27   
 28  import logging 
 29   
 30  _log = logging.getLogger(__name__) 
 31   
32 -class cscRoot (object):
33 """This little bundle of joy exists because in Python 2.6 it 34 became an error to invoke C{object.__init__} with parameters (unless 35 you also override C{__new__}, in which case it's only a warning. 36 Whatever.). Since I'm bloody not going to check in every class 37 whether C{super(Myclass,self)} refers to C{object} (even if I could 38 figure out how to do that, 'cuz the obvious solutions don't work), 39 we'll just make this thing the root of all U{cooperative super 40 calling<http://www.geocities.com/foetsch/python/new_style_classes.htm#super>} 41 hierarchies. The standard syntax in PyXB for this pattern is:: 42 43 def method_csc (self, *args, **kw): 44 self_fn = lambda *_args, **_kw: self 45 super_fn = getattr(super(ThisClass, self), 'method_csc', self_fn) 46 return super_fn(*args, **kw) 47 48 """ 49
50 - def __init__ (self, *args, **kw):
51 # Oh gross. If this class descends from list (and probably dict), we 52 # get here when object is *not* our direct superclass. In that case, 53 # we have to pass the arguments on up, or the strings don't get 54 # created right. Below is the only way I've figured out to detect the 55 # situation. 56 # 57 # Note that we might also get here if you mix-in a class that used 58 # object as a parent instead of cscRoot. Don't do that. Printing the 59 # mro() is a decent way of identifying the problem. 60 if issubclass(self.__class__.mro()[-2], ( list, dict )): 61 super(cscRoot, self).__init__(*args)
62 63 __version__ = '1.1.5' 64 """The version of PyXB""" 65 66 __url__ = 'http://pyxb.sourceforge.net' 67 """The URL for PyXB's homepage""" 68 69 __license__ = 'Apache License 2.0' 70 71 # Bring in the exception hierarchy 72 from exceptions_ import * 73 74 # Bring in namespace stuff 75 import namespace 76
77 -class BIND (object):
78 """Bundle data for automated binding generation. 79 80 Instances of this class capture positional and keyword arguments that are 81 used to create binding instances based on context. For example, if C{w} 82 is an instance of a complex type whose C{option} element is declared to be 83 an anonymous class with simple content of type integer and an attribute of 84 C{units}, a correct assignment to that element could be achieved with:: 85 86 w.option = BIND(54, units="m") 87 88 """ 89 __args = None 90 __kw = None 91
92 - def __init__ (self, *args, **kw):
93 """Cache parameters for subsequent binding creation. 94 Invoke just as you would the factory for a binding class.""" 95 self.__args = args 96 self.__kw = kw
97
98 - def createInstance (self, factory, **kw):
99 """Invoke the given factory method. 100 101 Position arguments to the factory are those cached in this instance. 102 Keyword arguments are the ones on the command line, updated from the 103 ones in this instance.""" 104 kw.update(self.__kw) 105 return factory(*self.__args, **kw)
106 107 108 XMLStyle_minidom = 0 109 """Use xml.dom.minidom for XML processing. This is the fastest, but does not 110 provide location information. It produces DOM instances.""" 111 112 XMLStyle_saxdom = 1 113 """Use pyxb.utils.saxdom for XML processing. This is the slowest, but both 114 provides location information and generates a DOM instance.""" 115 116 XMLStyle_saxer = 2 117 """Use pyxb.binding.saxer when converting documents to binding instances. 118 This style supports location information in the bindings. It produces binding 119 instances directly, without going through a DOM stage, so is faster than 120 XMLStyle_saxdom. However, since the pyxb.xmlschema.structures classes require 121 a DOM model, XMLStyle_saxdom will be used for pyxb.utils.domutils.StringToDOM 122 if this style is selected.""" 123 124 _XMLStyle = XMLStyle_saxer 125 """The current XML processing style.""" 126 127 _XMLStyleMap = { 'minidom' : XMLStyle_minidom, 128 'saxdom' : XMLStyle_saxdom, 129 'saxer' : XMLStyle_saxer } 130 _XMLStyleMapReverse = dict([ (_v, _k) for (_k, _v) in _XMLStyleMap.items() ]) 131 132 _XMLStyle_envvar = 'PYXB_XML_STYLE' 133
134 -def _SetXMLStyle (style=None):
135 """Set the interface used to parse XML content. 136 137 This can be invoked within code. The system default of L{XMLStyle_saxer} 138 can also be overridden at runtime by setting the environment variable 139 C{PYXB_XML_STYLE} to one of C{minidom}, C{saxdom}, or C{saxer}. 140 141 @param style: One of L{XMLStyle_minidom}, L{XMLStyle_saxdom}, 142 L{XMLStyle_saxer}. If not provided, the system default is used. 143 """ 144 global _XMLStyle 145 if style is None: 146 import os 147 style_name = os.environ.get(_XMLStyle_envvar) 148 if style_name is None: 149 style_name = 'saxer' 150 style = _XMLStyleMap.get(style_name) 151 if style is None: 152 raise PyXBException('Bad value "%s" for %s' % (style_name, _XMLStyle_envvar)) 153 if _XMLStyleMapReverse.get(style) is None: 154 raise PyXBException('Bad value %s for _SetXMLStyle' % (style,)) 155 _XMLStyle = style
156 157 _SetXMLStyle() 158 159 # Global flag that we can use to determine whether optimization is active in 160 # this session. There may be cases where we can bypass methods that just 161 # check for things we don't care about in an optimized context 162 _OptimizationActive = False 163 try: 164 assert False 165 _OptimizationActive = True 166 except: 167 pass 168 169 _CorruptionDetectionEnabled = not _OptimizationActive 170 """If C{True}, blocks attempts to assign to attributes that are reserved for 171 PyXB methods. 172 173 Applies only at compilation time; dynamic changes are ignored. 174 """ 175 176 _GenerationRequiresValid = True
177 -def RequireValidWhenGenerating (value=None):
178 """Query or set a flag that controls validation checking in XML generation. 179 180 Normally any attempts to convert a binding instance to a DOM or XML 181 representation requires that the binding validate against the content 182 model, since only in this way can the content be generated in the correct 183 order. In some cases it may be necessary or useful to generate a document 184 from a binding that is incomplete. If validation is not required, the 185 generated documents may not validate even if the content validates, 186 because ordering constraints will be ignored. 187 188 @keyword value: If absent or C{None}, no change is made; otherwise, this 189 enables (C{True}) or disables (C{False}) the requirement that instances 190 validate before being converted to XML. 191 @type value: C{bool} 192 193 @return: C{True} iff attempts to generate XML for a binding that does not 194 validate should raise an exception. """ 195 global _GenerationRequiresValid 196 if value is None: 197 return _GenerationRequiresValid 198 if not isinstance(value, bool): 199 raise TypeError(value) 200 _GenerationRequiresValid = value 201 return _GenerationRequiresValid
202 203 _ParsingRequiresValid = True
204 -def RequireValidWhenParsing (value=None):
205 """Query or set a flag that controls validation checking in XML parsing. 206 207 Normally any attempts to convert XML to a binding instance to a binding 208 instance requires that the document validate against the content model. 209 In some cases it may be necessary or useful to process a document that is 210 incomplete. If validation is not required, the generated documents may 211 not validate even if the content validates, because ordering constraints 212 will be ignored. 213 214 @keyword value: If absent or C{None}, no change is made; otherwise, this 215 enables (C{True}) or disables (C{False}) the requirement that documents 216 validate when being converted to bindings. 217 @type value: C{bool} 218 219 @return: C{True} iff attempts to generate bindings for a document that 220 does not validate should raise an exception.""" 221 global _ParsingRequiresValid 222 if value is None: 223 return _ParsingRequiresValid 224 if not isinstance(value, bool): 225 raise TypeError(value) 226 _ParsingRequiresValid = value 227 return _ParsingRequiresValid
228 229 _PreserveInputTimeZone = False
230 -def PreserveInputTimeZone (value=None):
231 """Control whether time values are converted to UTC during input. 232 233 The U{specification <http://www.w3.org/TR/xmlschema-2/#dateTime>} makes 234 clear that timezoned times are in UTC and that times in other timezones 235 are to be translated to UTC when converted from literal to value form. 236 Provide an option to bypass this step, so the input timezone is preserved. 237 238 @note: Naive processing of unnormalized times--i.e., ignoring the 239 C{tzinfo} field--may result in errors.""" 240 global _PreserveInputTimeZone 241 if value is None: 242 return _PreserveInputTimeZone 243 if not isinstance(value, bool): 244 raise TypeError(value) 245 _PreserveInputTimeZone = value 246 return _PreserveInputTimeZone
247 248 _OutputEncoding = 'utf-8' 249 """Default unicode encoding to use when creating output. 250 251 Material being written to an XML parser is not output.""" 252 253 _InputEncoding = 'utf-8' 254 """Default unicode encoding to assume when decoding input. 255 256 Material being written to an XML parser is treated as input.""" 257 258 ## Local Variables: 259 ## fill-column:78 260 ## End: 261