Backwards-incompatible change planned for v2022.0.0

pymatgen
1

Pymatgen root imports will be removed in v2022.0.0 in preparation for a change to a more modular, extensible architecture that will allow more developers to contribute.

Specifically, the following “convenience imports” have been removed in favor of
their canonical import:

from pymatgen import Composition  # now "from pymatgen.core.composition import Composition"
from pymatgen import Lattice  # now "from pymatgen.core.lattice import Lattice"
from pymatgen import SymmOp  # now "from pymatgen.core.operations import SymmOp"
from pymatgen import DummySpecie, DummySpecies, Element, Specie, Species  # now "from pymatgen.core.periodic_table ..."
from pymatgen import PeriodicSite, Site  # now "from pymatgen.core.sites ..."
from pymatgen import IMolecule, IStructure, Molecule, Structure  # now "from pymatgen.core.structure ..."
from pymatgen import ArrayWithUnit, FloatWithUnit, Unit  # now "from pymatgen.core.units ..."
from pymatgen import Orbital, Spin  # now "from pymatgen.electronic_structure.core ..."
from pymatgen import MPRester  # now "from pymatgen.ext.matproj ..."

If your existing code uses from pymatgen import <something>, you will need to make
modifications. The easiest way is to use an IDE to run a Search and Replace.
First, replace any from pymatgen import MPRester with
from pymatgen.ext.matproj import MPRester. Then, replace
from pymatgen import with from pymatgen.core import. Alternatively, if you
are using a Mac command line, you can do:

find . -name '*.py' | xargs sed -i "" 's/from pymatgen import MPRester/from pymatgen.ext.matproj import MPRester/g'
find . -name '*.py' | xargs sed -i "" 's/from pymatgen import/from pymatgen.core import/g'

From a Linux command line, you can do:

find . -name '*.py' | xargs sed -i 's/from pymatgen import MPRester/from pymatgen.ext.matproj import MPRester/g'
find . -name '*.py' | xargs sed -i 's/from pymatgen import/from pymatgen.core import/g'

This should resolve most import errors and only a few more modifications may
need to be done by hand.

See the change log for more information on pymatgen changes and compatibility for planned changes.

2

Could you clarify why the convenience imports will not be maintained? It may not be obvious to a pymatgen user why a move to a more modular structure would make the maintenance of the convenience imports a headache / source of burdensome complexity for pymatgen maintainers.

Thank you for continuing to improve pymatgen in future-looking ways!

3

Hi Donny,

It’s a fundamental limitation of using implicit namespace packages, see PEP 420.

There was a work-around that could maybe have kept the root-level imports while allowing specific submodules to be implicit namespace packages, but it felt like a bit of a hack and something that might not be optimal in the long run.

The benefit of the implicit namespace packages is that publishing add-ons to pymatgen becomes a lot simpler, for example see pymatgen-diffusion as an example of this, which now has the import from pymatgen.analysis.diffusion import ... even though it is maintained and installed as a separate package.

Nevertheless, the pymatgen v2022.0.* versions are technically all still “pre-release”, so there’s room to change track if a better solution presents itself.

Best,

Matt

4

Thanks. I see now how PEP 420 precludes the convenience imports.

5

Note that the suggested change breaks matminer due to the use of old convenience imports.

6

I believe matminer has been updated, as of v0.6.5 (Feb 17th).