acidplyr.left_join

acidplyr.left_join(x: DataFrame, y: DataFrame, by: str | list[str]) → DataFrame

Left join: return all rows from x, matching rows from y.

Guarantees exactly len(x) output rows by tracking x row positions through the merge — matches R’s index-based reconstruction.

Parameters:

  • x (pd.DataFrame) – Left DataFrame; every row is kept.

  • y (pd.DataFrame) – Right DataFrame.

  • by (str or list of str) – Column name(s) to join on. Must exist in both x and y with matching dtypes.

Returns:

All rows from x, with matching columns from y where available (NaN otherwise).

Return type:

pd.DataFrame

Examples

>>> import pandas as pd
>>> x = pd.DataFrame({"name": ["Mick", "John", "Paul"]})
>>> y = pd.DataFrame(
...     {"name": ["John", "Paul"], "plays": ["guitar", "bass"]}
... )
>>> left_join(x, y, by="name")["name"].tolist()
['Mick', 'John', 'Paul']