Skip to content

Instantly share code, notes, and snippets.

Created December 31, 2022 00:18
Show Gist options
  • Save JelleZijlstra/ff459edc5ff0918e22b56740bb28eb8b to your computer and use it in GitHub Desktop.
Save JelleZijlstra/ff459edc5ff0918e22b56740bb28eb8b to your computer and use it in GitHub Desktop.
Deprecations in CPython

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.


  • argparse: 2x whole method (covered by decorator)
  • ast: presence of method in a subclass (not covered by this proposal)
  • 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, 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
  • 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, (not covered)
  • unittest.async_case: non-None return in subclass (not covered)
  • 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)


  • 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)
  • deprecated re-export (not covered)
  • turtle: whole method (covered by decorator)


  • _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)

Anticipate pushback for Deprecated[]. Use cases:

  • Deprecating a parameter
  • Deprecating an attribute
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment