1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 """Helper classes that maintain the content model of XMLSchema in the binding
16 classes.
17
18 L{AttributeUse} and L{ElementUse} record information associated with a binding
19 class, for example the types of values, the original XML QName or NCName, and
20 the Python field in which the values are stored. They also provide the
21 low-level interface to set and get the corresponding values in a binding
22 instance.
23
24
25
26 L{Wildcard} holds content-related information used in the content model.
27 """
28
29 import pyxb
30 import pyxb.namespace
31 import basis
32
33 import xml.dom
34
35 -class ContentState_mixin (pyxb.cscRoot):
36 """Declares methods used by classes that hold state while validating a
37 content model component."""
38
39 - def accepts (self, particle_state, instance, value, element_use):
40 """Determine whether the provided value can be added to the instance
41 without violating state validation.
42
43 This method must not throw any non-catastrophic exceptions; general
44 failures should be transformed to a C{False} return value.
45
46 @param particle_state: The L{ParticleState} instance serving as the
47 parent to this state. The implementation must inform that state when
48 the proposed value completes the content model.
49
50 @param instance: An instance of a subclass of
51 {basis.complexTypeDefinition}, into which the provided value will be
52 stored if it is consistent with the current model state.
53
54 @param value: The value that is being validated against the state.
55
56 @param element_use: An optional L{ElementUse} instance that specifies
57 the element to which the value corresponds. This will be available
58 when the value is extracted by parsing a document, but will be absent
59 if the value was passed as a constructor positional parameter.
60
61 @return: C{True} if the value was successfully matched against the
62 state. C{False} if the value did not match against the state."""
63 raise Exception('ContentState_mixin.accepts not implemented in %s' % (type(self),))
64
65 - def notifyFailure (self, sub_state, particle_ok):
66 """Invoked by a sub-state to indicate that validation cannot proceed
67 in the current state.
68
69 Normally this is used when an intermediate content model must reset
70 itself to permit alternative models to be evaluated.
71
72 @param sub_state: the state that was unable to accept a value
73
74 @param particle_ok: C{True} if the particle that rejected the value is
75 in an accepting terminal state
76
77 """
78 raise Exception('ContentState_mixin.notifyFailure not implemented in %s' % (type(self),))
79
80 - def _verifyComplete (self, parent_particle_state):
81 """Determine whether the deep state is complete without further elements.
82
83 No-op for non-aggregate state. For aggregate state, all contained
84 particles should be checked to see whether the overall model can be
85 satisfied if no additional elements are provided.
86
87 This method does not have a meaningful return value; violations of the
88 content model should produce the corresponding exception (generally,
89 L{MissingContentError}).
90
91 @param parent_particle_state: the L{ParticleState} for which this state
92 is the term.
93 """
94 pass
95
96 -class ContentModel_mixin (pyxb.cscRoot):
97 """Declares methods used by classes representing content model components."""
98
99 - def newState (self, parent_particle_state):
100 """Return a L{ContentState_mixin} instance that will validate the
101 state of this model component.
102
103 @param parent_particle_state: The L{ParticleState} instance for which
104 this instance is a term. C{None} for the top content model of a
105 complex data type.
106 """
107 raise Exception('ContentModel_mixin.newState not implemented in %s' % (type(self),))
108
109 - def _validateCloneSymbolSet (self, symbol_set_im):
110 """Create a mutable copy of the symbol set.
111
112 The top-level map is copied, as are the lists of values to which the
113 symbols map. The values within the lists are unchanged, as validation
114 does not affect them."""
115 rv = symbol_set_im.copy()
116 for (k, v) in rv.items():
117 rv[k] = v[:]
118 return rv
119
120 - def _validateCloneOutputSequence (self, output_sequence_im):
121 """Create a mutable copy of the output sequence."""
122 return output_sequence_im[:]
123
124 - def _validateReplaceResults (self, symbol_set_out, symbol_set_new, output_sequence_out, output_sequence_new):
125 """In-place update of symbol set and output sequence structures.
126
127 Use this to copy from temporary mutable structures updated by local
128 validation into the structures that were passed in once the validation
129 has succeeded."""
130 symbol_set_out.clear()
131 symbol_set_out.update(symbol_set_new)
132 output_sequence_out[:] = output_sequence_new
133
134 - def _validate (self, symbol_set, output_sequence):
135 """Determine whether an output sequence created from the symbols can
136 be made consistent with the model.
137
138 The symbol set represents letters in an alphabet; the output sequence
139 orders those letters in a way that satisfies the regular expression
140 expressed in the model. Both are changed as a result of a successful
141 validation; both remain unchanged if the validation failed. In
142 recursing, implementers may assume that C{output_sequence} is
143 monotonic: its length remains unchanged after an invocation iff the
144 symbol set also remains unchanged. The L{_validateCloneSymbolSet},
145 L{_validateCloneOutputSequence}, and L{_validateReplaceResults}
146 methods are available to help preserve this behavior.
147
148 @param symbol_set: A map from L{ElementUse} instances to a list of
149 values. The order of the values corresponds to the order in which
150 they should appear. A key of C{None} identifies values that are
151 stored as wildcard elements. Values are removed from the lists as
152 they are used; when the last value of a list is removed, its key is
153 removed from the map. Thus an empty dictionary is the indicator that
154 no more symbols are available.
155
156 @param output_sequence: A mutable list to which should be appended
157 tuples C{( eu, val )} where C{eu} is an L{ElementUse} from the set of
158 symbol keys, and C{val} is a value from the corresponding list. A
159 document generated by producing the elements in the given order is
160 expected to validate.
161
162 @return: C{True} iff the model validates. C{symbol_set} and
163 C{output_path} will be unchanged if this returns C{False}.
164 """
165 raise Exception('ContentState_mixin._validate not implemented in %s' % (type(self),))
166
167
169 """A helper class that encapsulates everything we need to know
170 about the way an attribute is used within a binding class.
171
172 Attributes are stored internally as pairs C{(provided, value)}, where
173 C{provided} is a boolean indicating whether a value for the attribute was
174 provided externally, and C{value} is an instance of the attribute
175 datatype. The C{provided} flag is used to determine whether an XML
176 attribute should be added to a created DOM node when generating the XML
177 corresponding to a binding instance.
178 """
179
180 __name = None
181 """ExpandedName of the attribute"""
182
183 __id = None
184 """Identifier used for this attribute within the owning class"""
185
186 __key = None
187 """Private Python attribute used in instances to hold the attribute value"""
188
189 __dataType = None
190 """The L{pyxb.binding.basis.simpleTypeDefinition} for values of the attribute"""
191
192 __unicodeDefault = None
193 """The default attribute value as a unicode string, or C{None}"""
194
195 __defaultValue = None
196 """The default value as an instance of L{__dataType}, or C{None}"""
197
198 __fixed = False
199 """C{True} if the attribute value cannot be changed"""
200
201 __required = False
202 """C{True} if the attribute must appear in every instance of the type"""
203
204 __prohibited = False
205 """C{True} if the attribute must not appear in any instance of the type"""
206
207 - def __init__ (self, name, id, key, data_type, unicode_default=None, fixed=False, required=False, prohibited=False):
208 """Create an AttributeUse instance.
209
210 @param name: The name by which the attribute is referenced in the XML
211 @type name: L{pyxb.namespace.ExpandedName}
212
213 @param id: The Python identifier for the attribute within the
214 containing L{pyxb.basis.binding.complexTypeDefinition}. This is a
215 public identifier, derived from the local part of the attribute name
216 and modified to be unique, and is usually used as the name of the
217 attribute's inspector method.
218 @type id: C{str}
219
220 @param key: The string used to store the attribute
221 value in the dictionary of the containing
222 L{pyxb.basis.binding.complexTypeDefinition}. This is mangled so
223 that it is unique among and is treated as a Python private member.
224 @type key: C{str}
225
226 @param data_type: The class reference to the subclass of
227 L{pyxb.binding.basis.simpleTypeDefinition} of which the attribute
228 values must be instances.
229 @type data_type: C{type}
230
231 @keyword unicode_default: The default value of the attribute as
232 specified in the schema, or None if there is no default attribute
233 value. The default value (of the keyword) is C{None}.
234 @type unicode_default: C{unicode}
235
236 @keyword fixed: If C{True}, indicates that the attribute, if present,
237 must have the value that was given via C{unicode_default}. The
238 default value is C{False}.
239 @type fixed: C{bool}
240
241 @keyword required: If C{True}, indicates that the attribute must appear
242 in the DOM node used to create an instance of the corresponding
243 L{pyxb.binding.basis.complexTypeDefinition}. The default value is
244 C{False}. No more that one of L{required} and L{prohibited} should be
245 assigned C{True}.
246 @type required: C{bool}
247
248 @keyword prohibited: If C{True}, indicates that the attribute must
249 B{not} appear in the DOM node used to create an instance of the
250 corresponding L{pyxb.binding.basis.complexTypeDefinition}. The
251 default value is C{False}. No more that one of L{required} and
252 L{prohibited} should be assigned C{True}.
253 @type prohibited: C{bool}
254
255 @raise pyxb.BadTypeValueError: the L{unicode_default} cannot be used
256 to initialize an instance of L{data_type}
257 """
258
259 self.__name = name
260 self.__id = id
261 self.__key = key
262 self.__dataType = data_type
263 self.__unicodeDefault = unicode_default
264 if self.__unicodeDefault is not None:
265 self.__defaultValue = self.__dataType.Factory(self.__unicodeDefault, _from_xml=True)
266 self.__fixed = fixed
267 self.__required = required
268 self.__prohibited = prohibited
269
271 """The expanded name of the element.
272
273 @rtype: L{pyxb.namespace.ExpandedName}
274 """
275 return self.__name
276
278 """The default value of the attribute."""
279 return self.__defaultValue
280
282 """C{True} iff the value of the attribute cannot be changed."""
283 return self.__fixed
284
286 """C{True} iff the attribute must be assigned a value."""
287 return self.__required
288
290 """C{True} iff the attribute must not be assigned a value."""
291 return self.__prohibited
292
294 """C{True} iff the given instance has been explicitly given a value
295 for the attribute.
296
297 This is used for things like only generating an XML attribute
298 assignment when a value was originally given (even if that value
299 happens to be the default).
300 """
301 return self.__getProvided(ctd_instance)
302
304 """Tag used within Python code for the attribute.
305
306 This is not used directly in the default code generation template."""
307 return self.__id
308
310 """String used as key within object dictionary when storing attribute value."""
311 return self.__key
312
314 """The subclass of L{pyxb.binding.basis.simpleTypeDefinition} of which any attribute value must be an instance."""
315 return self.__dataType
316
318 """Retrieve the value information for this attribute in a binding instance.
319
320 @param ctd_instance: The instance object from which the attribute is to be retrieved.
321 @type ctd_instance: subclass of L{pyxb.binding.basis.complexTypeDefinition}
322 @return: C{(provided, value)} where C{provided} is a C{bool} and
323 C{value} is C{None} or an instance of the attribute's datatype.
324
325 """
326 return getattr(ctd_instance, self.__key, (False, None))
327
330
331 - def value (self, ctd_instance):
332 """Get the value of the attribute from the instance."""
333 return self.__getValue(ctd_instance)[1]
334
335 - def __setValue (self, ctd_instance, new_value, provided):
336 return setattr(ctd_instance, self.__key, (provided, new_value))
337
338 - def reset (self, ctd_instance):
339 """Set the value of the attribute in the given instance to be its
340 default value, and mark that it has not been provided."""
341 self.__setValue(ctd_instance, self.__defaultValue, False)
342
350
379
380 - def set (self, ctd_instance, new_value):
381 """Set the value of the attribute.
382
383 This validates the value against the data type, creating a new instance if necessary.
384
385 @param ctd_instance: The binding instance for which the attribute
386 value is to be set
387 @type ctd_instance: subclass of L{pyxb.binding.basis.complexTypeDefinition}
388 @param new_value: The value for the attribute
389 @type new_value: An C{xml.dom.Node} instance, or any value that is
390 permitted as the input parameter to the C{Factory} method of the
391 attribute's datatype.
392 """
393 provided = True
394 from_xml = False
395 if isinstance(new_value, xml.dom.Node):
396 from_xml = True
397 unicode_value = self.__name.getAttribute(new_value)
398 if unicode_value is None:
399 if self.__required:
400 raise pyxb.MissingAttributeError('Required attribute %s from %s not found' % (self.__name, ctd_instance._ExpandedName or type(ctd_instance)))
401 provided = False
402 unicode_value = self.__unicodeDefault
403 if unicode_value is None:
404
405 provided = False
406 new_value = None
407 else:
408 new_value = unicode_value
409 elif new_value is None:
410 if self.__required:
411 raise pyxb.MissingAttributeError('Required attribute %s in %s may not be set to None' % (self.__name, ctd_instance._ExpandedName or type(ctd_instance)))
412 provided = False
413 if provided and self.__prohibited:
414 raise pyxb.ProhibitedAttributeError('Value given for prohibited attribute %s' % (self.__name,))
415 if (new_value is not None) and (not isinstance(new_value, self.__dataType)):
416 new_value = self.__dataType.Factory(new_value, _from_xml=from_xml)
417 if self.__fixed and (new_value != self.__defaultValue):
418 raise pyxb.AttributeChangeError('Attempt to change value of fixed attribute %s' % (self.__name,))
419 self.__setValue(ctd_instance, new_value, provided)
420 return new_value
421
422 - def _description (self, name_only=False, user_documentation=True):
423 if name_only:
424 return str(self.__name)
425 assert issubclass(self.__dataType, basis._TypeBinding_mixin)
426 desc = [ str(self.__id), ': ', str(self.__name), ' (', self.__dataType._description(name_only=True, user_documentation=False), '), ' ]
427 if self.__required:
428 desc.append('required')
429 elif self.__prohibited:
430 desc.append('prohibited')
431 else:
432 desc.append('optional')
433 if self.__defaultValue is not None:
434 desc.append(', ')
435 if self.__fixed:
436 desc.append('fixed')
437 else:
438 desc.append('default')
439 desc.extend(['=', self.__unicodeDefault ])
440 return ''.join(desc)
441
442 -class ElementUse (ContentState_mixin, ContentModel_mixin):
443 """Aggregate the information relevant to an element of a complex type.
444
445 This includes the L{original tag name<name>}, the spelling of L{the
446 corresponding object in Python <id>}, an L{indicator<isPlural>} of whether
447 multiple instances might be associated with the field, and other relevant
448 information.
449 """
450
452 """The expanded name of the element.
453
454 @rtype: L{pyxb.namespace.ExpandedName}
455 """
456 return self.__name
457 __name = None
458
460 """The string name of the binding class field used to hold the element
461 values.
462
463 This is the user-visible name, and excepting disambiguation will be
464 equal to the local name of the element."""
465 return self.__id
466 __id = None
467
468
469
470
471 __key = None
472
474 """The L{basis.element} instance identifying the information
475 associated with the element declaration.
476 """
477 return self.__elementBinding
484 __elementBinding = None
485
487 """True iff the content model indicates that more than one element
488 can legitimately belong to this use.
489
490 This includes elements in particles with maxOccurs greater than one,
491 and when multiple elements with the same NCName are declared in the
492 same type.
493 """
494 return self.__isPlural
495 __isPlural = False
496
497 - def __init__ (self, name, id, key, is_plural, element_binding=None):
498 """Create an ElementUse instance.
499
500 @param name: The name by which the element is referenced in the XML
501 @type name: L{pyxb.namespace.ExpandedName}
502
503 @param id: The Python name for the element within the containing
504 L{pyxb.basis.binding.complexTypeDefinition}. This is a public
505 identifier, albeit modified to be unique, and is usually used as the
506 name of the element's inspector method or property.
507 @type id: C{str}
508
509 @param key: The string used to store the element
510 value in the dictionary of the containing
511 L{pyxb.basis.binding.complexTypeDefinition}. This is mangled so
512 that it is unique among and is treated as a Python private member.
513 @type key: C{str}
514
515 @param is_plural: If C{True}, documents for the corresponding type may
516 have multiple instances of this element. As a consequence, the value
517 of the element will be a list. If C{False}, the value will be C{None}
518 if the element is absent, and a reference to an instance of the type
519 identified by L{pyxb.binding.basis.element.typeDefinition} if present.
520 @type is_plural: C{bool}
521
522 @param element_binding: Reference to the class that serves as the
523 binding for the element.
524 """
525 self.__name = name
526 self.__id = id
527 self.__key = key
528 self.__isPlural = is_plural
529 self.__elementBinding = element_binding
530
532 """Return the default value for this element.
533
534 @todo: Right now, this returns C{None} for non-plural and an empty
535 list for plural elements. Need to support schema-specified default
536 values for simple-type content.
537 """
538 if self.isPlural():
539 return []
540 return None
541
542 - def value (self, ctd_instance):
543 """Return the value for this use within the given instance."""
544 return getattr(ctd_instance, self.__key, self.defaultValue())
545
546 - def reset (self, ctd_instance):
547 """Set the value for this use in the given element to its default."""
548 setattr(ctd_instance, self.__key, self.defaultValue())
549 return self
550
551 - def set (self, ctd_instance, value):
561
563 """Invoke either L{set} or L{append}, depending on whether the element
564 use is plural."""
565 if self.isPlural():
566 return self.append(ctd_instance, value)
567 return self.set(ctd_instance, value)
568
569 - def append (self, ctd_instance, value):
581
582 - def toDOM (self, dom_support, parent, value):
583 """Convert the given value to DOM as an instance of this element.
584
585 @param dom_support: Helper for managing DOM properties
586 @type dom_support: L{pyxb.utils.domutils.BindingDOMSupport}
587 @param parent: The DOM node within which this element should be generated.
588 @type parent: C{xml.dom.Element}
589 @param value: The content for this element. May be text (if the
590 element allows mixed content), or an instance of
591 L{basis._TypeBinding_mixin}.
592 """
593 if isinstance(value, basis._TypeBinding_mixin):
594 element_binding = self.__elementBinding
595 if value._substitutesFor(element_binding):
596 element_binding = value._element()
597 assert element_binding is not None
598 if element_binding.abstract():
599 raise pyxb.DOMGenerationError('Element %s is abstract but content %s not associated with substitution group member' % (self.name(), value))
600 element = dom_support.createChildElement(element_binding.name(), parent)
601 elt_type = element_binding.typeDefinition()
602 val_type = type(value)
603 if isinstance(value, basis.complexTypeDefinition):
604 assert isinstance(value, elt_type)
605 else:
606 if isinstance(value, basis.STD_union) and isinstance(value, elt_type._MemberTypes):
607 val_type = elt_type
608 if dom_support.requireXSIType() or elt_type._RequireXSIType(val_type):
609 val_type_qname = value._ExpandedName.localName()
610 tns_prefix = dom_support.namespacePrefix(value._ExpandedName.namespace())
611 if tns_prefix is not None:
612 val_type_qname = '%s:%s' % (tns_prefix, val_type_qname)
613 dom_support.addAttribute(element, pyxb.namespace.XMLSchema_instance.createExpandedName('type'), val_type_qname)
614 value._toDOM_csc(dom_support, element)
615 elif isinstance(value, (str, unicode)):
616 element = dom_support.createChildElement(self.name(), parent)
617 element.appendChild(dom_support.document().createTextNode(value))
618 else:
619 raise pyxb.LogicError('toDOM with unrecognized value type %s: %s' % (type(value), value))
620
621 - def _description (self, name_only=False, user_documentation=True):
629
630
631 - def newState (self, parent_particle_state):
632 """Implement parent class method."""
633 return self
634
635
636 - def accepts (self, particle_state, instance, value, element_use):
642
643 - def _accepts (self, instance, value, element_use):
666
667
668 - def _validate (self, symbol_set, output_sequence):
669 values = symbol_set.get(self)
670
671 if values is None:
672 return False
673 used = values.pop(0)
674 output_sequence.append( (self, used) )
675 if 0 == len(values):
676 del symbol_set[self]
677 return True
678
680 return 'EU.%s@%x' % (self.__name, id(self))
681
682
683 -class Wildcard (ContentState_mixin, ContentModel_mixin):
684 """Placeholder for wildcard objects."""
685
686 NC_any = '##any'
687 NC_not = '##other'
688 NC_targetNamespace = '##targetNamespace'
689 NC_local = '##local'
690
691 __namespaceConstraint = None
693 """A constraint on the namespace for the wildcard.
694
695 Valid values are:
696
697 - L{Wildcard.NC_any}
698 - A tuple ( L{Wildcard.NC_not}, a L{namespace<pyxb.namespace.Namespace>} instance )
699 - set(of L{namespace<pyxb.namespace.Namespace>} instances)
700
701 Namespaces are represented by their URIs. Absence is
702 represented by C{None}, both in the "not" pair and in the set.
703 """
704 return self.__namespaceConstraint
705
706 PC_skip = 'skip'
707 """No namespace constraint is applied to the wildcard."""
708
709 PC_lax = 'lax'
710 """Validate against available uniquely determined declaration."""
711
712 PC_strict = 'strict'
713 """Validate against declaration or xsi:type, which must be available."""
714
715 __processContents = None
716 """One of L{PC_skip}, L{PC_lax}, L{PC_strict}."""
717 - def processContents (self):
718 """Indicate how this wildcard's contents should be processed."""
719 return self.__processContents
720
728
730 """
731 @keyword namespace_constraint: Required namespace constraint(s)
732 @keyword process_contents: Required"""
733
734
735 nsc = kw['namespace_constraint']
736 if isinstance(nsc, tuple):
737 nsc = (nsc[0], self.__normalizeNamespace(nsc[1]))
738 elif isinstance(nsc, set):
739 nsc = set([ self.__normalizeNamespace(_uri) for _uri in nsc ])
740 self.__namespaceConstraint = nsc
741 self.__processContents = kw['process_contents']
742
743 - def matches (self, instance, value):
775
776
777 - def newState (self, parent_particle_state):
779
780
781 - def accepts (self, particle_state, instance, value, element_use):
795
796
797 - def _validate (self, symbol_set, output_sequence):
798
799
800 wc_values = symbol_set.get(None)
801 if wc_values is None:
802 return False
803 used = wc_values.pop(0)
804 output_sequence.append( (None, used) )
805 if 0 == len(wc_values):
806 del symbol_set[None]
807 return True
808
810 """Represent the state of validation against a sequence of particles."""
811
812 __sequence = None
813 __particleState = None
814 __parentParticleState = None
815
816 __index = -1
817
818 __failed = False
819 """C{True} iff the content provided is in conflict with the sequence
820 requirements.
821
822 Specifically, the model requires content that has not been provided. Set
823 within L{accepts}. This state is sticky."""
824
825 __satisfied = False
826 """C{True} iff the content provided is consistent with the sequence
827 requirements.
828
829 Specifically, nothing has been presented with conflicts with the model.
830 Set within L{notifyFailure}."""
831
832 - def __init__ (self, group, parent_particle_state):
842
843
844
845 - def accepts (self, particle_state, instance, value, element_use):
858
859
863
864
874
875
877 - def __init__ (self, group, parent_particle_state):
882
883
884
885 - def accepts (self, particle_state, instance, value, element_use):
886
887
888 if self.__activeChoice is None:
889 for choice in self.__choices:
890
891 try:
892 (consume, underflow_exc) = choice.step(instance, value, element_use)
893 except Exception, e:
894 consume = False
895 underflow_exc = e
896
897 if consume:
898 self.__activeChoice = choice
899 self.__choices = None
900 return True
901 return False
902 (consume, underflow_exc) = self.__activeChoice.step(instance, value, element_use)
903
904 if consume:
905 return True
906 if underflow_exc is not None:
907 self.__failed = True
908 raise underflow_exc
909 return False
910
911
928
929
991 -class ParticleState (pyxb.cscRoot):
992
993 __parentState = None
994 """The L{ContentState_mixin} which contains the mode for which this is state."""
995
996 __termState = None
997 """A L{ContentState_mixin} instance for one occurrence of this particle's term."""
998
999 __tryAccept = None
1000 """A flag indicating whether a proposed value should be applied to the
1001 state by L{step}."""
1002
1003 - def __init__ (self, particle, parent_state=None):
1004 self.__particle = particle
1005 self.__parentState = parent_state
1006 self.__count = -1
1007
1008 self.incrementCount()
1009
1010 __particle = None
1011 """The L{ParticleModel} for which this represents state."""
1012
1013 - def particle (self):
1014 """The L{ParticleModel} for which this represents state."""
1015 return self.__particle
1016
1017 __count = None
1018 """The number of times this particle's term has been matched."""
1019
1020 - def incrementCount (self):
1021 """Reset for a new occurrence of the particle's term."""
1022
1023 self.__count += 1
1024 self.__termState = self.__particle.term().newState(self)
1025 self.__tryAccept = True
1026
1027 - def verifyComplete (self):
1028 """Check whether the particle's occurrence constraints are satisfied.
1029
1030 @raise pyxb.MissingContentError: Particle requires additional content to be satisfied."""
1031
1032
1033
1034
1035
1036
1037 if not self.__particle.satisfiesOccurrences(self.__count):
1038 self.__termState._verifyComplete(self)
1039
1040
1041 if not self.__particle.satisfiesOccurrences(self.__count):
1042
1043 raise pyxb.MissingContentError('incomplete')
1044
1045
1046 if self.__parentState is not None:
1047 self.__parentState.notifyFailure(self, True)
1048
1049 - def step (self, instance, value, element_use):
1050 """Attempt to apply the value as a new instance of the particle's term.
1051
1052 The L{ContentState_mixin} created for the particle's term is consulted
1053 to determine whether the instance can accept the given value. If so,
1054 the particle's maximum occurrence limit is checked; if not, and the
1055 particle has a parent state, it is informed of the failure.
1056
1057 @param instance: An instance of a subclass of
1058 {basis.complexTypeDefinition}, into which the provided value will be
1059 stored if it is consistent with the current model state.
1060
1061 @param value: The value that is being validated against the state.
1062
1063 @param element_use: An optional L{ElementUse} instance that specifies
1064 the element to which the value corresponds. This will be available
1065 when the value is extracted by parsing a document, but will be absent
1066 if the value was passed as a constructor positional parameter.
1067
1068 @return: C{( consumed, underflow_exc )} A tuple where the first element
1069 is C{True} iff the provided value was accepted in the current state.
1070 When this first element is C{False}, the second element will be
1071 C{None} if the particle's occurrence requirements have been met, and
1072 is an instance of C{MissingElementError} if the observed number of
1073 terms is less than the minimum occurrence count. Depending on
1074 context, the caller may raise this exception, or may try an
1075 alternative content model.
1076
1077 @raise pyxb.UnexpectedElementError: if the value satisfies the particle,
1078 but having done so exceeded the allowable number of instances of the
1079 term.
1080 """
1081
1082
1083
1084
1085 consumed = False
1086 underflow_exc = None
1087
1088
1089
1090
1091 self.__tryAccept = True
1092 while self.__tryAccept and (self.__count != self.__particle.maxOccurs()):
1093 self.__tryAccept = False
1094 consumed = self.__termState.accepts(self, instance, value, element_use)
1095
1096 self.__tryAccept = self.__tryAccept and (not consumed)
1097
1098 if consumed:
1099 if not self.__particle.meetsMaximum(self.__count):
1100 raise pyxb.UnexpectedElementError('too many')
1101 else:
1102 if self.__parentState is not None:
1103 self.__parentState.notifyFailure(self, self.__particle.satisfiesOccurrences(self.__count))
1104 if not self.__particle.meetsMinimum(self.__count):
1105
1106
1107 underflow_exc = pyxb.MissingElementError(content=value, container=instance)
1108 return (consumed, underflow_exc)
1109
1110 - def __str__ (self):
1111 particle = self.__particle
1112 return 'ParticleState(%d:%d,%s:%s)@%x' % (self.__count, particle.minOccurs(), particle.maxOccurs(), particle.term(), id(self))
1113
1114 -class ParticleModel (ContentModel_mixin):
1115 """Content model dealing with particles: terms with occurrence restrictions"""
1116
1117 __minOccurs = None
1118 - def minOccurs (self):
1119 """The minimum number of times the term must occur.
1120
1121 This will be a non-negative integer."""
1122 return self.__minOccurs
1123
1124 __maxOccurs = None
1125 - def maxOccurs (self):
1126 """The maximum number of times the term may occur.
1127
1128 This will be a positive integer, or C{None} indicating an unbounded
1129 number of occurrences."""
1130 return self.__maxOccurs
1131
1132 __term = None
1133 """The L{ContentModel_mixin} for a single occurrence."""
1135 """The term for a single occurrence."""
1136 return self.__term
1137
1138 - def meetsMaximum (self, count):
1139 """@return: C{True} iff there is no maximum on term occurrence, or the
1140 provided count does not exceed that maximum"""
1141 return (self.__maxOccurs is None) or (count <= self.__maxOccurs)
1142
1143 - def meetsMinimum (self, count):
1144 """@return: C{True} iff the provided count meets the minimum number of
1145 occurrences"""
1146 return count >= self.__minOccurs
1147
1148 - def satisfiesOccurrences (self, count):
1149 """@return: C{True} iff the provided count satisfies the occurrence
1150 requirements"""
1151 return self.meetsMinimum(count) and self.meetsMaximum(count)
1152
1153 - def __init__ (self, term, min_occurs=1, max_occurs=1):
1154 self.__term = term
1155 self.__minOccurs = min_occurs
1156 self.__maxOccurs = max_occurs
1157
1158
1159 - def newState (self):
1160 return ParticleState(self)
1161
1162 - def validate (self, symbol_set):
1163 """Determine whether the particle requirements are satisfiable by the
1164 given symbol set.
1165
1166 The symbol set represents letters in an alphabet. If those letters
1167 can be combined in a way that satisfies the regular expression
1168 expressed in the model, a satisfying sequence is returned and the
1169 symbol set is reduced by the letters used to form the sequence. If
1170 the content model cannot be satisfied, C{None} is returned and the
1171 symbol set remains unchanged.
1172
1173 @param symbol_set: A map from L{ElementUse} instances to a list of
1174 values. The order of the values corresponds to the order in which
1175 they should appear. A key of C{None} identifies values that are
1176 stored as wildcard elements. Values are removed from the lists as
1177 they are used; when the last value of a list is removed, its key is
1178 removed from the map. Thus an empty dictionary is the indicator that
1179 no more symbols are available.
1180
1181 @return: returns C{None}, or a list of tuples C{( eu, val )} where
1182 C{eu} is an L{ElementUse} from the set of symbol keys, and C{val} is a
1183 value from the corresponding list.
1184 """
1185
1186 output_sequence = []
1187
1188 result = self._validate(symbol_set, output_sequence)
1189
1190 if result:
1191 return (symbol_set, output_sequence)
1192 return None
1193
1194
1195 - def _validate (self, symbol_set, output_sequence):
1196 symbol_set_mut = self._validateCloneSymbolSet(symbol_set)
1197 output_sequence_mut = self._validateCloneOutputSequence(output_sequence)
1198 count = 0
1199
1200 last_size = len(output_sequence_mut)
1201 while (count != self.__maxOccurs) and self.__term._validate(symbol_set_mut, output_sequence_mut):
1202
1203 this_size = len(output_sequence_mut)
1204 if this_size == last_size:
1205
1206
1207 if count < self.__minOccurs:
1208 count = self.__minOccurs
1209 break
1210 count += 1
1211 last_size = this_size
1212 result = self.satisfiesOccurrences(count)
1213 if (result):
1214 self._validateReplaceResults(symbol_set, symbol_set_mut, output_sequence, output_sequence_mut)
1215
1216 return result
1217
1218 -class _Group (ContentModel_mixin):
1219 """Base class for content information pertaining to a U{model
1220 group<http://www.w3.org/TR/xmlschema-1/#Model_Groups>}.
1221
1222 There is a specific subclass for each group compositor.
1223 """
1224
1225 _StateClass = None
1226 """A reference to a L{ContentState_mixin} class that maintains state when
1227 validating an instance of this group."""
1228
1229 __particles = None
1230 """List of L{ParticleModel}s comprising the group."""
1231
1232 - def particles (self):
1233 """The sequence of particles comprising the group"""
1234 return self.__particles
1235
1238
1239
1240
1241 - def newState (self, parent_particle_state):
1242 return self._StateClass(self, parent_particle_state)
1243
1244
1245
1246 - def _validate (self, symbol_set, output_sequence):
1254
1255
1275
1278
1281
1282
1283
1284
1285