improve source/sink api docs

metadata-ingestion/src/datahub/ingestion/api/decorators.py

@@ -1,3 +1,4 @@
+import abc
 from dataclasses import dataclass
 from enum import Enum, auto
 from typing import Callable, Dict, Optional, Type
@@ -25,6 +26,8 @@ def wrapper(cls: Type) -> Type:
             # add the create method only if it has not been overridden from the base Source.create method
             cls.create = classmethod(default_create)
 
+            abc.update_abstractmethods(cls)
+
         return cls
 
     return wrapper

metadata-ingestion/src/datahub/ingestion/api/sink.py

@@ -110,16 +110,28 @@ def __init__(self, ctx: PipelineContext, config: SinkConfig):
         self.__post_init__()
 
     def __post_init__(self) -> None:
+        """Hook called after the sink's main initialization is complete.
+
+        Sink subclasses can override this method to customize initialization.
+        """
         pass
 
     @classmethod
     def create(cls, config_dict: dict, ctx: PipelineContext) -> "Self":
         return cls(ctx, cls.get_config_class().parse_obj(config_dict))
 
     def handle_work_unit_start(self, workunit: WorkUnit) -> None:
+        """Called at the start of each new workunit.
+
+        This method is deprecated and will be removed in a future release.
+        """
         pass
 
     def handle_work_unit_end(self, workunit: WorkUnit) -> None:
+        """Called at the end of each workunit.
+
+        This method is deprecated and will be removed in a future release.
+        """
         pass
 
     @abstractmethod

metadata-ingestion/src/datahub/ingestion/api/source.py

@@ -400,13 +400,8 @@ class Source(Closeable, metaclass=ABCMeta):
     ctx: PipelineContext
 
     @classmethod
-    def create(cls, config_dict: dict, ctx: PipelineContext) -> Self:
-        # Technically, this method should be abstract. However, the @config_class
-        # decorator automatically generates a create method at runtime if one is
-        # not defined. Python still treats the class as abstract because it thinks
-        # the create method is missing. To avoid the class becoming abstract, we
-        # can't make this method abstract.
-        raise NotImplementedError('sources must implement "create"')
+    @abstractmethod
+    def create(cls, config_dict: dict, ctx: PipelineContext) -> Self: ...
 
     def get_workunit_processors(self) -> List[Optional[MetadataWorkUnitProcessor]]:
         """A list of functions that transforms the workunits produced by this source.