That documentation completely misses the point :( There's no list of what actions to use in the factory, or that a login action has setPassword method (as you're using the magic method __set(), those things aren't listed by phpDocumentor). It's that kind of things what I'd want to view (or an explanation on how to map the api documentation to dementia).
Like most generated documentation, the audience is more developers than end users (I hope to do a better write-up soon for end users, including what the core goals of the framework are, but I'm aware that my progress is slow at the moment). All of the methods to use on an Action or Query instance *are* listed, though; you can get variables, set variables, and execute, and that's it.
The variables you can get or set depend on what action or query is specified, but there is not a separate framework class for each action or query. The variables are by necessity defined in the API documentation (e.g. http://www.mediawiki.org/wiki/API:Allpages) and not the framework documentation; while I could write up examples using the framework for each type of action and query, I couldn't possibly cover the sheer breadth of options that are available in the API.
The point at the moment is that the framework automagically handles all prefixing of parameters, including generators' parameters, so the end user's code is more readable; it also continues queries automatically and selects an appropriate backend for actions and queries (which is its primary purpose).
Does that make more sense? -Madman
On 20/03/12 22:37, [[w:en:User:Madman]] wrote:
Like most generated documentation, the audience is more developers than end users (I hope to do a better write-up soon for end users, including what the core goals of the framework are, but I'm aware that my progress is slow at the moment). All of the methods to use on an Action or Query instance *are* listed, though; you can get variables, set variables, and execute, and that's it.
"Documentation designed for libary developers, useless for developers using the library" isn't a good slogan either :)
The variables you can get or set depend on what action or query is specified, but there is not a separate framework class for each action or query. The variables are by necessity defined in the API documentation (e.g. http://www.mediawiki.org/wiki/API:Allpages)
I expected something like that. How are you doing the db backend? Are you loading MediaWiki and using a FauxRequest?
and not the framework documentation; while I could write up examples using the framework for each type of action and query, I couldn't possibly cover the sheer breadth of options that are available in the API.
Well, I'd expect a handful of examples from which the pattern would b easy to infer, plus some explanation for when you need to use a new module for which there's no example.
The point at the moment is that the framework automagically handles all prefixing of parameters, including generators' parameters, so the end user's code is more readable; it also continues queries automatically and selects an appropriate backend for actions and queries (which is its primary purpose).
It even does more than I expected.
Does that make more sense?
Heh, I never doubted it was useful. I was just a bit.. deceived by the documentation.
My point is, if I wanted to perform an api query which I had. I have no idea how to do that with your library. When should the parameters be prefixed and when not, for instance.
Not to mention if I wanted to translate a more complex query with a generator, such as: https://commons.wikimedia.org/w/api.php?action=query&generator=search&am...
Best regards
On Tue, Mar 20, 2012 at 7:45 PM, Platonides platonides@gmail.com wrote:
"Documentation designed for libary developers, useless for developers using the library" isn't a good slogan either :)
Touche. ;) I'm probably going to start the end user documentation on-wiki, starting at [[User:Madman/Dementia]] which may move into project space at some point; I hope those interested in the framework will contribute. :)
I expected something like that. How are you doing the db backend? Are you loading MediaWiki and using a FauxRequest?
Yep. Obviously, there are some limitations to this approach; for example, DementiaRequest falls back to the HttpBackend when an edit token's requested as there's no way for it to get session data and edit tokens aren't based on database information. I hope to mitigate some of these limitations in time, with caching and the like, but if the worst case is using HTTP, which would have been used anyway... eh. I just hope all the cases where DbBackend will be useful aren't edge cases.
This does necessitate having a working copy of MediaWiki, which has to be patched in two places (a script does this automatically) so it doesn't attempt to expire blocks (which it would attempt to do even when $wgReadOnly is set) and so the option to force a given index is ignored (because the Toolserver doesn't have some-- maybe most-- of those indexes). In the long run, I hope to strip the files that need to be checked out to the bare essentials and I'm always open to better suggestions (including "wtf were you thinking? Using <x> is ten times as obvious"). I frequently miss the obvious.
Well, I'd expect a handful of examples from which the pattern would b easy to infer, plus some explanation for when you need to use a new module for which there's no example.
Will do. :) I'll probably use each of the API's examples and show how to execute the request via the framework and explain which backend it would use. (I run unit tests against each of the API's examples anyhow.)
The point at the moment is that the framework automagically handles all prefixing of parameters, including generators' parameters, so the end user's code is more readable; it also continues queries automatically and selects an appropriate backend for actions and queries (which is its primary purpose).
It even does more than I expected.
Also the benefit I forgot is never having to write SQL queries for common queries (categorymembers and the like) since the backend knows how to do that.
My point is, if I wanted to perform an api query which I had. I have no idea how to do that with your library. When should the parameters be prefixed and when not, for instance.
NEVAR. :p
Not to mention if I wanted to translate a more complex query with a generator, such as: https://commons.wikimedia.org/w/api.php?action=query&generator=search&am...
In case you're curious:
$search = DementiaQuery::factory('search'); $search->setSearch('"chartres cathedral"')->setNamespace(6); $search->setOffset(20)->setLimit(20); $imageinfo = DementiaQuery::factory('imageinfo'); $imageinfo->setProp('url'); $imageinfo->generator = $search; // just to show both ways of setting parameters while ($pages = $imageinfo->execute()) {} // this will loop, continuing the query automatically until no more results are available
Unfortunately this too would use the HttpBackend as the Toolserver doesn't have the searchindex table. But I do like the syntax.
Madman
On 21/03/12 01:20, [[w:en:User:Madman]] wrote:
This does necessitate having a working copy of MediaWiki, which has to be patched in two places (a script does this automatically) so it doesn't attempt to expire blocks (which it would attempt to do even when $wgReadOnly is set)
$wgReadOnly no longer means "don't write to the db ever", but if it gives problems with a ro db, maybe we could fix it somewhere so you don't need to patch it.
and so the option to force a given index is ignored (because the Toolserver doesn't have some-- maybe most-- of those indexes).
I think they are there, in the underlying tables. It's just not that we can't view or use them from the views, which is what we access to. It's a pity, when we know the optimum SQL queries using force index, but I see the point of the approach, as they could be abused in tables with only partial columns shown, and private ones covered by the indexes.
On Fri, Mar 30, 2012 at 7:05 PM, Platonides platonides@gmail.com wrote:
$wgReadOnly no longer means "don't write to the db ever", but if it gives problems with a ro db, maybe we could fix it somewhere so you don't need to patch it.
I do understand $wgReadOnly means MediaWiki may still write to the database, per the documentation; perhaps, though, an error from MySQL that the server's running with --read-only (which was the case when I tested) shouldn't be fatal, at least not to a list=blocks request.
I think they are there, in the underlying tables. It's just not that we can't view or use them from the views, which is what we access to. It's a pity, when we know the optimum SQL queries using force index, but I see the point of the approach, as they could be abused in tables with only partial columns shown, and private ones covered by the indexes.
The indexes I've verified we don't have that would be forced are oi_name_timestamp, rc_timestamp, pl_namespace, page_random, el_index, name_title, cl_sortkey, times, and usertext_timestamp. I can't imagine almost any of these are for privacy reasons, so I just assumed it was for performance reasons.
(Also, please note that I'm putting at least public work on Dementia on hold for a little bit, as my full-time job has just been insane lately and I don't have the time to dedicate to it and its potential users that it deserves.)
-Madman
On 04/04/12 20:44, [[w:en:User:Madman]] wrote:
On Fri, Mar 30, 2012 at 7:05 PM, Platonides platonides@gmail.com wrote:
$wgReadOnly no longer means "don't write to the db ever", but if it gives problems with a ro db, maybe we could fix it somewhere so you don't need to patch it.
I do understand $wgReadOnly means MediaWiki may still write to the database, per the documentation; perhaps, though, an error from MySQL that the server's running with --read-only (which was the case when I tested) shouldn't be fatal, at least not to a list=blocks request.
Interesting. Can you provide a simple test case? (eg. block this, restart mysql ro, visit this url).
Also, can you provide the MediaWiki patches you needed? I took a look at your home, but didn't see it.
I think they are there, in the underlying tables. It's just not that we can't view or use them from the views, which is what we access to. It's a pity, when we know the optimum SQL queries using force index, but I see the point of the approach, as they could be abused in tables with only partial columns shown, and private ones covered by the indexes.
The indexes I've verified we don't have that would be forced are oi_name_timestamp, rc_timestamp, pl_namespace, page_random, el_index, name_title, cl_sortkey, times, and usertext_timestamp. I can't imagine almost any of these are for privacy reasons, so I just assumed it was for performance reasons.
We are working from views, the indexes are in the tables.
toolserver-l@lists.wikimedia.org