ARROW-17320: [Python] Refine pyarrow.parquet API exposure (apache#14096)

milesgranger · web-flow · commit 4d0fbffdf6eb · 2022-09-27T11:11:58.000+02:00
Fixes [ARROW-17320](https://issues.apache.org/jira/browse/ARROW-17320?page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel&focusedCommentId=17577330) Added a deprecation for `_filters_to_expression` -> `filters_to_expression`, in apache@c7fdff3 let me know if that commit should be dropped. :) Authored-by: Miles Granger <miles59923@gmail.com> Signed-off-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>
diff --git a/python/pyarrow/parquet/core.py b/python/pyarrow/parquet/core.py
@@ -21,7 +21,6 @@
 from contextlib import nullcontext
 from functools import partial, reduce
 
-import sys
 import json
 from collections.abc import Collection
 import numpy as np
@@ -45,7 +44,7 @@
 from pyarrow.fs import (LocalFileSystem, FileSystem,
                         _resolve_filesystem_and_path, _ensure_filesystem)
 from pyarrow import filesystem as legacyfs
-from pyarrow.util import guid, _is_path_like, _stringify_path
+from pyarrow.util import guid, _is_path_like, _stringify_path, _deprecate_api
 
 _URI_STRIP_SCHEMES = ('hdfs',)
 
@@ -141,11 +140,27 @@ def _check_filters(filters, check_null_strings=True):
     """
 
 
-def _filters_to_expression(filters):
+def filters_to_expression(filters):
     """
-    Check if filters are well-formed.
+    Check if filters are well-formed and convert to an ``Expression``.
+
+    Parameters
+    ----------
+    filters : List[Tuple] or List[List[Tuple]]
+
+    Notes
+    -----
+    See internal ``pyarrow._DNF_filter_doc`` attribute for more details.
+
+    Examples
+    --------
+
+    >>> filters_to_expression([('foo', '==', 'bar')])
+    <pyarrow.compute.Expression (foo == "bar")>
 
-    See _DNF_filter_doc above for more details.
+    Returns
+    -------
+    pyarrow.compute.Expression
     """
     import pyarrow.dataset as ds
 
@@ -191,6 +206,11 @@ def convert_single_predicate(col, op, val):
     return reduce(operator.or_, disjunction_members)
 
 
+_filters_to_expression = _deprecate_api(
+    "_filters_to_expression", "filters_to_expression",
+    filters_to_expression, "10.0.0", DeprecationWarning)
+
+
 # ----------------------------------------------------------------------
 # Reading a single Parquet file
 
@@ -2343,7 +2363,7 @@ def __init__(self, path_or_paths, filesystem=None, *, filters=None,
 
         self._filter_expression = None
         if filters is not None:
-            self._filter_expression = _filters_to_expression(filters)
+            self._filter_expression = filters_to_expression(filters)
 
         # map old filesystems to new one
         if filesystem is not None:
@@ -3506,6 +3526,31 @@ def read_schema(where, memory_map=False, decryption_properties=None,
         return file.schema.to_arrow_schema()
 
 
-# re-export everything
-# std `from . import *` ignores symbols with leading `_`
-__all__ = list(sys.modules[__name__].__dict__)
+__all__ = (
+    "ColumnChunkMetaData",
+    "ColumnSchema",
+    "FileDecryptionProperties",
+    "FileEncryptionProperties",
+    "FileMetaData",
+    "ParquetDataset",
+    "ParquetDatasetPiece",
+    "ParquetFile",
+    "ParquetLogicalType",
+    "ParquetManifest",
+    "ParquetPartitions",
+    "ParquetReader",
+    "ParquetSchema",
+    "ParquetWriter",
+    "PartitionSet",
+    "RowGroupMetaData",
+    "Statistics",
+    "read_metadata",
+    "read_pandas",
+    "read_schema",
+    "read_table",
+    "write_metadata",
+    "write_table",
+    "write_to_dataset",
+    "_filters_to_expression",
+    "filters_to_expression",
+)
diff --git a/python/pyarrow/util.py b/python/pyarrow/util.py
@@ -39,11 +39,11 @@ def decorator(g):
     return decorator
 
 
-def _deprecate_api(old_name, new_name, api, next_version):
+def _deprecate_api(old_name, new_name, api, next_version, type=FutureWarning):
     msg = _DEPR_MSG.format(old_name, next_version, new_name)
 
     def wrapper(*args, **kwargs):
-        warnings.warn(msg, FutureWarning)
+        warnings.warn(msg, type)
         return api(*args, **kwargs)
     return wrapper
 
