Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise type annotations slightly #1860

Merged
merged 3 commits into from
Mar 5, 2024

Conversation

EliahKagan
Copy link
Contributor

This pull request is mostly a small revision to type hints to improve a couple things I had noticed when working on #1850 but omitted from there to avoid bloating its scope:

  • 9f226fc: __slots__ is typically unannotated, but in once place it had an unnecessary annotation.
  • 5d7e55b: Although mypy treats it the same when there are parameter annotations, __init__ is best annotated with an explicit return type of None, per PEP 484.

In addition, I noticed some slight under-indentation in a few docstrings I had worked on #1850, and fixed that here in e984bfe. (The type annotation tweaks are sufficiently minor that there is an argument to be made that this is really the most significant individual change in this pull request.)

There is some more information in the commit messages.

The correct type is inferred, and no other __slots__ variable in
the codebase has an annotation.
A few docstrings had parts that were meant to be indented the
usual four spaces beyond the surrounding indentation, but were
indented only three spaces beyond it instead.
Although sometimes found unintuitive, the reutrn type of a class's
__init__ method is best annotated as None, as in other functions
that return implicitly or by operand-less return statements.

Note that this is only a minor improvement, effectively just a
style fix, because mypy treats __init__ specially and, *when at
least one parameter is annotated*, its return type is implicitly
None rather than implicitly Any like other functions. All the
__init__ methods modified here did already have one or more
annotated parameters.

However, having __init__ methods without the return type makes it
easier to introduce a bug where an __init__ method with no
parameters besides self -- which itself should almost always be
unannotated and is properly inferred -- is written and the return
annotation needed to get mypy to regard it as statically typed,
so it checks it at all, is omitted. (It is also inelegant when
one considers the meaning of __init__ and the distinction between
it and __new__.)

This commit does not add any return type annotations to functions
in the test suite, since the test suite doesn't currently use
static typing.

Further reading:

- https://peps.python.org/pep-0484/#the-meaning-of-annotations
- python/mypy#604
- gitpython-developers#1755 (comment)
@EliahKagan EliahKagan marked this pull request as ready for review March 5, 2024 01:43
Copy link
Member

@Byron Byron left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot!

I really am impressed by the diligence needed to come up with all of these fixes (particularly in a codebase which might not be the most pleasant to read given its age and moved history).

@Byron Byron merged commit 12c139c into gitpython-developers:main Mar 5, 2024
26 checks passed
@EliahKagan EliahKagan deleted the typing-tweaks branch March 5, 2024 15:04
renovate bot referenced this pull request in allenporter/flux-local Mar 31, 2024
[![Mend
Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [GitPython](https://togithub.com/gitpython-developers/GitPython) |
`==3.1.42` -> `==3.1.43` |
[![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|

---

### Release Notes

<details>
<summary>gitpython-developers/GitPython (GitPython)</summary>

###
[`v3.1.43`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.43)

[Compare
Source](https://togithub.com/gitpython-developers/GitPython/compare/3.1.42...3.1.43)

#### Particularly Important Changes

These are likely to affect you, please do take a careful look.

- Issue and test deprecation warnings by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1886](https://togithub.com/gitpython-developers/GitPython/pull/1886)
- Fix version_info cache invalidation, typing, parsing, and
serialization by [@&#8203;EliahKagan](https://togithub.com/EliahKagan)
in
[https://github.com/gitpython-developers/GitPython/pull/1838](https://togithub.com/gitpython-developers/GitPython/pull/1838)
- Document manual refresh path treatment by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1839](https://togithub.com/gitpython-developers/GitPython/pull/1839)
- Improve static typing and docstrings related to git object types by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1859](https://togithub.com/gitpython-developers/GitPython/pull/1859)

#### Other Changes

- Test in Docker with Alpine Linux on CI by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1826](https://togithub.com/gitpython-developers/GitPython/pull/1826)
- Build online docs (RTD) with -W and dependencies by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1843](https://togithub.com/gitpython-developers/GitPython/pull/1843)
- Suggest full-path refresh() in failure message by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1844](https://togithub.com/gitpython-developers/GitPython/pull/1844)
- `repo.blame` and `repo.blame_incremental` now accept `None` as the
`rev` parameter. by [@&#8203;Gaubbe](https://togithub.com/Gaubbe) in
[https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846)
- Make sure diff always uses the default diff driver when
`create_patch=True` by
[@&#8203;can-taslicukur](https://togithub.com/can-taslicukur) in
[https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832)
- Revise docstrings, comments, and a few messages by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1850](https://togithub.com/gitpython-developers/GitPython/pull/1850)
- Expand what is included in the API Reference by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1855](https://togithub.com/gitpython-developers/GitPython/pull/1855)
- Restore building of documentation downloads by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1856](https://togithub.com/gitpython-developers/GitPython/pull/1856)
- Revise type annotations slightly by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1860](https://togithub.com/gitpython-developers/GitPython/pull/1860)
- Updating regex pattern to handle unicode whitespaces. by
[@&#8203;jcole-crowdstrike](https://togithub.com/jcole-crowdstrike) in
[https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853)
- Use upgraded pip in test fixture virtual environment by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1864](https://togithub.com/gitpython-developers/GitPython/pull/1864)
- lint: replace `flake8` with `ruff` check by
[@&#8203;Borda](https://togithub.com/Borda) in
[https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862)
- lint: switch Black with `ruff-format` by
[@&#8203;Borda](https://togithub.com/Borda) in
[https://github.com/gitpython-developers/GitPython/pull/1865](https://togithub.com/gitpython-developers/GitPython/pull/1865)
- Update readme and tox.ini for recent tooling changes by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1868](https://togithub.com/gitpython-developers/GitPython/pull/1868)
- Split tox lint env into three envs, all safe by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1870](https://togithub.com/gitpython-developers/GitPython/pull/1870)
- Slightly broaden Ruff, and update and clarify tool configuration by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1871](https://togithub.com/gitpython-developers/GitPython/pull/1871)
- Add a "doc" extra for documentation build dependencies by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1872](https://togithub.com/gitpython-developers/GitPython/pull/1872)
- Describe `Submodule.__init__` parent_commit parameter by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1877](https://togithub.com/gitpython-developers/GitPython/pull/1877)
- Include TagObject in git.types.Tree_ish by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1878](https://togithub.com/gitpython-developers/GitPython/pull/1878)
- Improve Sphinx role usage, including linking Git manpages by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1879](https://togithub.com/gitpython-developers/GitPython/pull/1879)
- Replace all wildcard imports with explicit imports by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1880](https://togithub.com/gitpython-developers/GitPython/pull/1880)
- Clarify how tag objects are usually tree-ish and commit-ish by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1881](https://togithub.com/gitpython-developers/GitPython/pull/1881)

#### New Contributors

- [@&#8203;Gaubbe](https://togithub.com/Gaubbe) made their first
contribution in
[https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846)
- [@&#8203;can-taslicukur](https://togithub.com/can-taslicukur) made
their first contribution in
[https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832)
- [@&#8203;jcole-crowdstrike](https://togithub.com/jcole-crowdstrike)
made their first contribution in
[https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853)
- [@&#8203;Borda](https://togithub.com/Borda) made their first
contribution in
[https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862)

**Full Changelog**:
gitpython-developers/GitPython@3.1.42...3.1.43

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined),
Automerge - At any time (no schedule defined).

🚦 **Automerge**: Enabled.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR has been generated by [Mend
Renovate](https://www.mend.io/free-developer-tools/renovate/). View
repository job log
[here](https://developer.mend.io/github/allenporter/flux-local).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
lettuce-bot bot referenced this pull request in lettuce-financial/github-bot-signed-commit Apr 1, 2024
[![Mend
Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [GitPython](https://togithub.com/gitpython-developers/GitPython) |
`==3.1.42` -> `==3.1.43` |
[![age](https://developer.mend.io/api/mc/badges/age/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![adoption](https://developer.mend.io/api/mc/badges/adoption/pypi/GitPython/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![passing](https://developer.mend.io/api/mc/badges/compatibility/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|
[![confidence](https://developer.mend.io/api/mc/badges/confidence/pypi/GitPython/3.1.42/3.1.43?slim=true)](https://docs.renovatebot.com/merge-confidence/)
|

---

### Release Notes

<details>
<summary>gitpython-developers/GitPython (GitPython)</summary>

###
[`v3.1.43`](https://togithub.com/gitpython-developers/GitPython/releases/tag/3.1.43)

[Compare
Source](https://togithub.com/gitpython-developers/GitPython/compare/3.1.42...3.1.43)

#### Particularly Important Changes

These are likely to affect you, please do take a careful look.

- Issue and test deprecation warnings by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1886](https://togithub.com/gitpython-developers/GitPython/pull/1886)
- Fix version_info cache invalidation, typing, parsing, and
serialization by [@&#8203;EliahKagan](https://togithub.com/EliahKagan)
in
[https://github.com/gitpython-developers/GitPython/pull/1838](https://togithub.com/gitpython-developers/GitPython/pull/1838)
- Document manual refresh path treatment by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1839](https://togithub.com/gitpython-developers/GitPython/pull/1839)
- Improve static typing and docstrings related to git object types by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1859](https://togithub.com/gitpython-developers/GitPython/pull/1859)

#### Other Changes

- Test in Docker with Alpine Linux on CI by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1826](https://togithub.com/gitpython-developers/GitPython/pull/1826)
- Build online docs (RTD) with -W and dependencies by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1843](https://togithub.com/gitpython-developers/GitPython/pull/1843)
- Suggest full-path refresh() in failure message by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1844](https://togithub.com/gitpython-developers/GitPython/pull/1844)
- `repo.blame` and `repo.blame_incremental` now accept `None` as the
`rev` parameter. by [@&#8203;Gaubbe](https://togithub.com/Gaubbe) in
[https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846)
- Make sure diff always uses the default diff driver when
`create_patch=True` by
[@&#8203;can-taslicukur](https://togithub.com/can-taslicukur) in
[https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832)
- Revise docstrings, comments, and a few messages by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1850](https://togithub.com/gitpython-developers/GitPython/pull/1850)
- Expand what is included in the API Reference by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1855](https://togithub.com/gitpython-developers/GitPython/pull/1855)
- Restore building of documentation downloads by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1856](https://togithub.com/gitpython-developers/GitPython/pull/1856)
- Revise type annotations slightly by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1860](https://togithub.com/gitpython-developers/GitPython/pull/1860)
- Updating regex pattern to handle unicode whitespaces. by
[@&#8203;jcole-crowdstrike](https://togithub.com/jcole-crowdstrike) in
[https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853)
- Use upgraded pip in test fixture virtual environment by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1864](https://togithub.com/gitpython-developers/GitPython/pull/1864)
- lint: replace `flake8` with `ruff` check by
[@&#8203;Borda](https://togithub.com/Borda) in
[https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862)
- lint: switch Black with `ruff-format` by
[@&#8203;Borda](https://togithub.com/Borda) in
[https://github.com/gitpython-developers/GitPython/pull/1865](https://togithub.com/gitpython-developers/GitPython/pull/1865)
- Update readme and tox.ini for recent tooling changes by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1868](https://togithub.com/gitpython-developers/GitPython/pull/1868)
- Split tox lint env into three envs, all safe by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1870](https://togithub.com/gitpython-developers/GitPython/pull/1870)
- Slightly broaden Ruff, and update and clarify tool configuration by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1871](https://togithub.com/gitpython-developers/GitPython/pull/1871)
- Add a "doc" extra for documentation build dependencies by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1872](https://togithub.com/gitpython-developers/GitPython/pull/1872)
- Describe `Submodule.__init__` parent_commit parameter by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1877](https://togithub.com/gitpython-developers/GitPython/pull/1877)
- Include TagObject in git.types.Tree_ish by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1878](https://togithub.com/gitpython-developers/GitPython/pull/1878)
- Improve Sphinx role usage, including linking Git manpages by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1879](https://togithub.com/gitpython-developers/GitPython/pull/1879)
- Replace all wildcard imports with explicit imports by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1880](https://togithub.com/gitpython-developers/GitPython/pull/1880)
- Clarify how tag objects are usually tree-ish and commit-ish by
[@&#8203;EliahKagan](https://togithub.com/EliahKagan) in
[https://github.com/gitpython-developers/GitPython/pull/1881](https://togithub.com/gitpython-developers/GitPython/pull/1881)

#### New Contributors

- [@&#8203;Gaubbe](https://togithub.com/Gaubbe) made their first
contribution in
[https://github.com/gitpython-developers/GitPython/pull/1846](https://togithub.com/gitpython-developers/GitPython/pull/1846)
- [@&#8203;can-taslicukur](https://togithub.com/can-taslicukur) made
their first contribution in
[https://github.com/gitpython-developers/GitPython/pull/1832](https://togithub.com/gitpython-developers/GitPython/pull/1832)
- [@&#8203;jcole-crowdstrike](https://togithub.com/jcole-crowdstrike)
made their first contribution in
[https://github.com/gitpython-developers/GitPython/pull/1853](https://togithub.com/gitpython-developers/GitPython/pull/1853)
- [@&#8203;Borda](https://togithub.com/Borda) made their first
contribution in
[https://github.com/gitpython-developers/GitPython/pull/1862](https://togithub.com/gitpython-developers/GitPython/pull/1862)

**Full Changelog**:
gitpython-developers/GitPython@3.1.42...3.1.43

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined),
Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you
are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about these
updates again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR has been generated by [Mend
Renovate](https://www.mend.io/free-developer-tools/renovate/). View
repository job log
[here](https://developer.mend.io/github/lettuce-financial/github-bot-signed-commit).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4yNjkuMiIsInVwZGF0ZWRJblZlciI6IjM3LjI2OS4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants