Module psdi_data_conversion.constants

@file psdi_data_conversion/constants.py

Created 2025-01-23 by Bryan Gillis.

Miscellaneous constant values used within this project.

These values are stored as constants rather than hardcoded literals for various reasons, including: - Better assurance of consistency that the same value is used every time - If a value needs to be changed, this only needs to be done at one location - Compatibility with IDE features - a constant can be checked for validity by an IDE, while e.g. a string key for a dict can't, allowing more errors to be caught and fixed by the IDE rather than at runtime - The use of a constant may improve readability - e.g. MEGABYTE = 1024*1024; max_file_size = 1*MEGABYTE is more readable than max_file_size = 1*1024*1024, and so doesn't require a comment like the latter would

There are some known drawbacks to this approach which need to be considered though: - Constants may obscure readability - it may be quite relevant to the reader exactly what a constant represents, which is obscured until they (at minimum) mouse over it - More code is necessary to use a constant than a literal (at minimum it needs an extra line to define it, and when stored here, it also needs a line to import it or this module)

With these drawbacks in mind, we make the following recommendations for constant use: - Messages for the user (print/logging messages, exceptions) should by default not be stored as constants. They should be made constants if it's necessary to reference their exact text elsewhere (either in the executable code or unit tests). In this case, the name of the constant should be descriptive, even if this means a rather long name - If a value is only used in one file and only likely to ever be used in that file, it can be defined as a constant there (or if used only two or three times in quick succession, left as a literal) - Of course, deviations from this should be made when necessary, such as to avoid circular imports