List

Overview

jsify.List is the jsified wrapper for Python lists, created by passing any list (or list-containing structure) to jsify().

It supports:

  • Standard index access for all elements.

  • All standard list methods: append, extend, insert, remove, pop, clear, copy, count, index, sort, reverse, etc.

  • Mutable and reference-based: changes are always reflected in the original data and vice versa.

  • Safe chaining: missing elements accessed by index out of range return Undefined.

  • Iteration returns a :class:`jsify.Iterator` supporting Python and JavaScript-like iteration semantics.

Creating a Jsified List

from jsify import jsify

lst = [{"x": 1}, {"y": 2}, 3]
obj = jsify(lst)

print(type(obj))       # <class 'jsify.List'>

Accessing Elements

  • Use standard index access: obj[0]

  • Do not use dot-style attribute access for list elements or keys; unlike dicts, jsified lists do not support attribute access for elements or keys to avoid collision with list methods.

  • For nested dicts/lists inside the list, use index access combined with attribute access on those nested dicts/lists.

print(obj[0]["x"])    # 1  (if element is dict)
print(obj[1]["y"])    # 2
print(obj[2])         # 3  (native int)

# Dot access like `obj.nope` is not supported on lists and may conflict with methods.

Note

This design preserves full access to list methods and avoids name collisions.

Iteration

  • Iterating over a jsify.List returns a jsify.Iterator.

  • The iterator supports Python and JavaScript-like iteration semantics.

it = iter(obj)
print(type(it))  # <class 'jsify.Iterator'>

for item in it:
    print(item)

Standard List Methods

jsify.List supports all standard Python list methods, including:

  • append(value)

  • extend(iterable)

  • insert(index, value)

  • remove(value)

  • pop([index])

  • clear()

  • copy()

  • count(value)

  • index(value)

  • sort(key=None, reverse=False)

  • reverse()

  • __len__()

  • __getitem__()

  • __setitem__()

  • __delitem__()

  • __iter__()

  • Slicing

  • Comparison (==, <, etc.)

  • String conversion and representation

obj.append({"z": 9})
print(obj[-1]["z"])    # 9

obj[0]["x"] = 42
print(lst[0]["x"])  # 42  # Changes affect original list

obj.remove(3)
print(len(obj))     # len(lst) after removal

# Iteration and length
for item in obj:
    print(item)
print(len(obj))

# List arithmetic and slicing
print(list(obj * 2))
sublist = obj[1:]
print(type(sublist))

# String representation
print(str(obj))
print(repr(obj))

Reference Behavior

  • All changes to the jsified list (and its nested elements) are immediately reflected in the original Python list and vice versa.

  • Assigning a jsified object as a list element keeps it jsified.

  • For example:

obj[0]["x"] = 100
print(lst[0]["x"])  # 100
  • For converting back to native types throughout nested structures, see jsify / unjsify.

Limitations and Gotchas

  • All mutation operations (append, insert, pop, etc.) directly modify the original data.

  • Slicing always produces a new jsified List (never a native Python list).

  • When unjsifying, only the top-level list becomes native unless you use unjsify_deepcopy to recurse.

  • Methods like index() and count() use Python equality comparison: - Be cautious comparing jsified children with native objects; equality may not behave as expected.

  • No type enforcement is performed; lists may contain mixed jsified and native elements.

  • Indexing out of range returns :class:`jsify.Undefined` instead of raising an exception.

  • Dot-style attribute access on the list itself for elements or keys is not supported to avoid method name collisions.

Exceptions

  • remove(value) raises ValueError if the value is not found.

  • index(value) raises ValueError if the value is not found.

  • pop(index) raises IndexError if the list is empty or index is out of range.

See Also

  • jsify.List — This class.

  • jsify.Tuple — Jsified tuples.

  • jsify.Dict — Jsified dictionaries.

  • jsify / unjsify — Conversion and reference handling.

  • jsify.Iterator — Iterators returned by lists and other containers.

Examples

from jsify import jsify

data = [{"a": 1}, {"b": 2}, 3]
js_list = jsify(data)

# Access nested attributes with index and dot notation on dicts
print(js_list[0]["a"])  # 1

# Modify nested values; changes reflect in original list
js_list[1]["b"] = 20
print(data[1]["b"])  # 20

# Append new item
js_list.append({"c": 3})
print(js_list[-1]["c"])  # 3

# Slicing returns jsified List
sublist = js_list[:2]
print(type(sublist))  # <class 'jsify.List'>

# Iteration
for item in js_list:
    print(item)

# Equality caution: comparing jsified with native
print(js_list[2] == 3)       # True
print(js_list[0] == {"a": 1}) # May be False due to jsify wrappers