On Sat, Dec 3, 2016 at 1:48 AM, Stefano Zacchiroli <[email protected]> wrote:
> On Fri, Dec 02, 2016 at 11:28:18AM -1000, Martin Blais wrote: > > > > - people just publish them independently (or keep them private) > > > > Best to start this way IMHO. > > See http://furius.ca/beancount/doc/contrib > > Publish it and I'll add a link there. > > *nod* > > This is now at https://github.com/zacchiro/beancount-plugins-zack . > Thanks! I added a link from the contrib doc so people can find it. Taking inspiration from the other plugins listed on that page, I've put > everything in the root dir, so that people can import it however they > like in their PYTHONPATH. > > It would be useful at some point if you could document best practices or > other expectations on how 3rd party plugins should be "bundled up". That > would make it easy and consistent to use them for Beancount users. > I keep it simple: if it's in your PYTHONPATH, and it has a __plugins__ attribute, it's all good. There's no convention beyond that. Documented here: https://docs.google.com/document/d/1QftxNvQPdH-MikMBHupftU6F4IsNZP5FlFh1LCbVgk8/edit#heading=h.s0kq0i1h7gdl Note: I think most Python projects organize their files a bit differently than Beancount's source code. If Beancount was organized like most projects, its Python source code would be user beancount/beancount/* instead of beancount/src/python/beancount/*. (The reason it's different is that when I rewrote it I wasn't sure which language I'd commit to, so src/<language>/* was how I started.) You may want to follow what other people generally do. I might even change it eventually (it's pretty solidly anchored in Python at this point). > The main difference there is testing. My experience with various OSS > > projects is that many people who share things often provide an > insufficient > > amount of testing, and invariably, adding good test coverage leads to > much > > more work afterwards - you always discover flaws with tests. If you build > > good test coverage it makes it much, much easier to integrate a > submission. > > Beancount has great support for building tests using Beancount syntax in > > docstrings; see the source code itself for examples. > > It would be great if you could document what the expectations are on > that front (e.g., 100% coverage or not?), and how to best integrate with > the main Beancount test suite. I'll then be happy to play guinea pig > for the documented expectations, and submit file_ordering for > integration in the main code base, if you want me to. > If you want examples of testing plugins, see here: https://bitbucket.org/blais/beancount/src/tip/src/python/beancount/plugins/ I would say at the very minimum, every function/method should be called at least once; that's a good baseline. If you have complicated logic, you should have tests that exercise each of the main different use cases. Beyond that, it doesn't have to be exhaustive. For example, if you look at my plugins tests, I think they're a bit on the lighter side of testing IMO. I use the tests to iterate on the source code, I've found it saves me a lot of time. There's really nice helpers to build test input from docstrings, it makes it fun. Otherwise I try to follow the Google style for Python development, except with 4 space indent and underscore_case instead of camelCase. I run pylint (see config under etc/) regularly on everything, and some custom scripts to avoid unwanted dependency order. > I kind-of tried that with Ledgerhub - for sharing importers, I thought > this > > would be popular, alas, so now it's gone - so I think the way it's built > > now it's very flexible (anything in your pythonpath) and I prefer to > keep a > > hands-off approach. I would say, start by building plugins which are > useful > > to you in a separate repo. Share them if you like. I like the idea of > > putting things under github.com/beancount/*, that's why it's there. > Maybe > > in the future banding together with others to make a consolidated repo of > > plugins might be a good idea, if there's a theme. If some of those > provide > > broadly useful functionality and have good test coverage, I'd be happy to > > fold them into the main source code. In general, I like the idea of > letting > > the dust settle a bit and get a fair amount of real usage before doing > that. > > Sounds good to me. > > Cheers > -- > Stefano Zacchiroli . [email protected] . upsilon.cc/zack . . o . . . o . o > Computer Science Professor . CTO Software Heritage . . . . . o . . . o o > Former Debian Project Leader . OSI Board Director . . . o o o . . . o . > « the first rule of tautology club is the first rule of tautology club » > > -- > You received this message because you are subscribed to the Google Groups > "Beancount" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > To view this discussion on the web visit https://groups.google.com/d/ > msgid/beancount/20161203114840.lhqi4cfeztkgst2g%40upsilon.cc. > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "Beancount" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/CAK21%2BhMM_MjDxY3tVve7_z2NBzAe2oW_0Tkoa9NEEj2xPcMzdQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
