md2reflect 3.1.1__py3-none-any.whl

md2reflect/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2020-present Jean-François Moulin <jean-francois.moulin@hereon.de>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+__version__ = "3.1.1"

md2reflect/__init__.py

@@ -0,0 +1,310 @@
+# SPDX-FileCopyrightText: 2020-present Jean-François Moulin <jean-francois.moulin@hereon.de>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+MD2Reflect - Molecular Dynamics to Reflectivity
+
+A package for calculating neutron and X-ray
+reflectivity from molecular dynamics simulations.
+
+Submodules and public names are resolved lazily (PEP 562).  Python
+executes a package's ``__init__`` before any of its submodules, so
+while this module imported everything eagerly, *any* import from the
+package paid for the whole tree -- ``import md2reflect.erf_profile``
+pulled in matplotlib, scipy.optimize and the plotting stack even
+though ``erf_profile`` itself needs only numpy and ``scipy.special``.
+Reaching a name now imports just the module that defines it.
+
+Nothing changes for callers: ``from md2reflect import Sample``,
+``import md2reflect; md2reflect.Sample``, ``from md2reflect import *``
+and ``import md2reflect.sample`` all behave exactly as before.  The one
+visible difference is *when* an error surfaces -- a broken or missing
+optional dependency now raises on first use of the name that needs it,
+rather than at ``import md2reflect``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+# Eager, not lazy, and deliberately so: `md2reflect.__version__` is the
+# first thing a bug report, a notebook header or a provenance record
+# asks for, and it must never depend on which optional stack happens to
+# be installed. `__about__` imports nothing, so this costs nothing.
+# The `as __version__` spelling is the explicit re-export form (PEP
+# 484): it tells ruff and mypy --strict that this name is deliberately
+# part of this module's surface, rather than an unused import.
+from .__about__ import __version__ as __version__
+
+# Submodules reachable as attributes of the package.
+_SUBMODULES = frozenset(
+    {
+        "abeles_minimal",
+        "api_overview",
+        "backends",
+        "bornagain_export",
+        "convolution",
+        "erf_profile",
+        "exceptions",
+        "export",
+        "materials",
+        "md_reader",
+        "reflectometer",
+        "region",
+        "sample",
+        "stepify",
+        "visualization",
+    }
+)
+
+# Public name -> the submodule that defines it.  Kept explicit rather
+# than discovered by scanning: a lazy loader that has to import
+# something to find out where a name lives would defeat its own
+# purpose.
+_ATTR_SOURCES = {
+    # API discovery
+    "api_table": "api_overview",
+    "load_api": "api_overview",
+    "show_api": "api_overview",
+    # Backend factory
+    "get_reflectivity_backend": "backends",
+    # BornAgain export (optional dependency)
+    "to_bornagain": "bornagain_export",
+    # Exceptions
+    "Error": "exceptions",
+    "HomogeneousLayerError": "exceptions",
+    "NevotCroceAccuracyWarning": "exceptions",
+    "ReflectometerError": "exceptions",
+    "SampleError": "exceptions",
+    "SimReaderError": "exceptions",
+    "SimulatedRegionError": "exceptions",
+    "WavelengthMissingError": "exceptions",
+    # Materials
+    "Material": "materials",
+    "MaterialsLibrary": "materials",
+    "PACKAGED_LIBRARY": "materials",
+    "default_library": "materials",
+    "homogeneous_layer_from_material": "materials",
+    # Core classes
+    "Reflectometer": "reflectometer",
+    "CU_K_ALPHA": "region",
+    "ISOTOPE_ALIASES": "region",
+    "HomogeneousLayer": "region",
+    "Region": "region",
+    "SimulatedRegion": "region",
+    "SLDSet": "region",
+    "mixed_b_c": "region",
+    "Sample": "sample",
+    "SampleDesc": "sample",
+    "StepifiedProfile": "sample",
+    # State management
+    "CachedProperty": "state_management",
+    "InvalidatingProperty": "state_management",
+    "ManagedStateMixin": "state_management",
+    "cached_property": "state_management",
+    # Types
+    "FM_TO_ANGSTROM": "typing_defs",
+    "SLD": "typing_defs",
+    "Angstrom": "typing_defs",
+    "Angstrom3": "typing_defs",
+    "AngstromArray1D": "typing_defs",
+    "BeamDirection": "typing_defs",
+    "BoolArr1D": "typing_defs",
+    "Element": "typing_defs",
+    "FloatArr1D": "typing_defs",
+    "FloatArr2D": "typing_defs",
+    "IntArr1D": "typing_defs",
+    "InverseAngstrom": "typing_defs",
+    "NanoMeter": "typing_defs",
+    "Probe": "typing_defs",
+    "RegionRole": "typing_defs",
+    "ResolutionMethod": "typing_defs",
+    "RoughnessMethod": "typing_defs",
+}
+
+if TYPE_CHECKING:
+    # Never executed.  Restated here so type checkers, IDEs and
+    # autocompletion see the real objects instead of the ``Any`` a
+    # module-level ``__getattr__`` would otherwise hand them.
+    from . import (
+        abeles_minimal,
+        api_overview,
+        backends,
+        bornagain_export,
+        convolution,
+        erf_profile,
+        exceptions,
+        export,
+        materials,
+        md_reader,
+        reflectometer,
+        region,
+        sample,
+        stepify,
+        visualization,
+    )
+    from .api_overview import api_table, load_api, show_api
+    from .backends import get_reflectivity_backend
+    from .bornagain_export import to_bornagain
+    from .exceptions import (
+        Error,
+        HomogeneousLayerError,
+        NevotCroceAccuracyWarning,
+        ReflectometerError,
+        SampleError,
+        SimReaderError,
+        SimulatedRegionError,
+        WavelengthMissingError,
+    )
+    from .materials import (
+        PACKAGED_LIBRARY,
+        Material,
+        MaterialsLibrary,
+        default_library,
+        homogeneous_layer_from_material,
+    )
+    from .reflectometer import Reflectometer
+    from .region import (
+        CU_K_ALPHA,
+        ISOTOPE_ALIASES,
+        HomogeneousLayer,
+        Region,
+        SimulatedRegion,
+        SLDSet,
+        mixed_b_c,
+    )
+    from .sample import Sample, SampleDesc, StepifiedProfile
+    from .state_management import (
+        CachedProperty,
+        InvalidatingProperty,
+        ManagedStateMixin,
+        cached_property,
+    )
+    from .typing_defs import (
+        FM_TO_ANGSTROM,
+        SLD,
+        Angstrom,
+        Angstrom3,
+        AngstromArray1D,
+        BeamDirection,
+        BoolArr1D,
+        Element,
+        FloatArr1D,
+        FloatArr2D,
+        IntArr1D,
+        InverseAngstrom,
+        NanoMeter,
+        Probe,
+        RegionRole,
+        ResolutionMethod,
+        RoughnessMethod,
+    )
+
+
+def __getattr__(name: str) -> Any:
+    """Import the module behind *name* on first access (PEP 562).
+
+    The resolved object is written into the module globals, so this
+    runs once per name and every later lookup is an ordinary attribute
+    read.
+    """
+    source = _ATTR_SOURCES.get(name)
+    if source is not None:
+        module = importlib.import_module(f".{source}", __name__)
+        value: Any = getattr(module, name)
+    elif name in _SUBMODULES:
+        value = importlib.import_module(f".{name}", __name__)
+    else:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Public names, without importing anything to list them."""
+    return sorted(set(__all__) | set(globals()))
+
+
+__all__ = [
+    # NB: `__version__` is deliberately absent. `__all__` lists the
+    # lazily-resolved names, and the tests assert that every entry is
+    # reachable through _SUBMODULES or _ATTR_SOURCES -- `__version__` is
+    # neither, being imported eagerly above. It is also a dunder, which
+    # `from md2reflect import *` has no business binding. It remains
+    # available as `md2reflect.__version__`.
+    # Submodules
+    "abeles_minimal",
+    "api_overview",
+    "backends",
+    "bornagain_export",
+    "convolution",
+    "erf_profile",
+    "exceptions",
+    "export",
+    "materials",
+    "md_reader",
+    "reflectometer",
+    "region",
+    "sample",
+    "stepify",
+    "visualization",
+    # API discovery
+    "api_table",
+    "load_api",
+    "show_api",
+    # Backend factory
+    "get_reflectivity_backend",
+    # Materials
+    "PACKAGED_LIBRARY",
+    "Material",
+    "MaterialsLibrary",
+    "default_library",
+    "homogeneous_layer_from_material",
+    # Core classes
+    "CU_K_ALPHA",
+    "HomogeneousLayer",
+    "ISOTOPE_ALIASES",
+    "Reflectometer",
+    "Region",
+    "SLDSet",
+    "Sample",
+    "SampleDesc",
+    "SimulatedRegion",
+    "StepifiedProfile",
+    "mixed_b_c",
+    "to_bornagain",
+    # Exceptions
+    "Error",
+    "HomogeneousLayerError",
+    "NevotCroceAccuracyWarning",
+    "ReflectometerError",
+    "SampleError",
+    "SimReaderError",
+    "SimulatedRegionError",
+    "WavelengthMissingError",
+    # State management
+    "CachedProperty",
+    "InvalidatingProperty",
+    "ManagedStateMixin",
+    "cached_property",
+    # Types
+    "Angstrom",
+    "Angstrom3",
+    "AngstromArray1D",
+    "BeamDirection",
+    "BoolArr1D",
+    "Element",
+    "FM_TO_ANGSTROM",
+    "FloatArr1D",
+    "FloatArr2D",
+    "IntArr1D",
+    "InverseAngstrom",
+    "NanoMeter",
+    "Probe",
+    "RegionRole",
+    "ResolutionMethod",
+    "RoughnessMethod",
+    "SLD",
+]