type SourcedString

source code

object --+    
         |    
basestring --+
             |
            SourcedString

Known Subclasses:

• CompoundSourcedString
• , SimpleSourcedString

A string that is annotated with information about the location in a document where it was originally found. Sourced strings are subclassed from Python strings. As a result, they can usually be used anywhere a normal Python string can be used.

There are two types of sourced strings: SimpleSourcedStrings, which correspond to a single substring of a document; and CompoundSourcedStrings, which are constructed by concatenating strings from multiple sources. Each of these types has two concrete subclasses: one for unicode strings (subclassed from ``unicode``), and one for byte strings (subclassed from ``str``).

Two sourced strings are considered equal if their contents are equal, even if their sources differ. This fact is important in ensuring that sourced strings act like normal strings. In particular, it allows sourced strings to be used with code that was originally intended to process plain Python strings.

If you wish to determine whether two sourced strings came from the same location in the same document, simply compare their sources attributes. If you know that both sourced strings are SimpleSourcedStrings, then you can compare their source attribute instead.

String operations that act on sourced strings will preserve location information whenever possible. However, there are a few types of string manipulation that can cause source information to be discarded. The most common examples of operations that will lose source information are:

• ``str.join()``, where the joining string is not sourced.
• ``str.replace()``, where the original string is not sourced.
• String formatting (the ``%`` operator).
• Regular expression substitution.