docs(numpydates): add NumpyDates reference and clarify unit docs

- Add NumpyDates section to pythoncall-reference with API docs
- Update release notes with NumpyDates overview
- Clarify docstrings: runtime vs inline units and memory layout

Author: Christopher Doris

docs/src/pythoncall-reference.md

@@ -255,3 +255,18 @@ PythonCall.getptr
 PythonCall.pydel!
 PythonCall.unsafe_pynext
 ```
+
+## NumpyDates
+
+The submodule `PythonCall.NumpyDates` provides types corresponding to Numpy's `datetime64` and `timedelta64` types. Enables conversion of these Numpy types (either as scalars or in arrays) to native Julia types.
+
+```@docs
+PythonCall.NumpyDates
+PythonCall.NumpyDates.AbstractDateTime64
+PythonCall.NumpyDates.InlineDateTime64
+PythonCall.NumpyDates.DateTime64
+PythonCall.NumpyDates.AbstractTimeDelta64
+PythonCall.NumpyDates.InlineTimeDelta64
+PythonCall.NumpyDates.TimeDelta64
+PythonCall.NumpyDates.Unit
+```

docs/src/releasenotes.md

@@ -1,5 +1,8 @@
 # Release Notes
 
+## Unreleased
+* Added NumpyDates: NumPy-compatible DateTime64/TimeDelta64 types and units.
+
 ## 0.9.27 (2025-08-19)
 * Internal: Use heap-allocated types (PyType_FromSpec) to improve ABI compatibility.
 * Minimum supported Python version is now 3.9.

src/NumpyDates/DateTime64.jl

@@ -6,6 +6,10 @@
 
 Construct an `DateTime64` with the given `value` and [`unit`](@ref Unit).
 
+The unit is stored as a run-time value. If the units in your code are known, using
+[`InlineDateTime64{unit}`](@ref InlineDateTime64) may be preferable. The memory layout
+is the same as for a `numpy.datetime64`.
+
 The value can be:
 - An `Integer`, in which case the `unit` is required.
 - A `Dates.Date` or `Dates.DateTime`.

src/NumpyDates/InlineDateTime64.jl

@@ -8,6 +8,8 @@
 
 Construct an `InlineDateTime64` with the given `value` and [`unit`](@ref Unit).
 
+The unit is part of the type, so an instance just consists of one `Int64` for the value.
+
 The `value` can be:
 - An `Integer`, in which case the `unit` is required.
 - A `Dates.Date` or `Dates.DateTime`.

src/NumpyDates/InlineTimeDelta64.jl

@@ -6,6 +6,8 @@
 
 Construct an `InlineTimeDelta64` with the given `value` and [`unit`](@ref Unit).
 
+The unit is part of the type, so an instance just consists of one `Int64` for the value.
+
 The value can be:
 - An `Integer`, in which case the `unit` is required.
 - `"NaT"` or `"NaN"` to make a not-a-time value.

src/NumpyDates/TimeDelta64.jl

@@ -5,6 +5,10 @@
 
 Construct a `TimeDelta64` with the given `value` and [`unit`](@ref Unit).
 
+The unit is stored as a run-time value. If the units in your code are known, using
+[`InlineTimeDelta64{unit}`](@ref InlineTimeDelta64) may be preferable. The memory layout
+is the same as for a `numpy.timedelta64`.
+
 The value can be:
 - An `Integer`, in which case the `unit` is required.
 - `"NaT"` or `"NaN"` to make a not-a-time value.