Module android 

Read-only decoder for the Android MediaStore trash filename convention.

On Android 11+ (API 30) the system-level, vendor-independent trash renames a media file in place to a self-describing hidden name:

.trashed-<dateExpires>-<originalDisplayName>

with a 7-day sibling mechanism using the pending prefix. Because the MediaProvider rebuilds its files-table row from this name on rescan, the name alone recovers the original filename and the expiry time even if the database is wiped. This module decodes that name; correlating it with the external.db files table is a separate (SQLite) concern.

Codec (authoritative)

AOSP packages/providers/MediaProvider util/FileUtils.java (https://android.googlesource.com/platform/packages/providers/MediaProvider/+/refs/heads/android11-release/src/com/android/providers/media/util/FileUtils.java):

PATTERN_EXPIRES_FILE = (?i)^\.(pending|trashed)-(\d+)-([^/]+)$
DEFAULT_DURATION_TRASHED = 30 days,  DEFAULT_DURATION_PENDING = 7 days

• <dateExpires> is epoch SECONDS (the source divides milliseconds by 1000), not milliseconds.
• <originalDisplayName> is the original filename including extension; it may itself contain - and ., so it is everything after the second -.
• The prefix match is case-insensitive; the display name keeps its case.

Structs

TrashedName

A decoded MediaStore .trashed-/.pending- filename.

Enums

TrashState

Whether a MediaStore name encodes the 30-day trashed state or the 7-day pending state.

Functions

parse_trashed_name

Decode a single filename per AOSP PATTERN_EXPIRES_FILE. Returns None for any name that is not a well-formed .trashed-/.pending- token (including a plain, non-trashed filename) — the caller decides whether a None that still carries a trashed/pending prefix is a malformed-token anomaly.