ADR Suggestion Source code folder structure

[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.

The current source code folder structure is confusing for both maintainers and users alike.

Current Implementation

This is the current source code folder structure of easyscience.

📦 easyscience
├── 📁 Datasets
│   ├── 📄 xarray.py
│   │   ├── 🏷️ class EasyScienceDatasetAccessor
│   │   ├── 🏷️ class EasyScienceDataarrayAccessor
│   │   ├── 🔧 def check_sanity_single
│   │   └── 🔧 def check_sanity_multiple
├── 📁 fitting
│   ├── 📁 minimizers
│   │   ├── . . .
│   ├── . . .
├── 📁 global_object
│   ├── . . .
├── 📁 models
│   ├──  📄 polynomial.py
│   │   ├── 🏷️ class Polynomial
│   │   ├── 🏷️ class Line
│   │   └── 🔧 def designate_calc_fn
├── 📁 Objects
│   ├── 📁 job
│   │   ├── . . .
│   ├── 📁 variable
│   │   ├── . . .
│   ├── 📄 core.py
│   │   └── 🏷️ class ComponentSerializer
│   ├── 📄 Groups.py
│   │   └── 🏷️ class BaseCollection
│   ├── 📄 Interface.py
│   │   ├── 🏷️ class InterfaceFactoryTemplate
│   │   └── 🏷️ class ItemContainer
│   ├── 📄 ObjectClasses.py
│   │   ├── 🏷️ class BasedBase
│   │   └── 🏷️ class BaseObj
├── 📁 Utils
│   ├── 📁 io
│   │   ├── 📄 dict.py
│   │   │   ├── 🏷️ class DictSerializer
│   │   │   └── 🏷️ class DataDictSerializer
│   │   ├── 📄 xml.py
│   │   │   └── 🏷️ class XMLSerializer
│   │   ├── 📄 json.py
│   │   │   ├── 🏷️ class JsonSerializer
│   │   │   ├── 🏷️ class JsonDataSerializer
│   │   │   ├── 🏷️ class JsonEncoderTemplate
│   │   │   └── 🏷️ class JsonDecoderTemplate
│   │   ├── 📄 template.py
│   │   │   └── 🏷️ class BaseEncoderDecoder
│   ├── . . .

Proposed Implementation

To make the source-code structure easier to navigate and less confusing, all source-files and folders should be full lowercase and each file should contain only 1 class and be named after the class it contains. The following is the suggested easyscience structure based on this suggestion:

📦 easyscience
├── 📁 base_classes
│   ├── 📄 obj_base.py
│   │   └── 🏷️ class ObjBase
│   ├── 📄 based_base.py
│   │   └── 🏷️ class BasedBase
│   ├── 📄 collection_base.py
│   │   └── 🏷️ class CollectionBase
├── 📁 fitting
│   ├── 📁 calculators
│   │   ├── 📄 interface_factory.py
│   │   │   ├── 🏷️ class InterfaceFactoryTemplate
│   │   │   └── 🏷️ class ItemContainer
│   ├── 📁 minimizers
│   │   ├── . . .
│   ├── . . .
├── 📁 global_object
│   ├── . . .
├── 📁 io
│   ├── 📄 serializer_component.py
│   │   └── 🏷️ class SerializerComponent
│   ├── 📄 serializer_dict.py
│   │   └── 🏷️ class SerializerDict
│   ├── 📄 serializer_base.py
│   │   └── 🏷️ class SerializerBase
├── 📁 job
│   ├── . . .
├── 📁 legacy
│   ├── 📄 legacy_core.py
│   │   └── 🏷️ class ComponentSerializer
│   ├── 📄 xml.py
│   │   └── 🏷️ class XMLSerializer
│   ├── 📄 json.py
│   │   ├──  🏷️ class JsonDataSerializer
│   │   ├── 🏷️ class JsonSerializer
│   │   ├── 🏷️ class JsonEncoderTemplate
│   │   └── 🏷️ class JsonDecoderTemplate
│   ├── 📄 dict.py
│   │   └── 🏷️ class DataDictSerializer
├── 📁 models
│   ├──  📄 polynomial.py
│   │   └── 🏷️ class Polynomial
├── 📁 utils
│   ├── . . .
├── 📁 variable
│   ├── . . .

The unittest folder structure should mimic this structure, with the word "test" preprended to all the filenames and classes. I.e. test_parameter contains only 1 class: the TestParameter class.

Module imports

In each module/folder, including the root folder,, the __init__.py file contains the following code (snippet from the variable 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,
]

To ensure that Parameter can be imported as:

from easyscience.variable import Parameter

Rather than:

from easyscience.variable.parameter import Parameter

Note that DescriptorBase has not been included despite being a class in the variable module. This is the case since it is a class which should not be imported by the user.

We could then further import really critical classes to the root module, such as Parameter, for even easier imports. Should we do that? And which classes are then "really critical "?

[AndrewSazonov]

I support the proposed restructuring and renaming. It makes sense and should improve maintainability. The transition can be broken into smaller steps to make the process easier.
One minor question: is there a convention for when we use Base as a prefix (e.g. BaseCollection) versus as a suffix (e.g. SerializerBase)?

[damskii9992]

No, but we probably should have a convention for it.
I think I prefer having the Base as a suffix, like for the DescriptorBase and DescriptorNumber, I believe it makes it easier to read and it also properly groups together similar things alphabetically.

[rozyczko]

Base as a suffix should be the standard.
BaseCollection doesn't look like a base class - it tells me that the class describes a base (adjective) collection of sorts.

[rozyczko]

We could then further import really critical classes to the root module, such as Parameter, for even easier imports. Should we do that? And which classes are then "really critical "?

This is a good thing to do with all API (user-facing) imports. This way, we can refactor/move around the actual implementation without having to modify the imports in the dependent modules.

[damskii9992]

Exactly. So, which classes are user-facing? I can think of this list:

• Fitter
• ObjBase (former BaseObj) (At least until we have a proper "container" class)
• Parameter
• DescriptorNumber
• Polynomial
• All the "jobs" classes

Did I miss anything or should anything be removed?

[rozyczko]

Also - Constraints

Do we really need Polynomial?

[damskii9992]

Well, Constraints is gone when this is merged.
I suppose we don't need Polynomial. And even if we did, I think its fair that the models supplied with the library, is imported from the models sub-module.