function method design

Function and Method design

Guidelines that have to be followed in the design of sbpy function and methods.

General Guidelines

• astropy Quantities should always be preferred over other object types (e.g., simple floats)
• Ephem/Orbit/Phys objects should be used where appropriate; inheriting from either of these classes is strictly encouraged!

Input

• by default, only the following data types are allowed for function input: None, dict or Ephem/Orbit/Phys, Quantity, float, int, string or iterable thereof
• any dict provided should be turned into a Ephem/Orbit/Phys internally (functionality provided as part of sbpy.data.DataClass)
• if only single properties of type Quantity, float, string (or iterables thereof) are provided that fit in either of Ephem/Orbit/Phys, this is permitted (for instance: a function/method takes phaseangle as argument, but there are no other argument that would fit into Ephem)
• if there are two or more properties of type Quantity, float, string (or iterables thereof) that fit into either of Ephem/Orbit/Phys, those properties have to be bundled in the object (for instance: in addition to phaseangle, a function/method also requires argument heliodist; both properties then have to be bundled into a Ephem object)
• float, string, int (and iterables thereof) are only permitted as input parameters if their nature and unit is unambiguosly defined in the function/method docstring
• exceptions to the aforementioned guidelines can be granted to input parameters of private functions that depend on performance

Output

• output properties should always be accompanied by a unit if applicable; permitted outputs are Quantity, Ephem/Orbit/Phys
• any function/method that computes only a single property (e.g., Quantity, float, string, or iterable thereof) should output only this property as a Quantity
• if a function/method produces several output properties, these should be bundled in a Ephem/Orbit/Phys object; if the function/method takes a Ephem/Orbit/Phys as input and produces a result property that fits in to a Ephem/Orbit/Phys object, there should be a keyword argument append_results that defines whether the resulting property gets added to the input object; by default, append_results=False
• other output data types (e.g., lists, floats, etc.) are only allowed in exceptional cases