feature: Expose typeguards for `Object` properties

[dangotbanned]

Is your feature request related to a problem? Please describe.

I've been working on some extensions which has been fun (thanks for griffe ❤️)

However, a stumbling block has been that the griffe.Object.is_* properties aren't playing nicely with type checkers:

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import griffe


def on_module(mod: griffe.Module) -> None:
    for member in mod.members.values():
        if member.is_class:
            _bases = member.bases
        elif member.is_module:
            _imports_future_annotations = member.imports_future_annotations

Show me red squiggles

Describe the solution you'd like

I like the color red, but not in my IDE.

Luckily, the typing spec has blessed is with (Type Narrowing) which can help avoid them:

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import griffe

if TYPE_CHECKING:
    import sys

    if sys.version_info >= (3, 13):
        from typing import TypeIs
    else:
        from typing_extensions import TypeIs


def is_class(obj: Any) -> TypeIs[griffe.Class]:
    return obj is griffe.Kind.CLASS


def is_module(obj: Any) -> TypeIs[griffe.Module]:
    return obj is griffe.Kind.MODULE


def on_module(mod: griffe.Module) -> None:
    for member in mod.members.values():
        if is_class(member):
            _bases = member.bases
        elif is_module(member):
            _imports_future_annotations = member.imports_future_annotations

Show me happy typing

Note

is_module and is_class are simple examples - the idea can extend to any kind of narrowing you'd use with griffe

Ideally, these guards would be accessible either at the top-level or their own namespace:

• griffe.is_*
• griffe.<somewhere-else>.is_*

Examples from elsewhere:

• narwhals.dependencies
• inspect.pyi (stdlib)
• pyarrow.types
• typing_inspection.typing_objects

Describe alternatives you've considered

• Ignore the issue
  • Use # <type-checker>: ignore[...]
    • Doesn't scale well to running multiple type checkers
  • Use typing.cast
    • Breaks exhaustiveness checking
    • Need to be careful that the target type is correct (can't rely on the type checker's help)
• Avoid the issue
  • Use isinstance (or identity checks) inline
    • Can get verbose, fast
  • Rolling your own TypeIs guards
    • This is what I'm doing now
    • In theory, keeping in sync with griffe may be a concern
    • Doing this in a low-overhead way is usually best understood by the author
      • E.g. I'd need to read the source and find out about Kind to know that's a cheaper check than isinstance

But wait, can't we just define these on the existing properties?

I wish 😔, more details here.

In short, you can define a method to be typeguard - but the narrowing applies to the first non-self|cls argument.

The properties don't fit into this narrow window sadly

Additional context

I did a quick search for ignore, and found these guys that demonstrate the issue:

Show examples within griffe

A healthy chunk of mixins.py

griffe/packages/griffelib/src/griffe/_internal/extensions/dataclasses.py

Lines 80 to 81 in 5dc97b7

	if member.is_attribute:
	member = cast("Attribute", member)

griffe/packages/griffelib/src/griffe/_internal/extensions/dataclasses.py

Lines 212 to 213 in 5dc97b7

	if not member.is_alias and member.is_class:
	_apply_recursively(member, processed) # ty:ignore[invalid-argument-type]

griffe/packages/griffelib/src/griffe/_internal/extensions/dataclasses.py

Lines 216 to 217 in 5dc97b7

	if not member.is_alias and (member.is_module or member.is_class):
	_apply_recursively(member, processed) # ty:ignore[invalid-argument-type]

griffe/packages/griffelib/src/griffe/_internal/models.py

Lines 1225 to 1226 in 5dc97b7

	if self.members[name].is_alias:
	return self.members[name].target_path # ty:ignore[unresolved-attribute]

griffe/packages/griffelib/src/griffe/_internal/models.py

Lines 2111 to 2116 in 5dc97b7

	while target.is_alias:
	if target.path in paths_seen:
	raise CyclicAliasError([*paths_seen, target.path])
	paths_seen[target.path] = None
	target = target.target # ty:ignore[unresolved-attribute]
	return target # ty:ignore[invalid-return-type]

griffe/packages/griffelib/src/griffe/_internal/models.py

Lines 2275 to 2276 in 5dc97b7

	and self.members["annotations"].is_alias
	and self.members["annotations"].target_path == "__future__.annotations" # ty:ignore[unresolved-attribute]

griffe/packages/griffelib/src/griffe/_internal/models.py

Line 2453 in 5dc97b7

bases: list[Class] = [base for base in self.resolved_bases if base.is_class] # ty:ignore[invalid-assignment]

[pawamoy]

Hey @dangotbanned, thanks for the request 🙂 Narwhals is a really nice project! I particularly enjoyed seeing how much work you put in your docs 👍

---

If I could answer in one link: https://discuss.python.org/t/using-a-property-as-type-guard/27956 😂

It would be really annoying to have to maintain a set of additional is_* functions, and that's why I went the ignore + cast route in my own code. I'll reconsider it though, thanks for bringing this up again 🙂

[dangotbanned]

Hey @dangotbanned, thanks for the request 🙂 Narwhals is a really nice project! I particularly enjoyed seeing how much work you put in your docs 👍

Ah thanks, wish I could take credit for that!
Although hopefully we'll be taking advantage of more zensical/mkdocstrings features soon

This was all mostly painless to switch on 🙏

diff --git a/zensical.toml b/zensical.toml
index 31ac3aaa7..be547b12a 100644
--- a/zensical.toml
+++ b/zensical.toml
 
@@ -111,6 +141,9 @@ features = [
     "navigation.top",
     "search.highlight",
     "toc.follow",
+    # NOTE: Fixes a bug where a `<span ...>` got injected into the `title` string?
+    # Also looks nice
+    "content.tooltips"
 ]
 
 [project.theme.font]
@@ -131,8 +164,22 @@ toggle.name = "Switch to light mode"
 icon = "fontawesome/brands/github"
 link = "https://github.com/narwhals-dev/narwhals"
 
+[project.plugins.mkdocstrings]
+# - 2-column "Parameters:" table `/python/material/docstring/parameters.html.jinja`
+custom_templates = "docs/templates"
+
 [project.plugins.mkdocstrings.handlers.python]
-inventories = ["https://docs.python.org/3/objects.inv"]
+# https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories
+inventories = [
+    "https://docs.python.org/3/objects.inv", 
+    "https://docs.pola.rs/py-polars/html/objects.inv",  # https://github.com/pola-rs/polars/issues/7027
+    "https://pandas.pydata.org/docs/objects.inv",
+    "https://arrow.apache.org/docs/objects.inv",
+    "https://numpy.org/doc/stable/objects.inv",
+    "https://typing-extensions.readthedocs.io/en/latest/objects.inv",
+    # https://github.com/ibis-project/ibis/issues/11723
+    # TODO @dangotbanned: cudf, dask, duckdb, pyspark, sqlframe
+]
 paths = ["narwhals"]
 
 [project.plugins.mkdocstrings.handlers.python.options]
@@ -140,6 +187,23 @@ docstring_style = "google"
 members_order = "alphabetical"
 separate_signature = true
 show_signature_annotations = true
+show_source = false
+show_if_no_docstring = true  # remember to turn this off after listing members everywhere
+signature_crossrefs = true
+type_parameter_headings = true
+line_length = 90  # (default: 60) this matches our ruff config
+filters = [
+    "!^_",
+    "^__",
+    # above are default filters, everything after refines from them
+    # https://mkdocstrings.github.io/python/usage/configuration/members/#filters
+    "!^_+(repr|slots|all)"
+]
+extensions = [
+    { "utils/griffe_extension.py:NewAsInitExtension" = { paths = ["narwhals._plan.schema.FrozenSchema"] } }, 
+    "utils/griffe_extension.py:PEP681Extension",
+]
+merge_init_into_class = true
 
 [project.markdown_extensions.admonition]
 [project.markdown_extensions.md_in_html]
@@ -157,3 +221,11 @@ emoji_generator = "zensical.extensions.emoji.to_svg"
 
 [project.markdown_extensions.pymdownx.arithmatex]
 generic = true
+
+[project.markdown_extensions.pymdownx.tilde]
+[project.markdown_extensions.pymdownx.highlight]
+# https://mkdocstrings.github.io/recipes/#automatic-highlighting-for-indented-code-blocks-in-docstrings
+pygments_lang_class = true
+default_lang = "python"
+[project.markdown_extensions.pymdownx.tasklist]
+custom_checkbox = true

If I could answer in one link: discuss.python.org/t/using-a-property-as-type-guard/27956 😂

Oh wow, you beat me to it by a few years 😂
I could've trimmed my pitch a bit if I'd done my homework better

It would be really annoying to have to maintain a set of additional is_* functions, and that's why I went the ignore + cast route in my own code.

Totally fair, I'm here asking you to take that burden from me 😉

But wait, there's more ...

You could also make use of the guards as functions at runtime ¹ with griffe.Object.filter_members.

Since @property's are descriptors, this wouldn't work and you'd need a lambda instead:

import griffe

with griffe.temporary_visited_module("def f(foo='<>'): ...") as module:
    module.filter_members(griffe.Object.is_public)

TypeError: 'property' object is not callable

---

I'll reconsider it though, thanks for bringing this up again 🙂

Thanks, really appreciate what you've made here

Footnotes

1. Getting filter_members to play nicely with a type checker is a different story.
   The single predicate case is solved in inspect.getmembers.
   But for *predicates you'd need something like the map (stdlib) overloads 😳 ↩