Michal Pryc wrote: > Brock Pytlik wrote: > >> Here's a draft of the API that's been discussed previously. Please let >> me know if there are capabilities not provided that the packamanger >> needs that can't easily be handled by extending the progresstracker >> class. The plan is to get the CLI working using the API and take the >> feedback with the goal of having a fairly firm API in 3-4 weeks in the >> gate that the GUI can integrate with. One thing that's still to come >> from an API design perspective is to collect all the exceptions that >> cross the API boundary together into a single module (or small number of >> modules) so that they're accessible and easily tracked. >> >> To be clear, this is a draft. Names, functionality, and nearly anything >> may change. Also, this version of the API is specifically for the most >> dangerous operations, ones that can harm a users system: Install, >> Uninstall, Image-Update, and Refresh. Others like list, search, info, >> etc... will be added to this API in the future, but the first step is to >> get the GUI and the CLI passing through the same interface on the >> critical actions. >> > > > Hello Brock, > I am very happy that you have made this proposal. Well done! > Thanks :-) > I believe that this API will be changing in the next few months and will > eventually become a little more stable, but having this will allow to > track changes very quickly and for sure remove dosen of GUI's duplicated > code. There is some missing functionallity, but we have agreed to go > with critical things in the first cut to make sure we will never break > user system. So we will need to make usage from some methods from > image.py or fmri.py. > Right, eventually the goal is to not have client.py, packagemanager.py, or anything gui/modules/* import any of the inner workings of pkg, but that's a bit further down the line. > What else I would like to see, not necessary in the first cut: > Some functions which will allow to get information about packages > itself. So we can't call any of the API functions if we don't know what > are the packages, which means that some functionallity for getting list > of packages toghether with informations about installed > version/available versions (incorporated)/newest versions is needed. > Adding/removing/changing authorities and mirrors. > Yep, those are all stages 2 or 3 of the API. > For the 2008.11 we will add license tab for packages. If this will be > not provided by the API then we will need to pull the license calling > other methods. > Fair enough, I'll look into adding this since the code isn't already in the GUI implementation. I'll get back to you on this in a day or so. > >> The flow of control for the consumer of a PkgClient object is: >> 1) Create an API object. This establishes which Image the API object is >> associated with and assigns a progresstracker (for simplicity) >> 2) Call either plan_install, plan_uninstall, plan_image_update >> 3) Call prepare >> 4) Call execute_plan >> >> Cancel essentially sends you back one step (so if it's doing 3 and >> cancel is sent, the state will return to 2). >> Reset returns the state to just after step 1. >> > > Will api be back to the initial state after operations which actually > finishes smoothly? > Good point. It probably should be. > I am not entirely convinced by coming back to n-1 step. What happens if > for example someone will call plan_install(["SUNWone"], None) then will > cancel during download operation and call plan_install(["SUNWtwo"), None)? > The short answer is, you (the consumer of the API) can't do that. The API can/will/should blow up if you do this. Or, to put it more simply, right now there's no guarantee that you can call plan_install again immediately after calling plan_install without first calling cancel or reset. Looking at the current implementation, it would probably work, but the API as currently written makes no guarantee that it will continue to. (And before I put the implementation out, I'll probably change it so that it raises an exception.) If that's something that's desired, I can think about what it would take to guarantee it. My instincts though are to give the API exactly the capabilities needed and no more as that retains the greatest freedom for implementation behind the API. Also, the more constrained the use of the API is, the easier it is to test.
In short, my inclination is not to include functionality without a good reason (but I'm happy to add it as needed providing a good reason exists). I also think providing API consumers (not end users) with a short list of rules, like the ones listed above, and expecting them to be followed is a reasonable approach to take. To me, an API is more than a set of functions, it's also information about how those functions fit together and should be used. That's probably way more rambling than you wanted in response to your question, but those are my thoughts. Thanks for taking a look, Brock > best > Michal > > > > > > _______________________________________________ > pkg-discuss mailing list > [email protected] > http://mail.opensolaris.org/mailman/listinfo/pkg-discuss > _______________________________________________ pkg-discuss mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
