feat: custom converter types

src/ape/api/convert.py

@@ -1,4 +1,4 @@
-from abc import abstractmethod
+from abc import ABC, abstractmethod
 from typing import Any, Generic, TypeVar
 
 from ape.utils.basemodel import BaseInterfaceModel
@@ -56,3 +56,23 @@ def name(self) -> str:
         class_name = self.__class__.__name__
         name = class_name.replace("Converter", "").replace("Conversions", "")
         return name.lower()
+
+
+class ConvertibleAPI(ABC):
+    """
+    Use this base-class mixin if you want your custom class to be convertible to a more basic type
+    without having to register a converter plugin for it.
+    """
+
+    @abstractmethod
+    def is_convertible(self, to_type: type) -> bool:
+        """
+        Returns ``True`` if ``self`` can be converted to ``to_type``.
+        """
+
+    @abstractmethod
+    def convert_to(self, to_type: type) -> Any:
+        """
+        Convert ``self`` to the given type. Implementing classes _should_ raise ``ConversionError`` if not convertible.
+        Ape's conversion system will **only** attempt to convert classes where ``.is_convertible()`` returns ``True``.
+        """

src/ape/managers/converters.py

@@ -12,7 +12,7 @@
 from eth_utils import is_0x_prefixed, is_checksum_address, is_hex, is_hex_address, to_int
 
 from ape.api.address import BaseAddress
-from ape.api.convert import ConverterAPI
+from ape.api.convert import ConverterAPI, ConvertibleAPI
 from ape.api.transactions import TransactionAPI
 from ape.exceptions import ConversionError
 from ape.logging import logger
@@ -365,6 +365,12 @@ def convert(self, value: Any, to_type: Union[type, tuple, list]) -> Any:
             # NOTE: Always process lists and tuples
             return value
 
+        if isinstance(value, ConvertibleAPI) and value.is_convertible(to_type):
+            return value.convert_to(to_type)
+
+        return self._convert_using_converter_apis(value, to_type)
+
+    def _convert_using_converter_apis(self, value: Any, to_type: type) -> Any:
         for converter in self._converters[to_type]:
             try:
                 is_convertible = converter.is_convertible(value)

src/ape/utils/basemodel.py

@@ -15,7 +15,11 @@
 from pydantic import BaseModel as RootBaseModel
 from pydantic import ConfigDict
 
-from ape.exceptions import ApeAttributeError, ApeIndexError, ProviderNotConnectedError
+from ape.exceptions import (
+    ApeAttributeError,
+    ApeIndexError,
+    ProviderNotConnectedError,
+)
 from ape.logging import logger
 from ape.utils.misc import log_instead_of_fail, raises_not_implemented
 

tests/functional/conversion/test_custom.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+import pytest
+
+from ape.api.convert import ConvertibleAPI
+from ape.types.address import AddressType
+
+
+@pytest.fixture(scope="module")
+def custom_type(accounts):
+    class MyAccountWrapper(ConvertibleAPI):
+        def __init__(self, acct):
+            self.acct = acct
+
+        def is_convertible(self, to_type: type) -> bool:
+            return to_type is AddressType
+
+        def convert_to(self, to_type: type) -> Any:
+            if to_type is AddressType:
+                return self.acct.address
+
+            raise NotImplementedError()
+
+    return MyAccountWrapper(accounts[0])
+
+
+def test_convert(custom_type, conversion_manager, accounts):
+    """
+    You can use the regular conversion manager to convert the custom type.
+    """
+    actual = conversion_manager.convert(custom_type, AddressType)
+    assert actual == accounts[0].address