sharing data across Examples docstrings

[Cameron Simpson]

On 11Jan2022 16:09, Sebastian Luque <spluque at gmail.com> wrote:
>I am searching for a mechanism for sharing data across Examples 
>sections
>in docstrings within a class.  For instance:
>
>class Foo:
>
>    def foo(self):
>        """Method foo title
>
>        The example generating data below may be much more laborious.
>
>        Examples
>        --------
>        >>> x = list("abc")  # may be very long and tedious to generate
>
>        """
>        pass
>
>    def bar(self):
>        """Method bar title
>
>        Examples
>        --------
>        >>> # do something else with x from foo Example
>
>        """
>        pass

Personally I'd be inclined to put long identical examples in the class 
docstring instead of the method, but that may not be appropriate.

I've got an @fmtdoc decorator I use mostly for embedding "constants" in 
docstrings, in my cs.deco module: https://pypi.org/project/cs.deco/, 
thus:

    from cs.deco import fmtdoc

It turns your docstring into a formatted string. You could embed a 
repeated example that way:

    EXAMPLE = r'''
        long example here
    '''


    @fmtdoc
    def foo(...):
        ''' Blah blah.

            Example:
            {EXAMPLE}
        '''

Note - @fmtdoc is only suitable for limited things - use with 
discretion.

Cheers,
Cameron Simpson <cs at cskk.id.au>