Style Guide.md

Style Guide

References

• The Google Python Style Guide
• PEP-8
• The Hitchhiker's Guide to Python

Take cues from the above references, then use linters, auto-formatters, and LLMs to enforce the styles.

Notes

• Run pylint with the pylintrc file (from the Google Python Style Guide) in the root directory:

  pylint --rcfile=pylintrc orbitpy tests examples

• Run black to format the python files.

  black orbitpy tests examples

• Run coverage. The HTML report will be generated in the htmlcov directory. Open htmlcov/index.html in a web browser to view the detailed coverage report.

  coverage run -m unittest discover -s tests
  coverage html

• Use Google style docstrings. https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html. The following configuration option in the conf.py enables Sphinx to parse Google style dosctrings: napoleon_google_docstring = True

• All OrbitPy objects (classes) intended for use by external users must support initialization and serialization using Python dictionaries. Each class should provide from_dict(...) and to_dict(...) methods to allow instantiation from dictionary inputs and export their state or data back into a dictionary format. Use the JsonSerializer class provided by the eosimutils.base module to save and retreive objects (with to_dict(.) and from_dict(.) functions) to/from JSON.

• Only classes and functions which are most commonly utiized in Earth Observation mission simulations will be developed.

• All enum values should be in capital letters and formatted with underscores, e.g., GREGORIAN_DATE.

• Imports of classes and/or functions from external libraries must be prefixed by the name of the external library. For example:

  from astropy.time import Time as Astropy_Time # for imported classes use upper-case for the first letter in the underscore seperated seperated words
  from skyfield.positionlib import build_position as skyfield_build_position # for function use all lower case

• Always use from_dict(...) and other public API functions to initialize EO-Sim objects, including in test functions. Avoid directly calling internal methods or the init(...) constructor. This ensures compatibility with future updates, as internal implementations may change, but the public API is expected to remain stable.

• A class representing a physical object (e.g., Ground-station, instrument, spacecraft) or a collection of objects (e.g., grid of physical locations) must include an identifier attribute which must be a valid UUID. If no identifier is provided, one will be autogenerated. Providing names of entities will be optional.

• Python dictionaries used for interfacing should have lowercase, underscore-separated keys. Avoid including units in the keys for physical quantities. For example: use min_elevation_angle or latitude instead of latitude_deg. Similarly, class variable names should not indicate units in their names but must be properly documented.

• Seperate tests which take a long time into a seperate long-duration-test folder, to give the flexibility to seperately run the long tests.

• Numpy arrays are used for storing numerical array-like data (e.g., 3d position, states, trajectories, etc.) At several places functions are built to have two versions: one which takes eosimutils objects and another which takes numpy arrays.

• Use factory methods in modules such as orbits, propagator, etc. This allows for dynamic creation of propagators based on input specifications in a dictionary. It centralizes the registration and creation of propagator types, making the system extensible and maintainable. Use identical implementation for all Factory classes with a class-level registry and decorator pattern.

• Use randomized tests wherever possible. Save seed for randomized test when it fails.

• Specify the expected dictionary key names with explicit suffixes when indicating a particular type (e.g., orientation_type, orbit_type), and avoid using the generic key name type on its own.