Resolve Substitutions in RestructuredText

docutils provides publisher functions to use docutils as a library.

So using docutils.core.publish_string could be an option for your usecase.

In [90]: from docutils import core

In [91]: text = '|python|\n\n.. |python| image:: python.jpg\n'

In [92]: print core.publish_string(text)
<document source="<string>">
    <paragraph>
        <image alt="python" uri="python.jpg">
    <substitution_definition names="python">
        <image alt="python" uri="python.jpg">

By default puplish_string uses a pseudoxml writer, which you can see in the output. However if you really want to have the plain text output from your question, you need a custom writer class derived from docutils.writers.Writer. I'm not sure how to implement this, maybe the Sphinx TextWriter could be a starting point.

Seems that if you really only need the simple substitution, using replace on your text would be a simpler solution, if you need more complicated things, implement this using docutils is complicated, too.