Source code folder structure & imports

[damskii9992]

General

The source code folder structure is important both from an user-experience point-of-view, but also for a maintainability point-of-view. When source code is structured into clearly distinct modules for their distinct functionalities, and when classes aren't hidden away in files with ambiguous names, it is easier for maintainers to find files and quickly gather what the purpose of the file is just from its location.

Good use of sub-modules also makes it easier for users to import their needed classes and functions and allows us to re-name things behind the scenes and provide aliases without directly interfering with the user-experience.

Source code structure rules:

• All source file names should be full lowercase.
• All source files should contain only 1 class and be named after the class it contains.
• Files should be separated into well-defined sub-folders (sub-modules) based on content.
• All base classes should be named with a suffixed "Base", i.e.: CollectionBase, ObjectBase, DescriptorBase etc.
• The unittest folder structure should copy the source code in both structure and names with "test" prepended in filenames and class names.
• The "legacy" sub-folder is not a module and therefore does not include an __init__.py file. Code that is no-longer maintained is put in here before it gets permanently removed later on.

Import rules

• All user classes and elements in a (sub-)module should be imported in the __init__.py of the module and added to the __all__ module attribute.
• Only the most important elements are further imported to the top-level __init__.py, to ease user imports.
• All internal imports in the source code should be relative imports.
• Relative imports should be avoided in tests.

Example from the variable sub-module:

from .descriptor_any_type import DescriptorAnyType
from .descriptor_array import DescriptorArray
from .descriptor_bool import DescriptorBool
from .descriptor_number import DescriptorNumber
from .descriptor_str import DescriptorStr
from .parameter import Parameter

__all__ = [
    DescriptorAnyType,
    DescriptorArray,
    DescriptorBool,
    DescriptorNumber,
    DescriptorStr,
    Parameter,
]

Link to the ADR suggestion:
#114