python-type-narrowing

Guide Python type narrowing with isinstance, TypeIs, TypeGuard, and assert_type.

Updated May 20, 2025
One-click install
npx skills add https://github.com/flext-sh/flext --skill python-type-narrowing
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-type-narrowing
Source: https://github.com/flext-sh/flext/tree/main/.claude/skills/python-type-narrowing
Command: npx skills add https://github.com/flext-sh/flext --skill python-type-narrowing

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and rules (resource) components.

What problem does it solve?

This Skill addresses the complexity of writing precise conditional logic in Python, ensuring type safety and clarity when dealing with union types, optional values, and discriminated unions.

Core Features & Use Cases

  • Conditional Type Logic: Safely handle variables that can be one of several types using isinstance, TypeIs, and TypeGuard.
  • Exhaustiveness Checking: Guarantee that all possible cases of a union type are handled in match statements or if-else chains using assert_never.
  • Use Case: When processing a FlextResult object that could be either a success or a failure, use type narrowing to apply specific operations only to the success payload, preventing runtime errors.

Quick Start

Use the python-type-narrowing skill to demonstrate how to use TypeIs for discriminated union narrowing.

Frequently Asked Questions about python-type-narrowing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is type narrowing in Python and when do I need it?

Type narrowing in Python refines a variable's type within conditional blocks, ensuring type safety when handling union types, optional values, and discriminated unions. You need it to safely apply operations to specific types while preventing runtime errors.

How do I use TypeIs and TypeGuard for discriminated union narrowing in Python?

Use TypeIs and TypeGuard to create custom type guards for discriminated union narrowing in Python. This safely handles variables that can be one of several types, allowing conditional logic to apply operations only to the narrowed, target type.

How to perform exhaustiveness checking in Python match statements?

Perform exhaustiveness checking in Python match statements by using the assert_never function. This guarantees all possible cases of a union type are explicitly handled, enforcing type safety and code clarity across your conditional logic branches.

What is the best way to handle conditional type logic for Python union types?

The best way to handle conditional type logic for Python union types is by using isinstance, TypeIs, and TypeGuard. These techniques safely narrow variables to specific types, ensuring type safety and preventing runtime errors during execution.

Why does my Python type checker not narrow types after an isinstance check?

If your Python type checker fails to narrow types after an isinstance check, you may need to use TypeIs or TypeGuard for complex discriminated unions. These provide explicit type narrowing guidance for better type safety and code clarity.

Can I use assert_type to verify type narrowing in Python conditional logic?

Yes, you can use assert_type to verify type narrowing in Python conditional logic. It checks that a variable matches the expected narrowed type, ensuring type safety when processing complex union types and optional values.