Adopt quotes around type names to make Reader ex. copy/paste-ready

[vreuter]

napari/docs#367 (review)
napari/docs#365

[lucyleeow]

That code snippet certainly gets there magically in a way I don't understand. I did not realise the code was 'copied' over from _docs/example_plugin/some_module.py. I am not sure of the purpose/all uses of the some_module.py example plugin so now I don't know if we still want to 'string' the annotations there? If we don't want to do strings, it seems we could add import code just above the '# example_plugin.some_module ' comment:

npe2/_docs/templates/_npe2_readers_guide.md.jinja

Lines 33 to 36 in 595b088

	```python
	# example_plugin.some_module
	{{ 'readers'|example_implementation }}
	```

I note also that the types alias definitions used in annotation of the functions also magically get into the code snippet - BUT we are missing LayerData, which is used in annotation but not given.

Maybe @melissawm or @psobolewskiPhD knows more about this?

[lucyleeow]

CI failures unrelated, don't worry about them, maybe due to the importlib release today?

[lucyleeow]

Fix for CIs in #341, we can update with main once that PR is merged. Thanks!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (595b088) to head (3747733).
Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #340   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           37        37           
  Lines         2750      2750           
=========================================
  Hits          2750      2750           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[tlambert03]

I understand the motivation, since the docs pluck out sub bits of example_plugin/some_module.py that aren't necessarily intended to be copy/pasted without the imports at the top.

But, if you go this direction, then you should also probably update example_plugin/some_module.py to put all the type imports inside of if TYPE_CHECKING. As is, this leaves some_module.py in a funny looking state with quotes around type names even though they've been imported at the top of the module

from npe2.types import LayerData, PathOrPaths, ReaderFunction

so, if someone were only looking at that module, they might say "hmm, why did they put them in quotes since they already imported it at the top of the module?"

[vreuter]

I understand the motivation, since the docs pluck out sub bits of example_plugin/some_module.py that aren't necessarily intended to be copy/pasted without the imports at the top.

But, if you go this direction, then you should also probably update example_plugin/some_module.py to put all the type imports inside of if TYPE_CHECKING. As is, this leaves some_module.py in a funny looking state with quotes around type names even though they've been imported at the top of the module

from npe2.types import LayerData, PathOrPaths, ReaderFunction

so, if someone were only looking at that module, they might say "hmm, why did they put them in quotes since they already imported it at the top of the module?"

indeed, good point @tlambert03 -- i update here: 3949b69

[vreuter]

@tlambert03 I guess the CI depends on #344 for the moment?

[tlambert03]

Looks like it

[lucyleeow]

@tlambert03 any idea how the type aliases at the top of the code snippet get there?

It does not seem to be from the code block in the jinja template:

npe2/_docs/templates/_npe2_readers_guide.md.jinja

Lines 33 to 36 in 595b088

	```python
	# example_plugin.some_module
	{{ 'readers'|example_implementation }}
	```

[lucyleeow]

Thanks! LGTM!

[tlambert03]

@tlambert03 any idea how the type aliases at the top of the code snippet get there?
It does not seem to be from the code block in the jinja template:

# example_plugin.some_module 
{{ 'readers'|example_implementation }} 

it is actually from that jinja block. that pipe (|) character in the {{ 'readers'|example_implementation }} expression is a jinja filter. It's a function defined somewhere that can modify the arguments passed to it (the bit before the pipe, in this case readers). If you grep for example_implementation in the repo, you'll find the function here:

npe2/_docs/render.py

Lines 125 to 130 in 595b088

	def example_implementation(contrib_name: str) -> str:
	"""Build an example string of python source implementing a specific contribution."""
	contrib = getattr(EXAMPLE_MANIFEST.contributions, contrib_name)
	if isinstance(contrib, list):
	return "\n\n".join([_build_example(x) for x in contrib]).strip()
	return _build_example(contrib)

which calls:

npe2/_docs/render.py

Line 94 in 595b088

def _build_example(contrib: Executable) -> str:

which grabs the needed types:

npe2/_docs/render.py

Lines 117 to 122 in 595b088

	needed = _get_needed_types(source)
	lines = [v for k, v in type_strings().items() if k in needed]
	if lines:
	lines.extend(["", ""])
	lines.extend(source.splitlines())
	return "\n".join(lines)

which is defined here:

npe2/_docs/render.py

Lines 79 to 91 in 595b088

	def _get_needed_types(source: str, so_far: Optional[Set[str]] = None) -> Set[str]:
	"""Return the names of types in the npe2.types.py that are used in `source`"""
	so_far = so_far or set()
	for name, string in type_strings().items():
	# we treat LayerData specially
	if (
	name != "LayerData"
	and name not in so_far
	and re.search(rf"\W{name}\W", source)
	):
	so_far.add(name)
	so_far.update(_get_needed_types(string, so_far=so_far))
	return so_far

[DragaDoncila]

CI is green again after merging main. Thanks for these updates @vreuter ❤️