Hi Erick,
First of all: Welcome!
On 23 May 2017 at 13:10, Erick Guan (fantasticfears) < fantasticfears@gmail.com> wrote:
I’ve working on to upload a list of natural reserves of China to wikidata recently for WikiLovesEarth. To be frankly, it's awkward to work with the API. Although the project grows faster now.
Some methods triggers the lazy load, while others like constructor can be an empty instance. Some triggers lazy save while others like setTarget might not be saved until addQualifer.
A loaded object doesn't know the difference between the downloaded state and changed state. Especially for the complicate project like wikidata, it makes the debugging hard and error prone.
The naming convention looks different than the document said.
Also, there's not a central place to look for the future development and version management.
So to speak, in my opinion, an ActiveRecord like model seems much more easier to debug. The bot operation should be I/O bounded, it makes sense to lower the burden of debugging/trying.
I think you provide a fair characterization. I think it is important to keep in mind Pywikibot is built by developers who largely are 'scatching an itch', i.e., they want to write a bot to do something on Wikidata, and then add the support to Pywikibot to do so. There is no formal process for designing APIs beforehand, although we do perform code review. Again -- these are things that would be possible if we would have the manpower to do so, but this is (unfortunately) not the case. The same can be said for roadmaps and versioning: we *tried* to maintain a stable version, but this just became a mess. Instead, we are now back on 'trunk-based' development, where we just push a new version to PyPI from trunk every now and then.
At some point, we had an architectural overview for the current version, but I cannot find it anymore. It was meant to follow an ActiveRecord-style interface, where indeed changing properties and then calling .save() is the way to go. Whether this makes sense for Wikibase is less clear to me -- the API provides much more finegrained commands than 'replace the whole JSON blob', and I think it makes sense to use those. How to consolidate that with an ActiveRecord based interface is not entirely clear to me :-)
Specifically on the Wikidata classes, I think Amir (ladsgroup) and Aaron (halfak) are working on a better-designed API, in a seperate project: https://github.com/wikimedia/pywikibot-wikibase
Cheers, Merlijn