ultraplot 0.99.3__py3-none-any.whl

ultraplot/internals/versions.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""
+Utilities for handling dependencies and version changes.
+"""
+from . import ic  # noqa: F401
+from . import warnings
+
+
+class _version(list):
+    """
+    Casual parser for ``major.minor`` style version strings. We do not want to
+    add a 'packaging' dependency and only care about major and minor tags.
+    """
+
+    def __str__(self):
+        return self._version
+
+    def __repr__(self):
+        return f"version({self._version})"
+
+    def __init__(self, version):
+        try:
+            major, minor, *_ = version.split(".")
+            major, minor = int(major or 0), int(minor or 0)
+        except Exception:
+            warnings._warn_ultraplot(f"Unexpected version {version!r}. Using 0.0.0.")
+            major = minor = 0
+        self._version = f"{major}.{minor}"
+        super().__init__((major, minor))  # then use builtin python list sorting
+
+    def __eq__(self, other):
+        return super().__eq__(_version(other))
+
+    def __ne__(self, other):
+        return super().__ne__(_version(other))
+
+    def __gt__(self, other):
+        return super().__gt__(_version(other))
+
+    def __lt__(self, other):
+        return super().__lt__(_version(other))
+
+    def __ge__(self, other):
+        return super().__ge__(_version(other))
+
+    def __le__(self, other):
+        return super().__le__(_version(other))
+
+
+# Matplotlib version
+import matplotlib  # isort:skip
+
+_version_mpl = _version(matplotlib.__version__)
+
+# Cartopy version
+try:
+    import cartopy
+except ImportError:
+    _version_cartopy = _version("0.0.0")
+else:
+    _version_cartopy = _version(cartopy.__version__)

ultraplot/internals/warnings.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""
+Utilities for internal warnings and deprecations.
+"""
+import functools
+import re
+import sys
+import warnings
+
+from . import ic  # noqa: F401
+
+# Internal modules omitted from warning message
+REGEX_INTERNAL = re.compile(r"\A(matplotlib|mpl_toolkits|ultraplot)\.")
+
+# Trivial warning class meant only to communicate the source of the warning
+UltraplotWarning = type("UltraPlotWarning", (UserWarning,), {})
+
+# Add due to overwriting the module name
+catch_warnings = warnings.catch_warnings
+simplefilter = warnings.simplefilter
+
+
+def next_release():
+    """
+    message indicating the next major release.
+    """
+    from .. import __version__
+
+    try:
+        # Find the first digit in the version string
+        version_start = next(i for i, c in enumerate(__version__) if c.isdigit())
+        num = int(__version__[version_start]) + 1
+    except (StopIteration, ValueError, TypeError):
+        string = "the next major release"
+    else:
+        which = "first" if num == 1 else "next"
+        string = f"the {which} major release (version {num}.0.0)"
+    return string
+
+
+def _warn_ultraplot(message):
+    """
+    Emit a `UltraPlotWarning` and show the stack level outside of matplotlib and
+    ultraplot. This is adapted from matplotlib's warning system.
+    """
+    frame = sys._getframe()
+    stacklevel = 1
+    while frame is not None:
+        if not REGEX_INTERNAL.match(frame.f_globals.get("__name__", "")):
+            break  # this is the first external frame
+        frame = frame.f_back
+        stacklevel += 1
+    warnings.warn(message, UltraplotWarning, stacklevel=stacklevel)
+
+
+def _rename_objs(version, **kwargs):
+    """
+    Emit a basic deprecation warning after renaming function(s), method(s), or
+    class(es). Each key should be an old name, and each argument should be the new
+    object to point to. Do not document the deprecated object(s) to discourage use.
+    """
+    objs = []
+    for old_name, new_obj in kwargs.items():
+        new_name = new_obj.__name__
+        message = (
+            f"{old_name!r} was deprecated in version {version} and may be "
+            f"removed in {next_release()}. Please use {new_name!r} instead."
+        )
+        if isinstance(new_obj, type):
+
+            class _deprecated_class(new_obj):
+                def __init__(self, *args, new_obj=new_obj, message=message, **kwargs):
+                    _warn_ultraplot(message)
+                    super().__init__(*args, **kwargs)
+
+            _deprecated_class.__name__ = old_name
+            objs.append(_deprecated_class)
+        elif callable(new_obj):
+
+            def _deprecated_function(*args, new_obj=new_obj, message=message, **kwargs):
+                _warn_ultraplot(message)
+                return new_obj(*args, **kwargs)
+
+            _deprecated_function.__name__ = old_name
+            objs.append(_deprecated_function)
+        else:
+            raise ValueError(f"Invalid deprecated object replacement {new_obj!r}.")
+    if len(objs) == 1:
+        return objs[0]
+    else:
+        return tuple(objs)
+
+
+def _rename_kwargs(version, **kwargs_rename):
+    """
+    Emit a basic deprecation warning after removing or renaming keyword argument(s).
+    Each key should be an old keyword, and each argument should be the new keyword
+    or *instructions* for what to use instead.
+    """
+
+    def _decorator(func_orig):
+        @functools.wraps(func_orig)
+        def _deprecate_kwargs_wrapper(*args, **kwargs):
+            for key_old, key_new in kwargs_rename.items():
+                if key_old not in kwargs:
+                    continue
+                value = kwargs.pop(key_old)
+                if key_new.isidentifier():
+                    # Rename argument
+                    kwargs[key_new] = value
+                elif "{}" in key_new:
+                    # Nice warning message, but user's desired behavior fails
+                    key_new = key_new.format(value)
+                _warn_ultraplot(
+                    f"Keyword {key_old!r} was deprecated in version {version} and may "
+                    f"be removed in {next_release()}. Please use {key_new!r} instead."
+                )
+            return func_orig(*args, **kwargs)
+
+        return _deprecate_kwargs_wrapper
+
+    return _decorator

ultraplot/proj.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+"""
+Additional cartopy projection classes.
+"""
+import warnings
+
+from .internals import ic  # noqa: F401
+from .internals import docstring
+
+try:
+    from cartopy.crs import (  # stereo projections needed in geo.py
+        AzimuthalEquidistant,
+        Gnomonic,
+        LambertAzimuthalEqualArea,
+        NorthPolarStereo,
+        SouthPolarStereo,
+        _WarpedRectangularProjection,
+    )
+except ModuleNotFoundError:
+    AzimuthalEquidistant = Gnomonic = LambertAzimuthalEqualArea = object
+    _WarpedRectangularProjection = NorthPolarStereo = SouthPolarStereo = object
+
+__all__ = [
+    "Aitoff",
+    "Hammer",
+    "KavrayskiyVII",
+    "WinkelTripel",
+    "NorthPolarAzimuthalEquidistant",
+    "SouthPolarAzimuthalEquidistant",
+    "NorthPolarGnomonic",
+    "SouthPolarGnomonic",
+    "NorthPolarLambertAzimuthalEqualArea",
+    "SouthPolarLambertAzimuthalEqualArea",
+]
+
+
+_reso_docstring = """
+The projection resolution.
+"""
+_init_docstring = """
+Parameters
+----------
+central_longitude : float, default: 0
+    The central meridian longitude in degrees.
+false_easting: float, default: 0
+    X offset from planar origin in metres.
+false_northing: float, default: 0
+    Y offset from planar origin in metres.
+globe : `~cartopy.crs.Globe`, optional
+    If omitted, a default globe is created.
+"""
+docstring._snippet_manager["proj.reso"] = _reso_docstring
+docstring._snippet_manager["proj.init"] = _init_docstring
+
+
+class Aitoff(_WarpedRectangularProjection):
+    """
+    The `Aitoff <https://en.wikipedia.org/wiki/Aitoff_projection>`__ projection.
+    """
+
+    #: Registered projection name.
+    name = "aitoff"
+
+    @docstring._snippet_manager
+    def __init__(
+        self, central_longitude=0, globe=None, false_easting=None, false_northing=None
+    ):
+        """
+        %(proj.init)s
+        """
+        from cartopy.crs import WGS84_SEMIMAJOR_AXIS, Globe
+
+        if globe is None:
+            globe = Globe(semimajor_axis=WGS84_SEMIMAJOR_AXIS, ellipse=None)
+
+        a = globe.semimajor_axis or WGS84_SEMIMAJOR_AXIS
+        b = globe.semiminor_axis or a
+        if b != a or globe.ellipse is not None:
+            warnings.warn(
+                f"The {self.name!r} projection does not handle elliptical globes."
+            )
+
+        proj4_params = {"proj": "aitoff", "lon_0": central_longitude}
+        super().__init__(
+            proj4_params,
+            central_longitude,
+            false_easting=false_easting,
+            false_northing=false_northing,
+            globe=globe,
+        )
+
+    @docstring._snippet_manager
+    @property
+    def threshold(self):  # how finely to interpolate line data, etc.
+        """
+        %(proj.reso)s
+        """
+        return 1e5
+
+
+class Hammer(_WarpedRectangularProjection):
+    """
+    The `Hammer <https://en.wikipedia.org/wiki/Hammer_projection>`__ projection.
+    """
+
+    #: Registered projection name.
+    name = "hammer"
+
+    @docstring._snippet_manager
+    def __init__(
+        self, central_longitude=0, globe=None, false_easting=None, false_northing=None
+    ):
+        """
+        %(proj.init)s
+        """
+        from cartopy.crs import WGS84_SEMIMAJOR_AXIS, Globe
+
+        if globe is None:
+            globe = Globe(semimajor_axis=WGS84_SEMIMAJOR_AXIS, ellipse=None)
+
+        a = globe.semimajor_axis or WGS84_SEMIMAJOR_AXIS
+        b = globe.semiminor_axis or a
+        if b != a or globe.ellipse is not None:
+            warnings.warn(
+                f"The {self.name!r} projection does not handle elliptical globes."
+            )
+
+        proj4_params = {"proj": "hammer", "lon_0": central_longitude}
+        super().__init__(
+            proj4_params,
+            central_longitude,
+            false_easting=false_easting,
+            false_northing=false_northing,
+            globe=globe,
+        )
+
+    @docstring._snippet_manager
+    @property
+    def threshold(self):  # how finely to interpolate line data, etc.
+        """
+        %(proj.reso)s
+        """
+        return 1e5
+
+
+class KavrayskiyVII(_WarpedRectangularProjection):
+    """
+    The `Kavrayskiy VII \
+<https://en.wikipedia.org/wiki/Kavrayskiy_VII_projection>`__ projection.
+    """
+
+    #: Registered projection name.
+    name = "kavrayskiyVII"
+
+    @docstring._snippet_manager
+    def __init__(
+        self, central_longitude=0, globe=None, false_easting=None, false_northing=None
+    ):
+        """
+        %(proj.init)s
+        """
+        from cartopy.crs import WGS84_SEMIMAJOR_AXIS, Globe
+
+        if globe is None:
+            globe = Globe(semimajor_axis=WGS84_SEMIMAJOR_AXIS, ellipse=None)
+
+        a = globe.semimajor_axis or WGS84_SEMIMAJOR_AXIS
+        b = globe.semiminor_axis or a
+        if b != a or globe.ellipse is not None:
+            warnings.warn(
+                f"The {self.name!r} projection does not handle elliptical globes."
+            )
+
+        proj4_params = {"proj": "kav7", "lon_0": central_longitude}
+        super().__init__(
+            proj4_params,
+            central_longitude,
+            false_easting=false_easting,
+            false_northing=false_northing,
+            globe=globe,
+        )
+
+    @docstring._snippet_manager
+    @property
+    def threshold(self):
+        """
+        %(proj.reso)s
+        """
+        return 1e5
+
+
+class WinkelTripel(_WarpedRectangularProjection):
+    """
+    The `Winkel tripel (Winkel III) \
+<https://en.wikipedia.org/wiki/Winkel_tripel_projection>`__ projection.
+    """
+
+    #: Registered projection name.
+    name = "winkeltripel"
+
+    @docstring._snippet_manager
+    def __init__(
+        self, central_longitude=0, globe=None, false_easting=None, false_northing=None
+    ):
+        """
+        %(proj.init)s
+        """
+        from cartopy.crs import WGS84_SEMIMAJOR_AXIS, Globe
+
+        if globe is None:
+            globe = Globe(semimajor_axis=WGS84_SEMIMAJOR_AXIS, ellipse=None)
+
+        a = globe.semimajor_axis or WGS84_SEMIMAJOR_AXIS
+        b = globe.semiminor_axis or a
+        if b != a or globe.ellipse is not None:
+            warnings.warn(
+                f"The {self.name!r} projection does not handle " "elliptical globes."
+            )
+
+        proj4_params = {"proj": "wintri", "lon_0": central_longitude}
+        super().__init__(
+            proj4_params,
+            central_longitude,
+            false_easting=false_easting,
+            false_northing=false_northing,
+            globe=globe,
+        )
+
+    @docstring._snippet_manager
+    @property
+    def threshold(self):
+        """
+        %(proj.reso)s
+        """
+        return 1e5
+
+
+class NorthPolarAzimuthalEquidistant(AzimuthalEquidistant):
+    """
+    Analogous to `~cartopy.crs.NorthPolarStereo`.
+    """
+
+    @docstring._snippet_manager
+    def __init__(self, central_longitude=0.0, globe=None):
+        """
+        %(proj.init)s
+        """
+        super().__init__(
+            central_latitude=90, central_longitude=central_longitude, globe=globe
+        )
+
+
+class SouthPolarAzimuthalEquidistant(AzimuthalEquidistant):
+    """
+    Analogous to `~cartopy.crs.SouthPolarStereo`.
+    """
+
+    @docstring._snippet_manager
+    def __init__(self, central_longitude=0.0, globe=None):
+        """
+        %(proj.init)s
+        """
+        super().__init__(
+            central_latitude=-90, central_longitude=central_longitude, globe=globe
+        )
+
+
+class NorthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea):
+    """
+    Analogous to `~cartopy.crs.NorthPolarStereo`.
+    """
+
+    @docstring._snippet_manager
+    def __init__(self, central_longitude=0.0, globe=None):
+        """
+        %(proj.init)s
+        """
+        super().__init__(
+            central_latitude=90, central_longitude=central_longitude, globe=globe
+        )
+
+
+class SouthPolarLambertAzimuthalEqualArea(LambertAzimuthalEqualArea):
+    """
+    Analogous to `~cartopy.crs.SouthPolarStereo`.
+    """
+
+    @docstring._snippet_manager
+    def __init__(self, central_longitude=0.0, globe=None):
+        """
+        %(proj.init)s
+        """
+        super().__init__(
+            central_latitude=-90, central_longitude=central_longitude, globe=globe
+        )
+
+
+class NorthPolarGnomonic(Gnomonic):
+    """
+    Analogous to `~cartopy.crs.NorthPolarStereo`.
+    """
+
+    @docstring._snippet_manager
+    def __init__(self, central_longitude=0.0, globe=None):
+        """
+        %(proj.init)s
+        """
+        super().__init__(
+            central_latitude=90, central_longitude=central_longitude, globe=globe
+        )
+
+
+class SouthPolarGnomonic(Gnomonic):
+    """
+    Analogous to `~cartopy.crs.SouthPolarStereo`.
+    """
+
+    @docstring._snippet_manager
+    def __init__(self, central_longitude=0.0, globe=None):
+        """
+        %(proj.init)s
+        """
+        super().__init__(
+            central_latitude=-90, central_longitude=central_longitude, globe=globe
+        )