DOC: dt.month_name & dt.day_name locale parameter needs improvment

[eduardochaves1]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

df['DIA_DA_SEMANA'] = df.DAT_EMISSAO.dt.day_name()
df['DIA'] = df.DAT_EMISSAO.dt.day
df['MÊS'] = df.DAT_EMISSAO.dt.month_name(locale='Portuguese') # OUTPUT: Error: unsupported locale setting
df['ANO'] = df.DAT_EMISSAO.dt.year
df

Traceback

Error                                     Traceback (most recent call last)
Cell In[24], line 3
      1 df['DIA_DA_SEMANA'] = df.DAT_EMISSAO.dt.day_name()
      2 df['DIA'] = df.DAT_EMISSAO.dt.day
----> 3 df['MÊS'] = df.DAT_EMISSAO.dt.month_name(locale='Portuguese')
      4 df['ANO'] = df.DAT_EMISSAO.dt.year
      5 df

File ~/.local/lib/python3.10/site-packages/pandas/core/accessor.py:94, in PandasDelegate._add_delegate_accessors.<locals>._create_delegator_method.<locals>.f(self, *args, **kwargs)
     93 def f(self, *args, **kwargs):
---> 94     return self._delegate_method(name, *args, **kwargs)

File ~/.local/lib/python3.10/site-packages/pandas/core/indexes/accessors.py:126, in Properties._delegate_method(self, name, *args, **kwargs)
    123 values = self._get_values()
    125 method = getattr(values, name)
--> 126 result = method(*args, **kwargs)
    128 if not is_list_like(result):
    129     return result

File ~/.local/lib/python3.10/site-packages/pandas/core/indexes/extension.py:98, in _inherit_from_data.<locals>.method(self, *args, **kwargs)
     96 if "inplace" in kwargs:
     97     raise ValueError(f"cannot use inplace with {type(self).__name__}")
---> 98 result = attr(self._data, *args, **kwargs)
     99 if wrap:
    100     if isinstance(result, type(self._data)):

File ~/.local/lib/python3.10/site-packages/pandas/core/arrays/datetimes.py:1212, in DatetimeArray.month_name(self, locale)
   1175 """
   1176 Return the month names with specified locale.
   1177 
   (...)
   1208 Index(['January', 'February', 'March'], dtype='object')
   1209 """
   1210 values = self._local_timestamps()
-> 1212 result = fields.get_date_name_field(
   1213     values, "month_name", locale=locale, reso=self._reso
   1214 )
   1215 result = self._maybe_mask_results(result, fill_value=None)
   1216 return result

File ~/.local/lib/python3.10/site-packages/pandas/_libs/tslibs/fields.pyx:179, in pandas._libs.tslibs.fields.get_date_name_field()

File ~/.local/lib/python3.10/site-packages/pandas/_libs/tslibs/fields.pyx:622, in pandas._libs.tslibs.fields._get_locale_names()
...
    618     # convert to string
    619     locale = normalize(_build_localename(locale))
--> 620 return _setlocale(category, locale)

Error: unsupported locale setting

Issue Description

I'm trying to set a month column for my DF with portuguese names by doing as the docs said, but it didn't work, I even tried with 'English' which says it is the default but it doesn't work either.

Expected Behavior

I expect it to return a serialized column with month names in Portuguese

Installed Versions

INSTALLED VERSIONS

commit : 2e218d1
python : 3.10.9.final.0
python-bits : 64
OS : Linux
OS-release : 6.0.12-76060006-generic
Version : #202212290932167413972522.04~ca93ccf SMP PREEMPT_DYNAMIC Thu J
machine : x86_64
processor : x86_64
byteorder : little
LC_ALL : None
LANG : en_US.UTF-8
LOCALE : pt_BR.UTF-8

pandas : 1.5.3
numpy : 1.23.5
pytz : 2022.7
dateutil : 2.8.2
setuptools : 65.6.3
pip : 22.3.1
Cython : None
pytest : None
hypothesis : None
sphinx : None
blosc : None
feather : None
xlsxwriter : None
lxml.etree : 4.9.1
html5lib : None
pymysql : None
psycopg2 : None
jinja2 : 3.1.2
IPython : 8.7.0
pandas_datareader: None
bs4 : 4.11.1
bottleneck : 1.3.5
brotli :
fastparquet : None
fsspec : None
gcsfs : None
matplotlib : 3.6.2
numba : None
numexpr : 2.8.4
...
xlrd : None
xlwt : None
zstandard : None
tzdata : 2022.7
/home/eduardochaves/miniconda3/envs/datasets_procenge/lib/python3.10/site-packages/_distutils_hack/init.py:33: UserWarning: Setuptools is replacing distutils.
warnings.warn("Setuptools is replacing distutils.")

[MarcoGorelli]

hi @eduardochaves1

what's the output of locale -a for you?

[eduardochaves1]

hi @eduardochaves1

what's the output of locale -a for you?

Ow, I didn't know about this command, and I just found out by this command's output that the right way to set the locale attribute was with locale="pt_BR.utf8" (for Brazilian Portuguese). Thank you for helping me with that!

Maybe a good tip was to modify the dt.day_name and dt.month_name pandas documentations with that command in mind so the users can know how to set their language in the right way?

[MarcoGorelli]

yup - do you want to make a PR?

[eduardochaves1]

I'd like to, actually it would be my first time helping an open source project 😅. But the closest thing i found on the repo was this path. Wich is not what I expected from the original doc page I read.

[MarcoGorelli]

here's the docstring

pandas/pandas/core/arrays/datetimes.py

Lines 1198 to 1209 in bcb6c1a

	Return the month names with specified locale.
	Parameters
	----------
	locale : str, optional
	Locale determining the language in which to return the month name.
	Default is English locale.
	Returns
	-------
	Series or Index
	Series or Index of month names.