# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-deprecation
VERSION=		2.1.0
KEYWORDS=		python
VARIANTS=		v11 v12
SDESC[v11]=		Library to handle automated deprecations (3.11)
SDESC[v12]=		Library to handle automated deprecations (3.12)
HOMEPAGE=		https://deprecation.readthedocs.io/
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPIWHL/02/c3/253a89ee03fc9b9682f1541728eb66db7db22148cd94f89ab22528cd1e1b
DISTFILE[1]=		deprecation-2.1.0-py2.py3-none-any.whl:main
DF_INDEX=		1
SPKGS[v11]=		single
SPKGS[v12]=		single

OPTIONS_AVAILABLE=	PY311 PY312
OPTIONS_STANDARD=	none
VOPTS[v11]=		PY311=ON PY312=OFF
VOPTS[v12]=		PY311=OFF PY312=ON

DISTNAME=		deprecation-2.1.0.dist-info

GENERATED=		yes

[PY311].RUN_DEPENDS_ON=			python-packaging:single:v11
[PY311].USES_ON=			python:v11,wheel

[PY312].RUN_DEPENDS_ON=			python-packaging:single:v12
[PY312].USES_ON=			python:v12,wheel

[FILE:2783:descriptions/desc.single]
deprecation
===========

   :alt: Documentation Status

The deprecation library provides a deprecated decorator and a
fail_if_not_removed decorator for your tests. Together, the two
enable the automation of several things:

1. The docstring of a deprecated method gets the deprecation details
   appended to the end of it. If you generate your API docs direct
   from your source, you don't need to worry about writing your own
   notification. You also don't need to worry about forgetting to
   write it. It's done for you.
2. Rather than having code live on forever because you only deprecated
   it but never actually moved on from it, you can have your tests
   tell you when it's time to remove the code. The ``@deprecated``
   decorator can be told when it's time to entirely remove the code,
   which causes ``@fail_if_not_removed to raise an AssertionError``,
   causing either your unittest or py.test tests to fail.

See http://deprecation.readthedocs.io/ for the full documentation.

Installation
============

 ::

    pip install deprecation

Usage
=====

 ::

    import deprecation

    @deprecation.deprecated(deprecated_in="1.0", removed_in="2.0",
                            current_version=__version__,
                            details="Use the bar function instead")
    def foo():
        """Do some stuff"""
        return 1

...but doesn't Python ignore DeprecationWarning?
====================================================

Yes, by default since 2.7—and for good reason [#]_ —and this works fine
with that.

1. It often makes sense for you to run your tests with a ``-W flag or
   the PYTHONWARNINGS`` environment variable so you catch warnings
   in development and handle them appropriately. The warnings raised by
   this library show up there, as they're subclasses of the built-in
   DeprecationWarning. See the [Command Line
  ]
   and [Environment Variable
  ]
   documentation for more details.
2. Even if you don't enable those things, the behavior of this library
   remains the same. The docstrings will still be updated and the tests
   will still fail when they need to. You'll get the benefits regardless
   of what Python cares about DeprecationWarning.

----

.. [#] Exposing application users to DeprecationWarning\s that are
       emitted by lower-level code needlessly involves end-users in
       "how things are done." It often leads to users raising issues
       about warnings they're presented, which on one hand is done
       rightfully so, as it's been presented to them as some sort of
       issue to resolve. However, at the same time, the warning could
       be well known and planned for. From either side, loud
       DeprecationWarning\s can be seen as noise that isn't
       necessary outside of development.


[FILE:117:distinfo]
a10811591210e1fb0e768a8c25517cabeabcba6f0bf96564f8ff45189f90b14a        11178 deprecation-2.1.0-py2.py3-none-any.whl