Repository: ipython/ipython

Issue:
`Image()` signature/doc improvements
The `Image` call has proved to be remarkably popular, but its signature is a bit awkward. 
- The most common usage I've seen from looking at many notebooks is to call it with a filename, but that's the third positional argument, forcing the vast majority of usage to be done with `Image(filename=...)`, instead of simply `Image(...)`.
- The data argument accepts raw data, a url or a filename, but the signature only mentions urls and data.

I think we should change the signature and dosctring to take simply a url/filename as the first argument, which could be called `pathspec` or `location`.  For backwards compatibility we can continue accepting the keywords `filename` and `url`, but both aren't necessary.  

The much less common usage of calling it with raw data can be relegated to be called with `data = ...`, though it's worth considering for backwards compatibility auto-detection of raw data if the argument is say longer than 10kbytes or so.



Discussion:
The `data` first positional arg is there because this model is uniform across all display classes:

```
DisplayClass(rawdata)
```

Now, it's easy to guess in the Image case if people are passing other info in the first position, and that's exactly what we do now (the docstring just hasn't kept up), but I do not think we should change the name or meaning of the first positional arg.


Resolving patch:
diff --git a/IPython/core/display.py b/IPython/core/display.py
--- a/IPython/core/display.py
+++ b/IPython/core/display.py
@@ -488,11 +488,14 @@ def __init__(self, data=None, url=None, filename=None, format=u'png', embed=None
         Parameters
         ----------
         data : unicode, str or bytes
-            The raw data or a URL to download the data from.
+            The raw image data or a URL or filename to load the data from.
+            This always results in embedded image data.
         url : unicode
-            A URL to download the data from.
+            A URL to download the data from. If you specify `url=`,
+            the image data will not be embedded unless you also specify `embed=True`.
         filename : unicode
             Path to a local file to load the data from.
+            Images from a file are always embedded.
         format : unicode
             The format of the image data (png/jpeg/jpg). If a filename or URL is given
             for format will be inferred from the filename extension.
@@ -512,11 +515,17 @@ def __init__(self, data=None, url=None, filename=None, format=u'png', embed=None
 
         Examples
         --------
-        # embed implicitly True, works in qtconsole and notebook
+        # embedded image data, works in qtconsole and notebook
+        # when passed positionally, the first arg can be any of raw image data,
+        # a URL, or a filename from which to load image data.
+        # The result is always embedding image data for inline images.
         Image('http://www.google.fr/images/srpr/logo3w.png')
+        Image('/path/to/image.jpg')
+        Image(b'RAW_PNG_DATA...')
 
-        # embed implicitly False, does not works in qtconsole but works in notebook if
-        # internet connection available
+        # Specifying Image(url=...) does not embed the image data,
+        # it only generates `<img>` tag with a link to the source.
+        # This will not work in the qtconsole or offline.
         Image(url='http://www.google.fr/images/srpr/logo3w.png')
 
         """


Test patch: