Skip to content

safe-returns

Декоратор для преобразования выходного типа данных функции в алгебраический тип данных, совмещая его с возможными типами исключений.

Основная цель пакета — предоставить возможность явно указывать типы исключений, которые может выбрасывать функция, и отслеживать их средствами тайп-чекеров.

Пакет предоставляет два декоратора: @safe и @async_safe для функций и корутин соответственно.

Декоратор предоставляет удобный механизм указания типов исключений, которые могут возникнуть в ходе работы функции. Это позволяет упростить написание кода обработки таких исключений, используя подсказки IDE и тайп-чекера, а также избегая необходимости просмотра кода вызываемой функции для определения возможных случаев исключений.

Ключевые особенности

  • Пакет позволяет декорировать функции и корутины.
  • Результат функции оборачивается в объект Success, чтобы отличить возникшее исключение от возвращённого значения, например, из фабрики исключений.
  • Широкий механизм указания типов. Используя оператор или (|), аналогичный UnionType, можно перечислять конкретные типы, передавать коллекции, составленные во время выполнения, или задекорированные таким образом функции.
  • Порождающий механизм типизации не ограничивает количество типов исключений, которые может распознавать тайп-чекер.
  • Использует чистый Python для типизации и не имеет дополнительных зависимостей.

Зависимости

Требуется только Python >= 3.11.

Установка

Установка из PyPI: safe-returns.

pip install safe-returns

poetry add safe-returns

uv add safe-returns

Примеры

При использование паттерн-матчинга будет указано замечание что KeyError не обрабатывается.

from safe import safe, Success, Failure

@safe @ ValueError | KeyError
def foo() -> int | str: ...


match foo():
    case Success(value=int()):
        print("It's int")
    case Success(value=str()):
        print("It's str")
    case Failure(error=ValueError()):
        print("Catch ValueError")

Больше примеров см. Возможности.

Лицензия

Этот проект распространяется на условиях лицензии MIT.