Module utility

Class decorator that fills in missing ordering methods.

Concept derived from Python 2.7.5 functools.total_ordering, but this version requires that __eq__ and __lt__ be provided, and unconditionally overrides __ne__, __gt__, __le__, and __ge__ with the derived versions.

This is still necessary in Python 3 because in Python 3 the comparison x >= y is done by the __ge__ inherited from object, which does not handle the case where x and y are not the same type even if the underlying y < x would convert x to be compatible.

Tuple comparison that permits None as lower than any value, and defines other cross-type comparison.

Returns:

-1 if lhs < rhs, 0 if lhs == rhs, 1 if lhs > rhs.

Convert a string into a literal value that can be used in Python source.

This just calls repr. No point in getting all complex when the language already gives us what we need.

Returns: str

Convert a string into something suitable to be a Python identifier.

The string is processed by _XMLIdentifierToPython. Following this, dashes, spaces, and periods are replaced by underscores, and characters not permitted in Python identifiers are stripped. Furthermore, any leading underscores are removed. If the result begins with a digit, the character 'n' is prepended. If the result is the empty string, the string 'emptyString' is substituted.

No check is made for conflicts with keywords.

Parameters:

• camel_case - If True, any underscore in the result string that is immediately followed by an alphanumeric is replaced by the capitalized version of that alphanumeric. Thus, 'one_or_two' becomes 'oneOrTwo'. If False (default), has no effect.

Returns: str

Convert a string into something that can be a valid element in a Python module path.

Module path elements are similar to identifiers, but may begin with numbers and should not have leading underscores removed.

If the provided string s matches a Python language keyword, append an underscore to distinguish them.

See also MakeUnique.

Parameters:

• s - string to be deconflicted
• aux_keywords - optional iterable of additional strings that should be treated as keywords.

Returns: str

Return an identifier based on s that is not in the given set.

The returned identifier is made unique by appending an underscore and, if necessary, a serial number.

The order is : x, x_, x_2, x_3, ...

Parameters:

• in_use - The set of identifiers already in use in the relevant scope. in_use is updated to contain the returned identifier.

Returns: str

Combine everything required to create a unique identifier.

Leading and trailing underscores are stripped from all identifiers.

Parameters:

• in_use - the set of already used identifiers. Upon return from this function, it is updated to include the returned identifier.
• aux_keywords - an optional set of additional symbols that are illegal in the given context; use this to prevent conflicts with known method names.
• private - if False (default), all leading underscores are stripped, guaranteeing the identifier will not be private. If True, the returned identifier has two leading underscores, making it a private variable within a Python class.
• protected - as for private, but uses only one underscore.

Returns: str

Normalize the given string.

Exactly one of the preserve, replace, and collapse keyword parameters must be assigned the value True by the caller.

• preserve: the text is returned unchanged.
• replace: all tabs, newlines, and carriage returns are replaced with ASCII spaces.
• collapse: the replace normalization is done, then sequences of two or more spaces are replaced by a single space.

See the whiteSpace facet.

Returns: str

Normalize a URI against an optional parent_uri in the way that is done for schemaLocation attribute values.

If no URI schema is present, this will normalize a file system path.

Optionally, the resulting absolute URI can subsequently be rewritten to replace specified prefix strings with alternative strings, e.g. to convert a remote URI to a local repository. This rewriting is done after the conversion to an absolute URI, but before normalizing file system URIs.

Parameters:

• uri - The URI to normalize. If None, function returns None
• parent_uri - The base URI against which normalization is done, if uri is a relative URI.
• prefix_map - A map used to rewrite URI prefixes. If None, the value defaults to that stored by SetLocationPrefixRewriteMap.

Retrieve the contents of the uri as raw data.

If the uri does not include a scheme (e.g., http:), it is assumed to be a file path on the local system.

Return a file object used to write binary data into the given file.

Use the tag keyword to preserve the contents of existing files that are not supposed to be overwritten.

To get a writable file but leaving any existing contents in place, set the preserve_contents keyword to True. Normally, existing file contents are erased.

The returned file pointer is positioned at the end of the file.

Parameters:

• tag - If not None and the file already exists, absence of the given value in the first 4096 bytes of the file (decoded as UTF-8) causes an IOError to be raised with errno set to EEXIST. I.e., only files with this value in the first 4KB will be returned for writing.
• preserve_contents - This value controls whether existing contents of the file will be erased (False, default) or left in place (True).

Calculate a cryptographic hash of the given string.

For example, this is used to verify that a given module file contains bindings from a previous generation run for the same namespace. See OpenOrCreate. If the text is in Unicode, the hash is calculated on the UTF-8 encoding of the text.

Returns:

A str, generally a sequence of hexadecimal "digit"s.

Provide a list of absolute paths to files present in any of a set of directories and meeting certain criteria.

This is used, for example, to locate namespace archive files within the archive path specified by the user. One could use:

 files = GetMatchingFiles('&bundles//:+',
                          pattern=re.compile('.*\.wxs$'),
                          default_path_wildcard='+',
                          default_path='/usr/local/pyxb/nsarchives',
                          prefix_pattern='&',
                          prefix_substituend='/opt/pyxb')

to obtain all files that can be recursively found within /opt/pyxb/bundles, or non-recursively within /usr/local/pyxb/nsarchives.

Parameters:

• path - A list of directories in which the search should be performed. The entries are separated by os.pathsep, which is a colon on POSIX platforms and a semi-colon on Windows. If a path entry ends with // regardless of platform, the suffix // is stripped and any directory beneath the path is scanned as well, recursively.
• pattern - Optional regular expression object used to determine whether a given directory entry should be returned. If left as None, all directory entries will be returned.
• default_path_wildcard - An optional string which, if present as a single directory in the path, is replaced by the value of default-path.
• default_path - A system-defined directory which can be restored to the path by placing the default_path_wildcard in the path.
• prefix_pattern - An optional string which, if present at the start of a path element, is replaced by the value of prefix_substituend.
• prefix_substituend - A system-defined string (path prefix) which can be combined with the user-provided path information to identify a file or subdirectory within an installation-specific area.

Filtered built-in repr for python 2/3 compatibility in generated bindings.

All generated string values are to be unicode. We always import unicode_literals from __future__, so we want plain quotes with no prefix u. Strip that off.

Integer constants should not have the suffix L even if they do not fit in a Python2 int. The references generated through this function are never used for calculations, so the implicit cast to a larger type is sufficient.

All other values use their standard representations.