From 4ba81eccdf7f26f075a615784c64f17b7f3de50f Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Sun, 24 Sep 2023 21:06:08 -0700 Subject: [PATCH] Add an anti-pitch for typing --- docs/source/guides.rst | 1 + docs/source/typing_anti_pitch.rst | 76 +++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/source/typing_anti_pitch.rst diff --git a/docs/source/guides.rst b/docs/source/guides.rst index e85c5eb02..578abd619 100644 --- a/docs/source/guides.rst +++ b/docs/source/guides.rst @@ -9,3 +9,4 @@ Type System Guides libraries writing_stubs unreachable + typing_anti_pitch diff --git a/docs/source/typing_anti_pitch.rst b/docs/source/typing_anti_pitch.rst new file mode 100644 index 000000000..6986cd83c --- /dev/null +++ b/docs/source/typing_anti_pitch.rst @@ -0,0 +1,76 @@ +.. _typing-anti-pitch: + +Reasons to avoid static type checking +===================================== + +In the words of :pep:`484`:: + + It should also be emphasized that Python will remain a dynamically typed language, and the + authors have no desire to ever make type hints mandatory, even by convention. + +The idea that dynamism in Python is a strength of the language is reflected in the fact that +Python's type system is gradual. See :pep:`483` for details, but the long and short of this is +that you can add static types to your codebase only to the extent that you want to, and static +type checkers are designed to be able to put up with this. + +It's also worth noting that "static type checking" encompasses a spectrum of possible degrees of +strictness. On the one hand, you can set yourself up so that your type checker does almost nothing. +On the other -- well, I love type checking, but I would quit Python if I had to enable all +possible strictness checks that type checkers offer. + +Anway, with all that said, here's a list of possible reasons to not use static type checking +in Python:: + +* You simply don't want to. Python is a tool that is meant to serve you. Python is a big tent, + multi-paradigm language that generally allows you to do things in the way that best suits your + needs, as best determined by you. + +* The cost-benefit ratio isn't good enough. Pleasing static type checkers requires a non-zero amount + of busy work. If this isn't worth the extra confidence you get, you shouldn't add static type + checking. + +* Your codebase fits in your developers' heads. Opinions vary, but people tend to agree that at + some number of developers and lines of code, static type checking confers significantly more + benefit. You don't feel like you're there yet. + +* If you maintain high test coverage, that might provide sufficient quality assurance for your + needs (acknowledging that static type checking and tests enforce different things; static type + checking usually cannot validate logic, tests can often not prove invariants of your code to + hold). + +* Your codebase is old, large and has been working fine without static type checking for years. + While Python's type system is designed to + `allow gradual adoption of static type checking `_, + the total cost of adding type annotations to a large extant codebase can be prohibitive. + +* Your library does enough dynamic things that type checking would be unlikely to help your users. + Either you would have to spend a lot of effort redesigning your library in ways that static type + checkers could better understand, or you'd have to invest a lot of effort into figuring out clever + type annotations to twist the arms of type checkers. + +* Your codebase has suffered at the hands of `Hyrum's Law `_ + and all possible observable behaviour is depended on. In order to avoid false positives for your + users, all your types end up being either a) complicated ``Protocol``s that are hard to maintain, + or b) ``Any`` in which case there's not much point. (On the other hand, static type checking could + be a good solution for communicating to users what behaviour they should be allowed to rely on) + +* You're not opposed to type checking in theory, but you dislike Python type checkers in practice. + Maybe they don't understand enough of the idioms you use, maybe you'd like them to infer more + instead of relying on explicit annotations, maybe they're too slow, maybe they don't integrate + well with your editor, maybe they're too hard to configure. Whatever the reason -- it just doesn't + work for your project. + +Advice for maintainers of untyped libraries +******************************************* + +You've made the decision that adding static types isn't the right choice for your library. But +perhaps you'd still like to help your users who do use static type checking -- and maybe you have +some enthusiastic would-be contributors willing to help with this). + +One option is encourage such contributors to publish a :pep:`561` stub-only package that is +maintained separately from your main project. You could also contribute these stubs to the +`typeshed `_ project. + +If more users pester you about adding static types, feel free to link them to this document. And if +you ever change your mind, make sure to check out some of the other guides in this documentation, +and ask any questions you have over at `Python's typing discussions `_.