Serialized Python objects

Note

This assumes familiarity with HGXLink, Ghid, Obj, and Proxy objects.

JSON serialization

class JsonObj(state, api_id, dynamic, private, *, hgxlink, ipc_manager, _legroom, ghid=None, binder=None, callback=None)

New in version 0.1.

A Hypergolix object that uses the built-in json library for serialization. The resulting string is then encoded in UTF-8. Use it exactly as you would any other Obj object.

Warning

TypeErrors as a result of improper state declarations will not be reported until their value is pushed upstream via Obj.push() or equivalent.

>>> obj = hgxlink.new_threadsafe(
...     cls = hgx.JsonObj,
...     state = 'Hello Json!',
... )
>>> obj
<JsonObj with state 'Hello Json!' at Ghid('bf3dR')>
>>> obj.state = 5
>>> obj
<JsonObj with state 5 at Ghid('bf3dR')>
>>> obj.state = {'seven': 7}
>>> obj
<JsonObj with state {'seven': 7} at Ghid('bf3dR')>
class JsonProxy(state, api_id, dynamic, private, *, hgxlink, ipc_manager, _legroom, ghid=None, binder=None, callback=None)

New in version 0.1.

A Hypergolix proxy that uses the built-in json library for serialization. The resulting string is then encoded in UTF-8. Use it exactly as you would any other Proxy object.

Warning

TypeErrors as a result of improper hgx_state declarations will not be reported until their value is pushed upstream via Obj._hgx_push() or equivalent.

>>> obj = hgxlink.new_threadsafe(
...     cls = hgx.JsonProxy,
...     state = 'Hello Json!',
... )
>>> obj
<JsonProxy to 'Hello Json!' at Ghid('bf3dR')>
>>> obj.hgx_state = 5
>>> obj
<JsonProxy to 5 at Ghid('bf3dR')>
>>> obj.hgx_state = {'seven': 7}
>>> obj
<JsonProxy to {'seven': 7} at Ghid('bf3dR')>

Pickle serialization

class PickleObj(state, api_id, dynamic, private, *, hgxlink, ipc_manager, _legroom, ghid=None, binder=None, callback=None)

New in version 0.1.

A Hypergolix object that uses the built-in pickle library for serialization. The resulting string is then encoded in UTF-8. Use it exactly as you would any other Obj object.

Danger

Never use pickle to de/serialize objects from an untrusted source. Because pickle allows objects to control their own deserialization, retrieving such an object effectively gives the object creator full control over your computer (within the privilege limits of the current Python process).

Warning

TypeErrors as a result of improper state declarations will not be reported until their value is pushed upstream via Obj.push() or equivalent.

>>> obj = hgxlink.new_threadsafe(
...     cls = hgx.PickleObj,
...     state = 'Hello Pickle!',
... )
>>> obj
<PickleObj with state 'Hello Pickle!' at Ghid('bf3dR')>
>>> obj.state = 5
>>> obj
<PickleObj with state 5 at Ghid('bf3dR')>
>>> obj.state = {'seven': 7}
>>> obj
<PickleObj with state {'seven': 7} at Ghid('bf3dR')>
class PickleProxy(state, api_id, dynamic, private, *, hgxlink, ipc_manager, _legroom, ghid=None, binder=None, callback=None)

New in version 0.1.

A Hypergolix proxy that uses the built-in pickle library for serialization. The resulting string is then encoded in UTF-8. Use it exactly as you would any other Proxy object.

Danger

Never use pickle to de/serialize objects from an untrusted source. Because pickle allows objects to control their own deserialization, retrieving such an object effectively gives the object creator full control over your computer (within the privilege limits of the current Python process).

Warning

TypeErrors as a result of improper hgx_state declarations will not be reported until their value is pushed upstream via Obj.hgx_push() or equivalent.

>>> obj = hgxlink.new_threadsafe(
...     cls = hgx.PickleProxy,
...     state = 'Hello Pickle!',
... )
>>> obj
<PickleProxy to 'Hello Pickle!' at Ghid('bf3dR')>
>>> obj.hgx_state = 5
>>> obj
<PickleProxy to 5 at Ghid('bf3dR')>
>>> obj.hgx_state = {'seven': 7}
>>> obj
<PickleProxy to {'seven': 7} at Ghid('bf3dR')>

Custom serialization

Custom serialization of objects can be easily added to Hypergolix by subclassing Obj or Proxy and overriding:

  1. class attribute _hgx_DEFAULT_API
  2. staticmethod or classmethod coroutine hgx_pack(state)
  3. staticmethod or classmethod coroutine hgx_unpack(packed)

A (non-functional) toy example follows:

from hgx.utils import ApiID
from hgx import Obj
from hgx import Proxy

class ToySerializer:
    ''' An Obj that customizes serialization.
    '''
    _hgx_DEFAULT_API = ApiID(bytes(63) + b'\x04')

    @staticmethod
    async def hgx_pack(state):
        ''' Packs the state into bytes.
        '''
        return bytes(state)

    @staticmethod
    async def hgx_unpack(packed):
        ''' Unpacks the state from bytes.
        '''
        return object(packed)


class ToyObj(ToySerializer, Obj):
    pass


class ToyProxy(ToySerializer, Proxy):
    pass