Repository: pandas-dev/pandas

Issue:
[documentation] merge(suffixes=(False, False)) should cause an error if a suffix would be required to complete the merge but it is undocumented
#### Problem description

This was going to be a request for an enhancement, but after investigation it just became a reminder that pandas has an undocumented feature. 

About once every few months I get into a tricky debug situation where a column has ceased to exist because it was suffixed with _x or _y, and while I understand use cases where suffixing is good, it is in some cases bad and unintended, and can be tricky because the _x and _y columns may not matter until much later.  I wanted to be able to specify in merge that it should fail if it is going to suffix. 

Turns out you can, but it is undocumented.  Tracing code I eventually arrived at https://github.com/pandas-dev/pandas/blob/v0.23.3/pandas/core/internals.py#L5242

A quick check seems to indicate that merge(..., suffixes=(False,False)) causes the line to execute and doesn't bite if it shouldn't.  Which is nice, but I would encourage you to document it at:
https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.merge.html

~~~python
import pandas as pd
left = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3'],
                    'A': ['A0', 'A1', 'A2', 'A3'],
                     'B': ['B0', 'B1', 'B2', 'B3']})


right = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3'],
            'C': ['C0', 'C1', 'C2', 'C3'],
                  'B': ['D0', 'D1', 'D2', 'D3']})

right_2 = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3'],
            'C': ['C0', 'C1', 'C2', 'C3'],
                  'D': ['D0', 'D1', 'D2', 'D3']})


result = pd.merge(left, right, on='key')
result

#should error and does
pd.merge(left, right, on='key', suffixes=(False, False))


#should not error and doesnt
pd.merge(left, right_2, on='key', suffixes=(False, False))
~~~


Discussion:
Encourage us to do it?  Why aren't **you** encouraged to submit a PR and do it yourself?  Nobody is (at least I am not) stopping you here on this one. 😉 
Claiming this one.  I will take care of it just to get some experience with the documentation system.  

Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -138,12 +138,11 @@
 """
 
 _merge_doc = """
-Merge DataFrame or named Series objects by performing a database-style join
-operation by columns or indexes.
+Merge DataFrame or named Series objects with a database-style join.
 
-If joining columns on columns, the DataFrame indexes *will be
-ignored*. Otherwise if joining indexes on indexes or indexes on a column or
-columns, the index will be passed on.
+The join is done on columns or indexes. If joining columns on
+columns, the DataFrame indexes *will be ignored*. Otherwise if joining indexes
+on indexes or indexes on a column or columns, the index will be passed on.
 
 Parameters
 ----------%s
@@ -153,13 +152,13 @@
     Type of merge to be performed.
 
     * left: use only keys from left frame, similar to a SQL left outer join;
-      preserve key order
+      preserve key order.
     * right: use only keys from right frame, similar to a SQL right outer join;
-      preserve key order
+      preserve key order.
     * outer: use union of keys from both frames, similar to a SQL full outer
-      join; sort keys lexicographically
+      join; sort keys lexicographically.
     * inner: use intersection of keys from both frames, similar to a SQL inner
-      join; preserve the order of the left keys
+      join; preserve the order of the left keys.
 on : label or list
     Column or index level names to join on. These must be found in both
     DataFrames. If `on` is None and not merging on indexes then this defaults
@@ -172,22 +171,23 @@
     Column or index level names to join on in the right DataFrame. Can also
     be an array or list of arrays of the length of the right DataFrame.
     These arrays are treated as if they are columns.
-left_index : boolean, default False
+left_index : bool, default False
     Use the index from the left DataFrame as the join key(s). If it is a
     MultiIndex, the number of keys in the other DataFrame (either the index
     or a number of columns) must match the number of levels.
-right_index : boolean, default False
+right_index : bool, default False
     Use the index from the right DataFrame as the join key. Same caveats as
     left_index.
-sort : boolean, default False
+sort : bool, default False
     Sort the join keys lexicographically in the result DataFrame. If False,
     the order of the join keys depends on the join type (how keyword).
-suffixes : 2-length sequence (tuple, list, ...)
+suffixes : tuple of (str, str), default ('_x', '_y')
     Suffix to apply to overlapping column names in the left and right
-    side, respectively.
-copy : boolean, default True
+    side, respectively. To raise an exception on overlapping columns use
+    (False, False).
+copy : bool, default True
     If False, avoid copy if possible.
-indicator : boolean or string, default False
+indicator : bool or str, default False
     If True, adds a column to output DataFrame called "_merge" with
     information on the source of each row.
     If string, column with information on source of each row will be added to
@@ -197,7 +197,7 @@
     "right_only" for observations whose merge key only appears in 'right'
     DataFrame, and "both" if the observation's merge key is found in both.
 
-validate : string, default None
+validate : str, optional
     If specified, checks if merge is of specified type.
 
     * "one_to_one" or "1:1": check if merge keys are unique in both
@@ -213,6 +213,7 @@
 Returns
 -------
 DataFrame
+    A DataFrame of the two merged objects.
 
 Notes
 -----
@@ -229,24 +230,27 @@
 Examples
 --------
 
->>> A = pd.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'],
-...                   'value': [1, 2, 3, 5]})
->>> B = pd.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'],
-...                   'value': [5, 6, 7, 8]})
->>> A
+>>> df1 = pd.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'],
+...                     'value': [1, 2, 3, 5]})
+>>> df2 = pd.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'],
+...                     'value': [5, 6, 7, 8]})
+>>> df1
     lkey value
 0   foo      1
 1   bar      2
 2   baz      3
 3   foo      5
->>> B
+>>> df2
     rkey value
 0   foo      5
 1   bar      6
 2   baz      7
 3   foo      8
 
->>> A.merge(B, left_on='lkey', right_on='rkey', how='outer')
+Merge df1 and df2 on the lkey and rkey columns. The value columns have
+the default suffixes, _x and _y, appended.
+
+>>> df1.merge(df2, left_on='lkey', right_on='rkey')
   lkey  value_x rkey  value_y
 0  foo        1  foo        5
 1  foo        1  foo        8
@@ -254,6 +258,28 @@
 3  foo        5  foo        8
 4  bar        2  bar        6
 5  baz        3  baz        7
+
+Merge DataFrames df1 and df2 with specified left and right suffixes
+appended to any overlapping columns.
+
+>>> df1.merge(df2, left_on='lkey', right_on='rkey',
+...           suffixes=('_left', '_right'))
+  lkey  value_left rkey  value_right
+0  foo           1  foo            5
+1  foo           1  foo            8
+2  foo           5  foo            5
+3  foo           5  foo            8
+4  bar           2  bar            6
+5  baz           3  baz            7
+
+Merge DataFrames df1 and df2, but raise an exception if the DataFrames have
+any overlapping columns.
+
+>>> df1.merge(df2, left_on='lkey', right_on='rkey', suffixes=(False, False))
+Traceback (most recent call last):
+...
+ValueError: columns overlap but no suffix specified:
+    Index(['value'], dtype='object')
 """
 
 # -----------------------------------------------------------------------


Test patch: