Importing EasyDiffraction library

[AndrewSazonov]

I propose to discuss here a way of importing EasyDiffraction library by user.

The main idea is to reduce the number of imported EasyScience modules (EasyCore, EasyCrystallography, EasyDiffraction) to as few as possible. An experienced user should be able to import the necessary classes when needed, but the default import should be minimal. This should be possible using the Job wrapper concept, which will be discussed elsewhere (#96).

⚙ Current

# EasyScience: generic
from easyCore import np
from easyCore.Fitting.Fitting import Fitter
from easyCrystallography.Components.AtomicDisplacement import AtomicDisplacement

# EsyScience: diffraction
from easyDiffractionLib import Phase, Phases
from easyDiffractionLib.Jobs import Powder1DCW
from easyDiffractionLib.elements.Backgrounds.Point import PointBackground, BackgroundPoint

💡 Suggested

import EasyDiffraction

[rozyczko]

Minor quibble:
rather than importing the whole module and then referencing classes/methods with the module name, it probably makes sense to import necessary modules etc. explicitly,

from EasyDiffraction import Job

[AndrewSazonov]

We use this approach, and it works well, for example, when importing necessary classes from PySide

from PySide6.QtCore import Object, QFile, QTextStream

However, most Qt class names are prefixed with Q, which makes them rather unique. EasyDiffraction, on the other hand, has classes with more generic names such as Atom, Phase, Job, etc. Importing them explicitly can lead to name conflicts in scripts where other crystallographic modules are used.

So for the case where the user accesses everything through the EasyDiffraction job object, I would suggest just to import the whole module

import EasyDiffraction
job = EasyDiffraction.Job()
phase = job.phases['lbco']
cell = phase.cell

or use, for example, the ED shortcut for EasyDiffraction similar to other modules, e.g. import numpy as np, import pandas as pd, etc.

import EasyDiffraction as ED
job = ED.Job()
phase = job.phases['lbco']
cell = phase.cell

An experienced user can always import the necessary classes explicitly, for example:

from EasyCore.Fitting import Fitter 
from EasyCrystallography import Cell
from EasyDiffraction import Phase

cell = Cell()
phase = Phase(cell=cell)

[damskii9992]

I agree with this sentiment. Straightforward usage of the API should only require a single import, to make it simpler for the user.

[rozyczko]

Obviously one can always modify imported module names to be explicit and non-clashing, e.g.

from EasyDiffraction import Job as EDJob

job = EDJob()
...

so the question is whether it's easier to do this slightly more "arcane" import and save keystrokes whenver a module is used in the code or explicitly import EasyDiffraction as ED and carry this prefix.

This is probably moot anyway, since power users (who we target with the notebooks) will write their own scripts using whichever method they prefer. We can default to carry ED throughout the example notebooks for clarity and do what Andrew is proposing.

[andped10]

Just to understand. So what is proposed is to create a library called EasyDiffraction. The purpose of this library is to serve as a facade to inexperienced users by only exposing the most general functionality. Is this correct?

If I understand it correctly I fear that it can cause significant confusion that we will then have the two libraries EasyDiffraction and easyDiffractionLib. Also, I thought the most stripped down name ( EasyDiffraction) was reserve to the App.

Are we not able to obtain a similar behavior by having the Job in the easyDiffractionLib?

[AndrewSazonov]

We have 2 repositories EasyDiffractionApp and EasyDiffractionLib for the application and library, respectively. The idea is to keep using them, but just change the name of the python package we distribute via PyPi from easyDiffractionLib to EasyDiffraction. Since we are only distributing the library as a python package, the Lib suffix in the package name is not needed. The graphical application is not planned to be distributed via PyPi, so there should be no name conflicts if we use the same EasyDiffraction name for both the library and the application.

[AndrewSazonov]

Another suggestion from @andped10 is to follow a more pythonic way of naming packages and modules (see PEP 8): Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

So far we have used the way the Qt library PySide uses (see, e.g. Qt for Python):

from PySide6.QtCore import Object, QFile, QTextStream

So instead of, for example, doing this

import EasyDiffraction as ED

it is proposed to do the following

import easydiffraction as ed

[andped10]

This change would also apply to EasyReflectometry. The import would then become:

from easyreflectometry import GoodStuff

Rather than:

from EasyReflectometry import GoodStuff

[rozyczko]

This makes sense, since the library is not supposed to be a QObject, so the Qt naming standard should not apply.
We should use PEP8 here.