Base classes representing basic elements

Author:Roland Hedberg
Version:1.2

Module

Contains base classes representing SAML elements.

These codes were originally written by Jeffrey Scudder for representing Saml elements. Takashi Matsuo had added some codes, and changed some. Roland Hedberg rewrote the whole thing from bottom up so barely anything but the original structures remained.

Module objective: provide data classes for SAML constructs. These classes hide the XML-ness of SAML and provide a set of native Python classes to interact with.

Conversions to and from XML should only be necessary when the SAML classes “touch the wire” and are sent over HTTP. For this reason this module provides methods and functions to convert SAML classes to and from strings.

exception saml2.Error

Exception class thrown by this module.

class saml2.ExtensionElement(tag, namespace=None, attributes=None, children=None, text=None)

XML which is not part of the SAML specification, these are called extension elements. If a classes parser encounters an unexpected XML construct, it is translated into an ExtensionElement instance. ExtensionElement is designed to fully capture the information in the XML. Child nodes in an XML extension are turned into ExtensionElements as well.

become_child_element_of(element_tree)

Converts this object into an etree element and adds it as a child node in an etree element.

Adds self to the ElementTree. This method is required to avoid verbose XML which constantly redefines the namespace.

Parameters:element_tree – ElementTree._Element The element to which this object’s XML will be added.
find_children(tag=None, namespace=None)

Searches child nodes for objects with the desired tag/namespace.

Returns a list of extension elements within this object whose tag and/or namespace match those passed in. To find all children in a particular namespace, specify the namespace but not the tag name. If you specify only the tag, the result list may contain extension elements in multiple namespaces.

Parameters:
  • tag – str (optional) The desired tag
  • namespace – str (optional) The desired namespace
Returns:

A list of elements whose tag and/or namespace match the parameters values

loadd(ava)

expects a special set of keys

to_string()

Serialize the object into a XML string

class saml2.SamlBase(text=None, extension_elements=None, extension_attributes=None)

A foundation class on which SAML classes are built. It handles the parsing of attributes and children which are common to all SAML classes. By default, the SamlBase class translates all XML child nodes into ExtensionElements.

become_child_element_of(node)

Note: Only for use with classes that have a c_tag and c_namespace class member. It is in SamlBase so that it can be inherited but it should not be called on instances of SamlBase.

Parameters:node – The node to which this instance should be a child
child_cardinality(child)

Return the cardinality of a child element

Parameters:child – The name of the child element
Returns:The cardinality as a 2-tuple (min, max). The max value is either a number or the string “unbounded”. The min value is always a number.
child_class(child)

Return the class a child element should be an instance of

Parameters:child – The name of the child element
Returns:The class
children_with_values()

Returns all children that has values

Returns:Possibly empty list of children.
keys()

Return all the keys that represent possible attributes and children.

Returns:list of keys
keyswv()

Return the keys of attributes or children that has values

Returns:list of keys
loadd(ava, base64encode=False)

Sets attributes, children, extension elements and extension attributes of this element instance depending on what is in the given dictionary. If there are already values on properties those will be overwritten. If the keys in the dictionary does not correspond to known attributes/children/.. they are ignored.

Parameters:
  • ava – The dictionary
  • base64encode – Whether the values on attributes or texts on children shoule be base64encoded.
Returns:

The instance

set_text(val, base64encode=False)

Sets the text property of this instance.

Parameters:
  • val – The value of the text property
  • base64encode – Whether the value should be base64encoded
Returns:

The instance

to_string(nspair=None)

Converts the Saml object to a string containing XML.

Parameters:nspair – A dictionary of prefixes and uris to use when constructing the text representation.
Returns:String representation of the object
saml2.create_class_from_element_tree(target_class, tree, namespace=None, tag=None)

Instantiates the class and populates members according to the tree.

Note: Only use this function with classes that have c_namespace and c_tag class members.

Parameters:
  • target_class – The class which will be instantiated and populated with the contents of the XML.
  • tree – An element tree whose contents will be converted into members of the new target_class instance.
  • namespace – The namespace which the XML tree’s root node must match. If omitted, the namespace defaults to the c_namespace of the target class.
  • tag – The tag which the XML tree’s root node must match. If omitted, the tag defaults to the c_tag class member of the target class.
Returns:

An instance of the target class - or None if the tag and namespace of the XML tree’s root node did not match the desired namespace and tag.

saml2.create_class_from_xml_string(target_class, xml_string)

Creates an instance of the target class from a string.

Parameters:
  • target_class – The class which will be instantiated and populated with the contents of the XML. This class must have a c_tag and a c_namespace class variable.
  • xml_string – A string which contains valid XML. The root element of the XML string should match the tag and namespace of the desired class.
Returns:

An instance of the target class with members assigned according to the contents of the XML - or None if the root XML tag and namespace did not match those of the target class.

saml2.element_to_extension_element(element)

Convert an element into a extension element

Parameters:element – The element instance
Returns:An extension element instance
saml2.extension_element_to_element(extension_element, translation_functions, namespace=None)

Convert an extension element to a normal element. In order to do this you need to have an idea of what type of element it is. Or rather which module it belongs to.

Parameters:
  • extension_element – The extension element
  • translation_functions – A dictionary with class identifiers as keys and string-to-element translations functions as values
  • namespace – The namespace of the translation functions.
Returns:

An element instance or None

saml2.extension_elements_to_elements(extension_elements, schemas)

Create a list of elements each one matching one of the given extension elements. This is of course dependent on the access to schemas that describe the extension elements.

Parameters:
  • extension_elements – The list of extension elements
  • schemas – Imported Python modules that represent the different known schemas used for the extension elements
Returns:

A list of elements, representing the set of extension elements that was possible to match against a Class in the given schemas. The elements returned are the native representation of the elements according to the schemas.

saml2.make_instance(klass, spec, base64encode=False)

Constructs a class instance containing the specified information

Parameters:
  • klass – The class
  • spec – Information to be placed in the instance (a dictionary)
Returns:

The instance

saml2.make_vals(val, klass, klass_inst=None, prop=None, part=False, base64encode=False)

Creates a class instance with a specified value, the specified class instance may be a value on a property in a defined class instance.

Parameters:
  • val – The value
  • klass – The value class
  • klass_inst – The class instance which has a property on which what this function returns is a value.
  • prop – The property which the value should be assigned to.
  • part – If the value is one of a possible list of values it should be handled slightly different compared to if it isn’t.
Returns:

Value class instance

Table Of Contents

Previous topic

Configuration of pySAML2 entities

Next topic

Base classes representing Saml2.0 elements

This Page