diff --git a/Python_Engine/Python/src/python_toolkit/bhom/analytics.py b/Python_Engine/Python/src/python_toolkit/bhom/analytics.py index a39b66c3..7ba81cb9 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom/analytics.py +++ b/Python_Engine/Python/src/python_toolkit/bhom/analytics.py @@ -154,7 +154,7 @@ def decorator(function: Callable): @wraps(function) def wrapper(*args, **kwargs) -> Any: """A wrapper around the function that captures usage analytics.""" - + if disable: CONSOLE_LOGGER.debug("bhom_analytics is curently disabled.") return function(*args, **kwargs) diff --git a/Python_Engine/Python/src/python_toolkit/bhom/bhom_object.py b/Python_Engine/Python/src/python_toolkit/bhom/bhom_object.py new file mode 100644 index 00000000..c09f76d6 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom/bhom_object.py @@ -0,0 +1,303 @@ +from base64 import decode +import copy +from ctypes import ArgumentError +from json import encoder +from pathlib import Path +import uuid +import re +from typing import Any, List, Dict, Union +import json +from json import JSONEncoder, JSONDecoder +from .logging import CONSOLE_LOGGER +from . import BHOM_VERSION +import pandas as pd +import numpy as np + +BHOM_SHORT_VERSION = ".".join(BHOM_VERSION.split(".")[0:2]) + +def convert_pascal_to_camel(s: str): + """Converts a string to camel_case.""" + sections = re.split("(?<=.)(?=[A-Z])", s) #zero-length match before capitals, skipping capital at the 0th index + parts = [] + for sec in sections: + parts.append(sec.lower()) + + return "_".join(parts) + +def convert_camel_to_pascal(s: str): + """Converts a string to PascalCase, ignoring _ if it is the first character.""" + sections = re.split(r'(?<=.)_', s) #match all `_` except if it is the first character. + + parts = [] + for sec in sections: #capitalise each section unless the section is empty (in which case, append an underscore) or the section starts with an underscore (first section can begin with _) + if sec == "": + parts.append("_") + continue + elif sec.startswith("_"): + parts.append(sec) + + parts.append(sec.capitalize()) + + return ''.join(parts) + +class BHoMJSONDecoder(JSONDecoder): + def __init__(self, *args, **kwargs): + json.JSONDecoder.__init__(self, object_hook=self.object_hook, *args, **kwargs) + + def object_hook(self, d): + if "_t" not in d: + CONSOLE_LOGGER.debug(f"BHoMJSONDecoder could not convert the following dictionary into a BHoMObject due to a missing '_t' property. Falling back to dictionary: {d}") + return self.deserialise_unknown(d) + + props = { + "_t": d.pop("_t"), + "_bhom_version": d.pop("_bhomVersion", BHOM_SHORT_VERSION) + } + + if (props["_bhom_version"] is not None) and (props["_bhom_version"] != BHOM_SHORT_VERSION): + CONSOLE_LOGGER.warning(f"The bhom version specified in the encoded json ({props['_bhom_version']}) is different from the BHoM version that python_toolkit was installed with ({BHOM_SHORT_VERSION}). There may be versioning issues with this object. Consider deserialising and then serialising again with the BHoM serialiser to get the correct version, or update BHoM to the correct version.") + + if d.get("BHoM_Guid", None) is not None: + #deserialise as BHoM Object + + #get default BHoMObject properties and replace with defaults if not present + props["name"] = d.pop("Name", "") + props["bhom_guid"] = uuid.UUID(d.pop("BHoM_Guid")) + props["tags"] = d.pop("Tags", []) + props["fragments"] = d.pop("Fragments", []) + props["custom_data"] = d.pop("CustomData", {}) + + #convert all other properties to camel_case as python users expect + for prop_name in d: + props[convert_pascal_to_camel(prop_name)] = d[prop_name] + + return self.deserialise_unknown(BHoMObject(**props)) + else: + if props["_t"].startswith("System.Collections.Generic.List"): #this handles when the BHoM serialiser makes generic lists from CustomObject list properties, which get converted to a dictionary. The BHoM serialiser does recognise lists if it can find the object definition via reflection. + return d["_v"] + + #deserialise as IObject + for prop_name in d: + props[convert_pascal_to_camel(prop_name)] = d[prop_name] + + return self.deserialise_unknown(IObject(**props)) + + def deserialise_unknown(self, obj: Union['IObject', 'BHoMObject', dict]): + """Override this method in a subclass to add extra object hook on top of the existing method. If the object is an object serialised by the BHoM serialiser, the output object will be a BHoMObject or IObject, so use isinstance() to select.""" + return obj + +class BHoMJSONEncoder(JSONEncoder): + def default(self, o): + if isinstance(o, BHoMObject): + #initialise special BHoMObject properties + + props = { + "Name": o.name, + "BHoM_Guid": str(o.bhom_guid), + "_t": o._t + } + + if len(o.tags) > 0: + props["Tags"] = o.tags + + if len(o.fragments) > 0: + props["Fragments"] = o.fragments + + if len(o.custom_data) > 0: + props["CustomData"] = o.custom_data + + if o._bhom_version is not None: + props["_bhomVersion"] = o._bhom_version + + #get property names with reflection and convert all properties to PascalCase as the BHoM serialiser expects + for prop_name, value in vars(o).copy().items(): + if prop_name in ["name", "bhom_guid", "tags", "fragments", "custom_data", "_t", "_bhom_version"]: + continue + + props[convert_camel_to_pascal(prop_name)] = value + + return props + elif isinstance(o, IObject): + props = { + "_t": o._t + } + + if o._bhom_version is not None: + props["_bhomVersion"] = o._bhom_version + + for prop_name, value in vars(o).copy().items(): + if prop_name in ["_t", "_bhom_version"]: + continue + + props[convert_camel_to_pascal(prop_name)] = value + + return props + #handle common non-serialisable types + elif isinstance(o, uuid.UUID): #UUID object is not json serialisable by default + return str(o) + elif isinstance(o, pd.DatetimeIndex): + return [date.isoformat() for date in o] + elif isinstance(o, np.ndarray): + return o.tolist() + elif isinstance(o, pd.Timestamp): + return o.isoformat() + elif isinstance(o, pd.Series): + return dict(zip(o.index.astype(str), o)) + elif isinstance(o, Path): + return { "FileName": str(o.name), "Directory": str(o.parent), "_t": "BH.oM.Adapter.FileSettings", "BHoM_Guid": str(uuid.uuid4()) } + + return self.serialise_unknown(o) #if the object is unknown at this point, call serialise_unknown to allow subclasses to add their own serialisation logic. + + def serialise_unknown(self, obj: Any) -> Union[Dict[str, str], str, List[str], Any]: + """ + This is called by the BHoMJSONEncoder to serialise unknown objects so that the BHoM can handle them if they exist as BHoM Objects in c# but not in python (i.e. an object from an external library). + + Override this method in a sub class with its own logic, and call super().serialise_unknown(obj) for objects that are unknown, or do not wish to serialise. + The following objects won't be passed to this method: BHoMObject, IObject, uuid.UUID, pandas.DatetimeIndex, numpy.ndarray, pandas.Timestamp, pandas.Series, pathlib.Path + """ + return super(type(self), self).default(obj) #fallback to default json decoder (ValueError) if object is not a BHoMObject or common serialisable type. + +class IObject: + """More generic version of BHoMObject, for non-native objects serialised by the BHoM serialiser, but do not inherit from BHoMObject.""" + _t: str + _bhom_version: str + + def __init__( + self, + _t: str, + _bhom_version: str = None, + **kwargs + ) -> 'IObject': + self._t = _t + self._bhom_version = _bhom_version + + #set properties with reflection. + for kwarg in kwargs: + setattr(self, kwarg, kwargs[kwarg]) + + def __repr__(self) -> str: + return f"{type(self).__name__} of type {self._t}, version: '{getattr(self, '_bhom_version', 'Unknown')}'" + + def __eq__(self, other) -> bool: + if not isinstance(other, IObject): + return False + + if self._t != other._t: + return False + + vself = vars(self).copy() + vother = vars(other).copy() + + #ignore these properties when comparing by property. + ignore = ["_bhom_version"] + _ = [(vself.pop(p, None), vother.pop(p, None)) for p in ignore] + + return vself == vother + + @classmethod + def from_json(cls, j: str, decoder_class: type = BHoMJSONDecoder) -> 'IObject': + obj = json.loads(j, cls=decoder_class) + + if not isinstance(obj, cls): #this only tests that the top level object was deserialised correctly, if there are problems with deep properties, change the CONSOLE_LOGGER log level to debug. + raise TypeError("The object provided does not deserialise to a valid BHoM object.") + + return obj + + def to_json(self, encoder_class: type = BHoMJSONEncoder) -> str: + return json.dumps(self, cls=encoder_class) + + @classmethod + def from_dict(cls, d: dict) -> 'IObject': + try: + return cls(**d) #should be valid as long as the dictionary has all necessary entries. + except ArgumentError as ae: + raise ArgumentError("Input dictionary was missing some required arguments, see traceback for more information.") from ae + + def to_dict(self, encoder_class: type = BHoMJSONEncoder) -> dict: + """Convert this IObject to a dictionary via deep copying vars(self).""" + return copy.deepcopy(vars(self)) + +class BHoMObject(IObject): + name: str + bhom_guid: uuid.UUID + tags: List[str] + fragments: List[Dict[str, object]] + custom_data: Dict[str, object] + + def __init__( + self, + _t: str, #don't make default, as subclasses of this class should set this with super().__init__ + name: str = "", + bhom_guid: uuid.UUID = uuid.uuid4(), + tags: List[str] = [], + fragments: List[Dict[str, object]] = [], + custom_data: Dict[str, object] = {}, + _bhom_version: str = None, + **kwargs + ) -> 'BHoMObject': + self._t = _t + self.name = name + self.bhom_guid = bhom_guid + self.fragments = fragments + self.tags = tags + self.custom_data = custom_data + self._bhom_version = _bhom_version + + #set non-CustomData properties with reflection. + for kwarg in kwargs: + setattr(self, kwarg, kwargs[kwarg]) + + def __repr__(self) -> str: + return f"{type(self).__name__} of type {self._t}, name: '{self.name}', version: '{getattr(self, '_bhom_version', 'Unknown')}', id: '{self.bhom_guid}'" + + def __eq__(self, other) -> bool: + if not isinstance(other, BHoMObject): + return False + + if self._t != other._t: + return False + + vself = vars(self).copy() + vother = vars(other).copy() + + #ignore these properties when comparing by property. + ignore = ["bhom_guid", "_bhom_version"] + _ = [(vself.pop(p, None), vother.pop(p, None)) for p in ignore] + + return vself == vother + + @classmethod + def from_json(cls, j: str, decoder_class: type = BHoMJSONDecoder): + obj = json.loads(j, cls=decoder_class) + + if isinstance(obj, list): + CONSOLE_LOGGER.warning("The root element of the JSON provided was a list, assuming that the first item is the desired object. If you intended to deserialise a list, please use the `.from_json_array(j)` method instead.") + obj = obj[0] + + if issubclass(cls, BHoMObject) and cls != BHoMObject: + obj = cls._from_bhom_object(obj) + + if not isinstance(obj, cls): #this only tests that the top level object was deserialised correctly, if there are problems with deep properties, change the CONSOLE_LOGGER log level to debug. + raise TypeError("The object provided does not deserialise to a valid BHoM object.") + + return obj + + @classmethod + def from_json_array(cls, j: str, decoder_class: type = BHoMJSONDecoder): + objs = json.loads(j, cls=decoder_class) + + if not isinstance(objs, list): + raise TypeError("The root element of the JSON provided was not a JSON array. Perhaps you intended to use `.from_json(j)` instead?") + + out = [] + for obj in objs: + if issubclass(cls, BHoMObject) and cls != BHoMObject: + out.append(cls._from_bhom_object(obj)) + continue + out.append(obj) + + return out + + @classmethod + def _from_bhom_object(cls, o: 'BHoMObject'): + return cls(**vars(o).copy()) #assuming that the sub class is correctly set up, then this should work \ No newline at end of file diff --git a/Python_Engine/Python/src/python_toolkit/bhom/decorators/__init__.py b/Python_Engine/Python/src/python_toolkit/bhom/decorators/__init__.py new file mode 100644 index 00000000..70cea52d --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom/decorators/__init__.py @@ -0,0 +1 @@ +from ._bhom_callable_decorator import bhom_wrapper \ No newline at end of file diff --git a/Python_Engine/Python/src/python_toolkit/bhom/decorators/_bhom_callable_decorator.py b/Python_Engine/Python/src/python_toolkit/bhom/decorators/_bhom_callable_decorator.py new file mode 100644 index 00000000..04e9963b --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom/decorators/_bhom_callable_decorator.py @@ -0,0 +1,83 @@ +import json +from typing import Any, Callable, Union, Dict +from functools import wraps +from ..bhom_object import CONSOLE_LOGGER, BHoMJSONDecoder, BHoMJSONEncoder, BHoMObject + +class _BHoMWrapper: + _registered_methods: Dict[str, Callable] = {} + + def bhom_callable(self, identifier: str, argument_types:Dict[str, type] = {}, encoder_cls: type = BHoMJSONEncoder, decoder_cls: type = BHoMJSONDecoder): + """Decorator for functions to be made callable from BHoM C# methods/adapters. + + Note: methods that this wraps must not have "__input_json__" as a default kwarg, as this is used internally to allow BHoM adapters to call the method. + + when __input_json__ is set, this will cause the method to always output BHoM style json (using the encoder_cls provided to this decorator) + + Args: + argument_types (dict[str, type]): this is a dictionary that is used to map the argument names to types (specifically BHoMObject types) to subclasses of BHoMObjects. + For example, if you have a class that is a subclass of BHoMObject, the default serialiser will only deserialise json to a BHoMObject. + To go the extra step to get your class, you must provide the type in this dictionary to allow the wrapper to convert the BHoMObject type to your desired type. + + encoder_cls (JSONEncoder): A JSONEncoder (ideally one that is a subclass of BHoMJSONEncoder). Mainly this is for if a custom encoder has been implemented for a specific toolkit. + + decoder_cls (JSONDecoder): same as encoder_cls but for JSONDecoder. + """ + def decorator(function: Callable): + + @wraps(function) + def wrapper(*args, **kwargs) -> Union[str, Any]: + + do_wrap:bool = False + + if "__input_json__" in kwargs and len(args) == 0: + do_wrap = True + + #get dictionary from input as file path or json like string. + input_json = kwargs.pop("__input_json__") + + if not input_json.startswith("{"): #assume it's a path + with open(input_json, "r") as f: + input_json = f.read() + + try: + json_kwargs: dict = json.loads(input_json, cls=decoder_cls) + except: + CONSOLE_LOGGER.error("Could not load JSON from file or string due to invalid JSON. Attempting to run with given args and kwargs.", exc_info=1) + + #update kwargs with json + for kwarg_name in json_kwargs: + val = json_kwargs[kwarg_name] + + if kwarg_name in argument_types: + t = argument_types[kwarg_name] + + if issubclass(t, BHoMObject) and type(json_kwargs[kwarg_name]) is BHoMObject: + val = t._from_bhom_object(json_kwargs[kwarg_name]) + + kwargs[kwarg_name] = val + + rtn = function(*args, **kwargs) + + if do_wrap: + json_rtn = json.dumps(rtn, cls=encoder_cls) + + return json_rtn + + return rtn + + self._registered_methods[identifier] = wrapper + return wrapper + + return decorator + + def get_registered_method(self, method_identifier: str): + method = self._registered_methods.get(method_identifier, None) + + if method is None: + CONSOLE_LOGGER.error("The requested method could not be found.") + + return method + +#the registered methods are stored as a class attribute, so this isn't actually needed +#but this is easier to use, otherwise a new instance must be created every time a method needs to be wrapped +bhom_wrapper = _BHoMWrapper() \ No newline at end of file diff --git a/Python_Engine/Python/src/python_toolkit/bhom/run_wrapped.py b/Python_Engine/Python/src/python_toolkit/bhom/run_wrapped.py new file mode 100644 index 00000000..2a21c362 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom/run_wrapped.py @@ -0,0 +1,7 @@ +from .decorators import bhom_wrapper +from . import wrapped + +def run_wrapped(identifier: str, json: str): + method = bhom_wrapper.get_registered_method(identifier) + + print(method(__input_json__ = json)) \ No newline at end of file diff --git a/Python_Engine/Python/src/python_toolkit/bhom/wrapped/__init__.py b/Python_Engine/Python/src/python_toolkit/bhom/wrapped/__init__.py new file mode 100644 index 00000000..10636f63 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom/wrapped/__init__.py @@ -0,0 +1,13 @@ +from importlib import import_module +from pathlib import Path +import os + +python_files = Path(__file__).parent.glob("**/*.py") + +for file in python_files: + if file.name == "__init__.py": + continue + + rel = file.relative_to(Path(__file__).parent) + module = "." + str(rel).replace(".py", "").replace(os.path.sep, ".") + import_module(module, "python_toolkit.bhom.wrapped") \ No newline at end of file diff --git a/Python_Engine/Python/src/python_toolkit/bhom/wrapped/_test_wrapped.py b/Python_Engine/Python/src/python_toolkit/bhom/wrapped/_test_wrapped.py new file mode 100644 index 00000000..ac0764f1 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom/wrapped/_test_wrapped.py @@ -0,0 +1,10 @@ +from python_toolkit.plot.heatmap import heatmap +from ..decorators import bhom_wrapper +import pandas as pd + +@bhom_wrapper.bhom_callable("test") +def heatmap_2(geometry, **kwargs): + print(geometry) + print(kwargs["arg2"]) + geometry.x = 20 + return geometry diff --git a/Python_Engine/Python/tests/test_bhom_serialiser.py b/Python_Engine/Python/tests/test_bhom_serialiser.py new file mode 100644 index 00000000..0d1385f3 --- /dev/null +++ b/Python_Engine/Python/tests/test_bhom_serialiser.py @@ -0,0 +1,95 @@ +from python_toolkit.bhom.bhom_object import convert_pascal_to_camel, convert_camel_to_pascal, BHoMObject, IObject, BHoMJSONDecoder, BHoMJSONEncoder +import uuid +import json + +SERIALISED_BHOM_OBJECT = '{ "_t" : "BH.oM.Adapter.FileSettings", "FileName" : "test.txt", "Directory" : "path/to/file", "BHoM_Guid" : "f428e614-bda1-4228-882e-21d0f318a322", "Name" : "", "_bhomVersion" : "9.2" }' #TODO: use the BHoM serialiser to make a BHoMObject json string, and use that here. +DESERIALISED_BHOM_OBJECT = BHoMObject(_t = "BH.oM.Adapter.FileSettings", bhom_guid = uuid.UUID("f428e614-bda1-4228-882e-21d0f318a322"), file_name = "test.txt", directory = "path/to/file", _bhom_version = "9.2") #TODO: make equivalent BHoMObject here identical to the one above. + +SERIALISED_IOBJECT = '{ "_t" : "BH.oM.Geometry.Point", "X" : 0.10000000000000001, "Y" : 0.10000000000000001, "Z" : 0.10000000000000001, "_bhomVersion" : "9.2" }' +DESERIALISED_IOBJECT = IObject(_t = "BH.oM.Geometry.Point", x = 0.10000000000000001, y = 0.10000000000000001, z = 0.10000000000000001, _bhom_version = "9.2") + +def test_case_convert(): + """Test that the camel and pascal converters are working correctly by using expected outputs and a round trip both ways.""" + #TODO: find edge cases within bhom to see if round trip converters work properly. + #arrange + test_pascal_str = "ThisIsAPascalCaseString" + test_camel_str = "this_is_a_camel_case_string" + expected_pascal_out = "this_is_a_pascal_case_string" + expected_camel_out = "ThisIsACamelCaseString" + + #act + pascal_out = convert_pascal_to_camel(test_pascal_str) + pascal_round_trip = convert_camel_to_pascal(pascal_out) + + camel_out = convert_camel_to_pascal(test_camel_str) + camel_round_trip = convert_pascal_to_camel(camel_out) + + #assert + assert pascal_out == expected_pascal_out, f"pascal conversion got '{pascal_out}' but expected '{expected_pascal_out}'." + assert camel_out == expected_camel_out, f"camel conversion got '{camel_out}' but expected '{expected_camel_out}'." + assert pascal_round_trip == test_pascal_str, f"pascal round trip got '{pascal_round_trip}' but expected '{test_pascal_str}'." + assert camel_round_trip == test_camel_str, f"camel round trip got '{camel_round_trip}' but expected '{test_camel_str}'." + +def test_serialise_bhom_object(): + """Test that bhom objects serialise correctly to a format that the c# bhom serialiser accepts as valid, and with the correct property case.""" + #act + serialised = json.dumps(DESERIALISED_BHOM_OBJECT, cls=BHoMJSONEncoder) + serialised_bhom_object_to_json = DESERIALISED_BHOM_OBJECT.to_json() + round_trip = BHoMObject.from_json(serialised) + + #assert + assert serialised == serialised_bhom_object_to_json, f"Direct serialisation to json differed to BHoMObject to_json method." + assert round_trip == DESERIALISED_BHOM_OBJECT, f"BHoMObject round trip failed for serialisation -> deserialisation." #this is the only direction the round trip can be tested without directly inspecting each dictionary entry, as it is not guaranteed that the other direction will produce identical order for json strings. + +def test_serialise_iobject(): + #act + serialised = json.dumps(DESERIALISED_IOBJECT, cls=BHoMJSONEncoder) + serialised_iobject_to_json = DESERIALISED_IOBJECT.to_json() + round_trip = IObject.from_json(serialised) + + #assert + assert serialised == serialised_iobject_to_json, f"Direct serialisation to json differed to IObject to_json method." + assert round_trip == DESERIALISED_IOBJECT, f"IObject round trip failed for serialisation -> deserialisation." #this is the only direction the round trip can be tested without directly inspecting each dictionary entry, as it is not guaranteed that the other direction will produce identical order for json strings. + +def test_deserialise_bhom_object(): + """Test that bhom objects deserialise correctly with no errors with expected properties with correct case.""" + #act + obj = json.loads(SERIALISED_BHOM_OBJECT, cls=BHoMJSONDecoder) + obj_bhom_object_from_json = BHoMObject.from_json(SERIALISED_BHOM_OBJECT) + + #assert + assert isinstance(obj, BHoMObject), "JSON decoded an object of the wrong type" + assert obj == DESERIALISED_BHOM_OBJECT, f"Actual deserialised object ({obj}) was not identical to expected deserialised object ({DESERIALISED_BHOM_OBJECT})." + assert obj_bhom_object_from_json == obj, f"Direct deserialisation from json differed to BHoMObject from_json method." + +def test_deserialise_iobject(): + """Test that bhom objects deserialise correctly with no errors with expected properties with correct case.""" + #act + obj = json.loads(SERIALISED_IOBJECT, cls=BHoMJSONDecoder) + obj_iobject_from_json = IObject.from_json(SERIALISED_IOBJECT) + + #assert + assert isinstance(obj, IObject), "JSON decoded an object of the wrong type" + assert obj == DESERIALISED_IOBJECT, f"Actual deserialised object ({obj}) was not identical to expected deserialised object ({DESERIALISED_IOBJECT})." + assert obj_iobject_from_json == obj, f"Direct deserialisation from json differed to IObject from_json method." + +def test_subclass(): + #arrange + class TestSubClass(BHoMObject): + _t: str = "BH.oM.Base.CustomObject" + some_other_data: str + + def __init__(self, some_other_data, **kwargs): + self.some_other_data = some_other_data + _t = kwargs.pop("_t", self._t) + super().__init__(_t, **kwargs) + + #act + test_object = TestSubClass("this is some test data") + test_object_json = test_object.to_json() + test_object_round_trip = TestSubClass.from_json(test_object_json) + + #assert + assert test_object == test_object_round_trip + assert test_object.some_other_data == "this is some test data" + assert test_object._t == "BH.oM.Base.CustomObject" \ No newline at end of file diff --git a/Python_Engine/Python_Engine.csproj b/Python_Engine/Python_Engine.csproj index 429318f6..d10626af 100644 --- a/Python_Engine/Python_Engine.csproj +++ b/Python_Engine/Python_Engine.csproj @@ -39,6 +39,6 @@ - +