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 format
: Runs black and formats each filemake test
: Runs the test suitemake coverage
: Runs the test suite and measures coveragemake docs
: Builds the documentationmake 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*
andexit*
functions must be implemented indjango_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
filesremove unnecessary
pass
statementsremove
else:
afterreturn
casesreformat some
while
andif
conditions according topylint
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.