optional tag for sage versions (doctest)

[Vincent Delecroix]

Dear all,

I do maintain Python libraries that depend on Sage and uses the
Sage doctest framework. I do my best so that the libraries
install and work on older versions of Sage. However, some features
are only working with recent enough versions of Sage. But I still
want them to pass the test suite with older Sage versions.

I thought that having a tag looking like

sage: my_computation() # optional: sage >= 9.0

would help me a lot.

- Any alternative suggestion?

- Can I do that with the current doctest framework? It would
be nice to be able to specify optional tags on the fly.

- Any vote pro or against such a tag? I think that if we go
for it, everybody should agree so that it becomes a standard
and gets specified in the SageMath documentation.

Of course such a tag would be useless for the Sage library itself.

Best
Vincent

[David Roe]

On Fri, Jan 10, 2020 at 1:16 PM Vincent Delecroix <20100.d...@gmail.com> wrote:

Dear all,

I do maintain Python libraries that depend on Sage and uses the
Sage doctest framework. I do my best so that the libraries
install and work on older versions of Sage. However, some features
are only working with recent enough versions of Sage. But I still
want them to pass the test suite with older Sage versions.

I thought that having a tag looking like

   sage: my_computation()   # optional: sage >= 9.0

would help me a lot.

- Any alternative suggestion?

- Can I do that with the current doctest framework? It would
   be nice to be able to specify optional tags on the fly.

I'm not sure what you mean by "on the fly".  For the relevant code, see the `parse_optional_tags` function in sage/doctest/parsing.py and the parse method of SageDocTestParser in the same file.

David

 

- Any vote pro or against such a tag? I think that if we go
   for it, everybody should agree so that it becomes a standard
   and gets specified in the SageMath documentation. 

Of course such a tag would be useless for the Sage library itself.

Best
Vincent

--
You received this message because you are subscribed to the Google Groups "sage-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/103a321e-6c58-f8cc-a1e3-cf1e426ec551%40gmail.com.

[Michael Orlitzky]

On 1/10/20 2:16 PM, Vincent Delecroix wrote:
>
> - Any alternative suggestion?

This comes up a lot. The ideal answer is: use a preprocessor directive
to compile out the unsupported tests. But naturally that doesn't work so
well in an interpreted language.

One workaround is to maintain separate branches of your code, for
example a 1.x branch that supports sage < 9.0, and a 2.x branch that
supports sage >= 9.0. So long as the number of distinct version ranges
you support is small, this isn't *too* annoying.

> - Any vote pro or against such a tag? I think that if we go
> for it, everybody should agree so that it becomes a standard
> and gets specified in the SageMath documentation.
>
> Of course such a tag would be useless for the Sage library itself.
>

All the other solutions I'm aware of involve runtime testing of some
kind. Even if you detect the sage version at "build time," you wind up
with a runtime variable test like

if sage_version >= 9.0:
some_function.__doc__ += "a test for sage-9.x"

And that's more or less what the "# optional" tag gives you anyway.

Since the doctests are supposed to serve foremost as documentation, my
first impression is that a dedicated tag would be appropriate here. It's
consistent with what we already do, and it helps the reader understand
what's going on without making the source code horrendous.

[E. Madison Bray]

On Fri, Jan 10, 2020 at 7:16 PM Vincent Delecroix

I think it's a reasonable request, although I think doctests are not a
great format for this kind of test that is very system-specific. I
don't know if I would use # optional: for this, but maybe a new
directive such as "# version".

Feel free to open a ticket.