CLN: Add annotations

Add annotations
Fix error message
Add backward compatible reference
Update what's new

Author: bashtage

doc/source/whatsnew/index.rst

@@ -10,6 +10,14 @@ This is the list of changes to pandas between each release. For full details,
 see the commit logs at http://github.com/pandas-dev/pandas. For install and
 upgrade instructions, see :ref:`install`.
 
+Version 1.1
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   v1.1.0
+
 Version 1.0
 -----------
 

doc/source/whatsnew/v1.0.0.rst

@@ -224,7 +224,7 @@ Other enhancements
 - :meth:`DataFrame.sort_values` and :meth:`Series.sort_values` have gained ``ignore_index`` keyword to be able to reset index after sorting (:issue:`30114`)
 - :meth:`DataFrame.sort_index` and :meth:`Series.sort_index` have gained ``ignore_index`` keyword to reset index (:issue:`30114`)
 - :meth:`DataFrame.drop_duplicates` has gained ``ignore_index`` keyword to reset index (:issue:`30114`)
-- Added new writer for exporting Stata dta files in version 118 and 119, ``StataWriterUTF8``.  This format supports exporting strings containing Unicode characters (:issue:`23573`)
+- Added new writer for exporting Stata dta files in version 118, ``StataWriter118``.  This format supports exporting strings containing Unicode characters (:issue:`23573`)
 - :meth:`Series.map` now accepts ``collections.abc.Mapping`` subclasses as a mapper (:issue:`29733`)
 - The ``pandas.datetime`` class is now deprecated. Import from ``datetime`` instead (:issue:`30296`)
 - Added an experimental :attr:`~DataFrame.attrs` for storing global metadata about a dataset (:issue:`29062`)

doc/source/whatsnew/v1.1.0.rst

@@ -0,0 +1,16 @@
+.. _whatsnew_110:
+
+What's new in 1.1.0 (??)
+------------------------
+
+Enhancements
+~~~~~~~~~~~~
+
+Other enhancements
+^^^^^^^^^^^^^^^^^^
+
+- Added new writer for exporting Stata dta files in version 119, ``StataWriterUTF8``.  This supersedes ``StataWriter118`` which was introduced in 1.0 (:issue:`30959`)
+
+Deprecations
+~~~~~~~~~~~~
+- ``StataWriter118`` is deprecated in favor of ``StataWriterUTF8`` which writes both 118 and 119 format files (:issue:`30959`).

pandas/core/frame.py

@@ -1945,7 +1945,7 @@ def to_stata(
         """
         kwargs = {}
         if version not in (114, 117, 118, 119, None):
-            raise ValueError("Only formats 114, 117 and 118 are supported.")
+            raise ValueError("Only formats 114, 117, 118 and 119 are supported.")
         if version == 114:
             if convert_strl is not None:
                 raise ValueError("strl is not supported in format 114")

pandas/io/stata.py

@@ -15,15 +15,16 @@
 import os
 import struct
 import sys
-from typing import Any
+from typing import Any, Dict, Hashable, Optional, Sequence
 import warnings
 
 from dateutil.relativedelta import relativedelta
 import numpy as np
 
 from pandas._libs.lib import infer_dtype
 from pandas._libs.writers import max_len_string_array
-from pandas.util._decorators import Appender
+from pandas._typing import FilePathOrBuffer
+from pandas.util._decorators import Appender, deprecate
 
 from pandas.core.dtypes.common import (
     ensure_object,
@@ -2696,7 +2697,7 @@ def _convert_key(self, key):
 
     def generate_table(self):
         """
-        Generates the GSO lookup table for the DataFRame
+        Generates the GSO lookup table for the DataFrame
 
         Returns
         -------
@@ -3229,6 +3230,8 @@ class StataWriterUTF8(StataWriter117):
         the version. 118 is used if data.shape[1] <= 32767, and 119 is used
         for storing larger DataFrames.
 
+        .. versionadded:: 1.1.0
+
     Returns
     -------
     StataWriterUTF8
@@ -3268,16 +3271,16 @@ class StataWriterUTF8(StataWriter117):
 
     def __init__(
         self,
-        fname,
-        data,
-        convert_dates=None,
-        write_index=True,
-        byteorder=None,
-        time_stamp=None,
-        data_label=None,
-        variable_labels=None,
-        convert_strl=None,
-        version=None,
+        fname: FilePathOrBuffer,
+        data: DataFrame,
+        convert_dates: Optional[Dict[Hashable, str]] = None,
+        write_index: bool = True,
+        byteorder: Optional[str] = None,
+        time_stamp: Optional[datetime.datetime] = None,
+        data_label: Optional[str] = None,
+        variable_labels: Optional[Dict[Hashable, str]] = None,
+        convert_strl: Optional[Sequence[Hashable]] = None,
+        version: Optional[int] = None,
     ):
         if version is None:
             version = 118 if data.shape[1] <= 32767 else 119
@@ -3297,7 +3300,7 @@ def __init__(
         # Override version set in StataWriter117 init
         self._dta_version = version
 
-    def _validate_variable_name(self, name):
+    def _validate_variable_name(self, name: str):
         """
         Validate variable names for Stata export.
 
@@ -3314,7 +3317,7 @@ def _validate_variable_name(self, name):
 
         Notes
         -----
-        Stata 118 support most unicode characters. The only limatation is in
+        Stata 118 support most unicode characters. The only limitation is in
         the ascii range where the characters supported are a-z, A-Z, 0-9 and _.
         """
         # High code points appear to be acceptable
@@ -3329,3 +3332,6 @@ def _validate_variable_name(self, name):
                 name = name.replace(c, "_")
 
         return name
+
+
+StataWriter118 = deprecate("pandas.io.stata.StataWriterUTF8", StataWriterUTF8, "2.0.0")