Metadata-Version: 2.4
Name: typemapping
Version: 0.1.7
Summary: Advanced type compatibility and checking system for Python
Author-email: rodbell <bellirodrigo2@gmail.com>
License: MIT
Keywords: typing,type-checking,generics,variance,annotations
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing-extensions>=4.13.2
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black>=23.1.0; extra == "dev"
Requires-Dist: isort>=5.11.5; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: ruff>=0.11.10; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# 🧬 typemapping

**Advanced Type Compatibility and Runtime Checking for Python 3.8+**

`typemapping` is a powerful and extensible package for deep type introspection and runtime type validation. It goes far beyond Python's built-in `isinstance` and `issubclass`, supporting generic types, `Annotated`, `Union`, specialized collections, and more — with compatibility across Python 3.8+ including `typing_extensions` support.

---

## 🚀 Features

* ✅ Generic type compatibility (`List[int] ~ Sequence[int]`)
* 🧠 Concrete-to-abstract compatibility (`Counter`, `OrderedDict`, `ChainMap`)
* 🔁 Full `Union` and `Optional` type support
* 🛠️ Python 3.8+ `Annotated` compatibility layer
* 🧪 Runtime type validation with container sampling
* 🔍 Field and function argument mapping with `Annotated` metadata extraction
* 📦 Framework-friendly: works with FastAPI, Pydantic, SQLAlchemy, etc.

---

## 📦 Installation

```bash
pip install typemapping
```

> ⚠️ `typing_extensions` is required for full support on Python 3.8.

---

## 🧑‍💻 Example

```python
from typing import List, Annotated
from typemapping.type_check import extended_isinstance

# Check generic type compatibility
print(extended_isinstance([1, 2, 3], List[int]))  # True
print(extended_isinstance([1, 2, 3], List[str]))  # False
```

---

## 🧩 Key APIs

### 🔎 Type Checking & Compatibility

* `extended_isinstance(obj, type_hint)`
* `generic_issubclass(subtype, supertype)`
* `is_equal_type(t1, t2)`
* `defensive_issubclass(cls, classinfo)`

### 🧬 Annotated Type Handling

* `is_annotated_type(type)`
* `strip_annotated(type)`
* `get_annotated_metadata(type)`

### 🧠 Function and Class Introspection

* `get_func_args(func)`
* `map_model_fields(cls)`
* `map_dataclass_fields(cls)`
* `get_field_type(cls, fieldname)`

### 🔁 Origin Compatibility

* `is_equivalent_origin(t1, t2)`
* `get_equivalent_origin(t)`
* `is_fully_compatible(t1, t2)`
* `get_compatibility_chain(t)`

---

## ⚙️ Compatibility

* ✅ Python 3.8 and above
* 🔄 Backward-compatible via `typing_extensions`

---

## 🧪 Running Tests

```bash
pytest
```

---

## 📄 License

MIT License

---

## 🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.
