Improve docstrings and autocomplete

ariebovenberg · Oct 31, 2024 · f44d6aa · f44d6aa
1 parent 978affa
commit f44d6aa
Show file tree

Hide file tree

Showing 23 changed files with 943 additions and 286 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -7,6 +7,7 @@
 - [ ] Build runs successfully
 - [ ] Type stubs updated
 - [ ] Docs updated
+- [ ] If docstrings were affected, check if they appear correctly in the docs as well as autocomplete
 
 # Release checklist (maintainers only)
 

diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
@@ -19,7 +19,7 @@ jobs:
           "3.10",
           "3.11",
           "3.12",
-          "3.13-dev",
+          "3.13",
         ]
     steps:
       - uses: actions/checkout@v4
@@ -62,14 +62,14 @@ jobs:
       - uses: actions/setup-python@v5
         if: ${{ !(matrix.os == 'windows-latest') }}
         with:
-          python-version: '3.12'
+          python-version: '3.13'
 
       # ensure 32-bit target is tested
       # FUTURE: Add a linux 32-bit target
       - uses: actions/setup-python@v5
         if: ${{ matrix.os == 'windows-latest' }}
         with:
-          python-version: '3.12'
+          python-version: '3.13'
           architecture: x86
 
 
@@ -91,7 +91,7 @@ jobs:
           "3.10",
           "3.11",
           "3.12",
-          "3.13-dev",
+          "3.13",
           # # NOTE: pypy/pytest fails sometimes (https://github.com/pypy/pypy/issues/3959)
           "pypy3.9",
           "pypy3.10"

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -8,7 +8,7 @@ sphinx:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
     # rust shouldn't be needed as we disable building the extension
     # in the readthedocs configuration
 

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,18 @@
 🚀 Changelog
 ============
 
+0.6.10 (2024-10-30)
+-------------------
+
+**Improved**
+
+- Improve method documentation and autocomplete support (#172, #173, #176)
+
+**Fixed**
+
+- Remove lingering undocumented ``offset`` on ``Instant``
+- Fix incorrect ``LocalDateTime.difference`` return type annotation
+
 0.6.9 (2024-09-12)
 ------------------
 

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/docs/api.rst b/docs/api.rst
@@ -41,16 +41,20 @@ Concrete classes
 
 .. autoclass:: whenever.Instant
    :members:
+     from_utc,
      format_rfc3339,
      parse_rfc3339,
      format_rfc2822,
      parse_rfc2822,
      add,
-     subtract
+     subtract,
    :special-members: __add__, __sub__
    :member-order: bysource
    :show-inheritance:
 
+   .. autoattribute:: MIN
+   .. autoattribute:: MAX
+
 .. autoclass:: whenever.LocalDateTime
    :members:
      assume_utc,
@@ -63,6 +67,9 @@ Concrete classes
    :member-order: bysource
    :show-inheritance:
 
+   .. autoattribute:: MIN
+   .. autoattribute:: MAX
+
 .. autoclass:: whenever.OffsetDateTime
    :members:
      format_rfc3339,

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -179,3 +179,17 @@ Additional advantages of ``pyo3_ffi`` are:
 - Its API is more stable than PyO3's, which is still evolving.
 - It allows support for per-interpreter GIL, and free-threaded Python,
   which are not yet supported by PyO3.
+
+Why can't I subclass Whenever classes?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whenever classes aren't meant to be subclassed.
+There's no plan to change this due to the following reasons:
+
+1. The benefits of subclassing are limited.
+   If you want to extend the classes, composition is a better way to do it.
+   Alternatively, you can use Python's dynamic features to create
+   something that "quacks" like a subclass.
+2. For a class to support subclassing properly, a lot of extra work is needed.
+   It also adds many subtle ways to misuse the API, that are hard to control.
+3. Enabling subclassing would undo some performance optimizations.
diff --git a/docs/overview.rst b/docs/overview.rst
@@ -361,8 +361,8 @@ Ambiguity in timezones
 
 In timezones, local clocks are often moved backwards and forwards
 due to Daylight Saving Time (DST) or political decisions.
-This creates two types of situations for the :class:`~whenever.ZonedDateTime`
-and :class:`~whenever.SystemDateTime` types:
+This makes it complicated to map a local datetime to a point on the timeline.
+Two common situations arise:
 
 - When the clock moves backwards, there is a period of time that repeats.
   For example, Sunday October 29th 2023 2:30am occurred twice in Paris.
@@ -374,7 +374,7 @@ and :class:`~whenever.SystemDateTime` types:
   Common approaches are to extrapolate the time forward or backwards
   to 1:30am or 3:30am.
 
-  .. important::
+  .. note::
 
      You may wonder why skipped time is "extrapolated" like this,
      and not truncated. Why turn 2:30am into 3:30am and not cut

diff --git a/pyproject.toml b/pyproject.toml
@@ -3,9 +3,12 @@ name = "whenever"
 authors = [
     {name = "Arie Bovenberg", email = "a.c.bovenberg@gmail.com"},
 ]
+maintainers = [
+    {name = "Arie Bovenberg", email = "a.c.bovenberg@gmail.com"},
+]
 readme = "README.md"
-version = "0.6.9"
-description = "Modern datetime library for Python, written in Rust"
+version = "0.6.10"
+description = "Modern datetime library for Python"
 requires-python = ">=3.9"
 classifiers = [
     "Development Status :: 4 - Beta",