Mailing List Archive

On Wed, Jan 12, 2022 at 9:11 AM Sebastian Luque <spluque@gmail.com> wrote:
>
> Hello,
>
> I am searching for a mechanism for sharing data across Examples sections
> in docstrings within a class. For instance:

This seems like trying to cram too much information into the
docstring, but oh well... do what you will.

I'd recommend a decorator. The easiest way would probably be to have a
placeholder of some sort in the actual docstring, and in the
decorator, you replace __doc__ with the modified form.

To do what you're asking for, your decorator would either need to go
through every method in the class and mutate its docstring (in which
case you'd decorate the class), or mutate the docstring of exactly one
function (in which case you'd decorate that method).

ChrisA
--
https://mail.python.org/mailman/listinfo/python-list

On 11Jan2022 16:09, Sebastian Luque <spluque@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@cskk.id.au>
--
https://mail.python.org/mailman/listinfo/python-list

On Wed, 12 Jan 2022 09:28:16 +1100,
Cameron Simpson <cs@cskk.id.au> wrote:

[...]

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

Good point, and perhaps it's best to put a comprehensive example in the
class docstring, rather than scatter it across the methods' docstrings.
The situation is one in which the methods are typically (but not always)
intended to be used as part of a pipeline of operations; e.g. Foo.foo()
would almost always be used before Foo.bar().

Thanks,
--
Seb
--
https://mail.python.org/mailman/listinfo/python-list

Hello,

I understand that you want to share data across examples (docstrings)
because you are running doctest to validate them (and test).

The doctest implementation evaluates each docstring separately without
sharing the context so the short answer is "no".

This is a limitation of doctest but it is not the only testing engine
that you can use.

You could use "byexample" ( https://byexamples.github.io ) which it
shares the context by default.

byexample has more features and fixes other caveats of doctests, but
don't take me too serious, I have a natural bias because I'm its author.

If you want to go with byexample, you may want to try its "doctest
compatibility mode" first so you don't have to rewrite any test.
( https://byexamples.github.io/byexample/recipes/python-doctest )

Let me know if it is useful for you.

Thanks,
Martin.

On Tue, Jan 11, 2022 at 04:09:57PM -0600, Sebastian Luque wrote:
>Hello,
>
>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
>
>
>Thanks,
>--
>Seb
>--
>https://mail.python.org/mailman/listinfo/python-list
--
https://mail.python.org/mailman/listinfo/python-list