add .to_pb decorator too, and docs

Signed-off-by: Max Chesterfield <max.chesterfield@zepben.com>

Author: chestm007

CONTRIBUTING.md

@@ -62,7 +62,7 @@ to prevent the test from timing out while you step through the code:
    * ```import <new_class_name> as PB<new_class_name>```
    * Add ```def <new_class_name>_to_pb```
    * Add ```"<new_class_name>_to_pb"``` to ```__all__```
-   * Add ```<new_class_name>.to_pb = <new_class_name>_to_pb```
+   * Annotate ```<new_class_name>_to_pb``` with the ```@bind_to_pb``` decorator
 1. Update  [network_proto2cim.py](src/zepben/ewb/services/network/translator/network_proto2cim.py)
    * ```import <new_class_name> as PB<new_class_name>```
    * Add ```def <new_class_name>_to_pb```

src/zepben/ewb/services/common/translator/base_cim2proto.py

@@ -5,6 +5,9 @@
 
 __all__ = ["identified_object_to_pb", "document_to_pb", "organisation_role_to_pb", "organisation_to_pb"]
 
+import inspect
+from typing import ParamSpec, TypeVar, Callable
+
 # noinspection PyPackageRequirements,PyUnresolvedReferences
 from google.protobuf.timestamp_pb2 import Timestamp as PBTimestamp
 from zepben.protobuf.cim.iec61968.common.Document_pb2 import Document as PBDocument
@@ -23,10 +26,23 @@
 from zepben.ewb.services.common.translator.util import mrid_or_empty
 
 
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def bind_to_pb(func: Callable[P, R]) -> Callable[P, R]:
+    """
+    Get the object described in the type hint of the first argument of the function we are wrapping
+    set that object's `to_pb` function to be the function we are wrapping
+    """
+    inspect.get_annotations(func, eval_str=True)[func.__code__.co_varnames[0]].to_pb = func
+    return func
+
 ###################
 # IEC61968 Common #
 ###################
 
+@bind_to_pb
 def document_to_pb(cim: Document) -> PBDocument:
     timestamp = None
     if cim.created_date_time:
@@ -44,26 +60,24 @@ def document_to_pb(cim: Document) -> PBDocument:
     )
 
 
+@bind_to_pb
 def organisation_to_pb(cim: Organisation) -> PBOrganisation:
     return PBOrganisation(io=identified_object_to_pb(cim))
 
 
+@bind_to_pb
 def organisation_role_to_pb(cim: OrganisationRole) -> PBOrganisationRole:
     return PBOrganisationRole(
         io=identified_object_to_pb(cim),
         organisationMRID=mrid_or_empty(cim.organisation)
     )
 
 
-Document.to_pb = document_to_pb
-Organisation.to_pb = organisation_to_pb
-OrganisationRole.to_pb = organisation_role_to_pb
-
-
 ######################
 # IEC61970 Base Core #
 ######################
 
+@bind_to_pb
 def identified_object_to_pb(cim: IdentifiedObject) -> PBIdentifiedObject:
     return PBIdentifiedObject(
         mRID=str(cim.mrid),
@@ -73,20 +87,17 @@ def identified_object_to_pb(cim: IdentifiedObject) -> PBIdentifiedObject:
     )
 
 
+@bind_to_pb
 def name_to_pb(cim: Name) -> PBName:
     return PBName(
         name=cim.name,
         type=cim.type.name if cim.type else None
     )
 
 
+@bind_to_pb
 def name_type_to_pb(cim: NameType) -> PBNameType:
     return PBNameType(
         name=cim.name,
         description=cim.description
     )
-
-
-IdentifiedObject.to_pb = identified_object_to_pb
-Name.to_pb = name_to_pb
-NameType.to_pb = name_type_to_pb