pllim · Dec 1, 2016 · Jun 28, 2016 · Nov 21, 2016 · Nov 21, 2016 · Nov 23, 2016
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -183,6 +183,13 @@ API Changes
     - Removed ``startColumn`` and ``endColumn`` arguments to the ``FITS_record``
       constructor.
 
+  - The ``clobber`` argument in FITS writers has been renamed to
+    ``overwrite``. This change affects the following functions and
+    methods: ``tabledump``, ``writeto``, ``Header.tofile``,
+    ``Header.totextfile``, ``_BaseDiff.report``,
+    ``_BaseHDU.overwrite``, ``BinTableHDU.dump`` and
+    ``HDUList.writeto``. [#5171]
+
 - ``astropy.io.misc``
 
 - ``astropy.io.registry``
@@ -225,6 +232,9 @@ API Changes
 
 - ``astropy.vo``
 
+  - The ``clobber`` argument in ``VOSDatabase.to_json()`` has been
+    renamed to ``overwrite``. [#5171]
+
 - ``astropy.wcs``
 
   - ``wcs.rotateCD()`` was deprecated without a replacement. [#5240]

diff --git a/astropy/io/fits/convenience.py b/astropy/io/fits/convenience.py
@@ -73,6 +73,7 @@
 from ...extern import six
 from ...extern.six import string_types
 from ...utils.exceptions import AstropyUserWarning
+from ...utils.decorators import deprecated_renamed_argument
 
 
 __all__ = ['getheader', 'getdata', 'getval', 'setval', 'delval', 'writeto',
@@ -382,8 +383,9 @@ def delval(filename, keyword, *args, **kwargs):
         hdulist.close(closed=closed)
 
 
+@deprecated_renamed_argument('clobber', 'overwrite', '1.3')
 def writeto(filename, data, header=None, output_verify='exception',
-            clobber=False, checksum=False):
+            overwrite=False, checksum=False):
     """
     Create a new FITS file using the supplied data/header.
 
@@ -408,9 +410,13 @@ def writeto(filename, data, header=None, output_verify='exception',
         ``+warn``, or ``+exception" (e.g. ``"fix+warn"``).  See :ref:`verify`
         for more info.
 
-    clobber : bool, optional
-        If `True`, and if filename already exists, it will overwrite
-        the file.  Default is `False`.
+    overwrite : bool, optional
+        If ``True``, overwrite the output file if it exists. Raises an
+        ``OSError`` (``IOError`` for Python 2) if ``False`` and the
+        output file exists. Default is ``False``.
+
+        .. versionchanged:: 1.3
+           ``overwrite`` replaces the deprecated ``clobber`` argument.
 
     checksum : bool, optional
         If `True`, adds both ``DATASUM`` and ``CHECKSUM`` cards to the
@@ -420,7 +426,7 @@ def writeto(filename, data, header=None, output_verify='exception',
     hdu = _makehdu(data, header)
     if hdu.is_image and not isinstance(hdu, PrimaryHDU):
         hdu = PrimaryHDU(data, header=header)
-    hdu.writeto(filename, clobber=clobber, output_verify=output_verify,
+    hdu.writeto(filename, overwrite=overwrite, output_verify=output_verify,
                 checksum=checksum)
 
 
@@ -688,8 +694,9 @@ def info(filename, output=None, **kwargs):
     return ret
 
 
+@deprecated_renamed_argument('clobber', 'overwrite', '1.3')
 def tabledump(filename, datafile=None, cdfile=None, hfile=None, ext=1,
-              clobber=False):
+              overwrite=False):
     """
     Dump a table HDU to a file in ASCII format.  The table may be
     dumped in three separate files, one containing column definitions,
@@ -717,8 +724,13 @@ def tabledump(filename, datafile=None, cdfile=None, hfile=None, ext=1,
         The number of the extension containing the table HDU to be
         dumped.
 
-    clobber : bool
-        Overwrite the output files if they exist.
+    overwrite : bool, optional
+        If ``True``, overwrite the output file if it exists. Raises an
+        ``OSError`` (``IOError`` for Python 2) if ``False`` and the
+        output file exists. Default is ``False``.
+
+        .. versionchanged:: 1.3
+           ``overwrite`` replaces the deprecated ``clobber`` argument.
 
     Notes
     -----
@@ -744,7 +756,7 @@ def tabledump(filename, datafile=None, cdfile=None, hfile=None, ext=1,
             datafile = root + '_' + repr(ext) + '.txt'
 
         # Dump the data from the HDU to the files
-        f[ext].dump(datafile, cdfile, hfile, clobber)
+        f[ext].dump(datafile, cdfile, hfile, overwrite)
     finally:
         if closed:
             f.close()

diff --git a/astropy/io/fits/diff.py b/astropy/io/fits/diff.py
@@ -31,6 +31,7 @@
 from ...utils.compat.funcsigs import signature
 from .card import Card, BLANK_CARD
 from .header import Header
+from ...utils.decorators import deprecated_renamed_argument
 # HDUList is used in one of the doctests
 from .hdu.hdulist import fitsopen  # pylint: disable=W0611
 from .hdu.table import _TableLikeHDU
@@ -134,7 +135,8 @@ def identical(self):
         return not any(getattr(self, attr) for attr in self.__dict__
                        if attr.startswith('diff_'))
 
-    def report(self, fileobj=None, indent=0, clobber=False):
+    @deprecated_renamed_argument('clobber', 'overwrite', '1.3')
+    def report(self, fileobj=None, indent=0, overwrite=False):
         """
         Generates a text report on the differences (if any) between two
         objects, and either returns it as a string or writes it to a file-like
@@ -151,9 +153,13 @@ def report(self, fileobj=None, indent=0, clobber=False):
         indent : int
             The number of 4 space tabs to indent the report.
 
-        clobber : bool
-            Whether the report output should overwrite an existing file, when
-            fileobj is specified as a path.
+        overwrite : bool, optional
+            If ``True``, overwrite the output file if it exists. Raises an
+            ``OSError`` (``IOError`` for Python 2) if ``False`` and the
+            output file exists. Default is ``False``.
+
+            .. versionchanged:: 1.3
+               ``overwrite`` replaces the deprecated ``clobber`` argument.
 
         Returns
         -------
@@ -164,9 +170,9 @@ def report(self, fileobj=None, indent=0, clobber=False):
         filepath = None
 
         if isinstance(fileobj, string_types):
-            if os.path.exists(fileobj) and not clobber:
+            if os.path.exists(fileobj) and not overwrite:
                 raise IOError("File {0} exists, aborting (pass in "
-                              "clobber=True to overwrite)".format(fileobj))
+                              "overwrite=True to overwrite)".format(fileobj))
             else:
                 filepath = fileobj
                 fileobj = open(filepath, 'w')

diff --git a/astropy/io/fits/file.py b/astropy/io/fits/file.py
@@ -22,8 +22,8 @@
                    _array_to_file, _write_string)
 from ...extern.six import b, string_types
 from ...utils.data import download_file, _is_url
-from ...utils.decorators import classproperty
-from ...utils.exceptions import AstropyUserWarning
+from ...utils.decorators import classproperty, deprecated_renamed_argument
+from ...utils.exceptions import AstropyUserWarning, AstropyDeprecationWarning
 
 
 # Maps PyFITS-specific file mode names to the appropriate file modes to use
@@ -87,7 +87,8 @@ class _File(object):
     Represents a FITS file on disk (or in some other file-like object).
     """
 
-    def __init__(self, fileobj=None, mode=None, memmap=None, clobber=False,
+    @deprecated_renamed_argument('clobber', 'overwrite', '1.3')
+    def __init__(self, fileobj=None, mode=None, memmap=None, overwrite=False,
                  cache=True):
         self.strict_memmap = bool(memmap)
         memmap = True if memmap is None else memmap
@@ -146,11 +147,11 @@ def __init__(self, fileobj=None, mode=None, memmap=None, clobber=False,
 
         # Initialize the internal self._file object
         if _is_random_access_file_backed(fileobj):
-            self._open_fileobj(fileobj, mode, clobber)
+            self._open_fileobj(fileobj, mode, overwrite)
         elif isinstance(fileobj, string_types):
-            self._open_filename(fileobj, mode, clobber)
+            self._open_filename(fileobj, mode, overwrite)
         else:
-            self._open_filelike(fileobj, mode, clobber)
+            self._open_filelike(fileobj, mode, overwrite)
 
         self.fileobj_mode = fileobj_mode(self._file)
 
@@ -375,8 +376,8 @@ def _maybe_close_mmap(self, refcount_delta=0):
             self._mmap.close()
             self._mmap = None
 
-    def _overwrite_existing(self, clobber, fileobj, closed):
-        """Overwrite an existing file if ``clobber`` is ``True``, otherwise
+    def _overwrite_existing(self, overwrite, fileobj, closed):
+        """Overwrite an existing file if ``overwrite`` is ``True``, otherwise
         raise an IOError.  The exact behavior of this method depends on the
         _File object state and is only meant for use within the ``_open_*``
         internal methods.
@@ -385,7 +386,7 @@ def _overwrite_existing(self, clobber, fileobj, closed):
         # The file will be overwritten...
         if ((self.file_like and hasattr(fileobj, 'len') and fileobj.len > 0) or
             (os.path.exists(self.name) and os.path.getsize(self.name) != 0)):
-            if clobber:
+            if overwrite:
                 if self.file_like and hasattr(fileobj, 'truncate'):
                     fileobj.truncate(0)
                 else:
@@ -395,14 +396,14 @@ def _overwrite_existing(self, clobber, fileobj, closed):
             else:
                 raise IOError("File {!r} already exists.".format(self.name))
 
-    def _open_fileobj(self, fileobj, mode, clobber):
+    def _open_fileobj(self, fileobj, mode, overwrite):
         """Open a FITS file from a file object or a GzipFile object."""
 
         closed = fileobj_closed(fileobj)
         fmode = fileobj_mode(fileobj) or PYFITS_MODES[mode]
 
         if mode == 'ostream':
-            self._overwrite_existing(clobber, fileobj, closed)
+            self._overwrite_existing(overwrite, fileobj, closed)
 
         if not closed:
             # Although we have a specific mapping in PYFITS_MODES from our
@@ -429,7 +430,7 @@ def _open_fileobj(self, fileobj, mode, clobber):
             # append mode the file pointer is at the end of the file
             self._file.seek(0)
 
-    def _open_filelike(self, fileobj, mode, clobber):
+    def _open_filelike(self, fileobj, mode, overwrite):
         """Open a FITS file from a file-like object, i.e. one that has
         read and/or write methods.
         """
@@ -455,7 +456,7 @@ def _open_filelike(self, fileobj, mode, clobber):
             self.mode = mode = 'ostream'
 
         if mode == 'ostream':
-            self._overwrite_existing(clobber, fileobj, False)
+            self._overwrite_existing(overwrite, fileobj, False)
 
         # Any "writeable" mode requires a write() method on the file object
         if (self.mode in ('update', 'append', 'ostream') and
@@ -468,11 +469,11 @@ def _open_filelike(self, fileobj, mode, clobber):
             raise IOError("File-like object does not have a 'read' "
                           "method, required for mode {!r}.".format(self.mode))
 
-    def _open_filename(self, filename, mode, clobber):
+    def _open_filename(self, filename, mode, overwrite):
         """Open a FITS file from a filename string."""
 
         if mode == 'ostream':
-            self._overwrite_existing(clobber, None, True)
+            self._overwrite_existing(overwrite, None, True)
 
         if os.path.exists(self.name):
             with fileobj_open(self.name, 'rb') as f:

diff --git a/astropy/io/fits/hdu/base.py b/astropy/io/fits/hdu/base.py
@@ -23,6 +23,7 @@
 from ....utils.compat import suppress
 from ....utils.compat.funcsigs import signature, Parameter
 from ....utils.exceptions import AstropyUserWarning
+from ....utils.decorators import deprecated_renamed_argument
 
 
 class _Delayed(object):
@@ -332,10 +333,11 @@ def readfrom(cls, fileobj, checksum=False, ignore_missing_end=False,
         fileobj.seek(hdu._data_offset + hdu._data_size, os.SEEK_SET)
         return hdu
 
-    def writeto(self, name, output_verify='exception', clobber=False,
+    @deprecated_renamed_argument('clobber', 'overwrite', '1.3')
+    def writeto(self, name, output_verify='exception', overwrite=False,
                 checksum=False):
         """
-        Write the HDU to a new file.  This is a convenience method to
+        Write the HDU to a new file. This is a convenience method to
         provide a user easier output interface if only one HDU needs
         to be written to a file.
 
@@ -352,8 +354,13 @@ def writeto(self, name, output_verify='exception', clobber=False,
             ``"silentfix"`` with ``"+ignore"``, ``+warn``, or ``+exception"
             (e.g. ``"fix+warn"``).  See :ref:`verify` for more info.
 
-        clobber : bool
-            Overwrite the output file if exists.
+        overwrite : bool, optional
+            If ``True``, overwrite the output file if it exists. Raises an
+            ``OSError`` (``IOError`` for Python 2) if ``False`` and the
+            output file exists. Default is ``False``.
+
+            .. versionchanged:: 1.3
+               ``overwrite`` replaces the deprecated ``clobber`` argument.
 
         checksum : bool
             When `True` adds both ``DATASUM`` and ``CHECKSUM`` cards
@@ -363,7 +370,7 @@ def writeto(self, name, output_verify='exception', clobber=False,
         from .hdulist import HDUList
 
         hdulist = HDUList([self])
-        hdulist.writeto(name, output_verify, clobber=clobber,
+        hdulist.writeto(name, output_verify, overwrite=overwrite,
                         checksum=checksum)
 
     @classmethod
@@ -1565,19 +1572,23 @@ def match_header(cls, header):
 
         raise NotImplementedError
 
-    def writeto(self, name, output_verify='exception', clobber=False,
+    @deprecated_renamed_argument('clobber', 'overwrite', '1.3')
+    def writeto(self, name, output_verify='exception', overwrite=False,
                 checksum=False):
         """
         Works similarly to the normal writeto(), but prepends a default
         `PrimaryHDU` are required by extension HDUs (which cannot stand on
         their own).
+
+        .. versionchanged:: 1.3
+           ``overwrite`` replaces the deprecated ``clobber`` argument.
         """
 
         from .hdulist import HDUList
         from .image import PrimaryHDU
 
         hdulist = HDUList([PrimaryHDU(), self])
-        hdulist.writeto(name, output_verify, clobber=clobber,
+        hdulist.writeto(name, output_verify, overwrite=overwrite,
                         checksum=checksum)
 
     def _verify(self, option='warn'):

diff --git a/astropy/io/fits/hdu/hdulist.py b/astropy/io/fits/hdu/hdulist.py
@@ -20,6 +20,7 @@
 from ....extern.six import string_types
 from ....utils import indent
 from ....utils.exceptions import AstropyUserWarning, AstropyDeprecationWarning
+from ....utils.decorators import deprecated_renamed_argument
 from ....extern.six.moves import range
 
 
@@ -640,7 +641,8 @@ def update_extend(self):
                 n = hdr['NAXIS']
                 hdr.set('EXTEND', True, after='NAXIS' + str(n))
 
-    def writeto(self, fileobj, output_verify='exception', clobber=False,
+    @deprecated_renamed_argument('clobber', 'overwrite', '1.3')
+    def writeto(self, fileobj, output_verify='exception', overwrite=False,
                 checksum=False):
         """
         Write the `HDUList` to a new file.
@@ -658,8 +660,13 @@ def writeto(self, fileobj, output_verify='exception', clobber=False,
             ``"silentfix"`` with ``"+ignore"``, ``+warn``, or ``+exception"
             (e.g. ``"fix+warn"``).  See :ref:`verify` for more info.
 
-        clobber : bool
-            When `True`, overwrite the output file if exists.
+        overwrite : bool, optional
+            If ``True``, overwrite the output file if it exists. Raises an
+            ``OSError`` (``IOError`` for Python 2) if ``False`` and the
+            output file exists. Default is ``False``.
+
+            .. versionchanged:: 1.3
+               ``overwrite`` replaces the deprecated ``clobber`` argument.
 
         checksum : bool
             When `True` adds both ``DATASUM`` and ``CHECKSUM`` cards
@@ -684,7 +691,7 @@ def writeto(self, fileobj, output_verify='exception', clobber=False,
         # sensible mode to require is 'ostream'.  This can accept an open
         # file object that's open to write only, or in append/update modes
         # but only if the file doesn't exist.
-        fileobj = _File(fileobj, mode='ostream', clobber=clobber)
+        fileobj = _File(fileobj, mode='ostream', overwrite=overwrite)
         hdulist = self.fromfile(fileobj)
 
         for hdu in self: