fix: replace the layer at an index instead of inserting before it - #811

psd[0] = layer does not replace the layer at index 0. It inserts the new layer in front of it and keeps the old one, so a document with 2 layers ends up with 3. Opening tests/psd_files/group.psd, whose layers are ['Background', 'Group 1'], and assigning a layer taken from tests/psd_files/1layer.psd to psd[0] gives ['Фон', 'Background', 'Group 1'] and len(psd) == 3.

GroupMixin.__setitem__ at src/psd_tools/api/layers.py:1069 was two lines whose whole body was self.insert(key, value). insert() at src/psd_tools/api/layers.py:1109 is the separate insert operation and does exactly what its name says, so item assignment was insertion under a second name. Every neighbour in the same class is real list emulation: __getitem__ at line 1066 is self._layers.__getitem__(key) and __delitem__ at line 1072 is self.remove(self._layers[key]).

docs/usage.rst:153 introduces the section as "methods emulating a python list" and then lists group[0] = layer at line 162 and group.insert(3, layer) at line 171 as two different operations, so the documented contract was replacement. Replacement itself was reachable, but only as two calls: psd.pop(0) followed by psd.insert(0, layer) replaces correctly on main. There was no single-expression form.

The method now reads the layer at that index, inserts the new one at its resolved position and removes it. The same _check_insertion() and the same reparenting in _update_children() still run. Two things differ from writing pop() then insert() by hand. insert() receives the resolved non-negative index rather than key. And the two steps run in the opposite order: this method inserts first and removes second, where pop() plus insert() removes first and inserts second. The number of _psd._update_record() calls is the same either way, 2. I monkeypatched PSDImage._update_record and counted 2 for psd[0] = layer and 2 for psd.pop(0) followed by psd.insert(0, layer), since insert() and remove() call it once each.

Nothing in the tree calls this method by name. git grep -n "__setitem__" -- src returns 7 hits in tracked files: the definition itself in api/layers.py, four in psd/base.py and two in psd/engine_data.py, both unrelated containers. Call sites would not appear in that grep anyway, because item assignment is written x[i] = y, so the tests below are the evidence that the new behaviour holds.

Four cases worth stating, all measured on this branch. An out-of-range index now raises IndexError('list index out of range') and leaves the group untouched, where on main psd[5] = layer on a 2 layer group appended silently and gave ['Background', 'Group 1', 'Фон']. Assigning the layer that is already at that index is a no-op. Assigning a layer that is elsewhere in the same group moves it rather than duplicating it, so the group shrinks by one: psd[-1] = psd[0] on group.psd leaves ['Background']. That move lands the layer next to where the replaced layer was, not necessarily at the index assigned to: on a 3 layer group ['A', 'B', 'C'], group[2] = group[0] gives ['B', 'A'] with A at index 1, because taking A out from before the target shifts the rest down. That no-duplicates behaviour follows the rule append() and insert() already document, not list semantics, and it is stated in the new docstring. Slice assignment was never supported: on main psd[0:1] = [layer] raised TypeError("Expected Layer instance, got list") from inside the insert path, and it now raises TypeError("Slice assignment is not supported") up front.

Two tests in tests/psd_tools/api/test_layers.py, next to test_group_insert. test_group_setitem covers replacement at a positive and a negative index, _parent on both layers and _psd on the incoming one, the no-op case, the move case, the 3 layer case that pins the moved layer at index 1, the out-of-range case and the two TypeError cases. It does not assert _psd on the removed layer, because remove() clears _parent and leaves _psd as it was, which this change does not touch. test_psd_image_setitem_round_trip builds a 2 layer document, replaces the bottom layer, saves and reopens, and asserts the file holds ['Blue', 'Green']. Neither needs aggdraw, scipy or scikit-image, so both run in the no-composite job. Reverting only src/psd_tools/api/layers.py and rerunning gives 2 failed, with AssertionError: assert 3 == 2 in the first and AssertionError: assert ['Blue', 'Red', 'Green'] == ['Blue', 'Green'] in the second.

Ran on macOS with Python 3.11. pytest --no-cov -q gives 2946 passed, 3 skipped, 19 xfailed, 2 xpassed against 2944 passed, 3 skipped, 19 xfailed, 2 xpassed on main at 5d2c957, so the only change is the 2 new tests. The no-composite job, pytest --ignore=tests/psd_tools/composite/ -m "not composite" --no-cov -q, gives 1785 passed, 3 skipped, 2 xfailed against 1783 passed, 3 skipped, 2 xfailed on main. ruff check gives "All checks passed!", ruff format --check gives "110 files already formatted", mypy gives "Success: no issues found in 109 source files".

docs/usage.rst needed no correction, only a sharper heading for the example: "Set an item" is now "Replace the layer at a given index". Changelog entry added under the existing 1.19.1 (unreleased) heading.