Add an AsIsLayoutStrategy

[gadomski]

Related Issue(s):

• Helps fix Add_item changes explicitly set links to fit the assumed structure #875

Description:

Currently, it's impossible to use Catalog.add_item but preserve the self_href of the item. This PR adds a new layout that simply preserves the existing href, or raises a ValueError if one isn't set.

I don't love the name AsIsLayoutStrategy, so improving suggestions are welcome! Other names I considered:

• NoopLayoutStrategy
• PassthroughLayoutStrategy

cc @kylemann16

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.12% // Head: 90.08% // Decreases project coverage by -0.04% ⚠️

Coverage data is based on head (01b9467) compared to base (f44de3c).
Patch coverage: 62.50% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #919      +/-   ##
==========================================
- Coverage   90.12%   90.08%   -0.04%     
==========================================
  Files          47       47              
  Lines        6063     6079      +16     
  Branches      909      912       +3     
==========================================
+ Hits         5464     5476      +12     
- Misses        420      422       +2     
- Partials      179      181       +2     

Impacted Files	Coverage Δ
pystac/layout.py	87.86% <62.50%> (-2.14%)	⬇️
pystac/stac_object.py	91.89% <0.00%> (+1.08%)	⬆️

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.

[kylemann16]

@gadomski Sorry for the late response here, but thanks for looking at this. Those names look good to me, maybe other options would beExplicitUrlLayoutStrategy, UrlNoopLayoutStrategy, or something to indicate that the user is handling all links themselves?

[gadomski]

UrlNoopLayoutStrategy

Yeah, I thought about NoopLayoutStrategy as well -- but then thought that it looked funny :-). I don't really have a strong inclination one way or the other, so will leave it to a reviewer to suggest/approve one of these (or other) options.

[pjhartzell]

Side note: The add_item() method on the Catalog class indicates the strategy parameter is optional, but it really is required with a default of BestPracticesLayoutStrategy (see the if strategy is None: line). Also, the strategy parameter is not given in the docstring Args list, adding another layer of ambiguity here.

pystac/pystac/catalog.py

Lines 277 to 297 in ea68043

	def add_item(
	self,
	item: "Item_Type",
	title: Optional[str] = None,
	strategy: Optional[HrefLayoutStrategy] = None,
	) -> None:
	"""Adds a link to an :class:`~pystac.Item`.
	This method will set the item's parent to this object, and its root to
	this Catalog's root.
	Args:
	item : The item to add.
	title : Optional title to give to the :class:`~pystac.Link`
	"""
	# Prevent typo confusion
	if isinstance(item, pystac.Catalog):
	raise pystac.STACError("Cannot add catalog as item. Use add_child instead.")
	if strategy is None:
	strategy = BestPracticesLayoutStrategy()

Also, it seems logical for a strategy parameter to be added to the Catalog.add_items() method.

Similar thoughts apply to the Collection class add_item() method.

[pjhartzell]

Looks good with caveat (in separate PR comment) about the need to better expose the default layout strategy.

[gadomski]

I opened #965 to capture the need to align the function signatures.