>>>>> Tim Crews <[email protected]> writes: > 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 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.
This is fantastic, Tim. I hope you can get to the Python part sooner rather than later! I'll help you with the segfaults as you go, though my time may be a little limited this summer (several work contracts ongoing). John
