file_name

mediautils.file_name.file_name_to_datetime(path: str | PathLike) → datetime

Extract a datetime from a file path based on its name.

Parameters:

path (str | os.PathLike) – Path to a file whose stem starts with YYYYMMDD_HHMMSS.

Return type:

datetime

Raises:

ValueError – If the file name does not match the expected format.

Examples

>>> file_name_to_datetime("20240131_181253_blabla.jpg")
datetime.datetime(2024, 1, 31, 18, 12, 53)

>>> file_name_to_datetime("some/dir/20250101_120000.png")
datetime.datetime(2025, 1, 1, 12, 0)

mediautils.file_name.replace_datetime_prefix(path: str | PathLike, dt: datetime) → str

Replace the YYYYMMDD_HHMMSS prefix of a file’s name with dt.

Parameters:

• path (str | os.PathLike) – Path to a file whose name starts with YYYYMMDD_HHMMSS.

• dt (datetime) – The datetime to encode as the new prefix.

Returns:

The corrected file name (not a path).

Return type:

str

Raises:

ValueError – If the file name does not match the expected format.

Examples

>>> replace_datetime_prefix(
...     "20240131_181253_blabla.jpg", datetime(2024, 1, 31, 18, 27, 53)
... )
'20240131_182753_blabla.jpg'

>>> replace_datetime_prefix(
...     "some/dir/20250101_120000.png", datetime(2025, 1, 1, 11, 45, 0)
... )
'20250101_114500.png'

mediautils.file_name.standardize_name(path: str | PathLike) → tuple[str, datetime]

Compute the standardized name of a file and the datetime it encodes.

A name that is already standardized (YYYYMMDD_HHMMSS...) is kept as is, with one exception: YYYYMMDD_HHMMSS_VIDyyyymmddhhmmss..., whose prefix is replaced by the datetime of the phone’s own name (start of the recording, local time where it was filmed). A name following one of the known source conventions is prefixed with YYYYMMDD_HHMMSS_, keeping the original name in full so that it is never lost (even if the date and time then appear twice).

Parameters:

path (str | os.PathLike) – Path to the file.

Returns:

The standardized file name (not a path) and the datetime it encodes (naive, local wall-clock time).

Return type:

tuple[str, datetime]

Raises:

ValueError – If the file name follows no known convention.

Examples

Already standardized: unchanged.

>>> standardize_name("20240131_181253_blabla.mp4")
('20240131_181253_blabla.mp4', datetime.datetime(2024, 1, 31, 18, 12, 53))

Prefix recomputed from the phone’s own name (end of recording -> start; MGifier suffixes kept):

>>> standardize_name("20251126_185311_VID20251126185303.mp4")
('20251126_185303_VID20251126185303.mp4', datetime.datetime(2025, 11, 26, 18, 53, 3))

>>> standardize_name("20260611_125751_VID20260611195724_MG.mp4")
('20260611_195724_VID20260611195724_MG.mp4', datetime.datetime(2026, 6, 11, 19, 57, 24))

Android phone video (milliseconds dropped from the datetime):

>>> standardize_name("some/dir/VID_20190924_162534168.mp4")
('20190924_162534_VID_20190924_162534168.mp4', datetime.datetime(2019, 9, 24, 16, 25, 34))

>>> standardize_name("VID_20190924_162534.mp4")
('20190924_162534_VID_20190924_162534.mp4', datetime.datetime(2019, 9, 24, 16, 25, 34))

Unknown convention:

>>> standardize_name("MVI_1234.MOV")
Traceback (most recent call last):
...
ValueError: Unknown file name convention: MVI_1234.MOV

mediautils.file_name.wa_file_name_to_date(path: str | PathLike) → date

Extract a date from a WhatsApp file path based on its name.

Parameters:

path (str | os.PathLike) – Path to a file matching IMG-YYYYMMDD-... or VID-YYYYMMDD-....

Return type:

date

Raises:

ValueError – If the file name does not match the expected WhatsApp format.

Examples

>>> wa_file_name_to_date("IMG-20251014-WA0010.jpg")
datetime.date(2025, 10, 14)

>>> wa_file_name_to_date("some/dir/VID-20251027-WA0001.mp4")
datetime.date(2025, 10, 27)