DOC: Document/ Deprecate functions exposed in "numpy" namespace #13222

kritisingh1 · 2019-03-30T17:49:09Z

Related to #12385
The checklist for future work on this PR is as follows:
Deprecate -

'mafromtxt`
'ndfromtxt'

@rgommers Please review and let me know the required changes. Thanks a lot!

mattip · 2019-03-30T21:00:10Z

Please remove from your checklist items that already appear in #13214.

mattip · 2019-03-31T06:58:26Z

xref #9312 which began documenting show_config but still needs work.

kritisingh1 · 2019-04-03T17:30:56Z

I have added the warning messages for the function ndfromtxt and mafromtxt and also edited the docstrings. I am not sure where equivalent functions for int_asbuffer exists and would be grateful for pointers on it. @mattip

seberg · 2019-04-03T17:54:13Z

@kritisingh1 int_asbuffer is defined in multiarray on the C side. Sometimes a nice way to find things can be to use git grep "int_asbuffer", etc. The definition is in numpy/core/src/multiarray/multiarraymodule.c.

kritisingh1 · 2019-04-03T18:50:45Z

@seberg yeah I was using git grep "int_asbuffer" but the function name was asbuffer so it didn't turn up in the results. I will take care of this from next time.

mattip · 2019-04-03T18:55:38Z

the interesting part will be determining what its docstring should be so we can put a deprecation notice in it. The docstring should be added to numpy/core/_add_newdocs.py, like

add_newdoc('numpy.core.multiarray', 'int_asbuffer', '''
<your text here>
.. deprecated:: 1.17
     Deprecated, use <your text here> instead
 ''')

Play with the function a bit, read the C code, and ask here or on the mailing list if you have a hard time coming up with some text

numpy/lib/npyio.py

mattip · 2019-04-03T18:58:52Z

numpy/lib/npyio.py

@@ -2235,13 +2237,18 @@ def ndfromtxt(fname, **kwargs):

    """
    kwargs['usemask'] = False
+    warnings.warn(
+        "np.ndfromtxt is deprecated",
+        DeprecationWarning, stacklevel=2)


Needs a comment above the warning with the date, version, gh-issue format

Should also recommend a replacement, perhaps `ndfromtxt` is a deprecated alias of `genfromtxt`, prefer the latter

mattip · 2019-04-03T19:00:31Z

Please update the checklist at the top of the PR with the additional items, and mark off the ones that are modified in the PR

kritisingh1 · 2019-04-05T15:01:45Z

@mattip I'm figuring out what text to add to the numpy/core/_add_newdocs.py . Meanwhile, I would be grateful if you could help me in fixing the failing tests. By the logs, the tests which are calling safe_eval, ndfromtxt and mafromtxt and are encountering warnings.warn(..) in the respective functions are failing which should not happen because they are just warnings. I'm not sure why this is happening. Thanks!

mattip · 2019-04-05T15:09:38Z

Look at the with warnings.* constructs in other tests, they are used to filter known warnings. Testing turns unexpected warnings into errors.

mattip · 2019-04-05T15:10:35Z

You should be running at least the basic tests locally, so you can avoid too much CI churn python runtests.py

kritisingh1 · 2019-04-09T04:33:59Z

@mattip the tests are failing despite adding the with warnings.* constructor for every mention of the deprecated functions. Is there anything I am missing?
Also, I looked at other functions which were deprecated in npyio.py and could see that the alternative to those functions were used in the tests. For example. pickle.loads in place of loads. So, as @rgommers suggested, I can instead modify the tests which use ndfromtxt and mafromtxt to use genfromtxt with the required flags as parameters. Please let me know what should be the better way to go ahead. Thanks!

mattip · 2019-04-09T07:21:07Z

You should add a test to numpy/core/tests/test_deprecated.py (or numpy/ma/tests/test_deprecations.py or numpy/linalg/tests/test_deprecations.py), for each deprecation. Then replace the deprecated function with its alternative inside numpy itself, so any function that used to call the deprecated function now should not be emitting warnings.

tests are failing despite adding the with warnings.* construct

It is hard to tell without seeing your changes. Note test_deprecations uses self.assert_deprecated

seberg · 2019-06-03T15:34:25Z

numpy/lib/utils.py

@@ -1136,7 +1139,6 @@ def safe_eval(source):
    """
    # Local import to speed up numpy's import time.
    import ast
-


I think you can put this deprecation back, but have to replace all use-cases with the ast.literal_eval(source) call that this does. Maybe the DeprecationWarning should mention to use ast.literal_eval instead.

@seberg , can I try deprecating self_eval in a different pull request altogether, if that is alright?

Yes of course, but should probably remove the documentation change as well for now then.

eric-wieser · 2019-06-07T07:53:12Z

numpy/lib/npyio.py

@@ -2225,6 +2225,9 @@ def ndfromtxt(fname, **kwargs):
    """
    Load ASCII data stored in a file and return it as a single array.

+    .. deprecated:: 1.17
+        np.ndfromtxt is deprecated


Again, mention the replacement here, possibly with a few more words than in the DeprecationWarning.

`ndfromtxt` is a deprecated alias of `genfromtxt` which overwrites the ``usemask`` argument with `False` even when explicitly called as ``ndfromtxt(..., usemask=True)``. Use `genfromtxt` instead.

kritisingh1 · 2019-06-07T18:12:51Z

@mattip I will open separate PRs for addressing the issue #12385 as and when I complete the work involved for documenting/deprecating different functions. Meanwhile, please let me know if there is anything else that needs to be done for deprecating the functions in the above checklist.

mattip · 2019-06-10T17:34:20Z

Thanks @kritisingh1

DOC: Document/ Deprecate functions exposed in numpy namespace

91a93ad

mattip mentioned this pull request Mar 30, 2019

DOC: add missing routines to reference guide #13214

Closed

11 tasks

mattip added the component: documentation label Mar 31, 2019

kritisingh1 force-pushed the patch1 branch from ce10c4f to 89c9a0b Compare April 3, 2019 17:32

kritisingh1 force-pushed the patch1 branch from 89c9a0b to 23ab3e6 Compare April 3, 2019 18:54

mattip reviewed Apr 3, 2019

View reviewed changes

Issue deprecation warnings

4c35a85

kritisingh1 force-pushed the patch1 branch from 23ab3e6 to 4c35a85 Compare April 5, 2019 14:02

mattip added the Outreachy 2019 label Apr 8, 2019

Fix tests

67b53e1

seberg self-requested a review May 28, 2019 16:41

seberg reviewed Jun 3, 2019

View reviewed changes

eric-wieser reviewed Jun 7, 2019

View reviewed changes

kritisingh1 force-pushed the patch1 branch from f7d7a89 to f554008 Compare June 7, 2019 16:23

fix tests

13561bd

kritisingh1 force-pushed the patch1 branch from f554008 to 13561bd Compare June 7, 2019 17:01

mattip merged commit 6472813 into numpy:master Jun 10, 2019

Uh oh!

DOC: Document/ Deprecate functions exposed in "numpy" namespace #13222

DOC: Document/ Deprecate functions exposed in "numpy" namespace #13222

Uh oh!

Conversation

kritisingh1 commented Mar 30, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattip commented Mar 30, 2019

Uh oh!

mattip commented Mar 31, 2019

Uh oh!

kritisingh1 commented Apr 3, 2019

Uh oh!

seberg commented Apr 3, 2019

Uh oh!

kritisingh1 commented Apr 3, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattip commented Apr 3, 2019

Uh oh!

Uh oh!

mattip Apr 3, 2019

Choose a reason for hiding this comment

Uh oh!

eric-wieser Jun 7, 2019

Choose a reason for hiding this comment

Uh oh!

mattip commented Apr 3, 2019

Uh oh!

kritisingh1 commented Apr 5, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattip commented Apr 5, 2019

Uh oh!

mattip commented Apr 5, 2019

Uh oh!

kritisingh1 commented Apr 9, 2019

Uh oh!

mattip commented Apr 9, 2019

Uh oh!

seberg Jun 3, 2019

Choose a reason for hiding this comment

Uh oh!

kritisingh1 Jun 7, 2019

Choose a reason for hiding this comment

Uh oh!

seberg Jun 7, 2019

Choose a reason for hiding this comment

Uh oh!

kritisingh1 Jun 7, 2019

Choose a reason for hiding this comment

Uh oh!

eric-wieser Jun 7, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kritisingh1 commented Jun 7, 2019

Uh oh!

mattip commented Jun 10, 2019

Uh oh!

Uh oh!

kritisingh1 commented Mar 30, 2019 •

edited

Loading

kritisingh1 commented Apr 3, 2019 •

edited

Loading

kritisingh1 commented Apr 5, 2019 •

edited

Loading

eric-wieser Jun 7, 2019 •

edited

Loading