Added example for Dataframe.align

[oovk]

• closes DOC add example to align #42125
• tests added / passed
• Ensure all linting tests pass, see here for how to run them
• whatsnew entry
  @MarcoGorelli

[phofl]

small comment, otherwise lgtm. Maybe adding one for axis=0?

[phofl]

Formatting looks a bit odd here, does this fit into one row?

[oovk]

It looks like this, I'm not really sure about linting styles, not able to figure out why autopep8 is not working for me.☹️

[MarcoGorelli]

autopep8 is not working for me

This is a docstring, autopep8 runs on code. And second, pandas doesn't use the autopep8 formatter, but the black formatter

[MarcoGorelli]

these results don't look correct

also, the formatting's off so it won't pass the checks - one way to fix this would be to paste your code in another file, run black on it, and then paste it back here. Or paste the entire docstring in another file and run blackdoc on it

[oovk]

When I run python scripts/validate_docstrings.py pandas.DataFrame.align I get these errors wrt example being not correct.

But when I checked the example in dev version the output differs.

PTAL!

[MarcoGorelli]

you've got join='right' in your docstring

[oovk]

ohh, sry my bad😅

[MarcoGorelli]

this won't pass CI checks - I suggest you copy and paste the code you've written to a new text file, run black and flake8 on it, then copy the code back to the docstrings

[oovk]

Soo, we use blackdocfor doc formatting right🤔? I was really confused between black n blackdoc.😕

[MarcoGorelli]

couple more things

one on naming, the other: can you add a little explanation in between the examples? So, after you've shown the axis=1 example, you can write something like "We can also align on the index" and then show the axis=0 example (see https://pandas.pydata.org/pandas-docs/stable/development/contributing_docstring.html#conventions-for-the-examples)

Rest looks good! 👍

[MarcoGorelli]

last thing - for consistency with the arguments, can we name the original dataframes df and other, and then the results left and right? So

Suggested change

	>>> left = pd.DataFrame(
	... [[1, 2, 3, 4], [6, 7, 8, 9]], columns=["D", "B", "E", "A"], index=[1, 2]
	... )
	>>> right = pd.DataFrame(
	... [[10, 20, 30, 40], [60, 70, 80, 90], [600, 700, 800, 900]],
	... columns=["A", "B", "C", "D"],
	... index=[2, 3, 4],
	... )
	>>> left
	D B E A
	1 1 2 3 4
	2 6 7 8 9
	>>> right
	A B C D
	2 10 20 30 40
	3 60 70 80 90
	4 600 700 800 900
	>>> a1, a2 = left.align(right, join="outer", axis=1)
	>>> df = pd.DataFrame(
	... [[1, 2, 3, 4], [6, 7, 8, 9]], columns=["D", "B", "E", "A"], index=[1, 2]
	... )
	>>> other = pd.DataFrame(
	... [[10, 20, 30, 40], [60, 70, 80, 90], [600, 700, 800, 900]],
	... columns=["A", "B", "C", "D"],
	... index=[2, 3, 4],
	... )
	>>> df
	D B E A
	1 1 2 3 4
	2 6 7 8 9
	>>> other
	A B C D
	2 10 20 30 40
	3 60 70 80 90
	4 600 700 800 900
	>>> left, right = left.align(right, join="outer", axis=1)

(likewise for the axis=0 example)

[MarcoGorelli]

thanks @oovk

[MarcoGorelli]

Soo, we use blackdocfor doc formatting rightthinking? I was really confused between black n blackdoc.confused

docstring are formatted with a custom check which runs flake8, but it doesn't autoformat them, that's something we need to do manually unfortunately. I'd like to make it automatic though, it's kinda on my todo list