Astropysics welcomes contributions from anyone interested, from simple bugfixes to contributing new functionality. If you want to check out the most recent version to contribute (or just want the latest and greatest), you can pull the current development version from the github page.
You will need to have git installed - it is available for all major OSes. Once you have it working, simply execute:
git clone git://github.com/eteq/astropysics.git astropysics-dev
This will create a directory with the name astropysics-dev containing the latest and greatest version of astropysics. If at any time you want to update this version, go into the directory and do:
If you plan on editing the astropysics source code (please do so, and submit patches/new features!), a useful way to immediately see changes without having to re-install every time is to use the command:
python setup.py develop
possibly prefixed with sudo depending on your OS. This will install links to the source code directory instead of copying over the source code, so any changes you make to a module can be seen just be doing reload(module).
If you intend to regularly contribute changes or patches to astropysics, a great way to submit changes is to use github’s “fork” feature. Just go to the astropysics page and click the “fork” button in the upper-right. Make a new branch in your fork with whatever change you want to make, and when you’ve fixed the bug of added whatever new fancy thing you want to add, just submit a pull request (button in the upper-right) to the main astropysics project.
For general coding style, PEP8 provides the main coding style for astropysics, with an important exception: PEP8 calls for methods (i.e. functions that are in the scope of a class) to use the lower_case_with_underscores convention. Astropysics instead uses camelCase (e.g. first letter of each word upper case, first letter of the method lower case) for method names. Functions that are not methods (i.e. directly in a module scope) remain lowercase_with_underscores. This allows methods and functions to be easily distinguished (but keeps method names distinct from class names, for which the first letter is always upper case). This could change in the future to be fully PEP8 compliant, but for now, given the already existing codebase, camelCase it is.
To summarize, the naming conventions are:
Documentation should be provided with every object, using sphinx REStructuredText markup. Functions and methods should use info field lists To specify input parameters, return values, and exceptions (where relevant). Below is an example of the standard format:
def a_function(arg1,arg2=None,flag=False): """ A short description of the function. Multiple paragraphs if necessary, i.e. background is needed. :param arg1: This argument is important input data, although I'm not specifying exactly what it's type is (maybe it'd duck-typed?) Also, the description is more than one line, so it has to start underneath and indented. :param arg2: This argument is an optional input. :type arg2: You can specify a type here if you want. :param bool flag: You can also give the type in param if it fits. :except ValueError: If you raise an exception, specify here what type it is and why. :returns: A description of the return value, if there is one. **Examples** If an examples are needed, they should go here, ideally in doctest format so that they can be used as tests: >>> inpt = 'something for a_function' >>> a_function(inpt,flag=True) 'whatever a_function should output' """
Classes with public attributes can document using the sphinx construct for documenting class attributes:
class MyClass(object): #: Documentation for :attr:`value` attribute. value = None def __init__(self,value): self.value = value
There is a test suite that should be periodically run to ensure everything that has tests is still working correctly. It requires nose. It can be run from the astropysics source directory (where setup.cfg lives) with the command:
Note that this is also set up to easily debug in the event that some of the tests fail. Simply do:
And nose will only run those tests that failed the last time around. If you want to run a particular test, do:
nostest --with-id 3
Where the ‘3’ can be replaced by whatever number test you want.
When writing functionality in astropysics, it’s a good idea to add tests. These should go in the ‘tests’ directory, and should have module names with the word ‘test’ in them, along with the function names themselves. This naming is necessary to allow nose to find all the tests. Alternatively, snippets of code as they would appear on the python interpreter (with output) can be placed directly in the docstrings, and they will be automatically included in the tests.