{"action":"created","issue":{"url":"https://api.github.com/repos/marl/jams/issues/29","labels_url":"https://api.github.com/repos/marl/jams/issues/29/labels{/name}","comments_url":"https://api.github.com/repos/marl/jams/issues/29/comments","events_url":"https://api.github.com/repos/marl/jams/issues/29/events","html_url":"https://github.com/marl/jams/issues/29","id":78653111,"number":29,"title":"Streamlining the API","user":{"login":"bmcfee","id":1190540,"avatar_url":"https://avatars.githubusercontent.com/u/1190540?v=3","gravatar_id":"","url":"https://api.github.com/users/bmcfee","html_url":"https://github.com/bmcfee","followers_url":"https://api.github.com/users/bmcfee/followers","following_url":"https://api.github.com/users/bmcfee/following{/other_user}","gists_url":"https://api.github.com/users/bmcfee/gists{/gist_id}","starred_url":"https://api.github.com/users/bmcfee/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bmcfee/subscriptions","organizations_url":"https://api.github.com/users/bmcfee/orgs","repos_url":"https://api.github.com/users/bmcfee/repos","events_url":"https://api.github.com/users/bmcfee/events{/privacy}","received_events_url":"https://api.github.com/users/bmcfee/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/marl/jams/labels/enhancement","name":"enhancement","color":"84b6eb"},{"url":"https://api.github.com/repos/marl/jams/labels/pyjams","name":"pyjams","color":"bfe5bf"},{"url":"https://api.github.com/repos/marl/jams/labels/question","name":"question","color":"cc317c"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/marl/jams/milestones/1","html_url":"https://github.com/marl/jams/milestones/0.2","labels_url":"https://api.github.com/repos/marl/jams/milestones/1/labels","id":1112647,"number":1,"title":"0.2","description":"","creator":{"login":"bmcfee","id":1190540,"avatar_url":"https://avatars.githubusercontent.com/u/1190540?v=3","gravatar_id":"","url":"https://api.github.com/users/bmcfee","html_url":"https://github.com/bmcfee","followers_url":"https://api.github.com/users/bmcfee/followers","following_url":"https://api.github.com/users/bmcfee/following{/other_user}","gists_url":"https://api.github.com/users/bmcfee/gists{/gist_id}","starred_url":"https://api.github.com/users/bmcfee/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bmcfee/subscriptions","organizations_url":"https://api.github.com/users/bmcfee/orgs","repos_url":"https://api.github.com/users/bmcfee/repos","events_url":"https://api.github.com/users/bmcfee/events{/privacy}","received_events_url":"https://api.github.com/users/bmcfee/received_events","type":"User","site_admin":false},"open_issues":6,"closed_issues":4,"state":"open","created_at":"2015-05-15T19:27:50Z","updated_at":"2015-06-01T15:06:04Z","due_on":null,"closed_at":null},"comments":5,"created_at":"2015-05-20T19:10:15Z","updated_at":"2015-06-01T15:45:32Z","closed_at":null,"body":"Still in the interest of minimizing the effort for #26 , I'm looking for ~~corners to cut~~ places in which the API can be streamlined, IMO.\r\n\r\nSince this keeps recurring, I figured we should have a dedicated thread.\r\n\r\n* [`AnnotationArray.create_annotation()`](https://github.com/marl/jams/blob/develop/jams/pyjams.py#L611)  -- construct a new `Annotation`, append it to the end of an existing `AnnotationArray`, and return the new annotation.\r\n\r\nThis is a minor convenience method.  Since both the AnnotationArray and the new Annotation will be in the caller's scope afterwards, I don't see why it's necessary.  For instance, the following are equivalent:\r\n\r\n```python\r\n>>> new_ann = jams.Annotation(namespace='foo', data='bar')\r\n>>> existing_jam.annotations.append(new_ann)\r\n```\r\nvs.\r\n```python\r\n>>> new_ann = existing_jam.annotations.create_annotation(namespace='foo', data='bar')\r\n```\r\nI prefer the former because it's entirely explicit about what's created and where.  In the latter case, appending to the annotation array is a side-effect of construction, which feels a little messy.\r\n\r\nThe only case in which it would make a qualitative difference is when the return value of `create_annotation` is ignored, but you can get the same effect by saying\r\n```python\r\n>>> existing_jam.annotations.append(jams.Annotation(namespace='foo', data='bar'))\r\n```\r\nwhich I think is also more clear, and more \"pythonic\" in that it uses existing API (inherited from list) rather than creating new terminology.\r\n\r\nAny counter-arguments?"},"comment":{"url":"https://api.github.com/repos/marl/jams/issues/comments/107597143","html_url":"https://github.com/marl/jams/issues/29#issuecomment-107597143","issue_url":"https://api.github.com/repos/marl/jams/issues/29","id":107597143,"user":{"login":"bmcfee","id":1190540,"avatar_url":"https://avatars.githubusercontent.com/u/1190540?v=3","gravatar_id":"","url":"https://api.github.com/users/bmcfee","html_url":"https://github.com/bmcfee","followers_url":"https://api.github.com/users/bmcfee/followers","following_url":"https://api.github.com/users/bmcfee/following{/other_user}","gists_url":"https://api.github.com/users/bmcfee/gists{/gist_id}","starred_url":"https://api.github.com/users/bmcfee/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bmcfee/subscriptions","organizations_url":"https://api.github.com/users/bmcfee/orgs","repos_url":"https://api.github.com/users/bmcfee/repos","events_url":"https://api.github.com/users/bmcfee/events{/privacy}","received_events_url":"https://api.github.com/users/bmcfee/received_events","type":"User","site_admin":false},"created_at":"2015-06-01T15:45:32Z","updated_at":"2015-06-01T15:45:32Z","body":"New legit-question time: do we need AnnotationArray?\r\n\r\nArguments in favor of keeping AnnotationArray:\r\n- It's already there, and it works\r\n- It helps contain the search and serialization logic for the annotations\r\n- The serialization logic might be simpler this way\r\n\r\nArguments in favor of ditching it:\r\n- It doesn't correspond to a definition in the JAMS schema\r\n- All it implements now is search and serialization\r\n- `JAMS.search()` is just a wrapper for `AnnotationArray.search()`.  Why not move the search logic up a level?\r\n- Serialization should be automatic anyway\r\n- Any JAMS object has exactly one AnnotationArray object now, so why have a separate class, instead of a primitive (list)?"}}