Get the source code

Please first fork the repository, then clone it. Every Pull Request is more than welcome!

Note

The following assumes that you have git, Python 3.7+, virtualenv and optionally make installed.

Setup

It is advised to develop a project in a virtual environment.

$ python -m virtualenv venv

All development dependencies are listed in dev_requirements.txt.

$ pip install -r dev_requirements.txt

A Makefile is available with the most common operations that are needed during development. The following targets are available:

  • make lint: Runs black in check mode and pylint

  • make format: Runs black and formats each file

  • make test: Runs the test suite

  • make coverage: Runs the test suite and measures coverage

  • make docs: Builds the documentation

  • make publish: Builds and publishes the package. Should not be used, the same happens for tag creation as a Github Action.

  • make lang: Builds the language with a listener. See below for further information.

If you are not familiar with GNU Make, use that file as reference on how to perform each operation.

Improving the language

When changing the grammar file, the whole runtime should be re-generated by running make lang. That however overwrites some files and introduces a lot of pylint messages. It also generates a new django_nlf/antlr/generated/DjangoNLFListener.py file. There are several things that should be done (currently manually, but any automation is greatly appreciated here):

  • If there were a new parser rule added, the corresponding enter* and exit* functions must be implemented in django_nlf/antlr/listener.py. After that the generated file can be safely deleted.

  • The introduces errors should be corrected, which most of the cases can be simply done by reseting the appropriate changes in the files, namely:

    • reset the changes made to the import section of the generated *.py files

    • remove unnecessary pass statements

    • remove else: after return cases

    • reformat some while and if conditions according to pylint suggestions

The test suite then can verify if old functionality has been kept intact.

Focus points

Functions

Functions are now an experimental feature, and needs a hell lot more testing, and feedback from real life usage. Any reported issue or feature idea is greatly appreciated.

Autocomplete

The biggest bottleneck for quickly introducing the language for your end users is the lack of Autocomplete functionality for the form fields. Any idea on how the supporting APIs should look and how the JS implementation should work is greatly appreciated.

Language housekeeping

The language was developed with no prior language engineering experience, so probably a lot of rationalizations and refactors can be made.

MyPy integration

Typing support is better with every release, but mypy integration is still missing.