{"action":"created","issue":{"url":"https://api.github.com/repos/astropy/astropy/issues/5186","repository_url":"https://api.github.com/repos/astropy/astropy","labels_url":"https://api.github.com/repos/astropy/astropy/issues/5186/labels{/name}","comments_url":"https://api.github.com/repos/astropy/astropy/issues/5186/comments","events_url":"https://api.github.com/repos/astropy/astropy/issues/5186/events","html_url":"https://github.com/astropy/astropy/issues/5186","id":166134860,"number":5186,"title":"Initializer signature/docstring for astropy.wcs.WCS omits mention of filename-based initialization","user":{"login":"josePhoenix","id":172886,"avatar_url":"https://avatars.githubusercontent.com/u/172886?v=3","gravatar_id":"","url":"https://api.github.com/users/josePhoenix","html_url":"https://github.com/josePhoenix","followers_url":"https://api.github.com/users/josePhoenix/followers","following_url":"https://api.github.com/users/josePhoenix/following{/other_user}","gists_url":"https://api.github.com/users/josePhoenix/gists{/gist_id}","starred_url":"https://api.github.com/users/josePhoenix/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/josePhoenix/subscriptions","organizations_url":"https://api.github.com/users/josePhoenix/orgs","repos_url":"https://api.github.com/users/josePhoenix/repos","events_url":"https://api.github.com/users/josePhoenix/events{/privacy}","received_events_url":"https://api.github.com/users/josePhoenix/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/astropy/astropy/labels/Docs","name":"Docs","color":"02d7e1"},{"url":"https://api.github.com/repos/astropy/astropy/labels/wcs","name":"wcs","color":"c7def8"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":2,"created_at":"2016-07-18T16:24:14Z","updated_at":"2016-08-03T21:42:43Z","closed_at":null,"body":"I was recently demonstrating the use of `astropy.wcs.WCS` in a class where I asked people to consult the docstring to figure out how to initialize the WCS from a file. It was only then that I realized the concise form of initializing a WCS (the one I actually use all the time) is totally non-obvious from the docs!\r\n\r\nOn the [main WCS module page](http://docs.astropy.org/en/stable/wcs/index.html), there's an example that goes\r\n\r\n```\r\n>>> from astropy.wcs import WCS\r\n>>> w = WCS('image.fits')\r\n>>> lon, lat = w.all_pix2world(30, 40, 0)\r\n>>> print(lon, lat)\r\n```\r\n\r\nIf you were to look at [the WCS class docs](http://docs.astropy.org/en/stable/api/astropy.wcs.WCS.html#astropy.wcs.WCS) you could be forgiven for being somewhat confused as to how the first argument to the initializer is interpreted in that example. The relevant text:\r\n\r\n> `class astropy.wcs.WCS(header=None, fobj=None, key=u' ', minerr=0.0, relax=True, naxis=None, keysel=None, colsel=None, fix=True, translate_units=u'', _do_set=True)`\r\n>\r\n> `header` : astropy.io.fits header object, Primary HDU, Image HDU, string, dict-like, or None, optional\r\n> If header is not provided or None, the object will be initialized to default values.\r\n\r\nI can probably make a PR for this if people agree the docstring should be improved. If there's canned text used in other places where Astropy takes filenames as strings in addition to the more explicit passing of the right kind of object, I can use that. (Just point me to an example!)"},"comment":{"url":"https://api.github.com/repos/astropy/astropy/issues/comments/237383902","html_url":"https://github.com/astropy/astropy/issues/5186#issuecomment-237383902","issue_url":"https://api.github.com/repos/astropy/astropy/issues/5186","id":237383902,"user":{"login":"astrofrog","id":314716,"avatar_url":"https://avatars.githubusercontent.com/u/314716?v=3","gravatar_id":"","url":"https://api.github.com/users/astrofrog","html_url":"https://github.com/astrofrog","followers_url":"https://api.github.com/users/astrofrog/followers","following_url":"https://api.github.com/users/astrofrog/following{/other_user}","gists_url":"https://api.github.com/users/astrofrog/gists{/gist_id}","starred_url":"https://api.github.com/users/astrofrog/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/astrofrog/subscriptions","organizations_url":"https://api.github.com/users/astrofrog/orgs","repos_url":"https://api.github.com/users/astrofrog/repos","events_url":"https://api.github.com/users/astrofrog/events{/privacy}","received_events_url":"https://api.github.com/users/astrofrog/received_events","type":"User","site_admin":false},"created_at":"2016-08-03T21:42:43Z","updated_at":"2016-08-03T21:42:43Z","body":"> The support for initialization from string (file name) is so bad that I would rather remove its mention at all until a better implementation is provided\r\n\r\nI use this all the time and I think other people will be using it too - we don't have the option to remove this without breaking a lot of user code unfortunately, since I know that I at least have shown it to quite a few people..."}}
{"actor":{"display_login":"astrofrog"}}