DOC: NaT - "alias of NaT"; NA - "alias of <NA>"

[wjandrea]

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.NaT.html

Documentation problem

pandas.NaT

alias of NaT

It's an alias of itself???

Suggested fix for documentation

I'm not sure yet; I'll need to check the source code.

[wjandrea]

This changed in 2.2. As of 2.1, it made more sense:

https://pandas.pydata.org/pandas-docs/version/2.1/reference/api/pandas.NaT.html

pandas.NaT = NaT

(N)ot-(A)-(T)ime, the time equivalent of NaN.

BTW, note that it was at a different location in the sidebar:

• then: pandas arrays, scalars, and data types
• now: Missing values

[wjandrea]

I just noticed the "Missing values" page contains the description:

https://pandas.pydata.org/docs/dev/reference/missing_value.html

NaT is the missing value for timedelta and datetime data (see below):

NaT
(N)ot-(A)-(T)ime, the time equivalent of NaN.

[wjandrea]

NA has the same problem:

https://pandas.pydata.org/docs/dev/reference/api/pandas.NA.html

pandas.NA

alias of <NA>

But unlike NaT, the problem goes back to 2.0:

https://pandas.pydata.org/pandas-docs/version/2.0/reference/api/pandas.NA.html

pandas.NA

alias of <NA>

[wjandrea]

OK, I checked the source code but I'm not sure where "alias" is coming from – maybe something is pulling from their __repr__s?

pandas/pandas/_libs/tslibs/nattype.pyx

Lines 305 to 306 in 188b2da

	def __repr__(self) -> str:
	return "NaT"

pandas/pandas/_libs/missing.pyx

Lines 386 to 387 in 188b2da

	def __repr__(self) -> str:
	return "<NA>"

---

On the way, I found fuller descriptions on their respective classes:

pandas/pandas/_libs/tslibs/nattype.pyx

Lines 347 to 373 in 188b2da

	class NaTType(_NaT):
	"""
	(N)ot-(A)-(T)ime, the time equivalent of NaN.
	NaT is used to denote missing or null values in datetime and timedelta objects
	in pandas. It functions similarly to how NaN is used for numerical data.
	Operations with NaT will generally propagate the NaT value, similar to NaN.
	NaT can be used in pandas data structures like Series and DataFrame
	to represent missing datetime values. It is useful in data analysis
	and time series analysis when working with incomplete or sparse
	time-based data. Pandas provides robust handling of NaT to ensure
	consistency and reliability in computations involving datetime objects.
	See Also
	--------
	NA : NA ("not available") missing value indicator.
	isna : Detect missing values (NaN or NaT) in an array-like object.
	notna : Detect non-missing values.
	numpy.nan : Floating point representation of Not a Number (NaN) for numerical data.
	Examples
	--------
	>>> pd.DataFrame([pd.Timestamp("2023"), np.nan], columns=["col_1"])
	col_1
	0 2023-01-01
	1 NaT
	"""

pandas/pandas/_libs/missing.pyx

Lines 339 to 377 in 188b2da

	class NAType(C_NAType):
	"""
	NA ("not available") missing value indicator.
	.. warning::
	Experimental: the behaviour of NA can still change without warning.
	The NA singleton is a missing value indicator defined by pandas. It is
	used in certain new extension dtypes (currently the "string" dtype).
	See Also
	--------
	numpy.nan : Floating point representation of Not a Number (NaN) for numerical data.
	isna : Detect missing values for an array-like object.
	notna : Detect non-missing values for an array-like object.
	DataFrame.fillna : Fill missing values in a DataFrame.
	Series.fillna : Fill missing values in a Series.
	Examples
	--------
	>>> pd.NA
	<NA>
	>>> True | pd.NA
	True
	>>> True & pd.NA
	<NA>
	>>> pd.NA != pd.NA
	<NA>
	>>> pd.NA == pd.NA
	<NA>
	>>> True | pd.NA
	True
	"""

[rhshadrach]

Thanks for the report! This is Sphinx behavior on private imports:

https://stackoverflow.com/questions/38765577/overriding-sphinx-autodoc-alias-of-for-import-of-private-class

Setting the __module__ attribute to be pandas should resolve. PRs welcome!

[zacharym-collins]

take

[meet-vasita]

take