The definition of tilepalettemapper.TilePaletteMapper has changed between 9.2.x and 10.0.0-alpha

[dglaude]

CircuitPython version and board name

Adafruit CircuitPython 10.0.0-alpha.6 on 2025-05-17; Adafruit Metro RP2350 with rp2350b

Code/REPL

= TilePaletteMapper(shader_palette, 2, SCREEN_WIDTH, SCREEN_HEIGHT)

from https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/54ab01feadf4206fa5ec1b5f22c6e2f646e2c0bc/Metro/Metro_RP2350_CircuitPython_Matrix/code.py#L67

(works fine in 9.x and fail in 10.0.0-alpha6)

Behavior

  File "code.py", line 67, in <module>
TypeError: extra positional arguments given
]0;🐍67@code.py TypeError | 10.0.0-alpha.6\

Description

The definition of tilepalettemapper.TilePaletteMapper has changed between 9.2.x and 10.0.0-alpha

(9)
https://docs.circuitpython.org/en/9.2.x/shared-bindings/tilepalettemapper/index.html#tilepalettemapper.TilePaletteMapper
class tilepalettemapper.TilePaletteMapper(palette: displayio.Palette, input_color_count: int, width: int, height: int)

vs
(10)
https://docs.circuitpython.org/en/latest/shared-bindings/tilepalettemapper/index.html#tilepalettemapper.TilePaletteMapper
class tilepalettemapper.TilePaletteMapper(palette: displayio.Palette, input_color_count: int)

This is a breaking change for some code such as line 67 here:
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/54ab01feadf4206fa5ec1b5f22c6e2f646e2c0bc/Metro/Metro_RP2350_CircuitPython_Matrix/code.py#L67
from Learn guide https://learn.adafruit.com/return-to-the-matrix-with-the-metro-rp2350/circuitpython-version

grid_color_shader = TilePaletteMapper(shader_palette, 2, SCREEN_WIDTH, SCREEN_HEIGHT)

This code works fine in 9.x but fail in 10.x.

Additional information

This is a breaking change, and I have not found a syntax that would make the same code work in 9.x and 10.x
There must be a better way to do that, or if not, to document that breaking change and suggest what to change in the code when going from 9 to 10.

Also a search for all usage of tilepalettemapper.TilePaletteMapper in Learn Guide to identify what guide need a fix would be needed (but maybe this is unique?).

[FoamyGuy]

That is true that the API changed and the old code is no longer working. Sorry, I have updated versions for the new API but have not PR'd them yet.

Under the new API you need to create the TilePalletteMapper first with no height or width, and then assign it to the TileGrid as a pixel_shader like normal. When that asignment happens the TilePaletteMapper gets the appropriate height and width from the TileGrid automatically now.

Here is the updated code section for the initialization of tpm and tilegrid in the matrix code:

# mapper to change colors of tiles within the grid
grid_color_shader = TilePaletteMapper(shader_palette, 2)

# load the spritesheet
katakana_bmp, katakana_pixelshader = adafruit_imageload.load("matrix_characters.bmp")

# how many characters are in the sprite sheet
char_count = katakana_bmp.width // 16

# grid to display characters within
display_text_grid = TileGrid(
    bitmap=katakana_bmp,
    width=SCREEN_WIDTH,
    height=SCREEN_HEIGHT,
    tile_height=16,
    tile_width=16,
    pixel_shader=grid_color_shader,
)

Matrix, Match3, and maybe one more need this update still, I will submit a PR for them tomorrow.

Note to self: we should add TPM initialization / most basic example code to the docstrings like some other modules have basic usage code in their docs pages.

[FoamyGuy]

actually, it slipped my mind when I made the previous comment, but I had already submitted a PR to update these here: adafruit/Adafruit_Learning_System_Guides#3034

[FoamyGuy]

That fix is merged now and the guide code is updated to support both versions of the API.