Update to Python 3.10 and enhance type annotations

[hunterhogan]

Upgrade the codebase to be compatible with Python 3.10 and introduce type aliases and overloads for improved type hinting in methods.

[bastibe]

Stop spamming.

[hunterhogan]

😞

I sincerely don't know what I did that is spamming. I am following the advice of other people about how to better organize a pull request and about typing. I want to know what mistake I made, so I can improve. I threw out the work I had previously done and started fresh because I wanted to make sure I did everything correctly. That's why it took me three hours of work to make this.

mgrinshpon/toolz-stubs#50 (comment)
fonttools/ufoLib2#423 (comment)
python/typeshed#15341 (review)
python/typeshed#15341 (comment)

I've been working on typing for soundfile for well over a year: it is in the initial commit of this stupid repo I made for stubs. I didn't about typeshed or how to ... hell, I basically didn't know how to find anything, do anything, or work with other people on anything. resampy was also in the initial commit to my stub repo. It's in typeshed now, despite the mountain of mistakes I made.

I'm sorry I spammed you, and I will adjust my actions if you tell me how to improve.

[bastibe]

My apologies. Your messages read too much like AI slop, so I assumed the worst. But your response proves that was an error on my part, for which I am very sorry.

For what it's worth, I would prefer to iterate on a single pull request instead of starting new ones. Regardless, I've reopened the pull request. The tests still fail, though.

[hunterhogan]

I would prefer to iterate on a single pull request instead of starting new ones.

Do you happen to know the right git syntax to "wipe the slate clean"? I tried to do that in a PR in one of the repos above, and a side effect was to close the original PR.

I will decipher the test failures.

for which I am very sorry

thank you.

[bastibe]

Each pull request is simply a branch on your github. If you force-push a new state to that branch, it will update the pull request accordingly. You can reset to base commit of the branch, which will reset it entirely.

[bastibe]

(note that two new pull requests have been merged, which will require a rebase)

[hunterhogan]

I'm 95% sure the newly merged pull requests are in my pull request.

On my computer, now the tests pass with 16 warnings. If there is a way for me to initiate the checks on GitHub, I don't know how to do it.

Tell me what I should do next.

[bastibe]

If there is a way for me to initiate the checks on GitHub, I don't know how to do it.

Github tests of pull requests are triggered manually by the maintainers.

[bastibe]

Please rebase onto master, where I've removed support for Python <= 3.9. This should make the tests pass.

[bastibe]

I am very conflicted about the overloads. It was probably a bad design decision on my part to have these complex functions with huge argument lists. But now that we have these functions, the overloads become very hard to read, you have to compare each argument one by one to understand what they are doing.

As such, I'd ask you to amend this pull request and leave out the overloads for the time being. The rest of the changes are great, and I'd like to incorporate them into the next release. If you feel strongly about the overloads, we can then continue this discussion in a new pull request - I'm not ruling out their use, and understand your points, but I'm not currently sure what the right course of action is.

Also, please rebase, as there are still some merge conflicts.

Thank you for your patience with this issue.

[hunterhogan]

rebase

I ran rebase again due to the new merged commit. If I'm doing it wrong, please tell me.

Details

Microsoft Windows [Version 10.0.26200.8246]
(c) Microsoft Corporation. All rights reserved.
C:\clones\python-soundfile>git branch
  master
* v310

C:\clones\python-soundfile>git remote
origin
upstream

C:\clones\python-soundfile>git rebase upstream/main
fatal: invalid upstream 'upstream/main'

C:\clones\python-soundfile>git rebase 7bfd207f430f17375a870a082f501f88ef11b79a
Auto-merging soundfile.py
CONFLICT (content): Merge conflict in soundfile.py
error: could not apply 0e9efcd... update to Python >=3.10 syntax
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Could not apply 0e9efcd... # update to Python >=3.10 syntax

C:\clones\python-soundfile>git rebase --continue
hint: Waiting for your editor to close the file...
[detached HEAD 6f15e3c] update to Python >=3.10 syntax
 2 files changed, 97 insertions(+), 101 deletions(-)
Successfully rebased and updated refs/heads/v310.

C:\clones\python-soundfile>git -v
git version 2.52.0.windows.1

C:\clones\python-soundfile>git push --force-with-lease
Enumerating objects: 22, done.
Counting objects: 100% (22/22), done.
Delta compression using up to 16 threads
Compressing objects: 100% (19/19), done.
Writing objects: 100% (19/19), 4.08 KiB | 596.00 KiB/s, done.
Total 19 (delta 13), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (13/13), completed with 3 local objects.
To https://github.com/hunterhogan/python-soundfile.git
 + 00a5f77...0f9646c v310 -> v310 (forced update)

overload

The overload definitions are hard to read, and if we were to make the overload definitions more comprehensive, it would be even more difficult to read.

overload `read`

@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, *, dtype: Literal['int16'],
        always_2d: Literal[True], fill_value: float | None = None, out: numpy.ndarray[tuple[int, int], numpy.dtype[numpy.int16]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, int], numpy.dtype[numpy.int16]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, *, dtype: Literal['int32'],
        always_2d: Literal[True], fill_value: float | None = None, out: numpy.ndarray[tuple[int, int], numpy.dtype[numpy.int32]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, int], numpy.dtype[numpy.int32]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, *, dtype: Literal['float32'],
        always_2d: Literal[True], fill_value: float | None = None, out: numpy.ndarray[tuple[int, int], numpy.dtype[numpy.float32]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, int], numpy.dtype[numpy.float32]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, dtype: Literal['float64'] = 'float64',
        *, always_2d: Literal[True], fill_value: float | None = None, out: numpy.ndarray[tuple[int, int], numpy.dtype[numpy.float64]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, int], numpy.dtype[numpy.float64]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, *, dtype: Literal['int16'],
        always_2d: bool = False, fill_value: float | None = None, out: numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.int16]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.int16]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, *, dtype: Literal['int32'],
        always_2d: bool = False, fill_value: float | None = None, out: numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.int32]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.int32]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, *, dtype: Literal['float32'],
        always_2d: bool = False, fill_value: float | None = None, out: numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.float32]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.float32]], int]:...
@overload
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, dtype: Literal['float64'] = 'float64',
        always_2d: bool = False, fill_value: float | None = None, out: numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.float64]] | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[numpy.ndarray[tuple[int, ...], numpy.dtype[numpy.float64]], int]:...
def read(file: FileDescriptorOrPath, frames: int = -1, start: int = 0, stop: int | None = None, dtype: dtype_str = 'float64',
        always_2d: bool = False, fill_value: float | None = None, out: AudioData | AudioData_2d | None = None,
        samplerate: int | None = None, channels: int | None = None, format: str | None = None, subtype: str | None = None,
        endian: str | None = None, closefd: bool = True) -> tuple[AudioData | AudioData_2d, int]:

I spent 20 minutes trying to make it work with TypeDict and typing.Unpack. It might be possible, but I doubt it. Without the overloads narrowing the type to a 2-axis ndarray, I will use typing.cast in my code, such as in my primary audio processing packaging.

But 32 long overload definitions (8 definitions x 4 functions) would be a headache. I don't have a solution, but I am happy to help.