Earlier  
Later
New Search
Posted Nick Remark
#openstack-sdks - 2019-11-06
22:16:23 efried in order to do that for the networking pieces, one would first have to split them into at least separate classes.
22:17:43 efried In any case, what I ended up doing was implementing this three-way code path: We look for neutron, and if we don't find it because it's not there we assume nova-net, but if we don't find it because we can't even ask the question, we assume we're building docs.
22:19:11 efried If neutron, we only run the methods that add neutron opts. If nova-net, likewise.
22:19:12 efried But for the docs fork, we run both; and everywhere we register an option, we decorate its help with "neutron only" or "nova net only" kind of thing.
22:20:06 efried To come full circle, this means that any code path that registers an option used by networking commands needs a way to understand *when* and *how* to add those decorations.
22:20:22 efried the easiest way was with a callable kwarg
22:20:44 efried so that in fact only the caller has to know when/how.
22:21:29 efried And making the default a no-op lambda was easier than having
22:21:30 efried in each of the methods (tags wasn't the only one)
22:21:30 efried help=enhance_help(_(normal))
22:21:30 efried else:
22:21:30 efried help=_(normal)
22:21:30 efried if enhance_help is None:
22:21:43 johnsom So, the odd thing is looking at the nova networks API, it doesn't even have tags
22:21:59 johnsom https://docs.openstack.org/api-ref/compute/?expanded=create-allocate-floating-ip-address-detail#create-allocate-floating-ip-address
22:23:50 johnsom Right, ok, so that is this use case.
22:24:16 efried please also keep in mind that I was trying to make $new_docs look as much like $old_docs as possible with this series. I wasn't getting in the business of figuring out where $old_docs were incorrect or whatever.
22:24:39 johnsom Right
22:25:07 efried ...except insofar as $old_docs had gotten left behind when new options were added, kind of thing.
22:25:17 johnsom There is a bunch of bit-rot in both the nova and neutron docs from what I have seen.. Fixing the API-ref for load balancing was a chore
22:25:23 efried which is one of the purposes of this transition: so you don't have to worry about maintaining two places.
22:26:41 efried Is dtroyer the/a maintainer of osc-lib?
22:27:16 efried Probably need to ask him whether he's willing to let this enhance_help kwarg cross the project boundary
22:27:32 johnsom Yeah I think so. He is the one I talked to when I did the tags move to osc_lib
22:27:41 efried Since the default is a no-op, it's probably not the worst thing in the world, shouldn't hurt callers who don't care about it.
22:28:04 efried I would want to see it documented.
22:28:42 efried ...but it looks like you put nice docstrings in the osc-lib incarnations, so yeah, just following that.
22:29:15 johnsom Yeah, I tried to make it better.
22:29:19 efried ++
22:29:57 efried I guess the way to go about this is to propose that modification to the osc-lib side and use that vehicle to get dtroyer's yea/nay.
22:30:20 efried You want to do that since you did the original, or you want me to do it since I made this mess? (inadvertently, and sorry)
22:30:32 johnsom Well, I didn't do a good job getting his attention to get the python-openstackclient patch merged, so....
22:30:40 dtroyer tbh I really don't like that approach but I don't have the time to do anything differrent. the entire generated docs is a huge compromise anyway so wtf
22:30:57 johnsom dtroyer Hi Dean
22:30:59 dtroyer johnsom: my apologies for that
22:32:24 johnsom I am wondering for tags if we can make a parameter that is more generic and optional and move forward that way. That way for these edge cases we can pass something over to have an annotation.
22:32:37 johnsom Ok, well, at least I understand the issue now.
22:32:51 johnsom efried Let me noodle on it a bit.
22:34:15 efried dtroyer: Yeah, the right thing is probably to split the neutron/nova-net commands/opts into distinct classes (preferably in distinct packages), but I'm not sure how the CLI would decide which entry points to load up.
22:34:48 efried uhh, maybe the framework is already there, because of how we use --os-*-api-versionZ
22:36:07 dtroyer efried: the problem there is there is nobody to do that work. That also needs to be done for volume v2/v3 and has sat there for 2-3 years now
22:37:04 dtroyer and I am now stuck trying to sort out how to deal with the SDK release breaking the snot out of nodepool and cleaning up the mess that made in my 3ci stacks
22:39:34 johnsom I think we can make the tags code in osc_lib take a version qualifier and produce the same result, just by handling the tags params special on the OSC side. I think a generic parameter like "version_qualifier" would be ok for the shared tags code.
22:41:16 efried johnsom: but then you have to duplicate the text, translation, formatting, and conditioning in osc-lib.
22:41:30 efried I suppose you could just *move* it in there, shrug.
22:43:16 johnsom One question I have is we don't call out api versions on any of the other commands right? We just assume the "not implemented" response is clear enough.
22:44:12 efried what do you mean?
22:44:52 johnsom Well, here: https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/network.html#network-create
22:45:15 johnsom --dns-domain only exists on certain versions of neutron API. We don't call that out here.
22:45:55 johnsom Same with --qos-policy which is only available in certain versions of neutron API and with the neutron extension loaded.
22:46:24 efried Yeah, that would be nice. Not a reason to move backwards on neutron vs nova-net though
22:47:10 efried and btw, the "not implemented" response is not necessarily clear.
22:47:49 efried as an osc noob I had a hell of a time figuring out that my under-the-covers microversion wasn't adequate, and how to remedy it.
22:48:27 johnsom I'm just noticing that this is the first time we have added any version information to the python-openstackclient docs.
22:48:28 efried Can't imagine someone trying to figure out why they can't use the --subnet flag
22:48:35 efried oh, no it's not at all
22:48:53 efried The previous version of these same docs had these same decorations.
22:48:54 efried stand by
22:49:00 johnsom Weil, in server create, the micro-versions aren't called out for those commands
22:49:06 efried https://docs.openstack.org/python-openstackclient/train/cli/command-objects/network.html#network-create
22:49:54 efried no, microversions aren't. That would arguably be a nice enhancement. Ideally it would somehow tie back into the client code to discover that automatically, rather than being hardcoded.
22:50:24 efried I'm just saying for neutron vs nova-net, it *was* called out, which is why I didn't see it being a viable path forward to stop doing that when the docs were generated.
22:51:12 efried also fwiw https://docs.openstack.org/python-openstackclient/train/cli/command-objects/role.html identity docs had v2 vs v3 markers.
22:51:21 johnsom were those static pages before?
22:51:22 efried that's major version of course, not microversion.
22:51:24 efried yes
22:51:29 johnsom ah
22:52:41 efried oh, and the way I found out this was even a thing was by trying to build the docs by running both paths. That gives errors on conflicting opts. If you look at the rest of the offending patch, you'll see where I had to put in some pretty weird "if docs build" conditions in some places.
22:53:04 johnsom Yeah, I saw those
22:53:47 efried anyway, as dtroyer implied, there's a right way and there's an expedient way. Unless you're signing up to do the former (I'm not) we're pretty much stuck doing the latter, even though it's kind of distasteful.
22:54:30 johnsom I think we can leave that nastiness in OSC. I'm just working on a way to allow passing that stuff into osc_lib in a more clean way, focused on the tags library for now.
22:54:58 johnsom Well, no good dead goes unpunished. I volunteered to do the tags library work... lol
22:55:25 efried for what it's worth, I played around with other "more clean" options when I was authoring the patch.
22:55:46 efried Believe it or not, this turned out to be the cleanest, from a DRY standpoint.
22:56:12 johnsom So you are advocating for leaving duplicate code in OSC and osc_lib?
22:56:42 efried oh, sorry, no; I'm advocating adding the enhance_help kwarg in osc-lib, properly documented.
22:57:07 efried Yeah, I guess there's two "expedient" solutions, but I was assuming "leave it like it is" (and abandon the removal patch) wasn't on the table.
23:14:17 johnsom Ugh, I really hate having to modify osc_lib again and start this cycle over and I'm not a fan of pulling forward this setup.
23:14:54 openstackgerrit Eric Fried proposed openstack/osc-lib master: WIP: Add enhance_help kwarg to tags option generators https://review.opendev.org/693267
23:15:10 efried johnsom: well, fwiw there's the code side ^
23:16:53 efried I'm out o/
23:16:53 efried I'll let you sleep on it :)
23:24:51 openstackgerrit Michael Johnson proposed openstack/python-openstackclient master: Switch to using osc_lib.utils.tags https://review.opendev.org/662864
23:25:50 johnsom Not sure those jobs are going to pick up that tags library hack patch, so mine is probably going to fail out even with the depends-on.
#openstack-sdks - 2019-11-07
16:00:14 elmiko API SIG office hour is now starting
16:00:26 efried whee
16:00:50 elmiko hehe
16:01:22 efried does the API SIG extend its tentacles into osc ux?
16:02:34 elmiko not specifically, but we have had talks in the past about helping the user community if possible
16:02:42 elmiko sadly, that work never really panned out
16:12:00 dtroyer efried: I'm afraid all of the blame for OSC UX falls on my shoulders (except for putting the resource name in front of the verb. That I resisted for a long time)
16:13:15 efried dtroyer: I'm not slinging blame, I think it's pretty cool given the scope of what it needs to do. I was just going to solicit an opinion on the thing we were talking about last night with johnsom
16:13:57 efried and really ux where u is "developer" more than anything, though there are routes we could take where u is the docs consumer
16:14:33 elmiko efried: from that standpoint, the api-sig explicitly does not get into the business of regular "code" apis
16:14:42 johnsom OSC is a huge leap forward from the old clients. We have also got a lot of positive feedback about it for our project. Just saying....
16:19:53 johnsom That said, yeah, the topic here is good-form for shared library method signatures.
16:21:13 johnsom efried FYI, it looks like the tips job on my patch with the depends-on did pass.
16:21:57 johnsom The others will not pass now until your osc-lib patch merges given the other changes.
16:22:12 efried johnsom: Okay, I hadn't looked yet this morning. IRL we would have to get it released and through u-c and required by python-openstackclient before merging.
16:22:13 johnsom Well, merges, releases, and upper-constraints merges

Earlier   Later