From 3050f9866b50cf2b0b5831092f8e46b32b6de7c0 Mon Sep 17 00:00:00 2001 From: Joshua Bronson Date: Mon, 28 Feb 2022 00:21:03 +0000 Subject: [PATCH] Minor docs improvements. --- CHANGELOG.rst | 33 +++++++----- CONTRIBUTING.rst | 9 ++-- README.rst | 15 +++--- docs/learning-from-bidict.rst | 95 +++++++++++++++++++---------------- 4 files changed, 82 insertions(+), 70 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 894cc68..52feab3 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -8,15 +8,25 @@ Changelog ========= +.. image:: https://img.shields.io/badge/GitHub-sponsor-ff69b4 + :target: https://github.com/sponsors/jab + :alt: Sponsor through GitHub + +.. image:: https://img.shields.io/github/sponsors/jab + :target: https://github.com/sponsors/jab + :alt: Sponsors on GitHub + + Release Notifications --------------------- .. duplicated in README.rst (would use `.. include::` but GitHub doesn't understand it) -Tip: Watch releases -`on GitHub `__ -to be notified when new versions of ``bidict`` are released. +Tip: +`Watch `__ releases +`on GitHub `__ +to be notified when new versions of bidict are released. 0.22.0 (not yet released) @@ -57,10 +67,6 @@ to be notified when new versions of ``bidict`` are released. In a microbenchmark on Python 3.10, this now performs **5-30% faster**. -- Optimize pickling bidicts. - In a microbenchmark on Python 3.10, - this now performs **5-10% faster**. - - Optimize rolling back :ref:`failed updates to a bidict ` in the case that the number of items passed to the update call @@ -68,13 +74,14 @@ to be notified when new versions of ``bidict`` are released. Previously this rollback was O(n) in the number of items passed. Now it is O(1), i.e. **unboundedly faster**. -- Optimize :meth:`~bidict.BidictBase.__contains__` - (the method called when you run ``key in any_bidict``). +- Optimize :meth:`bidict.BidictBase.__contains__` + (the method called when you run ``key in mybidict``). In a microbenchmark on Python 3.10, this now performs over **3x faster** in the False case, and at least **50% faster** in the True case. -- Optimize :meth:`~bidict.BidictBase.__eq__`. +- Optimize :meth:`bidict.BidictBase.__eq__` + (the method called when you run ``mybidict == other``). In a microbenchmark on Python 3.10, this now performs over **25x faster** for ordered bidicts, and at least **10x faster** for unordered bidicts. @@ -151,9 +158,9 @@ to be notified when new versions of ``bidict`` are released. an ``_isinv`` attribute, which :class:`~bidict.BidictBase` subclasses no longer provide. -- When attempting to pickle a bidict's inverse - whose class was dynamically generated - (as in :ref:`extending:Dynamic Inverse Class Generation`), +- When attempting to pickle a bidict's inverse whose class was + :ref:`dynamically generated + `, and no reference to the dynamically-generated class has been stored anywhere in :data:`sys.modules` where :mod:`pickle` can find it, the pickle call is now more likely to succeed diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0476579..6d3e7cb 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -144,14 +144,13 @@ Bidict is the product of thousands of hours of my unpaid work over the ~15 years that I've been the sole maintainer. If bidict has helped you or your company accomplish your work, -especially work that you or your company were paid for, please `sponsor my work through GitHub `__, -and ask others you know who got value from my work to do the same. +and/or ask your company to do the same. Choose a tier and GitHub handles everything else. -Sponsorship just goes on the same bill that GitHub -already charges you or your company for automatically, -so after the one-time signup, there's nothing extra to do. +Your GitHub sponsorship will automatically go +on the same bill you already have set up with GitHub, +so after the one-click signup, there's nothing else to do. You can also sponsor my work through `Gumroad `__ or diff --git a/README.rst b/README.rst index 438c9ff..8494085 100644 --- a/README.rst +++ b/README.rst @@ -149,8 +149,8 @@ Release Notifications .. duplicated in CHANGELOG.rst: (would use `.. include::` but GitHub doesn't understand it) -Watch releases -`on GitHub `__ +`Watch `__ releases +`on GitHub `__ to be notified when new versions of bidict are released. @@ -196,14 +196,13 @@ Bidict is the product of thousands of hours of my unpaid work over the ~15 years that I've been the sole maintainer. If bidict has helped you or your company accomplish your work, -especially work that you or your company were paid for, -please `sponsor my work through GitHub `__, -and ask others you know who got value from my work to do the same. +please `sponsor my work through GitHub `__ +and/or ask your company to do the same. Choose a tier and GitHub handles everything else. -Sponsorship just goes on the same bill that GitHub -already charges you or your company for automatically, -so after the one-time signup, there's nothing extra to do. +Your GitHub sponsorship will automatically go +on the same bill you already have set up with GitHub, +so after the one-click signup, there's nothing else to do. See the following for rationale and examples of companies supporting the open source projects they depend on diff --git a/docs/learning-from-bidict.rst b/docs/learning-from-bidict.rst index 82dd685..76d2ca6 100644 --- a/docs/learning-from-bidict.rst +++ b/docs/learning-from-bidict.rst @@ -1,45 +1,35 @@ Learning from ``bidict`` ------------------------ -Below is an outline of some of the more fascinating -and lesser-known Python corners I got to explore further -thanks to working on :mod:`bidict`. +Working on :mod:`bidict` has taken me to +some of the most interesting and unexpected places +I've ever been to in many years of programming. +(When I started :mod:`bidict` almost 15 years ago, +I didn't know what higher-kinded types even were, +let alone that I'd one day +`explain to Guido +`__ +how they're useful for bidirectional mapping types.) -If you would like to learn more about any of the topics below, -you may find `reading bidict's code -`__ -particularly interesting. +The problem space that :mod:`bidict` inhabits +is abundant with beautiful symmetries, +delightful surprises, and rich opportunities +to come up with elegant solutions. -I've sought to optimize the code not just for correctness and performance, -but also to make for a clear and enjoyable read, -illuminating anything that could otherwise be obscure or subtle. +You can check out :mod:`bidict`'s source +to see for yourself. +I've sought to optimize the code +not just for correctness and performance, +but also for clarity, maintainability, +and to make for an enjoyable read. -I hope it brings you some of the +See below for more, and +`let me know `__ +what you think. +I hope reading :mod:`bidict`'s code +gives you a taste of some of the immense `joy `__ -it's brought me. 😊 - - -Python syntax hacks -=================== - -:mod:`bidict` used to support -(ab)using a specialized form of Python's :ref:`slice ` syntax -for getting and setting keys by value: - -.. use `code-block` rather than `doctest` for this - since slice syntax is no longer supported: - -.. code-block:: python - - >>> element_by_symbol = bidict(H='hydrogen') - >>> element_by_symbol['H'] # [normal] syntax for the forward mapping - 'hydrogen' - >>> element_by_symbol[:'hydrogen'] # [:slice] syntax for the inverse (no longer supported) - 'H' - -See `this code `__ -for how this was implemented, -and `#19 `__ for why this was dropped. +that :mod:`bidict` has given me. Code structure @@ -55,7 +45,7 @@ as appropriate. Factoring the code to maximize reuse, modularity, and adherence to `SOLID `__ design principles -(while not missing any chances for special-case optimizations) +(while not missing any chances for specialized optimizations) has been one of the most fun parts of working on bidict. To see how this is done, check out the code starting with @@ -85,11 +75,8 @@ and you miss all the value that comes from ongoing, direct practical application Bidict shows how fundamental data structures can be implemented in Python for important real-world usage, with practical concerns at top of mind. -Come to catch sight of a real, live, industrial-strength linked list in the wild. -Stay for the rare, exotic bidirectional mapping breeds you'll rarely see at home. -[#fn-data-struct]_ -.. [#fn-data-struct] To give you a taste: +.. admonition:: To give you a taste... A regular :class:`~bidict.bidict` encapsulates two regular dicts, @@ -112,14 +99,34 @@ Stay for the rare, exotic bidirectional mapping breeds you'll rarely see at home And since :class:`~bidict.OrderedBidictBase` needs to not only look up nodes by key/value, but also key/value by node, - internally it uses an (unordered) :class:`~bidict.bidict` for this. + it uses an (unordered) :class:`~bidict.bidict` for this internally. Bidicts all the way down! -Check out `_orderedbase.py `__ -to see this in action. + +Python syntax hacks +=================== + +:mod:`bidict` used to support +(ab)using a specialized form of Python's :ref:`slice ` syntax +for getting and setting keys by value: + +.. use `code-block` rather than `doctest` for this + since slice syntax is no longer supported: + +.. code-block:: python + + >>> element_by_symbol = bidict(H='hydrogen') + >>> element_by_symbol['H'] # [normal] syntax for the forward mapping + 'hydrogen' + >>> element_by_symbol[:'hydrogen'] # [:slice] syntax for the inverse (no longer supported) + 'H' + +See `this code `__ +for how this was implemented, +and `#19 `__ for why this was dropped. -Property-based testing is revolutionary +Property-based testing is indispensable ======================================= When your automated tests run,