Repository: nltk/nltk

Issue:
usage function: repair or drop?
Do we need to support this usage method?
https://github.com/nltk/nltk/blob/develop/nltk/util.py#L40

Here's a discussion of it's shortcomings:
https://github.com/nltk/nltk/pull/2801#discussion_r706567025


Discussion:
My preference is to drop anything non-essential when it is consuming scarce human resources to maintain.
I prefer dropping too. Especially since it's not used in actual source code, and since python has a builtin `help()` function which seems super similar!
`usage` does seem like it's just a weaker `help()`. As far as I'm concerned, we can drop it.
It might be "proper" to change it to e.g.
```python
def usage(obj, selfname="self"):
    warnings.warn("nltk.usage(obj) is deprecated; use help(obj).", PendingDeprecationWarning)
    help(obj)
```
for the time being. 

However, do note that the warning will only be displayed if Python is ran with e.g. a `-Wd` flag to show warnings.
Then in some future version, we'll just remove the function all-together.

Resolving patch:
diff --git a/nltk/util.py b/nltk/util.py
--- a/nltk/util.py
+++ b/nltk/util.py
@@ -30,13 +30,14 @@
 )
 
 from nltk.collections import *
-from nltk.internals import raise_unorderable_types, slice_bounds
+from nltk.internals import deprecated, raise_unorderable_types, slice_bounds
 
 ######################################################################
 # Short usage message
 ######################################################################
 
 
+@deprecated("Use help(obj) instead.")
 def usage(obj):
     str(obj)  # In case it's lazy, this will load it.
 


Test patch:
diff --git a/nltk/test/classify.doctest b/nltk/test/classify.doctest
--- a/nltk/test/classify.doctest
+++ b/nltk/test/classify.doctest
@@ -11,16 +11,13 @@
 Classifiers label tokens with category labels (or *class labels*).
 Typically, labels are represented with strings (such as ``"health"``
 or ``"sports"``.  In NLTK, classifiers are defined using classes that
-implement the `ClassifyI` interface:
+implement the `ClassifierI` interface, which supports the following operations:
 
-    >>> import nltk
-    >>> nltk.usage(nltk.classify.ClassifierI)
-    ClassifierI supports the following operations:
-      - self.classify(featureset)
-      - self.classify_many(featuresets)
-      - self.labels()
-      - self.prob_classify(featureset)
-      - self.prob_classify_many(featuresets)
+- self.classify(featureset)
+- self.classify_many(featuresets)
+- self.labels()
+- self.prob_classify(featureset)
+- self.prob_classify_many(featuresets)
 
 NLTK defines several classifier classes:
 
@@ -42,6 +39,7 @@ We define a very simple training corpus with 3 binary features: ['a',
 that the correct answers can be calculated analytically (although we
 haven't done this yet for all tests).
 
+    >>> import nltk
     >>> train = [
     ...     (dict(a=1,b=1,c=1), 'y'),
     ...     (dict(a=1,b=1,c=1), 'x'),
diff --git a/nltk/test/unit/test_util.py b/nltk/test/unit/test_util.py
--- a/nltk/test/unit/test_util.py
+++ b/nltk/test/unit/test_util.py
@@ -1,58 +1,6 @@
 import pytest
 
-from nltk.util import everygrams, usage
-
-
-def test_usage_with_self(capsys):
-    class MyClass:
-        def kwargs(self, a=1):
-            ...
-
-        def no_args(self):
-            ...
-
-        def pos_args(self, a, b):
-            ...
-
-        def pos_args_and_kwargs(self, a, b, c=1):
-            ...
-
-    usage(MyClass)
-
-    captured = capsys.readouterr()
-    assert captured.out == (
-        "MyClass supports the following operations:\n"
-        "  - self.kwargs(a=1)\n"
-        "  - self.no_args()\n"
-        "  - self.pos_args(a, b)\n"
-        "  - self.pos_args_and_kwargs(a, b, c=1)\n"
-    )
-
-
-def test_usage_with_cls(capsys):
-    class MyClass:
-        @classmethod
-        def clsmethod(cls):
-            ...
-
-        @classmethod
-        def clsmethod_with_args(cls, a, b, c=1):
-            ...
-
-    usage(MyClass)
-
-    captured = capsys.readouterr()
-    assert captured.out == (
-        "MyClass supports the following operations:\n"
-        "  - cls.clsmethod()\n"
-        "  - cls.clsmethod_with_args(a, b, c=1)\n"
-    )
-
-
-def test_usage_on_builtin():
-    # just check the func passes, since
-    # builtins change each python version
-    usage(dict)
+from nltk.util import everygrams
 
 
 @pytest.fixture