Add TextEnvelope class for saving and loading Witness and Transaction files

[KINGH242]

This pull request introduces a new TextEnvelope class to add JSON serialization and deserialization capabilities. It is added to the Transaction and VerificationKeyWitness classes, while adding new tests to ensure robustness. The TextEnvelope class can later be added to the various Certificates to allow them the same save and load functionality. Below are the key changes grouped by theme:

Core Enhancements

• Added a new TextEnvelope class in pycardano/serialization.py to enable JSON-based serialization and deserialization with fields like type, description, and cborHex. This class also includes methods for saving and loading JSON data to and from files.
• Updated Transaction and VerificationKeyWitness classes to inherit from TextEnvelope, enabling them to utilize its serialization features. Added custom KEY_TYPE and DESCRIPTION properties to these classes. [1] [2]

Utility and Validation Improvements

• Added a method is_empty to TransactionWitnessSet for checking whether the witness set is empty.
• Introduced equality (__eq__) and shallow primitive conversion (to_shallow_primitive) methods to VerificationKeyWitness to work with TextEnvelope.

Testing Enhancements

• Added tests for the save and load methods of Transaction and VerificationKeyWitness to validate JSON serialization and file handling. [1] [2]
• Expanded test coverage for DRep by introducing parameterized tests to handle various input scenarios, including edge cases and invalid inputs.

[codecov]

Codecov Report

Attention: Patch coverage is 90.32258% with 6 lines in your changes missing coverage. Please review.

Project coverage is 89.98%. Comparing base (7d63d0e) to head (e48aee5).

Files with missing lines	Patch %	Lines
pycardano/serialization.py	85.71%	3 Missing and 1 partial ⚠️
pycardano/address.py	84.61%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #448      +/-   ##
==========================================
+ Coverage   88.86%   89.98%   +1.12%     
==========================================
  Files          33       33              
  Lines        4804     4852      +48     
  Branches      731      733       +2     
==========================================
+ Hits         4269     4366      +97     
+ Misses        374      314      -60     
- Partials      161      172      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cffls]

Thank you for raising this PR! Enabling classes to save to and load from json is amazing. I think it is possible to simplify the implementation by directly adding the json ability to CBORSerialzable. See the detailed comment below. Let me know if that makes sense to you. Thanks!

[cffls]

It might be a good idea to combine this directly with CBORSerializable, which would instantly enable all pycardano classes to save to and load from json. I don't think private fields, key_type and description, are necessary, because they usually don't change between instances. If we want to customize them for certain child class, the child class can always override the method json_key_type or json_description. Regarding payload, it becomes redundant once the logic is merged to CBORSerializable. The default implementation can directly use the class name as the key type, something like below:

class CBORSerializable:
    ....
    
    
    @property
    def json_key_type(self) -> str:
        return self.__class__.__name__

    @property
    def json_description(self) -> str:
        return self.__class__.__doc__
    
    def to_json(self) -> str:
        return json.dumps(
            {
                "type": self.json_key_type,
                "description": self.json_description,
                "cborHex": self.to_cbor_hex(),
            }
        )

Basic usage

Custom key type

[KINGH242]

This can work, but one limitation is that the json files generated by the cardano-cli for the same object can have different type and description depending on which Era it was created in. So being able to set the type and description has some benefits. The implementation for the Key class is a bit mode ideal, but the way Keys handle the payload is a bit different than needed for other classes. I thought about using it and overriding from_json and from_primitive, but then it would mess with my developer OCD as, for example, a Transaction is not a Key🤓.

The Transaction and Witness files generated and saved to JSON by PyCardano, should be able to work with cardano-cli. But if the type field has the incorrect text, it will fail. So the way that I currently use it is by getting the Era from the context, and using it to generate the correct text for the type. I don't think the text in the description field is too important as I would usually set it to Generated with PyCardano, but the type field will fail if it is not what the cardano-cli expects, which can change over the eras.

[cffls]

The current implementation is hardcoding the Era as well.

If the key type and description are dynamic, we can add them to_json I guess? Something like this:

    def to_json(self, key_type: str = None, description: str = None) -> str:
        return json.dumps(
            {
                "type": key_type if key_type else self.json_key_type,
                "description": description if description else self.json_description,
                "cborHex": self.to_cbor_hex(),
            }
        )

Also in the Transaction class, you just need to override one property without adding TextEnvelope type:

class Transaction:
    @property
    def json_key_type(self) -> str:
        return (
            "Unwitnessed Tx ConwayEra"
            if self.transaction_witness_set.is_empty()
            else "Signed Tx ConwayEra"
        )

[KINGH242]

The current implementation does hardcode it for convenience in the current Era, but it can be set as well during initialization or later.

Passing it as a parameter to the to_json should work as well. I will work on refactoring the necessary functions and properties from TextEnvelope to CBORSerializable, then override as necessary. This would be a cleaner solution as the save/load functionality would become immediately available to more classes.