Map & Set

Python equivalents of JavaScript’s Map & Set types.

jstypes.JSMap

jstypes.JSMap(
    init: SupportsKeysAndGetItem[KT, VT] | Iterable[tuple[KT, VT]] | None = None,
    **kwargs: VT,
)

A Python equivalent of JavaScript’s Map.

JSMap is a Mapping that uses object identity rather than == for key equality, and allows keys which are not hashable.

JSMap replicates the behaviour of JavaScript’s Map type, which considers keys equal by the same-value-zero rules (very close to Object.is() / ===).

Parameters

Name	Type	Description	Default
init	SupportsKeysAndGetItem[KT, VT] | Iterable[tuple[KT, VT]] | None	Another Mapping to copy items from, or a series of (key, value) pairs.	None
kwargs	VT	Keyword arguments become items, and override items from init if names occur in both.	{}

Notes

JSMap must be initialized using an iterable of item pairs instead of a dict if any keys are non-hashable or are equal using ==.

See Also

jstypes.same_value_zero : A key function that provides same-value-zero equality.

Examples

JSMap is like a Python dict, but as in JavaScript, any object can be a JSMap key — keys don’t need to be hashable.

>>> from v8serialize.jstypes import JSObject
>>> bob, alice = JSObject(name="Bob"), JSObject(name="Alice")
>>> m = JSMap([(bob, 1), (alice, 2)])
>>> m
JSMap([(JSObject(name='Bob'), 1), (JSObject(name='Alice'), 2)])
>>> m[alice]
2

Equality between JSMap instances works as if you compared a list of both map’s items. When comparing JSMap to normal Python dict, equality works as if the JSMap was a normal dict — order does not matter and the number of items must be equal. Same-value-zero is only used for internally matching keys, not for external equality.

Equality examples:

>>> a, b = bytearray(), bytearray()  # non-hashable but supports ==
>>> assert a == b
>>> assert a is not b

Because a and b are equal, lists containing them in different orders are equal:

>>> [a, b] == [b, a]
True

Equality between two JSMaps behaves like the list of items (JSMaps remember insertion order):

>>> JSMap([(a, 0), (b, 0)]) == JSMap([(a, 0), (b, 0)])
True
>>> JSMap([(a, 0), (b, 0)]) == JSMap([(b, 0), (a, 0)])
True
>>> JSMap([(a, 0), (a, 0)]) == JSMap([(b, 0), (b, 0)])
True

These behave like:

>>> list(JSMap([(a, 0), (b, 0)]).items()) == [(b, 0), (a, 0)]
True

Equality between a JSMap and a normal dict behaves as if the JSMap was a normal dict. The maps must have the same number of items.

>>> # hashable, distinct instances
>>> x, y, z = tuple([0]), tuple([0]), tuple([0])
>>> assert x == y and y == z
>>> assert x is not y and y is not z

>>> jsm_dup, jsm_no_dup = JSMap([(x, 0), (y, 0)]), JSMap([(x, 0)])
>>> m = dict([(y, 0), (z, 0)])
>>> jsm_dup, jsm_no_dup, m
(JSMap([((0,), 0), ((0,), 0)]), JSMap({(0,): 0}), {(0,): 0})

>>> jsm_no_dup == m
True
>>> jsm_dup == m  # different number of members
False

Equivalent to

>>> dict([(x, 0)]) == dict([(y, 0), (z, 0)])
True

Methods

Name	Description
clear
get
update

clear

jstypes.JSMap.clear()

get

jstypes.JSMap.get(key: KT, /, default: U | None = None)

update

jstypes.JSMap.update(
    other: SupportsKeysAndGetItem[KT, VT] | Iterable[tuple[KT, VT]] = (),
    /,
    **kwds: VT,
)

jstypes.JSSet

jstypes.JSSet(iterable: Iterable[T] | None = None, /)

A Python equivalent of JavaScript’s Set.

JSSet is a Python set that uses object identity rather than == for member equality, and allows members which are not hashable.

JSSet replicates the behaviour of JavaScript’s Set type, which considers members equal by the same-value-zero rules (very close to Object.is() / ===).

Parameters

Name	Type	Description	Default
iterable	Iterable[T] | None	Items to initialize the JSSet with. Can be empty or not specified.	None

Notes

JSSet must be initialized using an iterable or regular list instead of a set if any keys are non-hashable or are equal using ==.

See Also

jstypes.same_value_zero : A key function that provides same-value-zero equality.

Examples

Equality between JSSet instances works as if you compared a list of both set’s elements. When comparing JSSet to a normal Python set, equality works as if the JSSet was a regular set — order does not matter and the number of elements must be equal. Same-value-zero is only used for internal membership checks, not for external equality.

Equality examples:

>>> a, b = bytearray(), bytearray()  # non-hashable
>>> assert a == b
>>> assert a is not b

Equality between two JSSets behaves like the list of members (JSSets remember insertion order):

>>> JSSet([a, b]) == JSSet([a, b])
True
>>> JSSet([a, b]) == JSSet([b, a])
True
>>> JSSet([a, a]) == JSSet([b, b])
True

These behave like:

>>> list(JSSet([a, b])) == [b, a]
True

Equality between a JSSet and a normal set behaves as if the JSSet was a normal set. The sets must have the same number of members.

Note that if there are non-hashable members, the sets can’t be equal, as normal sets cannot contain non-hashable members.

>>> # hashable, distinct instances
>>> x, y, z = tuple([0]), tuple([0]), tuple([0])
>>> assert x == y and y == z
>>> assert x is not y and y is not z

>>> jss_dup, jss_no_dup, s = JSSet([x, y]), JSSet([x]), set([y, z])
>>> jss_dup, jss_no_dup, s
(JSSet([(0,), (0,)]), JSSet([(0,)]), {(0,)})

>>> jss_no_dup == s
True
>>> jss_dup == s  # different number of members
False

Equivalent to

>>> set([x]) == set([y, z])
True

Methods

Name	Description
add
clear
discard

add

jstypes.JSSet.add(value: T)

clear

jstypes.JSSet.clear()

discard

jstypes.JSSet.discard(value: T)