Metadata-Version: 2.1
Name: json-handler-registry
Version: 1.5.0
Summary: Standardized way of registering custom JSON serializers/deserializers.
Home-page: https://bitbucket.org/massultidev/tunit/
Author: P.J. Grochowski
Author-email: pawel.grochowski.dev@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt

[![PyPI pyversions](https://img.shields.io/pypi/pyversions/json-handler-registry.svg)](https://pypi.python.org/pypi/json-handler-registry)
[![PyPI version shields.io](https://img.shields.io/pypi/v/json-handler-registry.svg)](https://pypi.python.org/pypi/json-handler-registry)
[![PyPI license](https://img.shields.io/pypi/l/json-handler-registry.svg)](https://pypi.python.org/pypi/json-handler-registry)
[![Downloads](https://static.pepy.tech/badge/json-handler-registry)](https://pepy.tech/project/json-handler-registry)

# JSON Handler Registry
---
Standardized way of registering custom JSON serializers/deserializers.

Package `json` lacks standard approach to registering custom JSON handlers.

Project `json-handler-registry` has been created to solve that issue.

## Usage:

Registering your own handlers:

```python
from typing import Optional
from json_handler_registry.registry import JsonHandlerRegistry
from json_handler_registry.encoder import IJsonEncoder, EncodingResult
from json_handler_registry.decoder import IJsonDecoder


# Implement your custom class encoder:
class MyJsonEncoder(IJsonEncoder):
    def encodeObject(self, obj: object) -> Optional[EncodingResult]:
        """Convert object to a JSON serializable data.
        Or return ``None`` instead.
        """
        pass  # TODO: Actual implementation goes here!


# Implement your custom class decoder:
class MyJsonDecoder(IJsonDecoder):
    def decodeDict(self, dct: dict) -> Optional[object]:
        """Convert dictionary to your type instance.
        Or return ``None`` instead.
        """
        pass  # TODO: Actual implementation goes here!

    def decodeStr(self, valueStr: str) -> Optional[object]:
        """Convert string value to your type instance.
        Or return ``None`` instead.
        """
        pass  # TODO: Actual implementation goes here!


# Register your serializer and deserializer:
JsonHandlerRegistry.registerEncoder(MyJsonEncoder())
JsonHandlerRegistry.registerDecoder(MyJsonDecoder())
```

Serialization & deserialization:
```python
# Using `tunit` package as an example:
import json
from tunit.config import TUnitConfig
from tunit.unit import Seconds

TUnitConfig.registerJsonHandler() # Enables registry and registers handlers.

# JSON serialization:
messageDto = {"delay": Seconds(10)}
messageJson = json.dumps(messageDto)
print(messageJson) # Prints: '{"delay": "10s"}'

# JSON deserialization:
messageJson = '{"delay": "10s"}'
messageDto = json.loads(messageJson)
print(messageDto) # Prints: {'delay': Seconds(10)}
```

## Popular external packages support:

Package maintainers are encouraged to adopt `json-handler-registry` in their projects.
However, for now, support for popular packages will be successively provided here.

Support for `dataclasses-json`:

```python
from dataclasses import dataclass
from datetime import datetime
from decimal import Decimal
from enum import Enum, auto
from uuid import UUID, uuid4

from dataclasses_json import DataClassJsonMixin
from json_handler_registry.registry import JsonHandlerRegistry


class TestEnum(Enum):
  Option1 = auto()
  Option2 = auto()
  Option3 = auto()


@dataclass
class TestDataClass(DataClassJsonMixin):
  timestamp: datetime
  id: UUID
  option: TestEnum
  value: Decimal


testData = TestDataClass(
  timestamp=datetime.now().astimezone(),
  id=uuid4(),
  option=TestEnum.Option2,
  value=Decimal(7)
)

JsonHandlerRegistry.packageSupportManager.getPackageSupportConfig('dataclasses-json').enable()
assert TestDataClass.from_json(testData.to_json()) == testData
JsonHandlerRegistry.packageSupportManager.getPackageSupportConfig('dataclasses-json').disable()

# Instead of using 'PackageSupportManager' you can also manually register encoder:
from json_handler_registry.registry import JsonHandlerRegistry
from json_handler_registry.support.impl.dataclasses_json import DataClassJsonEncoder
JsonHandlerRegistry.registerEncoder(DataClassJsonEncoder)
```

### Changelog:
---
- Version: 1.5.0
    - Package support manager is now accessible from handler registry.
- Version: 1.4.0
    - Preserving registration order of encoders/decoders.
    - Configurable auto enable/disable registry feature. (Active by default.)
- Version: 1.3.0
    - Support for `dataclasses-json` package.
    - Debug methods for listing registered encoders/decoders.
- Version: 1.2.0
    - Guard to prevent registry from being easily overridden when enabled.
- Version: 1.1.0
    - Registry accepts both type and instance of encoder/decoder.

## License
MIT
