Move single-use imports from top level

Python import times are noticeable during
interactive use of CLI applications, so
push the (near) single-use imports into
the functions where they are used so
the import cost is paid when calling
the functions instead of when starting
the CLI to print the help or do some
other unrelated action.

Timings on top of #1583 inside
a Python:3.10-bookworm container.

Before this change:

$ uv run hyperfine --warmup 3 "python3 -c 'import pystac'"
Benchmark 1: python3 -c 'import pystac'
  Time (mean ± σ):      67.2 ms ±   1.6 ms    [User: 58.6 ms, System: 8.6 ms]
  Range (min … max):    62.5 ms …  69.9 ms    45 runs

After this change:

$ uv run hyperfine --warmup 3 "python3 -c 'import pystac'"
Benchmark 1: python3 -c 'import pystac'
  Time (mean ± σ):      59.9 ms ±   1.5 ms    [User: 52.0 ms, System: 7.8 ms]
  Range (min … max):    56.9 ms …  64.2 ms    48 runs

Author: pjonsson

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+- Speed up importing pystac ([#1584](https://github.com/stac-utils/pystac/pull/1584))
+
 ## [v1.14.1] - 2025-09-18
 
 ### Fixed

pystac/__init__.py

@@ -44,7 +44,6 @@
     "set_stac_version",
 ]
 
-import os
 import warnings
 from typing import Any
 
@@ -199,6 +198,8 @@ def write_file(
     """
     if stac_io is None:
         stac_io = StacIO.default()
+    import os
+
     dest_href = None if dest_href is None else str(os.fspath(dest_href))
     obj.save_object(
         include_self_link=include_self_link, dest_href=dest_href, stac_io=stac_io

pystac/asset.py

@@ -1,13 +1,10 @@
 from __future__ import annotations
 
-import os
 import shutil
 from copy import copy, deepcopy
-from html import escape
 from typing import TYPE_CHECKING, Any, Protocol, TypeVar
 
 from pystac import MediaType, STACError, common_metadata, utils
-from pystac.html.jinja_env import get_jinja_env
 from pystac.utils import is_absolute_href, make_absolute_href, make_relative_href
 
 if TYPE_CHECKING:
@@ -182,6 +179,10 @@ def __repr__(self) -> str:
         return f"<Asset href={self.href}>"
 
     def _repr_html_(self) -> str:
+        from html import escape
+
+        from pystac.html.jinja_env import get_jinja_env
+
         jinja_env = get_jinja_env()
         if jinja_env:
             template = jinja_env.get_template("JSON.jinja2")
@@ -259,6 +260,8 @@ def delete(self) -> None:
 
         Does not modify the asset.
         """
+        import os
+
         href = _absolute_href(self.href, self.owner, "delete")
         os.remove(href)
 

pystac/catalog.py

@@ -1,10 +1,8 @@
 from __future__ import annotations
 
 import os
-import warnings
 from collections.abc import Callable, Iterable, Iterator
 from copy import deepcopy
-from itertools import chain
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -521,6 +519,8 @@ def get_item(self, id: str, recursive: bool = False) -> Item | None:
         Return:
             Item or None: The item with the given ID, or None if not found.
         """
+        import warnings
+
         warnings.warn(
             "get_item is deprecated and will be removed in v2. "
             "Use next(self.get_items(id), None) instead",
@@ -549,6 +549,8 @@ def get_items(self, *ids: str, recursive: bool = False) -> Iterator[Item]:
                 (if recursive) all catalogs or collections connected to this catalog
                 through child links.
         """
+        from itertools import chain
+
         items: Iterator[Item]
         if not recursive:
             items = map(
@@ -615,6 +617,9 @@ def get_all_items(self) -> Iterator[Item]:
                 catalogs or collections connected to this catalog through
                 child links.
         """
+        import warnings
+        from itertools import chain
+
         warnings.warn(
             "get_all_items is deprecated and will be removed in v2",
             DeprecationWarning,

pystac/collection.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import warnings
 from collections.abc import Iterable, Sequence
 from copy import deepcopy
 from datetime import datetime, timezone
@@ -12,8 +11,6 @@
     cast,
 )
 
-from dateutil import tz
-
 import pystac
 from pystac import CatalogType, STACObjectType
 from pystac.asset import Asset, Assets
@@ -257,6 +254,8 @@ def from_dict(d: dict[str, Any]) -> TemporalExtent:
         parsed_intervals: list[list[datetime | None]] = []
         for i in d["interval"]:
             if isinstance(i, str):
+                import warnings
+
                 # d["interval"] is a list of strings, so we correct the list and
                 # try again
                 # https://github.com/stac-utils/pystac/issues/1221
@@ -384,6 +383,8 @@ def from_items(
             Extent: An Extent that spatially and temporally covers all of the
             given items.
         """
+        from dateutil import tz
+
         bounds_values: list[list[float]] = [
             [float("inf")],
             [float("inf")],
@@ -635,6 +636,8 @@ def from_dict(
         migrate: bool = True,
         preserve_dict: bool = True,
     ) -> C:
+        import warnings
+
         from pystac.extensions.version import CollectionVersionExtension
 
         if migrate:

pystac/extensions/eo.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import warnings
 from collections.abc import Iterable
 from typing import (
     Any,
@@ -386,6 +385,8 @@ def get_schema_uri(cls) -> str:
 
     @classmethod
     def get_schema_uris(cls) -> list[str]:
+        import warnings
+
         warnings.warn(
             "get_schema_uris is deprecated and will be removed in v2",
             DeprecationWarning,

pystac/extensions/file.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import warnings
 from collections.abc import Iterable
 from typing import Any, Generic, Literal, TypeVar, cast
 
@@ -370,6 +369,8 @@ def migrate(
                 found_fields[asset_key] = values
 
         if found_fields:
+            import warnings
+
             warnings.warn(
                 f"Assets {list(found_fields.keys())} contain fields: "
                 f"{list(set.union(*found_fields.values()))} which "

pystac/extensions/grid.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import re
-import warnings
 from re import Pattern
 from typing import Any, Literal
 
@@ -92,6 +91,8 @@ def get_schema_uri(cls) -> str:
 
     @classmethod
     def get_schema_uris(cls) -> list[str]:
+        import warnings
+
         warnings.warn(
             "get_schema_uris is deprecated and will be removed in v2",
             DeprecationWarning,

pystac/extensions/item_assets.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import warnings
 from typing import Any, Literal
 
 import pystac
@@ -27,6 +26,8 @@ class AssetDefinition(ItemAssetDefinition):
     """
 
     def __init__(cls, *args: Any, **kwargs: Any) -> None:
+        import warnings
+
         warnings.warn(
             (
                 "``AssetDefinition`` is deprecated. "
@@ -49,6 +50,8 @@ class ItemAssetsExtension(ExtensionManagementMixin[pystac.Collection]):
     collection: pystac.Collection
 
     def __init__(self, collection: pystac.Collection) -> None:
+        import warnings
+
         warnings.warn(
             (
                 "The ``item_assets`` extension is deprecated. "

pystac/extensions/projection.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import json
-import warnings
 from collections.abc import Iterable
 from typing import (
     Any,
@@ -223,6 +221,8 @@ def crs_string(self) -> str | None:
         elif self.wkt2:
             return self.wkt2
         elif self.projjson:
+            import json
+
             return json.dumps(self.projjson)
         else:
             return None
@@ -321,6 +321,8 @@ def get_schema_uri(cls) -> str:
 
     @classmethod
     def get_schema_uris(cls) -> list[str]:
+        import warnings
+
         warnings.warn(
             "get_schema_uris is deprecated and will be removed in v2",
             DeprecationWarning,