DOC: KeyError isn't raised if df/series at property is called with label not existing in the df/series

[FactorizeD]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.at.html
https://pandas.pydata.org/docs/dev/reference/api/pandas.Series.at.html

Documentation problem

Documentation states that KeyError would be raised if at was called on the DataFrame/Series with 'label' not existing in the data. It doesn't seem to be the case:

df = pd.DataFrame(data={'a':[0]})
df.at[0, 'b'] = 'no_error_raised'
df
Out[8]: 
   a                b
0  0  no_error_raised

srs = pd.Series([1, 2, 3], index=['a', 'b', 'c'])
srs.at['d'] = 'no_error_raised'
srs
Out[9]: 
a                  1
b                  2
c                  3
d    no_error_raised
dtype: object

Relates to #30649 - see the relevant comment:

That line of docs was added in #20290, and doesn't appear to be tested. It's not clear that that's the intentional behavior.

Originally posted by @TomAugspurger in #30649 (comment)

Suggested fix for documentation

As stated by Tom, it's not clear that that's the intentional behavior. I can see two ways to fix it:

1. If it is decided that raising a KeyError is an intentional behavior, then some code changes would be required to make sure that it is indeed raised
2. If it is decided that KeyError should not be raised in such cases, documentation for both dataframe.at and series.at needs to be updated

IMO the wording in the docs Access a single value for a row/column label pair. suggests that it should indeed raise such an error as this should rather not be used to create new columns, but more discussion might be needed to reach conclusions

I am happy to tackle this issue if it is decided that it should be done:)

[rhshadrach]

This behavior is documented in the user guide. I agree the API docs could use fixing here; they are correct for getting values but not setting them.

[FactorizeD]

Ah, should have searched the user guide for mentions too - it is indeed well documented there and it shows that setting the values using at is an intentional behavior. Will work on fixing the API docs tomorrow

[FactorizeD]

take