Review of project "Alchy"

  • An open source project by Derrick Gilland.

    Link to source:
    Link to documentation:

    Code QualityNone
    Ease of UseNone
    Ease of ContributionNone
    Project InfrastructureNone
    Overall (not an average)None


    Review date: None


    It's "The declarative companion to SQLAlchemy", which already has declarative functionality, but alchy makes me care about SQLAlchemy's declarative_base a lot less. It offers a good deal of convenience over vanilla SQLAlchemy, with focused mainly on making SQLAlchemy declarative style models and queries easier to work with. Models get enhancements like automatic naming (if no __tablename__ exists) and a query attribute (not unlike the Django ORM), while queries get built-in pagination (awesome) and the opportunity to make use of a simpler query syntax like so:

    #!py'', {'user_name': 'fred', 'item_name': 'shoes'}).all()`

    Session management and object life-cycle management is also made easier through the addition of session functions like add_commit, delete_commit, etc.

    Sadly, I wasn't able to get a few of the examples working (namely using search and pagination). The rest, however, functioned as advertised. Once a few kinks are worked out, I can definitely see this package being heavily used. It just makes working with SQLAlchemy (in the way everyone typically works with it) nicer, and those kinds of packages usually end up becoming popular.


    Before I nitpick, I can honestly say the code is fantastic. The package is doing somewhat complicated stuff, but it does it in a clear manner. This will make it easy to contribute to.

    That being said, I ran pylint with the vanilla options and the score was a 5.76/10. Many of the issues pylint picked up were related to line-length, but some (like undocumented functions or, especially, modules) should clearly be fixed.

    While the code is quite readable, it uses a generous amount of Python's inline ternary operation a = b if x else y. When this is combined with code constructs like list comprehensions, it can majorly impact readability. Variable naming is also somewhat inconsistent, as there are a number of 'one letter variables'. for k, v in dictionary.items() isn't terrible, but instances like d = {} should clearly be avoided.

    Overall, however, the code is quite approachable, which I almost found surprising given the complexity of the domain.

    Project Infrastructure

    Awesome. A+. Perfect! This is exactly what you hope to see in an open source Python project. It has a tox.ini file with settings for four different versions of Python (2 and 3). Test coverage is at 100% for all files, which is fantastic (although clearly some cases were missed, given my experience with parts of the package). properly installs and tests the code. Documentation is auto-generated using mkdocs. Continuous Integration is provided by TravisCI (with an associated .travis.yml file) and, at the time of this writing, the build was passing (and coverage was 100%).


    The user documentation is a bit sparse. This is somewhat understandable given it the project has only been used internally by the author and his peers. There was an issue in the first example (easily fixed, and hopefully now non-existent since I sent a pull request for it), but most of the documentation was easy to follow.

    As it describes more complex portions of the code, the documentation falls flat. Especially in the Querying section, it seems to suffer from a case of "the author already knows how to use it-itis". The fact that almost all of the user-facing code is documented in some form, however, was a treat. Sparse parts of the documentation can always be rewritten. Much more difficult is starting from zero.


    While alchy contains a few rough edges, it's not too far from being ready for everyday use.


    A bit of focus on making sure the code samples are clear and work properly, fleshing out the documentation, and making the code even more readable are in order. Ditto for adding a guide for contributors ( Features the author would like to see added, or bugs that are known to exist, should be added to the GitHub "Issues" page. Otherwise, fantastic work.

comments powered by Disqus