feat: Implement operator @ for DataFrame.dot (#139)

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://togithub.com/googleapis/python-bigquery-dataframes/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)

Fixes b/297502513 🦕

Author: shobsi

bigframes/dataframe.py

@@ -2707,3 +2707,5 @@ def get_right_id(id):
             result = result[other.name].rename()
 
         return result
+
+    __matmul__ = dot

tests/system/small/test_dataframe.py

@@ -3264,6 +3264,23 @@ def test_df_dot(
     )
 
 
+def test_df_dot_operator(
+    matrix_2by3_df, matrix_2by3_pandas_df, matrix_3by4_df, matrix_3by4_pandas_df
+):
+    bf_result = (matrix_2by3_df @ matrix_3by4_df).to_pandas()
+    pd_result = matrix_2by3_pandas_df @ matrix_3by4_pandas_df
+
+    # Patch pandas dtypes for testing parity
+    # Pandas result is object instead of Int64 (nullable) dtype.
+    for name in pd_result.columns:
+        pd_result[name] = pd_result[name].astype(pd.Int64Dtype())
+
+    pd.testing.assert_frame_equal(
+        bf_result,
+        pd_result,
+    )
+
+
 def test_df_dot_series(
     matrix_2by3_df, matrix_2by3_pandas_df, matrix_3by4_df, matrix_3by4_pandas_df
 ):
@@ -3278,3 +3295,19 @@ def test_df_dot_series(
         bf_result,
         pd_result,
     )
+
+
+def test_df_dot_operator_series(
+    matrix_2by3_df, matrix_2by3_pandas_df, matrix_3by4_df, matrix_3by4_pandas_df
+):
+    bf_result = (matrix_2by3_df @ matrix_3by4_df["x"]).to_pandas()
+    pd_result = matrix_2by3_pandas_df @ matrix_3by4_pandas_df["x"]
+
+    # Patch pandas dtypes for testing parity
+    # Pandas result is object instead of Int64 (nullable) dtype.
+    pd_result = pd_result.astype(pd.Int64Dtype())
+
+    pd.testing.assert_series_equal(
+        bf_result,
+        pd_result,
+    )

tests/system/small/test_multiindex.py

@@ -998,13 +998,19 @@ def test_df_multi_index_dot_not_supported():
     with pytest.raises(NotImplementedError, match="Multi-index input is not supported"):
         bf1.dot(bf2)
 
+    with pytest.raises(NotImplementedError, match="Multi-index input is not supported"):
+        bf1 @ bf2
+
     # right multi-index
     right_index = pandas.MultiIndex.from_tuples([("a", "aa"), ("a", "ab"), ("b", "bb")])
     bf1 = bpd.DataFrame(left_matrix)
     bf2 = bpd.DataFrame(right_matrix, index=right_index)
     with pytest.raises(NotImplementedError, match="Multi-index input is not supported"):
         bf1.dot(bf2)
 
+    with pytest.raises(NotImplementedError, match="Multi-index input is not supported"):
+        bf1 @ bf2
+
 
 def test_column_multi_index_dot_not_supported():
     left_matrix = [[1, 2, 3], [2, 5, 7]]
@@ -1022,10 +1028,20 @@ def test_column_multi_index_dot_not_supported():
     ):
         bf1.dot(bf2)
 
+    with pytest.raises(
+        NotImplementedError, match="Multi-level column input is not supported"
+    ):
+        bf1 @ bf2
+
     # right multi-columns
     bf1 = bpd.DataFrame(left_matrix)
     bf2 = bpd.DataFrame(right_matrix, columns=multi_level_columns)
     with pytest.raises(
         NotImplementedError, match="Multi-level column input is not supported"
     ):
         bf1.dot(bf2)
+
+    with pytest.raises(
+        NotImplementedError, match="Multi-level column input is not supported"
+    ):
+        bf1 @ bf2