Types

TypedDict hints for every object — verified against live API responses. The client returns plain dicts; these exist for typing, autocompletion, and docs.

deezify.types

Typed hints for every Deezer API object.

Field coverage below was verified against live https://api.deezer.com responses (not just the docs tables), so nested shapes — e.g. the artist inside a :class:Track, or the per-kind sub-lists of :class:Chart — match what the API actually returns.

Runtime behavior is unchanged: the client returns plain dict objects (and :class:~deezify.paginator.PaginatedList for collections). These TypedDict classes exist for static typing, IDE autocompletion and documentation. Every class has total=False because the API only ever returns a subset of fields depending on context (a track inside an album carries fewer keys than a full track.get()).

Generic aliases at the bottom describe the shapes of paginated envelopes and write-action results:

• PaginatedTracks etc. — what client.*.<connection>() items look like once iterated (each item is the corresponding object type).
• ChartBundle — the dict returned by client.chart.get().

Contributor

Bases: _Entity

An artist contributor entry (track.contributors[]).

Source code in deezify/types.py

class Contributor(_Entity):
    """An artist contributor entry (``track.contributors[]``)."""

    name: str
    link: str
    share: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str
    radio: bool
    tracklist: str
    role: str

GenreRef

Bases: _Entity

Genre entry inside album.genres.data[].

Source code in deezify/types.py

class GenreRef(_Entity):
    """Genre entry inside ``album.genres.data[]``."""

    name: str
    picture: str

ArtistRef

Bases: _Entity

Compact artist nested in tracks/albums/charts.

Source code in deezify/types.py

class ArtistRef(_Entity):
    """Compact artist nested in tracks/albums/charts."""

    name: str
    link: str
    share: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str
    nb_album: int
    nb_fan: int
    radio: bool
    tracklist: str
    role: str

Artist

Bases: ArtistRef

Full artist object (GET /artist/{id}).

Source code in deezify/types.py

class Artist(ArtistRef):
    """Full artist object (``GET /artist/{id}``)."""

AlbumRef

Bases: _Entity

Compact album nested in tracks/charts.

Source code in deezify/types.py

class AlbumRef(_Entity):
    """Compact album nested in tracks/charts."""

    title: str
    upc: str
    link: str
    cover: str
    cover_small: str
    cover_medium: str
    cover_big: str
    cover_xl: str
    md5_image: str
    genre_id: int
    release_date: str
    tracklist: str

AlbumTrack

Bases: _Entity

Track entry inside album.tracks.data[] / playlist listings.

Source code in deezify/types.py

class AlbumTrack(_Entity):
    """Track entry inside ``album.tracks.data[]`` / playlist listings."""

    readable: bool
    title: str
    title_short: str
    title_version: str
    isrc: str
    link: str
    duration: int
    rank: int
    explicit_lyrics: bool
    explicit_content_lyrics: int
    explicit_content_cover: int
    preview: str
    md5_image: str
    time_add: str
    artist: ArtistRef
    album: AlbumRef

Album

Bases: AlbumRef

Full album object (GET /album/{id}).

Source code in deezify/types.py

class Album(AlbumRef):
    """Full album object (``GET /album/{id}``)."""

    share: str
    genres: GenresEnvelope
    label: str
    provider: str
    nb_tracks: int
    duration: int
    fans: int
    record_type: str
    available: bool
    alternative: AlbumRef
    explicit_lyrics: bool
    explicit_content_lyrics: int
    explicit_content_cover: int
    contributors: list[Contributor]
    fallback: dict[str, Any]
    artist: ArtistRef
    tracks: AlbumTracksEnvelope

Track

Bases: _Entity

Full track object (GET /track/{id}).

Source code in deezify/types.py

class Track(_Entity):
    """Full track object (``GET /track/{id}``)."""

    readable: bool
    title: str
    title_short: str
    title_version: str
    unseen: bool
    isrc: str
    link: str
    share: str
    duration: int
    track_position: int
    disk_number: int
    rank: int
    release_date: str
    explicit_lyrics: bool
    explicit_content_lyrics: int
    explicit_content_cover: int
    preview: str
    bpm: float
    gain: float
    available_countries: list[str]
    alternative: Track
    contributors: list[Contributor]
    md5_image: str
    track_token: str
    time_add: str
    position: int
    artist: ArtistRef
    album: AlbumRef

ChartTrack

Bases: Track

Track entry inside chart listings (adds position).

Source code in deezify/types.py

class ChartTrack(Track, total=False):
    """Track entry inside chart listings (adds ``position``)."""

    position: int

CreatorRef

Bases: _Entity

Playlist creator (playlist.creator).

Source code in deezify/types.py

class CreatorRef(_Entity):
    """Playlist creator (``playlist.creator``)."""

    name: str
    tracklist: str

PlaylistRef

Bases: _Entity

Compact playlist nested in charts / user listings.

Source code in deezify/types.py

class PlaylistRef(_Entity):
    """Compact playlist nested in charts / user listings."""

    title: str
    description: str
    duration: int
    public: bool
    is_loved_track: bool
    collaborative: bool
    nb_tracks: int
    unseen_track_count: int
    fans: int
    link: str
    share: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str
    checksum: str
    position: int
    creator: CreatorRef
    user: UserRef  # noqa: F821 - defined below; resolved lazily

Playlist

Bases: PlaylistRef

Full playlist object (GET /playlist/{id}).

Source code in deezify/types.py

class Playlist(PlaylistRef):
    """Full playlist object (``GET /playlist/{id}``)."""

    tracklist: str
    creation_date: str
    add_date: str
    mod_date: str
    md5_image: str
    picture_type: str
    tracks: AlbumTracksEnvelope

UserRef

Bases: _Entity

Public user nested in fans/creators (GET /user/{id} unauthenticated).

Source code in deezify/types.py

class UserRef(_Entity):
    """Public user nested in fans/creators (``GET /user/{id}`` unauthenticated)."""

    name: str
    lastname: str
    firstname: str
    link: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str
    country: str
    tracklist: str

User

Bases: UserRef

Full user object (extra fields need an access token).

Source code in deezify/types.py

class User(UserRef):
    """Full user object (extra fields need an access token)."""

    email: str
    status: int
    birthday: str
    inscription_date: str
    gender: str
    lang: str
    is_kid: bool
    explicit_content_level: str
    explicit_content_levels_available: list[str]

PodcastRef

Bases: _Entity

Compact podcast nested in charts / episode payloads.

Source code in deezify/types.py

class PodcastRef(_Entity):
    """Compact podcast nested in charts / episode payloads."""

    title: str
    description: str
    available: bool
    fans: int
    link: str
    share: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str
    position: int

Podcast

Bases: PodcastRef

Full podcast object (GET /podcast/{id}).

Source code in deezify/types.py

class Podcast(PodcastRef):
    """Full podcast object (``GET /podcast/{id}``)."""

EpisodeRef

Bases: _Entity

Compact episode inside podcast.episodes listings.

Source code in deezify/types.py

class EpisodeRef(_Entity):
    """Compact episode inside ``podcast.episodes`` listings."""

    title: str
    release_date: str
    duration: int
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str

Episode

Bases: EpisodeRef

Full episode object (GET /episode/{id}).

Source code in deezify/types.py

class Episode(EpisodeRef):
    """Full episode object (``GET /episode/{id}``)."""

    description: str
    available: bool
    link: str
    share: str
    picture: str
    track_token: str
    podcast: PodcastRef

Radio

Bases: _Entity

Radio object (GET /radio / GET /radio/{id}).

Source code in deezify/types.py

class Radio(_Entity):
    """Radio object (``GET /radio`` / ``GET /radio/{id}``)."""

    title: str
    description: str
    share: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str
    tracklist: str
    md5_image: str

Genre

Bases: _Entity

Genre object (GET /genre / GET /genre/{id}).

Source code in deezify/types.py

class Genre(_Entity):
    """Genre object (``GET /genre`` / ``GET /genre/{id}``)."""

    name: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str

Editorial

Bases: _Entity

Editorial object (GET /editorial).

Source code in deezify/types.py

class Editorial(_Entity):
    """Editorial object (``GET /editorial``)."""

    name: str
    picture: str
    picture_small: str
    picture_medium: str
    picture_big: str
    picture_xl: str

Chart

Bases: TypedDict

Bundle returned by GET /chart and GET /chart/{genre_id}.

Source code in deezify/types.py

class Chart(TypedDict, total=False):
    """Bundle returned by ``GET /chart`` and ``GET /chart/{genre_id}``."""

    tracks: ChartTracks
    albums: ChartAlbums
    artists: ChartArtists
    playlists: ChartPlaylists
    podcasts: ChartPodcasts

EditorialCharts

Bases: TypedDict

Bundle returned by GET /editorial/{id}/charts.

Source code in deezify/types.py

class EditorialCharts(TypedDict, total=False):
    """Bundle returned by ``GET /editorial/{id}/charts``."""

    tracks: ChartTracks
    albums: ChartAlbums
    artists: ChartArtists
    playlists: ChartPlaylists

Infos

Bases: TypedDict

GET /infos — country/API information.

Source code in deezify/types.py

class Infos(TypedDict, total=False):
    """``GET /infos`` — country/API information."""

    country_iso: str
    country: str
    open: bool
    pop: str
    upload_token: str
    upload_token_lifetime: int
    user_token: str | None
    hosts: InfosHosts
    ads: dict[str, Any]
    has_podcasts: bool
    offers: list[Offer]

Options

Bases: TypedDict

GET /options — current-user streaming capabilities.

Source code in deezify/types.py

class Options(TypedDict, total=False):
    """``GET /options`` — current-user streaming capabilities."""

    streaming: bool
    streaming_duration: int
    offline: bool
    hq: bool
    ads_display: bool
    ads_audio: bool
    too_many_devices: bool
    can_subscribe: bool
    radio_skips: int
    lossless: bool
    preview: bool
    radio: bool
    type: str

OEmbed

Bases: TypedDict

GET /oembed?url=... — widget metadata.

Source code in deezify/types.py

class OEmbed(TypedDict, total=False):
    """``GET /oembed?url=...`` — widget metadata."""

    version: str
    type: str
    cache_age: int
    provider_name: str
    provider_url: str
    entity: str
    id: int
    url: str
    author_name: str
    title: str
    thumbnail_url: str
    thumbnail_width: int
    thumbnail_height: int
    width: int
    height: int
    html: str

CreatePlaylistResult

Bases: _Entity

Created playlist id returned by POST /user/{id}/playlists.

Source code in deezify/types.py

class CreatePlaylistResult(_Entity):
    """Created playlist id returned by ``POST /user/{id}/playlists``."""

    title: str

PaginatedEnvelope

Bases: TypedDict, Generic[T]

Raw shape of a list envelope (data/total/next/prev).

Source code in deezify/types.py

class PaginatedEnvelope(TypedDict, Generic[T], total=False):
    """Raw shape of a list envelope (``data``/``total``/``next``/``prev``)."""

    data: list[T]
    total: int
    prev: str
    next: str
    checksum: str