| *** e0ne has quit IRC | 00:49 | |
| *** kaufer has joined #openstack-api | 02:09 | |
| *** kaufer has quit IRC | 02:57 | |
| *** jamie_h has joined #openstack-api | 10:46 | |
| *** etoews has joined #openstack-api | 11:29 | |
| *** cdent has joined #openstack-api | 11:52 | |
| *** terrylhowe has joined #openstack-api | 11:58 | |
| *** annegentle has joined #openstack-api | 12:36 | |
| *** sigmavirus24_awa is now known as sigmavirus24 | 12:39 | |
| *** kaufer has joined #openstack-api | 13:25 | |
| *** annegentle has quit IRC | 14:10 | |
| *** annegentle has joined #openstack-api | 14:15 | |
| *** annegentle has quit IRC | 14:54 | |
| *** annegentle has joined #openstack-api | 15:23 | |
| kaufer | In the resource counting review https://review.openstack.org/#/c/147684/7/guidelines/counting.rst sigmevirus24 had a comment to define what is "truthy" and "falsey", do we have an existing doc to put this information in? Or any thoughts on if I should create a new miscellaneous.rst file? | 15:59 |
|---|---|---|
| kaufer | oops ... sigmavirus24 ^ | 16:00 |
| sigmavirus24 | kaufer: let me think about that for a few | 16:01 |
| kaufer | sigmavirus24: Sure, this seemed like the best fit but I wasn't sure if it was the right: https://github.com/openstack/api-wg/blob/master/guidelines/general.rst | 16:02 |
| sigmavirus24 | yeah it might be | 16:03 |
| elmiko | that might be a nice place, i wonder if we need a "types.rst" or something similiar? | 16:03 |
| *** annegentle has quit IRC | 16:06 | |
| sigmavirus24 | so | 16:08 |
| sigmavirus24 | I think truthy and falsey are more specific to the query parameters in that case, yes? | 16:08 |
| kaufer | In this case yes | 16:08 |
| sigmavirus24 | Right, but in what other cases is it ambiguous is what I am trying to ask | 16:08 |
| sigmavirus24 | JSON: Not ambiguous | 16:09 |
| sigmavirus24 | XML: No longer relevant =P | 16:09 |
| sigmavirus24 | I'm not sure where else we need booleans in an API where truthy/falsey aren't predefined by something else | 16:09 |
| sigmavirus24 | So if it's just for query parameters, in what cases do we use truthy/falsey values in query parameters, etc. | 16:09 |
| sigmavirus24 | I think answering those questions will help us decide where to put the reference. | 16:09 |
| sigmavirus24 | We can always move it elsewhere if we change our minds as a matter of structuring | 16:10 |
| kaufer | So I know that similiar logic is also used for the all_tenants query string parameter, I've seen that in nova | 16:10 |
| kaufer | https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/servers.py#L195-L196 | 16:11 |
| kaufer | I can do a search for the 'bool_from_string' function to find other hits | 16:11 |
| kaufer | sigmavirus24: Is that what you are looking for? | 16:12 |
| stevelle | sigmavirus24: kaufer wondering if existing filtering options do truthy values in query strings. In glance & ceilometer possibly | 16:13 |
| sigmavirus24 | kaufer: yeah | 16:16 |
| kaufer | stevelle, sigmavirus24: I'll dig into that and see what I can find | 16:16 |
| sigmavirus24 | kaufer: yeah I just can't imagine this being necessary other than in query strings | 16:16 |
| sigmavirus24 | but I'm sure there's exactly one project using it elsewhere =P | 16:16 |
| kaufer | sigmavirus24: Yes, I think that it is only in query string as well, since it is clearly defined in a request body | 16:18 |
| sigmavirus24 | Right, and we only send query strings for list operations where we would be doing searching filtering etc. right? | 16:18 |
| sigmavirus24 | So I think it needs to at least be referenced there | 16:19 |
| kaufer | sigmavirus24: Yep, AFAIK | 16:19 |
| sigmavirus24 | Not sure if we need a separate section on query parameters in general or not though | 16:20 |
| sigmavirus24 | Which might be the place for this but yeah, I can't imagine there's much to say about query parameters | 16:20 |
| kaufer | sigmavirus24: I'm envisioning the reference in our docs to be really simple for this (ie, use oslo bool_from_string function) so that's what I was thinking that we may want to have a miscellaneous file to put things like this in | 16:20 |
| kaufer | since we will need to reference it from more then 1 guideline doc | 16:21 |
| sigmavirus24 | So, we have yet to call out a specific function etc | 16:21 |
| sigmavirus24 | And to be honest, I'd rather it be more explicit and opinionated | 16:21 |
| sigmavirus24 | *function, library, etc. | 16:21 |
| sigmavirus24 | bool_from_string is also very very very accepting right? It'll accept 1, true, True, and other things right? | 16:22 |
| miguelgrinberg | sigmavirus24: yes: http://docs.openstack.org/developer/oslo.utils/api/strutils.html#oslo_utils.strutils.bool_from_string | 16:23 |
| sigmavirus24 | recommending bool_from_string also ties the guideline to the implementation instead of the other way around | 16:23 |
| sigmavirus24 | miguelgrinberg: yeah was just reading that | 16:23 |
| sigmavirus24 | I'm not sure how often we really need anything other than "true" or "false" though | 16:23 |
| miguelgrinberg | didn't know this was available, I agree with recommending it | 16:23 |
| miguelgrinberg | 1 and 0 are nice to have too | 16:24 |
| kaufer | 1 equates to True | 16:24 |
| sigmavirus24 | right | 16:24 |
| miguelgrinberg | and then you have javascript's true vs. Python's True | 16:24 |
| sigmavirus24 | miguelgrinberg: can you quantify how many times people would rather someone give you 1 to represent true instead of "true"? | 16:25 |
| sigmavirus24 | I mean, assuming you don't want modern technology to behave like C. | 16:25 |
| miguelgrinberg | don't know, but yesterday was working on my PyCon talk and used 1 for an option | 16:25 |
| miguelgrinberg | because it is shorter | 16:25 |
| miguelgrinberg | basically my thinking is to set the variable to any value for true, and not include it in the query string at all for false | 16:26 |
| miguelgrinberg | given those rules, setting var=1 is the less effort choice | 16:26 |
| sigmavirus24 | miguelgrinberg: what if the default is true and it needs to be disabled? | 16:26 |
| miguelgrinberg | good point. I tend to turn things around so that always the default is false | 16:27 |
| miguelgrinberg | I think having a true default on a query string var is confusing | 16:27 |
| miguelgrinberg | but in any case, using bool_from_string handles that well | 16:28 |
| miguelgrinberg | the discussion was about whether 1 and 0 are useful or not | 16:28 |
| kaufer | In that case wouldn't the user would pass ‘f’, ‘false’, ‘off’, ‘n’, ‘no’, or ‘0’ to override? All those equate to False and are handled by that function | 16:28 |
| sigmavirus24 | kaufer: right, we got side-tracked into whether every boolean query param should be false by default | 16:29 |
| miguelgrinberg | kaufer: yes, that's correct | 16:29 |
| miguelgrinberg | my fault, sorrty | 16:29 |
| sigmavirus24 | s/my/our/ | 16:29 |
| sigmavirus24 | I guess this boils down to "be liberal in what you accept" | 16:29 |
| kaufer | So I agree that in general we wouldn't want to recommend specific functions/libraries ... but in this case it seems like this function is the standard for this type of processing and I think that we need to make it easy to find in our guideline docs | 16:30 |
| sigmavirus24 | I still would rather have the spec itself call out acceptable values. I don't think guidelines should ever be tied to implementation details of a utility function in anything | 16:30 |
| sigmavirus24 | kaufer: a .. note:: that it exists won't bother me | 16:30 |
| sigmavirus24 | A "you should use this because we're recommending it" would bother me | 16:31 |
| miguelgrinberg | it should be there as a note to clients as well, they don't have a function to come up with the accepted values | 16:31 |
| kaufer | sigmavirus: Yes, that makes sense, I think that we need to note that it is an option but let them decide if they want to use it | 16:31 |
| sigmavirus24 | Cool. | 16:32 |
| kaufer | Ok, so then back to my original question, any thoughts on where this note would link? | 16:32 |
| sigmavirus24 | Yeah, not sure about that still =P | 16:32 |
| sigmavirus24 | Perhaps a separate query parameter section just to air on the side of "We may have more to say on this" | 16:33 |
| kaufer | I can see this being referenced from the counting guideline and from the filtering one (once that TODO is done) | 16:33 |
| sigmavirus24 | Agreed | 16:33 |
| sigmavirus24 | that's what :ref: is for ;) | 16:33 |
| kaufer | Yep, just wanted to point out that it will be referenced from more then 1 guideline doc | 16:34 |
| elmiko | that's why i was saying maybe we need a document about types in general | 16:34 |
| sigmavirus24 | Yep | 16:34 |
| sigmavirus24 | elmiko: what other types would we talk about? | 16:34 |
| sigmavirus24 | I really don't have strong feelings on where it needs to live | 16:34 |
| elmiko | i dunno, just trying to be cautious about running across this again | 16:34 |
| sigmavirus24 | And we can always restructure our text more later | 16:34 |
| elmiko | true, it's not a huge deal | 16:34 |
| sigmavirus24 | It can even live with the searching/filtering/pagination docs now | 16:34 |
| sigmavirus24 | although I was hoping we might split those out into separate docs though | 16:35 |
| elmiko | i guess the original impulse to put it in the general doc makes the most sense lol | 16:35 |
| kaufer | sigmavirus24: +1 ... I'd like to see them split | 16:35 |
| sigmavirus24 | elmiko: yeah | 16:35 |
| sigmavirus24 | works for me | 16:35 |
| kaufer | another option would be to create a doc whose purpose is to recommend specific functions/libraries | 16:36 |
| kaufer | with a disclamer that you don't have to use them, but that they exist | 16:36 |
| elmiko | that's an interesting thought | 16:36 |
| elmiko | i'm not sure how far down the implementation road we want to walk though | 16:36 |
| kaufer | right, thus far we have been avoiding recommending specific libraries ... but i think that this is an exception | 16:37 |
| kaufer | not sure if there will be others, so maybe it's the wrong approach | 16:37 |
| stevelle | that path leads us to strongly recommending a bunch of oslo libs or the like which raises a bunch of implementation concerns. I'd prefer to note that the code has been written and leave it at that. | 16:40 |
| elmiko | i don't see an issue with adding language to the general section that calls out usage of "True" and "False" in the guidelines, that may be safest for now | 16:40 |
| kaufer | I agree, so here's my plan: Update the general.rst file with a new section for boolean query string parameters and reference the oslo lib there ... objections? | 16:44 |
| sigmavirus24 | so I'd like to never ever add library recommendations | 16:44 |
| sigmavirus24 | that leads us to pecan, jsonschema, warwhatever, wsgi, flask, django-rest, etc. | 16:44 |
| elmiko | sigmavirus24++ | 16:45 |
| sigmavirus24 | I'd love to stay away from that quagmire with a 500 mile pole | 16:45 |
| sigmavirus24 | Or 500 mile email whatever | 16:45 |
| elmiko | kaufer: if you've got a strong idea, i'd say throw it up for review. sounds like the lib language might get clipped, but at least we can start discussing the actual phrasing then. | 16:46 |
| kaufer | sigmavirus24: I agree, but I think that we need something here ... so when I prototyped the nova server counting work I wrote my own utility function to figure out what was True and False, then I found the oslo one, I'm trying to avoid that for others with a simple heads up that let's them know that this lib exists and that they can use it if they want to | 16:47 |
| sigmavirus24 | kaufer: like I said, a .. note:: that it exists doesnt' bother me | 16:48 |
| sigmavirus24 | A list of recommendations does | 16:48 |
| sigmavirus24 | And a list of recommendations will never make it through | 16:48 |
| kaufer | sigmavirus24: Maybe I'm misunderstanding what you think that note:: will reference; are you thinking that it will reference another guideline doc or just reference the lib function directly? | 16:49 |
| sigmavirus24 | kaufer: .. note:: is a directive in Sphinx and it creates a call out | 16:51 |
| sigmavirus24 | See http://toolbelt.readthedocs.org/en/latest/adapters.html#socketoptionsadapter for examples | 16:51 |
| sigmavirus24 | That note will simply say: "A function to convert these values to a boolean already exists in oslo_utils.strutils" | 16:52 |
| kaufer | sigmavirus24: Ok, that makes sense ... so that negates the need for a separate topic in a guideline doc, I like that approach | 16:52 |
| sigmavirus24 | Or "already exists in oslo.utils. See <link-to-docs>oslo_utils.strutils.boolean_from_string</link> for more details" | 16:52 |
| sigmavirus24 | And restructuredtext cares not how many notes you have: http://toolbelt.readthedocs.org/en/latest/adapters.html#tcpkeepaliveadapter | 16:53 |
| elmiko | ..note seems like a nice solution | 16:53 |
| sigmavirus24 | I wish there was a .. disclaimer:: | 16:54 |
| kaufer | :) | 16:54 |
| elmiko | lol | 16:54 |
| kaufer | I'll push up something with the ..note and we can see how that looks | 16:54 |
| kaufer | thanks all for the discussion, sorry that it got more involved then it needed to | 16:55 |
| stevelle | it's better thoroughly discussed an logged :) | 16:57 |
| sigmavirus24 | OH RIGHT WE HAVE LOGS | 16:57 |
| sigmavirus24 | I KEEP FORGETTING | 16:57 |
| elmiko | stevelle++ | 16:58 |
| *** annegentle has joined #openstack-api | 17:07 | |
| *** annegentle has quit IRC | 17:55 | |
| *** annegentle has joined #openstack-api | 17:55 | |
| *** annegentle has quit IRC | 18:08 | |
| openstackgerrit | Steven Kaufer proposed openstack/api-wg: Add oslo.utils note to counting guidelines https://review.openstack.org/162716 | 18:52 |
| kaufer | sigmavirus24: Hopefully that is what you had in mind ^ | 18:53 |
| * sigmavirus24 queues it up for reading time | 18:56 | |
| *** e0ne has joined #openstack-api | 19:38 | |
| *** annegentle has joined #openstack-api | 19:46 | |
| openstackgerrit | Steven Kaufer proposed openstack/api-wg: Add oslo.utils note to counting guidelines https://review.openstack.org/162716 | 19:53 |
| *** e0ne has quit IRC | 20:06 | |
| *** e0ne has joined #openstack-api | 20:06 | |
| *** cdent has quit IRC | 20:30 | |
| *** sigmavirus24 is now known as sigmavirus24_awa | 21:41 | |
| *** jamie_h has quit IRC | 21:47 | |
| *** kaufer has quit IRC | 21:51 | |
| *** annegentle has quit IRC | 22:19 | |
| *** annegentle has joined #openstack-api | 22:21 | |
| *** openstack has joined #openstack-api | 22:25 | |
| *** annegentle has quit IRC | 22:26 | |
| *** annegentle has joined #openstack-api | 22:27 | |
| *** annegentle has quit IRC | 23:03 | |
| *** e0ne has quit IRC | 23:13 | |
| *** sigmavirus24_awa is now known as sigmavirus24 | 23:20 | |
| *** openstack has joined #openstack-api | 23:24 | |
| *** sigmavirus24 is now known as sigmavirus24_awa | 23:33 | |
Generated by irclog2html.py 2.14.0 by Marius Gedminas - find it at mg.pov.lt!