Closes #180

Author: sobolevn

README.md

@@ -74,10 +74,11 @@ class IntField(Field):
 
 It literally has a lot of problems:
 
-- It is hard to type this code. How can I be sure that my `json` will be parsed by the given schema?
-- It contains a lot of boilerplate
-- It has complex API: there are usually several methods to override, some fields to adjust. Moreover, we use a class, not a callable
+- It is hard to type this code. How can I be sure that my `json` is parseable by the given schema?
+- It produces a lot of boilerplate
+- It has complex API: there are usually several methods to override, some fields to adjust. Moreover, we use a class, not a simple function
 - It is hard to extend the default library for new custom types you will have in your own project
+- It is hard to override
 
 There should be a better way of solving this problem!
 And typeclasses are a better way!
@@ -107,7 +108,6 @@ How would new API look like with this concept?
 ...         ', '.join(to_json(list_item) for list_item in instance),
 ...     )
 
-
 ```
 
 See how easy it is to works with types and implementation?

docs/pages/concept.rst

@@ -162,6 +162,54 @@ There's even a pattern to allow all objects in:
   >>> assert example('a') == 'obj'
 
 
+Overriding and extending existing instances
+-------------------------------------------
+
+Sometimes we really need to override how things work.
+With objects and classes this can be problematic,
+because we would need to definie a new subclass
+and chances are that it won't be used in some situations.
+
+With ``@typeclass`` overriding something is as easy.
+Let's define a typeclass with an instance to be overriden later:
+
+.. code:: python
+
+  >>> from classes import typeclass
+
+  >>> @typeclass
+  ... def example(instance) -> str:
+  ...    ...
+
+  >>> @example.instance(str)
+  ... def _example_str(instance: str) -> str:
+  ...      return instance.lower()
+
+  >>> assert example('Hello') == 'hello'
+
+Now, let's change how ``example`` behaves for ``str``.
+The only thing we need to do is to define ``.instance(str)`` once again:
+
+.. code:: python
+
+  >>> @example.instance(str)
+  ... def _example_str_new(instance: str) -> str:
+  ...      return instance.upper()
+
+  >>> assert example('Hello') == 'HELLO'
+
+Note, that we can reuse the original implementation
+by calling the instance case directly:
+
+.. code:: python
+
+  >>> @example.instance(str)
+  ... def _example_str_new(instance: str) -> str:
+  ...      return _example_str(instance) + '!'
+
+  >>> assert example('Hello') == 'hello!'
+
+
 supports typeguard
 ------------------
 

typesafety/test_typeclass/test_instance/test_instance_method.yml

@@ -247,3 +247,23 @@
         ...
 
     a(None)
+
+
+- case: typeclass_instance_override
+  disable_cache: false
+  main: |
+    from classes import typeclass
+
+    @typeclass
+    def example(instance) -> str:
+        ...
+
+    @example.instance(str)
+    def _example_str(instance: str) -> str:
+        return instance.lower()
+
+    @example.instance(str)
+    def _example_str_new(instance: str) -> str:
+        return _example_str(instance) + '!'
+
+    reveal_type(example('a'))  # N: Revealed type is "builtins.str"