Структурное сопоставление с образцом: match-case

`match`/`case` из Python 3.10: литеральные, захватывающие и «любые» образцы, образцы последовательностей, словарей и классов, OR-образцы, `as` и условия-стражи — на примере разбора текстовых команд и диспетчера JSON-событий.

  • Продвинутый
  • 22 мин
  • 12 вопросов
  • Урок 22 из 66

В этом уроке ты узнаешь

  • Объяснять, как работает match/case: проверка сверху вниз, побеждает первое совпадение, захват против сравнения
  • Разбирать текстовые команды с помощью образцов последовательностей
  • Проверять и разбирать JSON-данные образцами словарей и классов
  • Уместно применять стражи, OR-образцы и as

Маленькому игровому боту приходят команды вроде go north, take lamp key или quit, а интернет-магазин получает JSON-события вида {"type": "payment", "amount": 16.5}. Проверять такие данные через if/elif неудобно: сначала длину, потом тип, потом ключи, а затем ещё и переносить нужные части в переменные. С Python 3.10 (октябрь 2021 года) в языке есть структурное сопоставление с образцом: match проверяет форму данных и за один шаг извлекает их части.

match, case и образецОпределение

match subject: берёт проверяемое значение (субъект), а каждый case pattern: — это образец, описание того, как должны выглядеть данные. Варианты проверяются сверху вниз; выполняется блок первого подошедшего case, и match завершается. Если не подошёл ни один, ничего не происходит.

Литералы, OR и образец «всё остальное»

Простейший образец — литерал: case 404: срабатывает, когда субъект == 404. | объединяет несколько вариантов, а _ подходит ко всему и обычно пишется последним как «все остальные случаи». В отличие от switch в C или JavaScript, break не нужен, и выполнение никогда не «проваливается» в следующий case.

Python
def http_status(code):
    match code:
        case 200:
            return 'OK'
        case 301 | 302:
            return 'Redirect'
        case 401 | 403:
            return 'No access'
        case 404:
            return 'Not Found'
        case _:
            return f'Unknown code {code}'


for c in (200, 302, 403, 404, 418):
    print(c, http_status(c))
Ожидаемый результат
200 OK
302 Redirect
403 No access
404 Not Found
418 Unknown code 418
  1. Субъект

    Выражение после match вычисляется один раз.

  2. Варианты по порядку

    Образцы проверяются сверху вниз: подходят ли форма и значения?

  3. Привязка имён

    Подошедший образец присваивает значения своим захватывающим именам.

  4. Страж

    Если есть if, он должен быть истинным, иначе проверяется следующий case.

  5. Блок

    Выполняется блок первого успешного case, и match завершается.

ОбразецПримерПодходит, когда
литералcase 404: case 'quit':субъект == значение (None, True, False — через is)
захватcase x:всегда; привязывает субъект к x
«всё остальное»case _:всегда; ничего не привязывает
значение (имя с точкой)case Cmd.QUIT:субъект == константа
ORcase 401 | 403:подходит один из вариантов
последовательностьcase [x, y, *rest]:список или кортеж подходящей длины
словарьcase {'type': t}:словарь с этими ключами (остальные не важны)
классcase Point(x=0):isinstance + атрибуты подходят
AScase [_, _] as pair:внутренний образец подходит; привязывает всё значение
страж (guard)case x if x > 0:образец подходит и условие истинно

Простое имя (case x:) — никогда не сравнение: это захватывающий образец, который подходит к любому значению и присваивает его этому имени. Поэтому константу нельзя писать как case QUIT: — это не проверяет значение QUIT, а перезаписывает его. Для сравнения с константой нужно имя с точкой: Cmd.QUIT, config.LIMIT, Color.RED (Enum).

Python
QUIT = 'quit'


def handle(command):
    match command:
        case QUIT:                 # a capture pattern, not a comparison!
            return f'quitting... (QUIT is now {QUIT!r})'


class Cmd:
    QUIT = 'quit'
    HELP = 'help'


def handle_fixed(command):
    match command:
        case Cmd.QUIT:             # a dotted name is compared with ==
            return 'bye'
        case Cmd.HELP:
            return 'commands: help, quit'
        case _:
            return f'unknown command {command!r}'


print(handle('hello'))
print(handle_fixed('hello'), '|', handle_fixed('quit'))
Ожидаемый результат
quitting... (QUIT is now 'hello')
unknown command 'hello' | bye
case QUIT: подошёл и к 'hello' и сделал локальную QUIT равной 'hello'. А Cmd.QUIT сравнивается через ==.

Чтобы читать дальше, зарегистрируйся бесплатно

Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.

Образцы последовательностей: разбор команд

command.split() превращает строку в список слов, а match проверяет форму этого списка: ['go', direction] — ровно два слова, первое go; ['take', *items] — take и любое число слов (они попадут в список items); ['quit' | 'exit'] — одно слово, один из двух вариантов. Имена внутри образца захватывают подходящие части.

Python
DIRECTIONS = {'north', 'south', 'east', 'west'}


def handle(command):
    match command.split():
        case []:
            return 'Say something'
        case ['go', direction] if direction in DIRECTIONS:
            return f'You go {direction}'
        case ['go', _]:
            return 'You cannot go there'
        case ['take']:
            return 'Take what?'
        case ['take', *items]:
            return 'You take ' + ', '.join(items)
        case ['look'] | ['l']:
            return 'A dark room. There is a lamp.'
        case ['quit' | 'exit']:
            return 'Bye!'
        case [verb, *_]:
            return f'I do not know how to {verb!r}'


for line in ['go north', 'go up', 'take lamp key', 'take', 'l', 'exit', 'dance now', '']:
    print(f'{line!r:15} -> {handle(line)}')
Ожидаемый результат
'go north'      -> You go north
'go up'         -> You cannot go there
'take lamp key' -> You take lamp, key
'take'          -> Take what?
'l'             -> A dark room. There is a lamp.
'exit'          -> Bye!
'dance now'     -> I do not know how to 'dance'
''              -> Say something
Для go up первый образец go подошёл, но страж (if direction in DIRECTIONS) оказался ложным, поэтому проверка перешла к следующему case. Пустая строка даёт пустой список: case [].

через if/elif

words = command.split()
if len(words) == 2 and words[0] == 'go':
    move(words[1])
elif len(words) >= 2 and words[0] == 'take':
    take(words[1:])
elif words in (['quit'], ['exit']):
    stop()

через match

match command.split():
    case ['go', direction]:
        move(direction)
    case ['take', *items] if items:
        take(items)
    case ['quit' | 'exit']:
        stop()
Та же логика: match сам проверяет длину и индексы и даёт частям имена.

Образец последовательности подходит к спискам, кортежам, range и другим последовательностям, но не к строкам, bytes и словарям — иначе любая строка разбиралась бы по буквам. Образец без звёздочки требует точной длины, а *name захватывает любое число элементов в виде списка (в образце может быть только одна звёздочка).

Python
def describe(value):
    match value:
        case []:
            return 'empty sequence'
        case [x]:
            return f'one item: {x}'
        case [x, y]:
            return f'pair: {x}, {y}'
        case [first, *middle, last]:
            return f'from {first} to {last}, {len(middle)} in between'
        case str():
            return f'a string: {value!r}'
        case _:
            return f'something else: {type(value).__name__}'


for v in [[], (7,), [1, 2], range(5), 'ab', {'a': 1}]:
    print(describe(v))
Ожидаемый результат
empty sequence
one item: 7
pair: 1, 2
from 0 to 4, 3 in between
a string: 'ab'
something else: dict
(7,) — кортеж, но подходит к [x]: квадратные или круглые скобки не важны. Для range(5) middle стал [1, 2, 3].

Примеры: какой case сработает?

Задача

1) match (3, 4): → case [x, 0]: print('zero'), case [x, y]: print(x * y)
2) match [1]: → case [x, y, *rest]: print('long'), case _: print('short')
3) match ['take']: → case ['take', *items] if items: print('A'), case ['take', *items]: print(len(items))

Показать решениеСкрыть решение

Решение

1) 12: первому образцу нужен 0 вторым элементом (4 ≠ 0), второй даёт x = 3, y = 4.
2) short: [x, y, *rest] требует минимум 2 элемента.
3) 0: первый образец подходит, но страж ложен, так как items == []; второй case захватывает items как пустой список.

Образцы словарей: JSON и ответы API

Образец словаря {'ключ': образец} требует, чтобы эти ключи были и их значения подходили к внутренним образцам. В отличие от последовательностей, лишние ключи игнорируются — новые поля в JSON код не ломают. Если остальные ключи нужны, **rest соберёт их в отдельный словарь. Чтобы проверить тип, вставь внутрь образец класса: str(city) — «если это строка, привяжи её к city», int() | float() as t — «если это число, привяжи его к t».

Python
def read_weather(response):
    match response:
        case {'status': 'ok', 'data': {'city': str(city), 'temp': int() | float() as t}}:
            return f'{city}: {t} °C'
        case {'status': 'error', 'message': str(msg)}:
            return 'error: ' + msg
        case {'status': status}:
            return f'unexpected response with status {status!r}'
        case _:
            return 'not a response'


print(read_weather({'status': 'ok', 'data': {'city': 'Baku', 'temp': 23.5}, 'time': '12:00'}))
print(read_weather({'status': 'error', 'message': 'city not found'}))
print(read_weather({'status': 'ok', 'data': {'city': 'Quba', 'temp': 'warm'}}))
print(read_weather(['ok', 23]))
Ожидаемый результат
Baku: 23.5 °C
error: city not found
unexpected response with status 'ok'
not a response
В первом ответе лишний ключ 'time' не помешал. В третьем 'temp' — не число, поэтому первый образец не подошёл, и ответ попал в общий образец {'status': status}. Список к образцам словарей не подходит.

Образцы классов и стражи

case Point(x=0, y=y): сначала проверяет isinstance(subject, Point), затем атрибуты. Позиционная форма Point(0, y) требует в классе __match_args__ (порядок атрибутов) — @dataclass создаёт его автоматически (см. «Аннотации типов и dataclasses»). Для встроенных типов вроде int(), str(), float(), list() и dict() один позиционный образец захватывает всё значение: str(name). После образца можно добавить страж через if: если образец подошёл, а условие ложно, проверка переходит к следующему case.

Python
from dataclasses import dataclass


@dataclass
class Point:
    x: float
    y: float


@dataclass
class Circle:
    center: Point
    r: float


@dataclass
class Rect:
    corner: Point
    w: float
    h: float


def describe(shape):
    match shape:
        case Circle(Point(0, 0), r):
            return f'circle at the origin, r = {r}'
        case Circle(r=r) if r <= 0:
            return 'invalid circle'
        case Rect(w=w, h=h) if w == h:
            return f'square {w} × {h}'
        case Rect(Point(x, y), w, h):
            return f'rectangle {w} × {h} at ({x}, {y})'
        case _:
            return f'unknown shape: {shape}'


for s in [Circle(Point(0, 0), 5), Circle(Point(2, 3), -1), Rect(Point(1, 1), 4, 4),
          Rect(Point(0, 2), 6, 3), Point(1, 2)]:
    print(describe(s))
print(Rect.__match_args__)
Ожидаемый результат
circle at the origin, r = 5
invalid circle
square 4 × 4
rectangle 6 × 3 at (0, 2)
unknown shape: Point(x=1, y=2)
('corner', 'w', 'h')
Circle(Point(0, 0), r) — вложенный образец: окружность с центром в точке (0; 0). Rect(w=w, h=h) if w == h ловит квадрат раньше обычного прямоугольника, потому что частный случай записан выше.

Мини-проект: диспетчер событий

Сервер интернет-магазина получает поток JSON-событий. Каждое событие нужно направить по типу и форме: записать входы, посчитать сумму заказов, отбросить пустые заказы, добавить правильные платежи к выручке, отклонить отрицательные суммы и сообщить о неизвестных и повреждённых событиях. Здесь вместе работают все образцы урока: OR и as, **extra, вложенная последовательность, проверка типов и страж.

Python
import json

raw = '''[
  {"type": "login", "user": "aysel"},
  {"type": "order", "user": "aysel", "items": [{"sku": "pen", "qty": 3, "price": 1.5},
                                               {"sku": "book", "qty": 1, "price": 12.0}]},
  {"type": "order", "user": "murad", "items": []},
  {"type": "payment", "user": "aysel", "amount": 16.5, "currency": "AZN"},
  {"type": "payment", "user": "leyla", "amount": -3, "currency": "AZN"},
  {"type": "logout", "user": "aysel", "reason": "timeout"},
  {"type": "upload", "file": "cv.pdf"},
  "garbage"
]'''

revenue = 0
for event in json.loads(raw):
    match event:
        case {'type': 'login' | 'logout' as kind, 'user': str(user), **extra}:
            print(f'{user}: {kind}' + (f' {extra}' if extra else ''))
        case {'type': 'order', 'user': user, 'items': [_, *_] as items}:
            total = sum(item['qty'] * item['price'] for item in items)
            print(f'{user}: order of {len(items)} items, {total:.2f} AZN')
        case {'type': 'order', 'user': user}:
            print(f'{user}: empty order ignored')
        case {'type': 'payment', 'amount': int() | float() as amount, 'currency': 'AZN'} if amount > 0:
            revenue += amount
        case {'type': 'payment', 'user': user, 'amount': amount}:
            print(f'{user}: rejected payment {amount}')
        case {'type': str(kind)}:
            print(f'unknown event type {kind!r}')
        case _:
            print(f'not an event: {event!r}')
print('revenue:', revenue, 'AZN')
Ожидаемый результат
aysel: login
aysel: order of 2 items, 16.50 AZN
murad: empty order ignored
leyla: rejected payment -3
aysel: logout {'reason': 'timeout'}
unknown event type 'upload'
not an event: 'garbage'
revenue: 16.5 AZN
[_, *_] as items означает «список хотя бы из одного элемента», поэтому пустой заказ попадает в следующий case. Платёж добавляется к выручке, только если выполнен страж; отрицательная сумма отклоняется следующим, более общим образцом платежа.

Задание

Допиши classify(value): bool → 'bool' (уже написано; должно идти первым, ведь True — тоже int), 0 → 'zero', положительное целое → 'positive int', отрицательное целое → 'negative int', дробное → 'float', пустая строка → 'empty string', другая строка → 'string', последовательность из двух элементов → 'pair', всё остальное → 'other'.

Задание · Python
def classify(value):
    match value:
        case bool():
            return 'bool'
        # add the other cases here
        case _:
            return 'other'


for v in [0, 42, -7, 3.14, '', 'hi', (1, 2), [1, 2, 3], True, None]:
    print(repr(v), '->', classify(v))
Ожидаемый результат
0 -> zero
42 -> positive int
-7 -> negative int
3.14 -> float
'' -> empty string
'hi' -> string
(1, 2) -> pair
[1, 2, 3] -> other
True -> bool
None -> other

Задание

Допиши калькулятор команд на образцах последовательностей: add a b, mul a b, neg a и sum a b c … хотя бы с одним числом. Числа переводи во float; всё остальное должно возвращать 'error'.

Задание · Python
def calc(line):
    match line.split():
        case ['add', a, b]:
            return float(a) + float(b)
        # add: mul a b, neg a, sum a b c ... (at least one number)
        case _:
            return 'error'


for line in ['add 2 3', 'mul 4 2.5', 'neg 7', 'sum 1 2 3 4', 'sum', 'add 1']:
    print(line, '=', calc(line))
Ожидаемый результат
add 2 3 = 5.0
mul 4 2.5 = 10.0
neg 7 = -7.0
sum 1 2 3 4 = 10.0
sum = error
add 1 = error

Запомни

  • match проверяет case сверху вниз; срабатывает первое совпадение, break не нужен, «проваливания» нет.
  • Простое имя — захватывающий образец, подходящий ко всему; константы пиши через точку (Cmd.QUIT).
  • Образцы последовательностей подходят к спискам и кортежам (не к строкам); *rest захватывает остальные элементы.
  • Образцы словарей игнорируют лишние ключи; **rest собирает остальные; str(x) и int() | float() as n проверяют тип.
  • Образцы классов проверяют isinstance и атрибуты (__match_args__ у dataclass есть сразу); страж if проверяется после образца.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 12. Каждый правильный ответ приносит XP.

Вопрос 1 / 12

Вопрос 1 / 12. С какой версии Python доступен match/case?