Merge pull request #109 from python-periodictable/fix-104-type-hinting

Add type hinting

Author: pkienzle

.github/workflows/test.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [ master ]
   pull_request:
-    branches: [ master ]
+  #  branches: [ master ]
   release:
     types: [published]
 
@@ -18,11 +18,11 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.11'
+        python-version: '3.14'
 
     - name: Build the wheel
       run: |
-        python -m pip install build
+        python -m pip install --group dev
         python -m build
 
     - name: Upload wheel
@@ -33,13 +33,10 @@ jobs:
 
     - name: Run the tests
       run: |
-        python -m pip install numpy pyparsing pytest pytest-cov
         pytest -v
 
     - name: Build the docs
       run: |
-        python -m pip install matplotlib sphinx
-        python -m pip install dist/periodictable*.whl
         make -j 4 -C doc/sphinx SPHINXOPTS="-W --keep-going" html
 
   # Test the wheel on different platforms
@@ -50,12 +47,11 @@ jobs:
     strategy:
       matrix:
         cfg:
-          #- { os: ubuntu-20.04, py: 2.7 }
-          #- { os: ubuntu-20.04, py: 3.6 }
-          - { os: ubuntu-latest, py: 3.8 }
-          - { os: ubuntu-latest, py: 3.11, doc: 1 }
-          - { os: windows-latest, py: 3.11 }
-          - { os: macos-latest, py: 3.11 }
+          #- { os: ubuntu-20.04, py: '3.6' }
+          - { os: ubuntu-latest, py: '3.10' }
+          - { os: ubuntu-latest, py: '3.14', doc: 1 }
+          - { os: windows-latest, py: '3.14' }
+          - { os: macos-latest, py: '3.14' }
       fail-fast: false
 
     steps:
@@ -76,17 +72,22 @@ jobs:
       run: python -m pip install dist/periodictable*.whl
       shell: bash
 
-    - name: Install Python dependencies
+    # uncertainties and matplotlib are optional packages, but they are needed for mypy tests
+    - name: Install test dependencies
       run: |
-        python -m pip install pytest pytest-cov
+        python -m pip install --group test
 
+    # Use --pyargs --import-mode=append to target the installed package.
     # Change into the test directory to test the wheel so that the
-    # source directory is not on the path. Full tests with coverage are
-    # run before building the wheel.
+    # source directory is not on the path. We are running coverage tests
+    # because it shows that it is indeed the installed package that is tested.
+    # The mypy plugin fails when testing the installed package. Since there is no
+    # way to turn the option off, so we instead erase the addopts configuration
+    # and put them explicitly on the pytest command line below without --mypy.
     - name: Test wheel with pytest
       run: |
         cd test
-        pytest -v --pyargs --import-mode=append periodictable . ../doc/sphinx/guide
+        pytest -v --pyargs --import-mode=append periodictable --override-ini addopts= --doctest-modules --doctest-glob=*.rst --cov=periodictable . ../doc/sphinx/guide
 
   # Upload wheel to PyPI only when a tag is pushed, and its name begins with 'v'
   upload-to-pypi:

MANIFEST.in

@@ -3,6 +3,7 @@ include README.rst
 graft periodictable/xsf
 include periodictable/f0_WaasKirf.dat
 include periodictable/activation.dat
+include periodictable/py.typed
 prune doc
 prune doc/sphinx/_build
 prune doc/sphinx/build

doc/sphinx/conf.py

@@ -49,6 +49,26 @@
 nitpick_ignore = [
     ('py:class', 'type'),
     ('py:class', 'object'),
+
+    ('py:class', 'collections.abc.Callable'),
+    ('py:class', 'collections.abc.Iterator'),
+    ('py:class', 'collections.abc.Sequence'),
+    ('py:class', 'pathlib.Path'),
+
+    ('py:class', 'numpy.dtype'),
+    ('py:class', 'numpy.ndarray'),
+    ('py:class', 'numpy.float64'),
+    ('py:class', 'numpy._typing._array_like._Buffer'),
+    ('py:class', 'numpy._typing._array_like._SupportsArray'),
+    ('py:class', 'numpy._typing._array_like._ScalarT'),
+    ('py:class', 'numpy._typing._nested_sequence._NestedSequence'),
+    ('py:class', 'pyparsing.core.ParserElement'),
+
+    ('py:class', 'periodictable.core._AtomBase'),
+    ('py:class', 'periodictable.core.IonSet'),
+    ('py:class', 'periodictable.core.AtomVar'),
+    ('py:class', 'Fragment'),
+    ('py:class', 'FormulaInput'),
     ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/sphinx/discoverer/__init__.py

@@ -1,10 +1,10 @@
-import periodictable.core
+from periodictable.core import default_table, delayed_load
 
 # Delayed loading of the element discoverer information
 def _load_discoverer():
     """
     The name of the person or group who discovered the element.
     """
     from . import discoverer
-    discoverer.init(periodictable.core.default_table())
-periodictable.core.delayed_load(['discoverer'], _load_discoverer)
+    discoverer.init(default_table())
+delayed_load(['discoverer'], _load_discoverer)

doc/sphinx/discoverer/discoverer.py

@@ -4,14 +4,14 @@
 From http://en.wikipedia.org/wiki/Discoveries_of_the_chemical_elements.
 """
 
-import periodictable.core
+from periodictable.core import Element
 
 def init(table, reload=False):
     if 'discoverer' in table.properties and not reload: return
     table.properties.append('discoverer')
 
     # Set the default, if any
-    periodictable.core.Element.discoverer = "Unknown"
+    Element.discoverer = "Unknown"
 
     # Not numeric, so no discoverer_units
 

doc/sphinx/shelltable/__init__.py

@@ -1,11 +1,11 @@
-import periodictable.core
+from periodictable.core import default_table, delayed_load
 
 # Delayed loading of the element discoverer information
 def _load():
     """
     The name of the person or group who discovered the element.
     """
     from . import shelltable
-    shelltable.init(periodictable.core.default_table())
-periodictable.core.delayed_load(
+    shelltable.init(default_table())
+delayed_load(
     ['shells'], _load, isotope=True, element=False)

periodictable/__init__.py

@@ -36,7 +36,7 @@
 from . import mass
 from . import density
 
-_LAZY_MODULES = []
+_LAZY_MODULES: list[str] = []
 _LAZY_LOAD = {
     'formula': 'formulas',
     'mix_by_weight': 'formulas',
@@ -77,6 +77,129 @@ def __dir__():
 density.init(elements)
 del mass, density
 
+# For type hinting with vscode we need an explicit list of elements.
+hydrogen = H = elements.symbol("H")
+helium = He = elements.symbol("He")
+lithium = Li = elements.symbol("Li")
+beryllium = Be = elements.symbol("Be")
+boron = B = elements.symbol("B")
+carbon = C = elements.symbol("C")
+nitrogen = N = elements.symbol("N")
+oxygen = O = elements.symbol("O")
+fluorine = F = elements.symbol("F")
+neon = Ne = elements.symbol("Ne")
+sodium = Na = elements.symbol("Na")
+magnesium = Mg = elements.symbol("Mg")
+aluminum = Al = elements.symbol("Al")
+silicon = Si = elements.symbol("Si")
+phosphorus = P = elements.symbol("P")
+sulfur = S = elements.symbol("S")
+chlorine = Cl = elements.symbol("Cl")
+argon = Ar = elements.symbol("Ar")
+potassium = K = elements.symbol("K")
+calcium = Ca = elements.symbol("Ca")
+scandium = Sc = elements.symbol("Sc")
+titanium = Ti = elements.symbol("Ti")
+vanadium = V = elements.symbol("V")
+chromium = Cr = elements.symbol("Cr")
+manganese = Mn = elements.symbol("Mn")
+iron = Fe = elements.symbol("Fe")
+cobalt = Co = elements.symbol("Co")
+nickel = Ni = elements.symbol("Ni")
+copper = Cu = elements.symbol("Cu")
+zinc = Zn = elements.symbol("Zn")
+gallium = Ga = elements.symbol("Ga")
+germanium = Ge = elements.symbol("Ge")
+arsenic = As = elements.symbol("As")
+selenium = Se = elements.symbol("Se")
+bromine = Br = elements.symbol("Br")
+krypton = Kr = elements.symbol("Kr")
+rubidium = Rb = elements.symbol("Rb")
+strontium = Sr = elements.symbol("Sr")
+yttrium = Y = elements.symbol("Y")
+zirconium = Zr = elements.symbol("Zr")
+niobium = Nb = elements.symbol("Nb")
+molybdenum = Mo = elements.symbol("Mo")
+technetium = Tc = elements.symbol("Tc")
+ruthenium = Ru = elements.symbol("Ru")
+rhodium = Rh = elements.symbol("Rh")
+palladium = Pd = elements.symbol("Pd")
+silver = Ag = elements.symbol("Ag")
+cadmium = Cd = elements.symbol("Cd")
+indium = In = elements.symbol("In")
+tin = Sn = elements.symbol("Sn")
+antimony = Sb = elements.symbol("Sb")
+tellurium = Te = elements.symbol("Te")
+iodine = I = elements.symbol("I")
+xenon = Xe = elements.symbol("Xe")
+cesium = Cs = elements.symbol("Cs")
+barium = Ba = elements.symbol("Ba")
+lanthanum = La = elements.symbol("La")
+cerium = Ce = elements.symbol("Ce")
+praseodymium = Pr = elements.symbol("Pr")
+neodymium = Nd = elements.symbol("Nd")
+promethium = Pm = elements.symbol("Pm")
+samarium = Sm = elements.symbol("Sm")
+europium = Eu = elements.symbol("Eu")
+gadolinium = Gd = elements.symbol("Gd")
+terbium = Tb = elements.symbol("Tb")
+dysprosium = Dy = elements.symbol("Dy")
+holmium = Ho = elements.symbol("Ho")
+erbium = Er = elements.symbol("Er")
+thulium = Tm = elements.symbol("Tm")
+ytterbium = Yb = elements.symbol("Yb")
+lutetium = Lu = elements.symbol("Lu")
+hafnium = Hf = elements.symbol("Hf")
+tantalum = Ta = elements.symbol("Ta")
+tungsten = W = elements.symbol("W")
+rhenium = Re = elements.symbol("Re")
+osmium = Os = elements.symbol("Os")
+iridium = Ir = elements.symbol("Ir")
+platinum = Pt = elements.symbol("Pt")
+gold = Au = elements.symbol("Au")
+mercury = Hg = elements.symbol("Hg")
+thallium = Tl = elements.symbol("Tl")
+lead = Pb = elements.symbol("Pb")
+bismuth = Bi = elements.symbol("Bi")
+polonium = Po = elements.symbol("Po")
+astatine = At = elements.symbol("At")
+radon = Rn = elements.symbol("Rn")
+francium = Fr = elements.symbol("Fr")
+radium = Ra = elements.symbol("Ra")
+actinium = Ac = elements.symbol("Ac")
+thorium = Th = elements.symbol("Th")
+protactinium = Pa = elements.symbol("Pa")
+uranium = U = elements.symbol("U")
+neptunium = Np = elements.symbol("Np")
+plutonium = Pu = elements.symbol("Pu")
+americium = Am = elements.symbol("Am")
+curium = Cm = elements.symbol("Cm")
+berkelium = Bk = elements.symbol("Bk")
+californium = Cf = elements.symbol("Cf")
+einsteinium = Es = elements.symbol("Es")
+fermium = Fm = elements.symbol("Fm")
+mendelevium = Md = elements.symbol("Md")
+nobelium = No = elements.symbol("No")
+lawrencium = Lr = elements.symbol("Lr")
+rutherfordium = Rf = elements.symbol("Rf")
+dubnium = Db = elements.symbol("Db")
+seaborgium = Sg = elements.symbol("Sg")
+bohrium = Bh = elements.symbol("Bh")
+hassium = Hs = elements.symbol("Hs")
+meitnerium = Mt = elements.symbol("Mt")
+darmstadtium = Ds = elements.symbol("Ds")
+roentgenium = Rg = elements.symbol("Rg")
+copernicium = Cn = elements.symbol("Cn")
+nihonium = Nh = elements.symbol("Nh")
+flerovium = Fl = elements.symbol("Fl")
+moscovium = Mc = elements.symbol("Mc")
+livermorium = Lv = elements.symbol("Lv")
+tennessine = Ts = elements.symbol("Ts")
+oganesson = Og = elements.symbol("Og")
+deuterium = D = elements.symbol("D")
+tritium = T = elements.symbol("T")
+neutron = n = elements.symbol("n")
+
 # Add element name and symbol (e.g. nickel and Ni) to the public attributes.
 __all__ += core.define_elements(elements, globals())
 
@@ -91,6 +214,7 @@ def _load_covalent_radius():
                    'covalent_radius_units',
                    'covalent_radius_uncertainty'],
                   _load_covalent_radius)
+del _load_covalent_radius
 
 def _load_crystal_structure():
     """
@@ -102,6 +226,7 @@ def _load_crystal_structure():
     from . import crystal_structure
     crystal_structure.init(elements)
 core.delayed_load(['crystal_structure'], _load_crystal_structure)
+del _load_crystal_structure
 
 def _load_neutron():
     """
@@ -114,6 +239,7 @@ def _load_neutron():
     from . import nsf
     nsf.init(elements)
 core.delayed_load(['neutron'], _load_neutron, isotope=True)
+del _load_neutron
 
 def _load_neutron_activation():
     """
@@ -127,6 +253,7 @@ def _load_neutron_activation():
     activation.init(elements)
 core.delayed_load(['neutron_activation'], _load_neutron_activation,
                   element=False, isotope=True)
+del _load_neutron_activation
 
 def _load_xray():
     """
@@ -138,6 +265,7 @@ def _load_xray():
     from . import xsf
     xsf.init(elements)
 core.delayed_load(['xray'], _load_xray, ion=True)
+del _load_xray
 
 def _load_emission_lines():
     """
@@ -149,6 +277,7 @@ def _load_emission_lines():
     xsf.init_spectral_lines(elements)
 core.delayed_load(['K_alpha', 'K_beta1', 'K_alpha_units', 'K_beta1_units'],
                   _load_emission_lines)
+del _load_emission_lines
 
 def _load_magnetic_ff():
     """
@@ -161,6 +290,7 @@ def _load_magnetic_ff():
     from . import magnetic_ff
     magnetic_ff.init(elements)
 core.delayed_load(['magnetic_ff'], _load_magnetic_ff)
+del _load_magnetic_ff
 
 
 # Data needed for setup.py when bundling the package into an exe
@@ -173,9 +303,11 @@ def data_files():
     """
     import os
     import glob
+    from .core import get_data_path
+
     def _finddata(ext, patterns):
         files = []
-        path = core.get_data_path(ext)
+        path = get_data_path(ext)
         for p in patterns:
             files += glob.glob(os.path.join(path, p))
         return files