JelleZijlstra/deprecations.md

## deprecations.md

      
    Raw
  

              deprecations.md
            
          
    This contains some notes in connection to an in-progress PEP about
deprecation support in the type system.
Briefly, the proposals being considered are:

@deprecated decorator for functions and classes
Deprecated[T] modifier for parameter and attribute types

I looked for usage of deprecations in the CPython codebase and whether some variation
of this proposal could cover them, in the sense that it would be possible to write a
stub that allows type checkers to detect code that would trigger the deprecation.
DeprecationWarning:

argparse: 2x whole method (covered by decorator)
ast: presence of method in a subclass (not covered by this proposal)
asyncio.events: calling get_event_loop() without a current eventt loop (not covered by this proposal)
asyncio.tasks: presence of method on third-party Tasks: (not covered by this proposal)
cgi: whole function (covered by decorator)
configparser: whole class (covered by decorator)
distutils, distutils.sysconfig: whole module (not covered by this proposal)
enum: member-to-member access, behavior of nested classes, enum.auto requirements (not covered)
ftplib: keyfile and certfile params (covered by Deprecated[])
gettext: passing a non-integer to a returned function (maybe can do with an overloaded callback protocol + decorator)
http.client: key_file, cert_file, check_hostname params (covered by Deprecated[])
imaplib: keyfiile, certfile params (covered by Deprecated[])
imp: whole module (not covered by this proposal)
importlib.find_loader: whole function (covered by decorator)
importlib._bootstrap: 3x whole function/method (covered by decorator), one about __package__ (not covered)
importlib._bootstrap_external: cache_from_source debug_override param (covered by Deprecated[]), 4x whole function (covered by decorator), 2x special conditions
importlib.abc: 3x whole class/function (covered by decorator)
importlib.metadata: the tupliness of some namedtuples (not covered)
importlib.resources: whole function (covered by decorator)
lib2to3: whole module (not covered by this proposal)
locale: 2x whole function (covered by decorator)
logging: 3x whole method (covered by decorator)
mailbox: 4x specific argument types (covered by overloads)
mailcap: whole function (covered by decorator)
pathlib: whole method (covered by decorator)
pkgutil: 2x whole class (covered by decorator)
poplib: keyfile, certfile params (covered by Deprecated[])
re: template function (covered by decorator), use of re.T/re.Template (covered by Deprecated[])
re._parser: 2x specific things in regex syntax (not covered)
smtplib: 2x keyfile, certfile params (covered by Deprecated[])
sqlite3.dbapi2: 4x usage of standard converters/adapters (not covered)
sre_compile, sre_constants, sre_parse: whole module (not covered by this proposal)
ssl: SSLContext without a param (covered by decorator + overloads), 3x whole method (covered by decorator)
sysconfig: check_home param (covered by Deprecated[])
threading: 8x whole method/function (covered by decorator)
tkinter.tix: whole module (not covered by this proposal)
typing: kwargs-based TypedDict, typing.re/io (not covered)
unittest.async_case: non-None return in subclass (not covered)
unittest.case: same (not covered)
unittest.loader: 3x whole function (covered by decorator)
unittest.main: whole method (covered by decorator)
urllib.parse: 12x whole function/class (covered by decorator)
urllib.request: cafile, capath, cadefault params (covered by Deprecated[]), whole class (covered by decorator)
webbrowser: 1x whole class, 2x property (covered by decorator)
wsgiref.handlers: something about partial writes (not covered by the type system)
zipimport: whole method (covered by decorator)

warnings._deprecated:

aifc, asyncore, cgi, cgitb, chunk, crypt, imghdr, mailcap, msilib, nntplib, pipes, sndhdr, sunau, telnetlib, uu, xdrlib: whole module (not covered)
asyncio.unix_events: 3x whole class (covered by decorator)
importlib.abc: deprecated re-export (not covered)
turtle: whole method (covered by decorator)

PyExc_DeprecationWarning

_asynciomodule.c: get_event_loop() without an event loop (not covered); FutureIter_throw with 3 args (covered by decorator + overloads I think)
_ssl.c: Use of certain protocols (probably Deprecated[] on module-level constants?)
audioop: whole module (not covered)
nismodule.c: whole module (not covered)
ossaudiodev: whole module (not covered)
posixmodule.c: passing non-bytes buffer type to paths (probably doable with decoorator + overloads)
spwdmodule.c: whole module (not covered)
abstract.c: return type of __trunc__, __float__, __index__ (not covered), int() using __trunc__ (doable with decorator + overloads)
bytesobject.c: something about escape sequences (not covered)
complexobject.c: return type of __complex__ (not covered)
floatobject.c: return type of __float__ (not covered)
genobject.c: 2x signature of .throw() (covered by decorator + overloads)
object.c: NotImplemented.__bool__ (covered by decoorator)
typeobject.c: things you can only do from C (not covered)
unicodeobject.c: various C functions; non-bytes buffers like posixmodule; escape sequences like bytesobject.c (mostly not covered)
string_parser.c: invalid escape sequences (not covered)
import.c: __package__ stuff (not covered)

SUMMARY (out of 150)

method/function/class: 74
module: 28
parameter: 9
constant: 1
too complicated: 38

Other links and notes


TypingError

python/mypy#13893
python/typing#1043
(Eric argues, probably persuasively, for a decorator)


Should specify that type checkers should prefer skipping @typing_error overloads?


@deprecated


Deprecated[]
https://mail.python.org/archives/list/typing-sig@python.org/thread/E24WTMQUTGKPFKEXVCGGEFFMG7LDF3WT/
microsoft/pyright#2300
Python-ideas thread "Create a @deprecated decorator (annotation)"


https://docs.google.com/presentation/d/1yzAh1Tok_wIk3lYo3rq1ieQp8MciVzO7pWI_m_LY30Y/edit#slide=id.g1af1a90c5d_0_84
Anticipate pushback for Deprecated[]. Use cases:

Deprecating a parameter
Deprecating an attribute