Как только вы разработаете библиотеку, SDK или любой другой кусок кода, который предназначен для использования несколькими людьми или программным обеспечением, вы должны подумать о обесценение Отказ
Как изящно внедрить изменения в свой код с течением времени?
Следующие показывают, как использовать амортизацию в Python для разных частей вашего кода с помощью стандартной библиотеки Python.
Как проверить амортизацию, чтобы обеспечить повышение предупреждений, когда вы ожидаете, что они будут поднять.
Наконец, предлагается формат сообщения для амортизационных сообщений, предоставляя мета-информацию для лучшего обслуживания.
Соответствующий исходный код и полные примеры к этой статье можно найти здесь .
Бросание лечебных предупреждений
Следующий раздел показывает, как использовать предупреждения онизма в разных частях вашего кода.
Для того, чтобы бросить предупреждения, вы хотите использовать встроенные Python в Предупреждающий контроль Отказ
from warnings import warn
warn('This is deprecated', DeprecationWarning, stacklevel=2)
Чтобы предупредить о снижении, вам нужно установить встроенный Python Обесценениевое вождение как категория. Чтобы сообщить о предупреждении обратиться к абонеру, чтобы вы точно знали, где вы используете устаревший код, вы должны установить Stacklevel = 2 Отказ
Функция амортизации
Уницируя функцию довольно легко, просто используя предупреждать в такой функции.
from warnings import warn
def a_deprecated_function():
warn('This method is deprecated.', DeprecationWarning, stacklevel=2)
Уницирование аргументов функции
Изложение на аргументы функций, требует, чтобы вы проверили желаемые изменения и бросить Обесценениевое вождение с методом.
from warnings import warn
def a_function_with_deprecated_arguments(arg1, *args, kwarg1=None, **kwargs):
# Positional argument `arg1` is going to change its type from (int, str) to (None, str)
if type(arg1) is int:
warn('arg1 of type int is going to be deprecated', DeprecationWarning, stacklevel=2)
# Keyword argument `kwarg2` is going to be dropped completely.
if 'kwarg2' in kwargs.keys():
warn('kwarg2 will be deprecated', DeprecationWarning, stacklevel=2)
Амортизация классов
При уставке классов вы должны рассмотреть два отдельных случая использования. Осреживание объекта устаренного класса может бросить предупреждение амортизации путем переопределения __init__ метод. Для того, чтобы бросить предупреждение о подклассах из устаренного метода, вы должны переопределить __init_sublcall__ Метод вместо этого.
from warnings import warn
class ADeprecatedClass(object):
def __init_subclass__(cls, **kwargs):
"""This throws a deprecation warning on subclassing."""
warn(f'{cls.__name__} will be deprecated.', DeprecationWarning, stacklevel=2)
super().__init_subclass__(**kwargs)
def __init__(self, *args, **kwargs):
"""This throws a deprecation warning on initialization."""
warn(f'{self.__class__.__name__} will be deprecated.', DeprecationWarning, stacklevel=2)
super().__init__(*args, **kwargs)
Упорядочение метода класса
Снижение метода класса в основном следует одни и те же правила, что и функциональная амортизация.
Уницирование переменных классов
Для того, чтобы обесценить переменные класса, вам нужно подключить к __getattribute__ Способ объектов метакласс.
from warnings import warn
class DeprecatedMetaclass(type):
def __getattribute__(self, item):
if 'a_deprecated_class_variable' == item:
warn(f'{item} class variable is deprecated', DeprecationWarning, stacklevel=2)
return type.__getattribute__(self, item)
class AClass(object, metaclass=DeprecatedMetaclass):
a_class_variable = 'foo'
a_deprecated_class_variable = None # deprecated
Уницирующие значения Enum.
Из-за того, что значения Enum будут иметь переменные классов подкласса Enum, снижение следует тем же подходу, что и Перечислительные переменные классов делает. Напротив, вы должны вернуть Enummeta .__ getattribute__ В качестве супер вызова вместо того, как вы подклассы от Enummeta Отказ
from enum import EnumMeta, Enum
from warnings import warn
class ADeprecatedEnumMeta(EnumMeta):
def __getattribute__(self, item):
if item == 'BAR':
warn('BAR is going to be deprecated', DeprecationWarning, stacklevel=2)
return EnumMeta.__getattribute__(self, item)
class ADeprecatedEnum(Enum, metaclass=ADeprecatedEnumMeta):
FOO = 'foo'
BAR = 'bar' # deprecated
Модуль обесценения
Чтобы обесценить целую модуль, просто поместите предупреждение амортизации на верхнем уровне этого модуля.
# lib.py
from warnings import warn
warn(f'The module {__name__} is deprecated.', DeprecationWarning, stacklevel=2)
Амортизация пакета
Амортизация пакета работает так же, как Модуль амортизации , где верхний уровень будет вашим __init__.py пакета, чтобы быть устаревшим.
Тестирование амортизаций
Питона Предупреждающий контроль Обеспечивает метод под названием Catch_warnings собирать предупреждения в пределах с блокировать. Настройка запись = Правда Позволяет записать предупреждения, которые были испущены во время выполнения вашего кода и проверьте, являются ли желаемые предупреждения, где подняты, как ожидалось. Мы не будем оценивать это глубину, благодаря это хорошо документировано в документации Python здесь .
from warnings import catch_warnings
def test_a_deprecated_enum_value():
with catch_warnings(record=True) as w:
# ADeprecatedEnum.FOO is not deprecated and should not throw any warning
ADeprecatedEnum.FOO
assert len(w) == 0
# ADeprecatedEnum.BAR is deprecated and we expect to have a warning raised.
ADeprecatedEnum.BAR
assert len(w) == 1
assert issubclass(w[0].category, DeprecationWarning)
assert str(w[0].message) == 'BAR is deprecated'
Версию амортизации
Амортизационные сообщения имеют наибольшее значение, когда они также предоставляют информацию, когда определенная амортизация предназначена для активного. В зависимости от вашей амортизации и ваших циклов выпуска вы можете иметь амортизацию, привязанную к версии или определенному моменту во времени.
Примите решение о формате сообщения, например сообщение; Отказ Таким образом, добавление метаинформации проходит прямую и легко проаналируют другие инструменты.
from warnings import warn
warn("This is deprecated; version=1.0.0", DeprecationWarning, stacklevel=2)
Используйте общие ключевые слова, такие как Версия или Дата для указания изменений в определенном моменте во времени.
from warnings import warn
warn("This is deprecated; date=2022-01-01", DeprecationWarning, stacklevel=2)
Предупреждения амортизации – это хороший инструмент для отслеживания изменений в рамках ваших API. Стандартная библиотека Python предоставляет ваши инструменты, необходимые для обезначения любой части вашего кода. Тем не менее, отсутствует правильная документация и лучшие практики вокруг амортизации в целом.
Для небольшого амортизации проекта может быть несложно. Когда дело доходит до более крупных проектов, с определенным уровнем ловкости это быстро может стать раздражающей рукой и может превратиться в потенциальный источник ошибки. Добавление информации о версии для передачи сообщений, позволяет легко отслеживать объявления и сроки. Тем не менее, есть место для конвенции и автоматизации, чтобы сделать амортизацию полезным, легко и распространенным для ежедневного использования.
амортизация – предупреждения Python. Warn () против регистрации. Воспроизведение ()
Управление предупреждением Python
PEP 565 – Показать обесценение во время __main__
Регистрация. Каплир ворна
Оригинал: “https://dev.to/hckjck/python-deprecation-2mof”