# Brine

Brine is a simple, fast and secure object serializer for immutable objects.

The following types are supported: `int`, `bool`, `str`, `float`, `unicode`, `bytes`, `slice`, `complex`, `tuple` (of simple types), `frozenset` (of simple types) as well as the following singletons: `None`, `NotImplemented`, and `Ellipsis`.

Example::

      >>> x = ("he", 7, u"llo", 8, (), 900, None, True, Ellipsis, 18.2, 18.2j + 13,
      ... slice(1,2,3), frozenset([5,6,7]), NotImplemented)
      >>> dumpable(x)
      True
      >>> y = dump(x)
      >>> y.encode("hex")
      '140e0b686557080c6c6c6f580216033930300003061840323333333333331b402a000000000000403233333333333319125152531a1255565705'
      >>> z = load(y)
      >>> x == z
      True

rpyc.core.brine.dump(obj)

  Converts (dumps) the given object to a byte-string representation

  Parameters

    obj – any `dumpable()` object

  Returns

    a byte-string representation of the object

rpyc.core.brine.load(data)

  Recreates (loads) an object from its byte-string representation

  Parameters

    data – the byte-string representation of an object

  Returns

    the dumped object

rpyc.core.brine.dumpable(obj)

  Indicates whether the given object is dumpable by brine

  Returns

    `True` if the object is dumpable (e.g., `dump()` would succeed), `False` otherwise

# Vinegar

Vinegar (“when things go sour”) is a safe serializer for exceptions. The `configuration parameters` control its mode of operation, for instance, whether to allow old-style exceptions (that do not derive from `Exception`), whether to allow the `load()` to import custom modules (imposes a security risk), etc.

Note that by changing the configuration parameters, this module can be made non-secure. Keep this in mind.

rpyc.core.vinegar.dump(typ, val, tb, include_local_traceback, include_local_version)

  Dumps the given exceptions info, as returned by `sys.exc_info()`

  Parameters

    - typ – the exception’s type (class)

    - val – the exceptions’ value (instance)

    - tb – the exception’s traceback (a `traceback` object)

    - include_local_traceback – whether or not to include the local traceback in the dumped info. This may expose the other side to implementation details (code) and package structure, and may theoretically impose a security risk.

  Returns

    A tuple of `((module name, exception name), arguments, attributes, traceback text)`. This tuple can be safely passed to `brine.dump`

rpyc.core.vinegar.load(val, import_custom_exceptions, instantiate_custom_exceptions, instantiate_oldstyle_exceptions)

  Loads a dumped exception (the tuple returned by `dump()`) info a throwable exception object. If the exception cannot be instantiated for any reason (i.e., the security parameters do not allow it, or the exception class simply doesn’t exist on the local machine), a `GenericException` instance will be returned instead, containing all of the original exception’s details.

  Parameters

    - val – the dumped exception

    - import_custom_exceptions – whether to allow this function to import custom modules (imposes a security risk)

    - instantiate_custom_exceptions – whether to allow this function to instantiate “custom exceptions” (i.e., not one of the built-in exceptions, such as `ValueError`, `OSError`, etc.)

    - instantiate_oldstyle_exceptions – whether to allow this function to instantiate exception classes that do not derive from `BaseException`. This is required to support old-style exceptions. Not applicable for Python 3 and above.

  Returns

    A throwable exception object

exception rpyc.core.vinegar.GenericException

  A ‘generic exception’ that is raised when the exception the gotten from the other party cannot be instantiated locally