FIX: StataReader: don't buffer entire file into memory unless necessary

Refs #48922

Author: akx

doc/source/whatsnew/v2.0.0.rst

@@ -487,6 +487,7 @@ Performance improvements
 - Memory improvement in :meth:`RangeIndex.sort_values` (:issue:`48801`)
 - Performance improvement in :class:`DataFrameGroupBy` and :class:`SeriesGroupBy` when ``by`` is a categorical type and ``sort=False`` (:issue:`48976`)
 - Performance improvement in :func:`merge` when not merging on the index - the new index will now be :class:`RangeIndex` instead of :class:`Int64Index` (:issue:`49478`)
+- Memory improvement in :class:`StataReader` when reading seekable files (:issue:`48922`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_200.bug_fixes:

pandas/io/stata.py

@@ -23,6 +23,7 @@
     TYPE_CHECKING,
     Any,
     AnyStr,
+    Callable,
     Final,
     Hashable,
     Sequence,
@@ -1149,6 +1150,7 @@ def __init__(
         self._encoding = ""
         self._chunksize = chunksize
         self._using_iterator = False
+        self._entered = False
         if self._chunksize is None:
             self._chunksize = 1
         elif not isinstance(chunksize, int) or chunksize <= 0:
@@ -1158,6 +1160,7 @@ def __init__(
         # NB: _path_or_buf is mistyped on purpose, since the alternative is to placate
         #     mypy by having an assert before every read.
         self._path_or_buf: IO[bytes] = None  # type: ignore[assignment]
+        self._close_file: Callable[[], None] | None = None
         self._has_string_data = False
         self._missing_values = False
         self._can_read_value_labels = False
@@ -1180,21 +1183,36 @@ def _open_file(self) -> None:
         """
         Open the file (with compression options, etc.), and read header information.
         """
-        with get_handle(
+        if not self._entered:
+            warnings.warn(
+                "StataReader is being used without using a context manager. "
+                "Using StataReader as a context manager is the only supported method.",
+                ResourceWarning,
+                stacklevel=4,
+            )
+        handles = get_handle(
             self._original_path_or_buf,
             "rb",
             storage_options=self._storage_options,
             is_text=False,
             compression=self._compression,
-        ) as handles:
-            # Copy to BytesIO, and ensure no encoding
-            self._path_or_buf = BytesIO(handles.handle.read())
+        )
+        if hasattr(handles.handle, "seekable") and handles.handle.seekable():
+            # If the handle is directly seekable, use it without an extra copy.
+            self._path_or_buf = handles.handle
+            self._close_file = handles.close
+        else:
+            # Copy to memory, and ensure no encoding.
+            with handles:
+                self._path_or_buf = BytesIO(handles.handle.read())
+            self._close_file = self._path_or_buf.close
 
         self._read_header()
         self._setup_dtype()
 
     def __enter__(self) -> StataReader:
         """enter context manager"""
+        self._entered = True
         return self
 
     def __exit__(
@@ -1203,12 +1221,26 @@ def __exit__(
         exc_value: BaseException | None,
         traceback: TracebackType | None,
     ) -> None:
-        """exit context manager"""
-        self.close()
+        if self._close_file:
+            self._close_file()
 
     def close(self) -> None:
-        """close the handle if its open"""
-        self._path_or_buf.close()
+        """Close the handle if its open.
+
+        .. deprecated: 1.6.0
+
+           The close method is not part of the public API.
+           The only supported way to use StataReader is to use it as a context manager.
+        """
+        warnings.warn(
+            "The StataReader.close() method is not part of the public API and "
+            "may be removed in a future version without notice. "
+            "Using StataReader as a context manager is the only supported method.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        if self._close_file:
+            self._close_file()
 
     def _set_encoding(self) -> None:
         """

pandas/tests/io/test_stata.py

@@ -1839,6 +1839,38 @@ def test_backward_compat(version, datapath):
     tm.assert_frame_equal(old_dta, expected, check_dtype=False)
 
 
+def test_direct_read(datapath, monkeypatch):
+    file_path = datapath("io", "data", "stata", "stata-compat-118.dta")
+
+    # Test that opening a file path doesn't buffer the file.
+    with StataReader(file_path) as reader:
+        # Must not have been buffered to memory
+        assert not reader.read().empty
+        assert not isinstance(reader._path_or_buf, io.BytesIO)
+
+    # Test that we use a given fp exactly, if possible.
+    with open(file_path, "rb") as fp:
+        with StataReader(fp) as reader:
+            assert not reader.read().empty
+            assert reader._path_or_buf is fp
+
+    # Test that we use a given BytesIO exactly, if possible.
+    with open(file_path, "rb") as fp:
+        with io.BytesIO(fp.read()) as bio:
+            with StataReader(bio) as reader:
+                assert not reader.read().empty
+                assert reader._path_or_buf is bio
+
+
+def test_statareader_warns_when_used_without_context(datapath):
+    file_path = datapath("io", "data", "stata", "stata-compat-118.dta")
+    with tm.assert_produces_warning(ResourceWarning):
+        sr = StataReader(file_path)
+        sr.read()
+    with tm.assert_produces_warning(FutureWarning):
+        sr.close()
+
+
 @pytest.mark.parametrize("version", [114, 117, 118, 119, None])
 @pytest.mark.parametrize("use_dict", [True, False])
 @pytest.mark.parametrize("infer", [True, False])