DOC: Note that StataReaders are context managers

Author: akx

doc/source/user_guide/io.rst

@@ -6033,6 +6033,14 @@ values will have ``object`` data type.
    ``int64`` for all integer types and ``float64`` for floating point data.  By default,
    the Stata data types are preserved when importing.
 
+.. note::
+
+   All :class:`~pandas.io.stata.StataReader` objects, whether created by :func:`~pandas.read_stata`
+   (when using ``iterator=True`` or ``chunksize``) or instantiated by hand, must be used as context
+   managers (e.g. the ``with`` statement).
+   While the :meth:`~pandas.io.stata.StataReader.close` method is available, its use is unsupported.
+   It is not part of the public API and will be removed in with future without warning.
+
 .. ipython:: python
    :suppress:
 

pandas/io/stata.py

@@ -183,10 +183,10 @@
 >>> df = pd.DataFrame(values, columns=["i"])  # doctest: +SKIP
 >>> df.to_stata('filename.dta')  # doctest: +SKIP
 
->>> itr = pd.read_stata('filename.dta', chunksize=10000)  # doctest: +SKIP
->>> for chunk in itr:
-...    # Operate on a single chunk, e.g., chunk.mean()
-...    pass  # doctest: +SKIP
+>>> with pd.read_stata('filename.dta', chunksize=10000) as itr: # doctest: +SKIP
+>>>     for chunk in itr:
+...         # Operate on a single chunk, e.g., chunk.mean()
+...         pass  # doctest: +SKIP
 """
 
 _read_method_doc = f"""\