On Wednesday, May 30, 2012 1:46:49 AM UTC-7, stunsch wrote: > > I am willing to invest time developing this. > So Tim and John, if you need help, let's team up and see if we can get > this going. > > Regards, Stefan Tunsch > > I have some down-time, I love to write Python, I am good at C++, and I have received a lot of value from Ledger, so I see this as an opportunity to contribute. I do not want to give the impression that I'm trying to take charge of anything!
With that said, here are the tasks that I was planning to start chipping away at. None of this has been coordinated with John. I would welcome any feedback if my work is misguided. 1. I created a github fork at https://github.com/code-affinity/ledger 2. I want to produce a Python API document. I don't think the majority of Python developers would be comfortable crawling through the C++ code to discover the capabilities. Since the exposed Python functions don't have any docstrings (yet), the usual Pythonic approach to exploration from the Python REPL isn't very productive either. 3. I created a python_api_reference topic branch for this purpose. 4. I've started by editing docs/ledger3.texi to add documentation for each Python class. This is quickly getting large, and the section nesting levels are getting out of hand. I think it might need to be a separate document. Opinions? 5. So far, I'm only listing classes, methods, and properties by name, and listing parameters and return types. There is no descriptive documentation yet. 6. For each method/property, if I see any problems, I'm adding a @comment right in the texinfo document to describe the problem. I was planning to update Bugzilla bug 306<http://bugs.ledger-cli.org/show_bug.cgi?id=306>with my findings once I'm done. Summarizing what I've found so far: 1. Lots of methods that would be more Pythonic if they were represented as read-only properties (for example the xacts() and posts() methods that have been discussed so much in this thread). 2. Several native C++ types need converting to native Python types to be useful to a Python developer. For example, datetime and date, boost::filesystem::path, and perhaps FileInfo. 3. A few C++ containers are returned directly without giving them iterator wrappers first. 4. The C++ code uses boost::optional, and I don't think Boost::Python knows how to wrap that without help, so I think a conversion might be needed to produce the Python None type as appropriate. I could be wrong about that. 7. This process takes a lot of time! I've probably put 20 hours into it so far, and even with this incomplete documentation, I've only finished Account, AccountXData, AccountXDataDetails, Amount, FileInfo, Journal, PostCollectorWapper, and PostHandler. I guess this is about 25% of the overall work required. Ouch! 8. Depending on any feedback from John Wiegley or other interested parties, update the Python bridge implementation, and modify the documentation to match. 9. Fill out the documentation with user-friendly descriptions, perhaps stealing comments from the C++ code where they exist. 10. Modify the Python bridge code to include Python docstrings for each class, method, and property. (This is not hard with boost::python.) Python developers really like their docstrings! 11. Time permitting, I really want to figure out why ledger python segfaults so often. Even if it were feature-complete, the frequent segfaults make it very difficult for me to use and explore. Also, after ledger python exits, my shell is usually in some weird state that doesn't show subsequent typed input. That is also bad for productivity. And none of this involves writing any Python! I don't enjoy this kind of work, but I see it as preparatory for the more-fun stuff. Any feedback? Tim Crews
