Document numpy.lib.stride_tricks.as_strided

[anntzer]

As far as I can tell as_strided (which can be rather useful, even though it is involved) is documented nowhere -- it doesn't even appear in the general index, probably because it isn't listed in stride_tricks.__all__.

[rkern]

Intentionally! It's dangerous! It was just low-level plumbing to help implement broadcast_arrays().

[anntzer]

Fair enough. FWIW, it is mentioned as a "See also" in the docs of ndarray.strides though.

[argriffing]

In https://github.com/numpy/numpy/blob/master/numpy/lib/stride_tricks.py the two functions in __all__ (broadcast_to and 'broadcast_arrays) are not underscored, but the helper functions have the underscore prefix. Except as_strided. Should it be changed to have an underscore prefix? Or is its absence from __all__ enough to mark it as not part of the public interface?

[insertinterestingnamehere]

It'd be great if we could not move or deprecate that. There's plenty of code that relies on it out there (e.g. the various rolling window idioms floating around, among other things). IMHO it makes more sense to add it to the docs and say explicitly that it's dangerous and ought not to be used when another option is available.

[shoyer]

I agree with @insertinterestingnamehere that it would be better to add it to the docs with lots of warnings and disclaimers. For what it's worth, it's definitely part of the implicit public API at this point -- there is plenty of code that relies on it. Note that as of NumPy 1.10 we don't even rely on as_strided for implementing broadcast_array.

[rgommers]

I agree as well - add to the docs with a clear "this is dangerous" at the top of the docstring.

Or is its absence from __all__ enough to mark it as not part of the public interface?

Maybe that was the idea, but it doesn't work so well in practice. Same for stuff that's not in the docs.

[mrkwjc]

I'd like also vote for leaving and documenting as_strided. This is very useful function.

[mattip]

Documented

[endolith]

There's plenty of code that relies on it out there (e.g. the various rolling window idioms floating around, among other things).

(I was going to ask about making official functions for this and then found #7753, so linking that from here for anyone else who is looking.)