Use from __future__ import annotations

[gadomski]

Related Issue(s):

• Supports alternative constructors shouldn't hardcode their return types #862

Tl;dr:

Switch to using from __future__ import annotations to give us slightly cleaner type signatures.

Description:

As described in the mypy documentation, there are three tools at our disposal when resolving runtime typing issues:

• from __future__ import annotations
• String types
• typing.TYPE_CHECKING

Currently, pystac uses string types and typing.TYPE_CHECKING. This works fine, but does lead to a bit of clutter in the typing namespace, e.g.:

pystac/pystac/asset.py

Lines 8 to 11 in f44de3c

	if TYPE_CHECKING:
	from pystac.collection import Collection as Collection_Type
	from pystac.common_metadata import CommonMetadata as CommonMetadata_Type
	from pystac.item import Item as Item_Type

"Item_Type" and friends work fine for the purposes of defining our type signatures, but (IMO) they feel like a workaround and are a little awkward. Additionally, names like "Item_Type" will be confusing when combined with the names required to fix #862, e.g.:

TItem = TypeVar("TItem", bound=Item)
if typing.TYPE_CHECKING:
    from pystac.item import Item as Item_Type

# We now have both `TItem` and `Item_Type` in scope, and that feels confusing

class Item:
    def from_dict(d: Dict[str, Any]) -> TItem:
        ....

This PR removes the *_Type names, and uses from __future__ import annotations throughout the library to simplify some type signatures. I don't believe this is a risky change, because (a) it's recommended by mypy as a potential solution to typing issues, and (b) this may become the default Python behavior in the future, in which case we're setting ourselves up for success later.

There are no functional changes to behavior in this PR, this is purely a typing change. Also, because names like Item_Type are only used internally, I believe this PR is a non-breaking change.

As a sidecar fix, I also removed two unused imports in the top-level __init__.py.

PR Checklist:

• Code is formatted (run pre-commit run --all-files)
• Tests pass (run scripts/test)
• Documentation has been updated to reflect changes, if applicable
• This PR maintains or improves overall codebase code coverage.
• Changes are added to the CHANGELOG. See the docs for information about adding to the changelog.

[codecov-commenter]

Codecov Report

Base: 90.09% // Head: 90.13% // Increases project coverage by +0.04% 🎉

Coverage data is based on head (b21a0c5) compared to base (98246a0).
Patch coverage: 100.00% of modified lines in pull request are covered.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #962      +/-   ##
==========================================
+ Coverage   90.09%   90.13%   +0.04%     
==========================================
  Files          47       47              
  Lines        6086     6111      +25     
  Branches      913      913              
==========================================
+ Hits         5483     5508      +25     
  Misses        422      422              
  Partials      181      181              

Impacted Files	Coverage Δ
pystac/__init__.py	94.00% <100.00%> (ø)
pystac/asset.py	88.15% <100.00%> (+0.15%)	⬆️
pystac/cache.py	92.80% <100.00%> (+0.05%)	⬆️
pystac/catalog.py	91.98% <100.00%> (+0.01%)	⬆️
pystac/collection.py	93.46% <100.00%> (+0.02%)	⬆️
pystac/extensions/datacube.py	66.46% <100.00%> (+0.09%)	⬆️
pystac/extensions/eo.py	93.18% <100.00%> (+0.03%)	⬆️
pystac/extensions/file.py	91.79% <100.00%> (+0.06%)	⬆️
pystac/extensions/grid.py	100.00% <100.00%> (ø)
pystac/extensions/hooks.py	81.35% <100.00%> (+0.32%)	⬆️
... and 16 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[TomAugspurger]

There are no functional changes to behavior in this PR, this is purely a typing change. Also, because names like Item_Type are only used internally, I believe this PR is a non-breaking change.

If we're worried about this, we could leave stubs for these names around for a bit that emit a warning if they're accessed. It seems that pystac-client at least is OK: https://github.com/stac-utils/pystac-client/search?q=Item_Type. With a module-level __getattr__ (https://peps.python.org/pep-0562/) this wouldn't be too much of a hassle.

[gadomski]

If we're worried about this, we could leave stubs for these names around for a bit that emit a warning if they're accessed.

After playing some more, I think it's not worth worrying about. As a test, I tried to import Item_Type on current main, and got the following mypy error:

So it appears there's decent guardrails in place already to ensure no one is using these "internal" type names.

[duckontheweb]

This looks really good to me; much cleaner. __future__ to the rescue!