Package pyxb :: Package utils :: Module utility |
[hide private]
[frames] | no frames]

# Module utility

source code

Utility functions and classes.

Classes | [hide private]
_DeconflictSymbols_mixin Mix-in used to deconflict public symbols in classes that may be inherited by generated binding classes.
Graph Represent a directed graph with arbitrary objects as nodes.
UniqueIdentifier Records a unique identifier, generally associated with a binding generation action.
UTCOffsetTimeZone A `datetime.tzinfo` subclass that helps deal with UTC conversions in an ISO8601 world.
LocalTimeZone A `datetime.tzinfo` subclass for the local time zone.
PrivateTransient_mixin Emulate the transient keyword from Java for private member variables.
Location
Locatable_mixin

Functions | [hide private]
BackfillComparisons(cls) Class decorator that fills in missing ordering methods. | source code
IteratedCompareMixed(lhs, rhs) Tuple comparison that permits `None` as lower than any value, and defines other cross-type comparison. | source code
`str` |
QuotedEscaped(s) Convert a string into a literal value that can be used in Python source. | source code
_DefaultXMLIdentifierToPython(identifier) Default implementation for _XMLIdentifierToPython | source code
`unicode` |
_SetXMLIdentifierToPython(xml_identifier_to_python) Configure a callable MakeIdentifier uses to pre-process an XM Lidentifier. | source code
_XMLIdentifierToPython(identifier) Default implementation for _XMLIdentifierToPython | source code
`str` |
MakeIdentifier(s, camel_case=False) Convert a string into something suitable to be a Python identifier. | source code
`str` |
DeconflictKeyword(s, aux_keywords=`frozenset([``])`) If the provided string `s` matches a Python language keyword, append an underscore to distinguish them. | source code
`str` |
MakeUnique(s, in_use) Return an identifier based on `s` that is not in the given set. | source code
`str` |
PrepareIdentifier(s, in_use, aux_keywords=`frozenset([``])`, private=False, protected=False) Combine everything required to create a unique identifier. | source code
`str` |
NormalizeWhitespace(text, preserve=False, replace=False, collapse=False) Normalize the given string. | source code
SetLocationPrefixRewriteMap(prefix_map) Set the map that is used to by NormalizeLocation to rewrite URI prefixes. | source code
NormalizeLocation(uri, parent_uri=None, prefix_map=None) Normalize a URI against an optional parent_uri in the way that is done for `schemaLocation` attribute values. | source code
DataFromURI(uri, archive_directory=None) Retrieve the contents of the uri as raw data. | source code
OpenOrCreate(file_name, tag=None, preserve_contents=False) Return a file object used to write binary data into the given file. | source code
HashForText(text) Calculate a cryptographic hash of the given string. | source code
`str` |
_NewUUIDString() Obtain a UUID using the best available method. | source code
GetMatchingFiles(path, pattern=None, default_path_wildcard=None, default_path=None, prefix_pattern=None, prefix_substituend=None) Provide a list of absolute paths to files present in any of a set of directories and meeting certain criteria. | source code

Variables | [hide private]
| _log = `logging.getLogger(__name__)`
| _UnderscoreSubstitute_re = `re.compile(r'`[`- \.`]`')`
| _NonIdentifier_re = `re.compile(r'`[``^`a`-`zA`-`Z0`-`9_`]`')`
| _PrefixUnderscore_re = `re.compile(r'^_`+`')`
| _PrefixDigit_re = `re.compile(r'^\d`+`')`
| _CamelCase_re = `re.compile(r'_\w')`
| _PythonKeywords = ``frozenset([``'``and``'``,` `'``as``'``,` `'``assert``'``,` `'``break``'``,` `'``...`` Python keywords.
| _PythonBuiltInConstants = ``frozenset([``'``Ellipsis``'``,` `'``False``'``,` `'``Non``...`` Other symbols that aren't keywords but that can't be used.
| _Keywords = ``frozenset([``'``Ellipsis``'``,` `'``False``'``,` `'``None``'``,` `'``NotImplem``...`` The keywords reserved for Python, derived from _PythonKeywords and _PythonBuiltInConstants.
| __TabCRLF_re = `re.compile(r'`[`\t\n\r`]`')`
| __MultiSpace_re = `re.compile(r' `+`')`
| LocationPrefixRewriteMap_ = ``{``}``
| __HaveUUID = `True`
| __package__ = ``'``pyxb.utils``'``

Function Details | [hide private]

### BackfillComparisons(cls) | source code
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.

### IteratedCompareMixed(lhs, rhs) | source code
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.

### QuotedEscaped(s) | source code
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`

### _DefaultXMLIdentifierToPython(identifier) | source code
Default implementation for _XMLIdentifierToPython For historical reasons, this converts the identifier from a str to unicode in the system default encoding. This should have no practical effect. Parameters: `identifier` - some XML identifier Returns: `unicode(identifier)`

### _SetXMLIdentifierToPython(xml_identifier_to_python) | source code
Configure a callable MakeIdentifier uses to pre-process an XM Lidentifier. In Python3, identifiers can be full Unicode tokens, but in Python2, all identifiers must be ASCII characters. MakeIdentifier enforces this by removing all characters that are not valid within an identifier. In some cases, an application generating bindings may be able to transliterate Unicode code points that are not valid Python identifier characters into something else. This callable can be assigned to perform that translation before the invalid characters are stripped. It is not the responsibility of this callable to do anything other than replace whatever characters it wishes to. All transformations performed by MakeIdentifier will still be applied, to ensure the output is in fact a legal identifier. Parameters: `xml_identifier_to_python` - A callable that takes a string and returns a Unicode, possibly with non-identifier characters replaced by other characters. Pass `None` to reset to the default implementation, which is _DefaultXMLIdentifierToPython. Returns: `unicode`

### _XMLIdentifierToPython(identifier) | source code
Default implementation for _XMLIdentifierToPython For historical reasons, this converts the identifier from a str to unicode in the system default encoding. This should have no practical effect. Parameters: `identifier` - some XML identifier Returns: `unicode(identifier)`

### MakeIdentifier(s, camel_case=False) | source code
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`

### DeconflictKeyword(s, aux_keywords=`frozenset([``])`) | source code
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`

### MakeUnique(s, in_use) | source code
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`

### PrepareIdentifier(s, in_use, aux_keywords=`frozenset([``])`, private=False, protected=False) | source code
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` Note: Only module-level identifiers should be treated as protected. The class-level _DeconflictSymbols_mixin infrastructure does not include protected symbols. All class and instance members beginning with a single underscore are reserved for the PyXB infrastructure.

### NormalizeWhitespace(text, preserve=False, replace=False, collapse=False) | source code
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`

### NormalizeLocation(uri, parent_uri=None, prefix_map=None) | source code
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.

### DataFromURI(uri, archive_directory=None) | source code
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.

### OpenOrCreate(file_name, tag=None, preserve_contents=False) | source code
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`).

### HashForText(text) | source code
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.

### _NewUUIDString() | source code
Obtain a UUID using the best available method. On a version of python that does not incorporate the `uuid` class, this creates a string combining the current date and time (to the second) with a random number. Returns: `str`

### GetMatchingFiles(path, pattern=None, default_path_wildcard=None, default_path=None, prefix_pattern=None, prefix_substituend=None) | source code
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.

Variables Details | [hide private]

  ### _PythonKeywords Python keywords. Note that types like int and float are not keywords. See Also: http://docs.python.org/reference/lexical_analysis.html#keywords. Value:
      frozenset(['and',
                 'as',
                 'assert',
                 'break',
                 'class',
                 'continue',
                 'def',
                 'del',
      ...

  ### _PythonBuiltInConstants Other symbols that aren't keywords but that can't be used. See Also: http://docs.python.org/library/constants.html. Value:
      frozenset(['Ellipsis',
                 'False',
                 'None',
                 'NotImplemented',
                 'True',
                 '__debug__',
                 'set'])

  ### _Keywords The keywords reserved for Python, derived from _PythonKeywords and _PythonBuiltInConstants. Value:
      frozenset(['Ellipsis',
                 'False',
                 'None',
                 'NotImplemented',
                 'True',
                 '__debug__',
                 'and',
                 'as',
      ...