Add a page detailing the time complexity of operations on built-in types

[StanFromIreland]

Inspired by @nedbat's post on Discourse:

One page in the wiki that I think should be in the docs is Time Complexity. It seems like important information about CPython and should be documented.

The page's location isn't ideal, but we don't have a better place for it currently. We discussed this at the last Docs Community meeting, but didn't come up with a better place to put it, and creating new top level sections is in my opinion, out of scope (as we'd need to move other pages as well). If it's desired we can do it in a future PR.

I spend a while considering how to best present time complexity here, avoiding complexity ;-) The wiki pages splits it into amortised, worst, best and averages cases (each type had a selection of those), but I think that it would be too confusing for readers. As such I give the average case, and put the details in the prose/footnotes.

The numbers are, hopefully, correct, as I don't think I missed any quirks (at least I don't know of any ;-). But I'd appreciate a review from the experts here, maybe Serhiy or Tim could please take a peek?

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34195064 | 📁 Comparing 116f21e against main (bfd774d)

  🔍 Preview build  

95 files changed · + 1 added · ± 94 modified

+ Added

• library/time-complexity.html

± Modified

• glossary.html
• index.html
• license.html
• c-api/arg.html
• c-api/capsule.html
• c-api/exceptions.html
• c-api/frame.html
• c-api/import.html
• c-api/init_config.html
• c-api/intro.html
• and 84 more...

[picnixz]

Iteration is, AFAICT, always O(n) so we can group that under a common table. Likewise, getting the length of a sized object is O(1).

I think it's better to keep pythonic exmaples as well. "d[key]" is mucher better than "get item" IMO.

When I read "the non-mtating operations below", it also rings "the opertaions below are all non-mutating". Instead, I suggest to add some * if the opertaion is mutating and explain that at the beginning of the document.

[StanFromIreland]

Iteration is, AFAICT, always O(n) so we can group that under a common table. Likewise, getting the length of a sized object is O(1).

While it would make the tables shorter, it's not so straightforward unfortunately. There are subtle differences, see footnote six. I also think that reference pages are scanned, not read linearly. As such, I'd prefer to keep them where they are.

[eendebakpt]

I am +0.5 in this. I like to the idea, but it will take time to maintain and it is not clear to me where to draw the line when more additions are requested (e.g. memory complexity, alternatives, more detailed descriptions, more references).

[picnixz]

FTR the Qt help pages once had a page for complexty of operations of their STL containers, so it might be worth reading them if you need precedents in other languages. I do not know if those pages still exist as they were available for Qt5 dirdctly in the Qt Creator IDE.

[picnixz]

I found back the link: https://doc.qt.io/qt-6/containers.html#algorithmic-complexity

[StanFromIreland]

Thanks Pieter, Bénédikt and Hugo for the reviews ❤️ !

[picnixz]

This looks better but can you comment with saying what you deferred. I don't really understand why we should deferring some additions as this would create un-necessary future commits.

[StanFromIreland]

This has gotten four approvals, so I plan to merge this tomorrow. Please let me know if you'd like time to review, and I can wait.

[StanFromIreland]

This looks better but can you comment with saying what you deferred. I don't really understand why we should deferring some additions as this would create un-necessary future commits.

I have deferred adding various operations (we'll need to go through all of them, not just those mentioned in reviews here) for the reasons I outlined in #154363 (comment) (it took me quite a while to get to that comment, which I think is another reason for deferring). If we land the initial structure and design, we can iterate on the operations in follow ups. It would also be nice to get some user feedback once this goes live, to see if we should make any larger changes.

[hugovk]

This looks better but can you comment with saying what you deferred. I don't really understand why we should deferring some additions as this would create un-necessary future commits.

We follow Diátaxis for the docs which recommends incremental steps rather than big bangs, which frequently stall and end up unmerged.

https://diataxis.fr/how-to-use-diataxis/#work-one-step-at-a-time

[miss-islington-app]

Thanks @StanFromIreland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-156326 is a backport of this pull request to the 3.15 branch.

[dg-pb]

🎉

[StanFromIreland]

Thanks to everyone who contributed! This was a pretty considerable effort, and it took some time, but it has finally landed!

[miss-islington-app]

Thanks @StanFromIreland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @StanFromIreland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @StanFromIreland, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker c3f7c33dd7c6496d474979d5bd7f5dc22103dd22 3.13

[bedevere-app]

GH-156337 is a backport of this pull request to the 3.14 branch.

[hugovk]

Sorry, @StanFromIreland, I could not cleanly backport this to 3.13 due to a conflict. Please backport using cherry_picker on command line.

cherry_picker c3f7c33dd7c6496d474979d5bd7f5dc22103dd22 3.13

• TODO: Remove at least frozendict (added in 3.15)

[bedevere-app]

GH-156338 is a backport of this pull request to the 3.13 branch.