display_data() function

Author: jlumpe

docs/src/library/public.md

@@ -46,3 +46,9 @@ IJulia.load_string
 IJulia.readprompt
 IJulia.set_max_stdio
 ```
+
+
+## Multimedia display
+```@docs
+IJulia.display_data
+```

src/display.jl

@@ -45,6 +45,51 @@ register_mime(x::AbstractVector{<:MIME}) = push!(ijulia_mime_types, Vector{Mime}
 register_jsonmime(x::Union{MIME, Vector{MIME}}) = push!(ijulia_jsonmime_types, x)
 register_jsonmime(x::AbstractVector{<:MIME}) = push!(ijulia_jsonmime_types, Vector{Mime}(x))
 
+
+# Check mime bundle dict key type and convert to string keys for JSON
+_format_mime_key(k::String) = k
+_format_mime_key(k::MIME) = string(k)
+_format_mime_key(k) = error("MIME bundle keys should be instances of String or MIME")
+_format_mimebundle(d::Dict{String}) = d
+_format_mimebundle(d::AbstractDict) = Dict(_format_mime_key(k) => v for (k, v) in pairs(d))
+
+"""
+    display_data(mime::Union{MIME, String}, data; metadata::Dict=Dict())
+    display_data(mimebundle::Dict; metadata::Dict=Dict())
+
+Publish raw data to be displayed on all Jupyter front ends.
+The first form of the function takes a single MIME type `mime` and encoded data
+`data`, which should be one of the following:
+
+* A string representing plain-text data (e.g. for MIME types `text/html' or
+  `application/javascript`) or base64-encoded binary data (e.g. for `image/png`).
+* Any other value which can be converted to a JSON string by `JSON.json`, including
+  `JSON.JSONText`.
+
+The second form of the function takes a MIME bundle, which is a dictionary of
+all possible representations of the data keyed by MIME type. The front end will
+automatically select the richest supported type to display.
+
+`metadata` is an additional JSON dictionary describing the output. See the
+[jupyter client documentation](https://jupyter-client.readthedocs.io/en/latest/messaging.html#id6)
+for the keys defined by IPython, notable ones are `width::Int` and `height::Int`
+to control the size of displayed images.
+When using the second form of the function, the metadata dictionary may have
+additional sub-dictionaries keyed by specific MIME types.
+"""
+function display_data(mimebundle::AbstractDict, metadata::Dict=Dict())
+    content = Dict("data" => _format_mimebundle(mimebundle), "metadata" => metadata)
+    send_ipython(publish[], msg_pub(execute_msg, "display_data", content))
+end
+
+function display_data(mime::Union{MIME, AbstractString}, data, metadata::Dict=Dict())
+    mt = string(mime)
+    d = Dict{String, Any}(mt => data)
+    mt != "text/plain" && (d["text/plain"] = "Unable to display data with MIME type $mt")  # Fallback
+    display_data(d, metadata)
+end
+
+
 # return a String=>Any dictionary to attach as metadata
 # in Jupyter display_data and pyout messages
 metadata(x) = Dict()