Coding Style

This document describes some of the stylistic patterns in LCS and is intended for people making their own version.

First, this document covers the enforcement of JSON schema (with needless talk of continuation passing style and declarative programming). Then testing and linting are covered and finally, travis is touched upon.

JSON Validation

The input type of the API is JSON, so to ensure validity, JSON validation is paramount. We use the jsonschema library to do this validation.

The main use of this is in the ensure_schema decorator: this decorator puts the JSON validation before the function is executed. You can customize what this function does on failure, but you'll notice that we seldom do.

The schema.py file has two other utilites: a general function that provides users and one that ensures that the user provided has the roles expected. The three utilities mentioned above let us us continuation passing style to modularize the code and abstract the same control-flow decisions into the same functions. Additionally, a great boon of the schema library is that this makes the code declarative which, in this oversimplification, means that it's readable. We do not care how the JSON schema is validated, so in the code we focus on highlighting what is validated. This also allows for security and safety: the schema library does not miss corner-cases that we did in our hand-implementation. You can also see that, in testing, using JSON schemas lets us clearly specify what we expect from the outputs and provide stronger gaurantees there.

Testing and Linting

Testing

Read the contributing docs to have python properly set up.

We use pytest and have a unit-testing coverage of between 25% and 30%. You can test by pretty much having a test database. Using that configuration, running at the project root python -m pytest --cov=. suffices.

You write tests in the tests folder. You basically just assert that the JSON you get from the functions are the JSON you expect. Python importing voodoo lets you just import the files from the project root into the test file. The ordering of the tests is semi-important: it ensures that users you've created for tests are destroyed only after they're used. (This also makes sure that user creations works as you'd expect it to if you run the tests again.)

Testing relative to third parties is much more difficult and due to travis, unlikely to happen without some encryption. That's a transition...

JK,

Linting

We don't lint enough. There are some syntax issues that will be caught in the linting, but there are severe limitations, mostly due to a lack of research.

The largest issue is that the ensure_logged_in_user utility causes the linter to fail. (It's actually a pylint issue.) This is because correct usage changes the number of parameters passed into the decorated function: after decorating, the user parameter is automatically passed in to the undecorated function.

Travis

We use travis to run tests on all the pushes. It runs LCS in a container with a dedicated MongoDB. In there, it runs the tests and succeeds only if the coverage conditions are met and all tests passed.

You can see our builds online. The set up is in the .travis.yml file.