ARROW-8232: [Python] Deprecate pyarrow.open_stream and pyarrow.open_f…

…ile APIs in favor of accessing via pyarrow.ipc namespace

In my opinion, these APIs in the top level namespace are unclear and possibly misleading. We should encourage people to use the `pyarrow.ipc` namespace.

Closes #6757 from wesm/ARROW-8232

Authored-by: Wes McKinney <wesm+git@apache.org>
Signed-off-by: Antoine Pitrou <antoine@python.org>

python/pyarrow/__init__.py

@@ -167,8 +167,6 @@ def parse_git(root, **kwargs):
                          read_message, read_record_batch, read_schema,
                          read_tensor, write_tensor,
                          get_record_batch_size, get_tensor_size,
-                         open_stream,
-                         open_file,
                          serialize_pandas, deserialize_pandas)
 import pyarrow.ipc as ipc
 
@@ -201,6 +199,13 @@ def _plasma_store_entry_point():
 
 from pyarrow.util import _deprecate_api  # noqa
 
+
+open_stream = _deprecate_api("open_stream", "ipc.open_stream",
+                             ipc.open_stream, "0.17.0")
+
+open_file = _deprecate_api("open_file", "ipc.open_file", ipc.open_file,
+                           "0.17.0")
+
 # ----------------------------------------------------------------------
 # Returning absolute path to the pyarrow include directory (if bundled, e.g. in
 # wheels)

python/pyarrow/tests/test_ipc.py

@@ -715,6 +715,23 @@ def test_schema_serialization_with_metadata():
     assert recons_schema[1].metadata == field_metadata
 
 
+def test_deprecated_pyarrow_ns_apis():
+    table = pa.table([pa.array([1, 2, 3, 4])], names=['a'])
+    sink = pa.BufferOutputStream()
+    with pa.RecordBatchStreamWriter(sink, table.schema) as writer:
+        writer.write(table)
+
+    with pytest.warns(FutureWarning,
+                      match="please use pyarrow.ipc.open_stream"):
+        pa.open_stream(sink.getvalue())
+
+    sink = pa.BufferOutputStream()
+    with pa.RecordBatchFileWriter(sink, table.schema) as writer:
+        writer.write(table)
+    with pytest.warns(FutureWarning, match="please use pyarrow.ipc.open_file"):
+        pa.open_file(sink.getvalue())
+
+
 def write_file(batch, sink):
     with pa.RecordBatchFileWriter(sink, batch.schema) as writer:
         writer.write_batch(batch)

python/pyarrow/util.py

@@ -32,12 +32,12 @@ def decorator(g):
 
 
 def _deprecate_api(old_name, new_name, api, next_version):
-    msg = ('pyarrow.{} is deprecated as of {}, please use {} instead'
+    msg = ('pyarrow.{} is deprecated as of {}, please use pyarrow.{} instead'
            .format(old_name, next_version, new_name))
 
     def wrapper(*args, **kwargs):
         warnings.warn(msg, FutureWarning)
-        return api(*args)
+        return api(*args, **kwargs)
     return wrapper