This section describes the Pykaryote development workflow. It covers topics such as git, coding style, testing, profiling, and packaging.
Pykaryote uses git, a distributed version control system, to keep track of changes in the code. If you haven’t used git before, find a tutorial online. To use git with Pykaryote, you should at least understand commiting, branching, pushing, pulling, rebaseing and interactive rebaseing.
Guidelines:
For its first two years of development, Pykaryote has not had a definitive coding style. As a result, the code is ugly and inconsistent.
To ensure clean code, Pykaryote has adopted PEP 08 as its official style guide. If you have never read a style guide before, your code is ugly. Go read PEP 08 now.
Guidelines:
Use single instead of double quotes for string literals.
% syntax is deprecated
Good:
'hello {}'.format('world')
Bad:
'hello %s' % 'world'
Note
The code for loading simulation configuration files is super hacky and gross. If you have time, re-write config.py and get rid of global_generator.py. It should only take a few hours. Ideally, ConfigParser would be used to load the current configuration file on top of the default master.cfg. JSON should be used instead of calls to eval.
Configuration options are loaded from config.py, which is auto-generated by global_generator.py. Every time you add or remove a configuration option, you must add it to master.cfg and then run global_generator.py to re-build config.py.
Pykaryote has very few unit tests. They can be run with the pyk-test command.
pyk-test does two things. First, it runs tests with the unittest framework. Next, pyk-test runs the command line utilities, making sure they do not crash. Output of the command line utilities is not checked for correctness.
As of version 1.0, test coverage is less than 1%. It would be nice to have more coverage.
Guidelines:
Before optimizing, always profile using python’s built in profiler.
Profiling is done with the pyk-profile command, which profiles a simulation with the random seed set to 1337.
Before running pyk-profile, enable Cython profiling by adding the following compiler directive to the top of all .pyx files:
# cython: profile=True
Be sure to disable profiling when packaging for release, as code is slower with profiling enabled.
Note
Profiling can be easily enabled and disabled using the included enable_profiling.sh and disabled_profiling.sh bash scripts.
Once profiling is enabled, rebuild Pykaryote with:
$ python setup.py build_ext --inplace
To profile a comparison, run:
$ pyk-profile
This will run a simulation and save statistics to Profile.prof in the current directory. To analyze profile data interactively, run:
$ python -m pstats Profile.prof
You will be presented with a prompt. Use these commands to print the top 10 functions by runtime:
% sort time
% stats 10
For more information, use the internal help:
% help
% help sort
% help stats
More information on pstats can be found in this tutorial.
Pykaryote’s documentation is created using Sphinx. It is located in the docs directory.
Sphinx uses the reStructuredText markup language. To update the documentation, edit the .rst files.
When you are done making your changes, move into the docs directory and build the documentation with:
$ make html
If you run into an error, ensure that sphinx is installed:
$ pip install sphinx
Pykaryote uses setuptools for packaging. Distribution is done through PyPI, the Python Package Index.
To build an .egg for your current platform, run:
$ python setup.py bdist_egg
To build a source distribution, run:
$ python setup.py sdist
Test the newly packaged release in a fresh virtual machine. When everything is working correctly, upload to PyPI with:
$ python setup.py sdist bdist_egg upload
You will be prompted for a user name and password. For access to the pykaryote PyPI account, contact Professor Serita Nelesen.