An open source project by Derrick Gilland.
| Metric | Score | Rationale |
| Documentation | | None |
| Code Quality | | None |
| Ease of Use | | None |
| Ease of Contribution | | None |
| Project Infrastructure | | None |
| Overall (not an average) | | None |
Review
Review date: None
Project
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.query.search('example.com', {'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.
Code
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). setup.py 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%).
Documentation
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.
Summary
While alchy contains a few rough edges, it's not too far from being ready for
everyday use.
Recommendations
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
(CONTRIBUTING.md). 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.