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 docstrings, comments, and a few messages #1850

Merged
merged 61 commits into from
Feb 29, 2024

Conversation

EliahKagan
Copy link
Contributor

@EliahKagan EliahKagan commented Feb 29, 2024

Fixes #1845
Fixes #1847
Fixes #1849

This pull request is a sequel to #1725. Most changes are to docstrings. Notable changes:

  • Applies revisions to recently discussed docstrings, including improving on the wording I added in #1839 and #1844, and making the changes discussed in #1845, #1847, and #1849.

  • Revises docstrings throughout the git package along the lines of #1725, covering areas I outright missed, or where a further improvement or kind of improvement became apparent since then (either over time or due to recent rereading), or arose since then, or where I am better able to check the effect on rendered documentation, or where I am more comfortable making the change due to an improved understanding of the code being documented (or commented).

  • Goes beyond that in making some new kinds of formatting changes to improve consistency that I had not included there, some that I had intentionally omitted at that time due to less experience with the project, and others that I only realized the benefit of more recently. See 1cd73ba for a list of many of these (that commit only covers a handful of files, but other commits made those kinds of changes to more files).

  • Makes bigger formatting changes for readability, when reading the docstrings in the code, than in #1725. These also improve consistency, but their value is even more for readability:

    • Putting blank lines between all sections of all docstrings (in the git package).
    • Giving role-labeled sections a newline after the leading :role:/:role args...:.
    • Wrapping nearly all docstrings and most comments to 88 columns.
    • Formatting all occurrences of a class name that is intended to refer to that class with :class:, except in rare cases where there are disadvantages of doing so (e.g., the first line of a class docstring must not link to the class itself, or some readers may infer that it is a reference to another same-named class).

    The addition of blank lines and line breaks in docstrings is unneeded in some projects and often not done, but seems very useful to me in GitPython, where many docstrings have long sections (rather than, for example, sections like :param foo: the predecessor of *bar* that fit on a single line).

    The advantages of linking class names almost everywhere are that it:

    • makes clear that the class is what is being referred to (this is not always obvious, especially in GitPython due to subtleties of Git itself and, to a lesser extent, of GitPython's design), and
    • makes it easy to use the reference to get to information on something one is reading about.
  • Codes all Sphinx references to classes, methods/functions, and attributes as either:

    • Relative to the current module, top-level function, class, or method.
    • Absolute.

    One effect is that there are far more absolute Sphinx references than before. This does not cause rendered Sphinx documentation to become more longwinded, because the references are written in such a way that the rendered text still omits the qualifiers (except on hover). This is mostly achieved by writing things like :class:`~a.b.c.D`, which is short for :class:`D <a.b.c.D>`, though occasionally I used the latter form: when the last two parts should be shown (:meth:`D.e <a.b.c.D.e>`), and in base classes' bulleted lists of documented subclasses where having the displayed name first lined it up better so as also to be readable unrendered in the code.

    There are important tradeoffs to consider here. It is not at all obvious that this is the correct choice. When I began to do it, it was not even with the intention that this would stay that way; I planned to make them all absolute, and thus obviously correct, and then thorough a combination of experimentation and consulting documentation about Sphinx and autodoc, make them relative again where correct, sufficiently reliable, and clear on reading. However, I noticed two things as I made many references absolute:

    • Clarity seems to be greatly improved by distinguishing things in the current module from other things that only happen to be in scope due to having been imported into it.
    • The entire module structure and logical organization of GitPython became clear when reading the docstrings in the code.

    Taken together with the advantage of avoiding confusing scoping issues (example: does Sphinx autodoc resolve references that are brought in scope due to TYPE_CHECKING imports?), I think it may actually be justified to leave it this way.

    But it may not be justified, and this is an area that I want to call attention to for review. The rendered documentation is not more longwinded as a result of doing this, but the unrendered documentation, i.e., the docstrings as written in the code, certainly are more longwinded in many cases. This potentially worsens readability.

    Overall readability seems improved to me, but there are two caveats to this:

    • I've been looking at the docstrings in this state for a while as I work on them, so what is readable to me may differ from what is readable in general.
    • I worry I may be giving with one hand and taking away with another: it may be that these absolute references are worsening readability, and by enough to make them unjustified in their current form, but that it is hard to know that this is so, because adding consistent spacing between sections (as described above) improves readability enough that it more than counterbalances it.
  • Adds a small number of missing docstrings, and a moderately small number of previously omitted sections in docstrings. But this was not the focus.

  • Slightly adjusts the wording of a few messages that GitPython outputs to signify errors. This is in cd8a312 (see #1844), afd943a, and c67b2e2. These are the only behavioral changes. Besides adjusting code formatting slightly in small handful of cases, these are also the only code changes outside docstrings and comments.

There are some kinds of changes that are notably omitted from this pull request. These include:

  • As in #1725, to limit the scope, I have not undertaken to update outdated documentation in doc/source/ here, and nor applied any revisions to the project readme.
  • Unlike #1725, I've kept the scope here a bit narrower: There are no modifications to type annotations, aspects of code style other than formatting (and very few of those), or changes of any kind in doc/source/ (including no changes to its conf.py).
  • This conspicuously excludes the git.types module from being revised. The reason is that, while docstrings should be revised there, it looks like it will make the most sense to do that together with changes to imports, which are beyond the intended scope of this pull request.
  • This revises docstrings and (to a lesser extent) comments both in git/ and test/, but the changes in test/ are much less substantial, since there are fewer docstrings there, and tradeoffs there are different due to no part of the docstrings in the test suite being rendered by Sphinx. (This distinction is expanded on in 5cf5b60.)

This further improves the text previously introduced in gitpython-developers#1829 and
improved in gitpython-developers#1844.
The fragment of the refresh failure message (which is often written
to a terminal) about the effect of setting GIT_PYTHON_REFRESH to
control refesh failure reporting had previously been formatted with
a maximum line length of 79 columns--in the message itself, not the
code for the message--so that it would fit in a traditional 80
column wide terminal. This remains one of the popular widths to set
for terminal windows in a GUI, so it seems worthwhile to preserve.

In 3a6e3ef (gitpython-developers#1815), I had inadvertently made the line one character
too long for that; at 80 columns, it would cause the newline to be
written at the start of the next line, creating an unsightly extra
line break.

This is pretty minor, but what seems to me like an equally good
alternative wording avoids it, so this commit shortens the wording.
The git.db.partial_to_complete_sha_hex docstring refers to
"AmbiguousObjects", suggesting the existence of an AmbiguousObject
type (or an AmbiguousObjects type).

Since there appears to be no such type in GitPython (or in gitdb),
this seems to have been written in reference to the condition
expressed by the AmbiguousObjectName exception, which the note
says is not currently able to be raised (such that BadObject is
raised instead) in situations where it would apply.

Since the connection to that exeception is already clear from
context, this commit changes the wording to "ambiguous objects" to
avoid being misread as a reference to a Python class of ambiguous
objects.
This converts it from a specially formatted comment to a docstring
(gitpython-developers#1734), rewords for clarity, and removes the mention of unicode,
which appears to have been referring to the data type.

(GitPython no longer supports Python 2, and unicode is not a
separate type from str in Python 3, where instead str and bytes
are different types.)
For slightly easier reading.
- Replace the goo.gl web shortlink with a Sphinx reference that
  displays and also (in built documentation) becomes a hyperlink to
  the documentation on the method being referred to.

- Refer to a related class (which is in another module) as being
  in the module where it is defined, rather than in the top-level
  git module (where it also can be accessed because it is imported
  there, which is reasonable to do, but less clear documentation).

- Tweak punctuation so the effect of passing None is a bit clearer.
Except for:

- git.cmd, where docstrings were revised in e08066c.

- git.types, where docstring changes may best be made together with
  changes to how imports are organized and documented, which seems
  not to be in the same scope as the changes in this commit.

This change, as well as those in e08066c, are largely along the
lines of gitpython-developers#1725, with most revisions here being to docstrings and a
few being to comments.

The major differences between the kinds of docstring changes here
and those ind gitpython-developers#1725 are that the changes here push somewhat harder
for consistency and apply some kinds of changes I was reluctant to
apply widely in gitpython-developers#1725:

- Wrap all docstrings and comments to 88 columns, except for parts
  that are decisively clearer when not wrapped. Note that semi-
  paragraph changes represented as single newlines are still kept
  where meaningful, which is one reason this is not always the same
  effect as automatic wrapping would produce.

- Avoid code formatting (double backticks) for headings that
  precede sections and code blocks. This was done enough that it
  seems to have been intentional, but it doesn't really have the
  right semantics, and the documentation is currently rendering in
  such a way (including on readthedocs.org) where removing that
  formatting seems clearly better.

- References (single backticks with a role prefix) and code spans
  (double backticks) everywhere applicable, even in the first lines
  of docstrings.

- Single-backticks around parameter names, with no role prefix.
  These were mostly either formatted that way or emphasized (with
  asterisks). This is one of the rare cases that I have used single
  backticks without a role prefix, which ordinarily should be
  avoided, but to get a role for references to a function's
  parameters within that function, a plugin would be needed. In the
  rare case that one function's docstring refers to another
  function's parameters by names those are double-backticked as
  code spans (and where applicable the name of the referred-to
  function is single-backticked with the :func: or :meth: role).

- All sections, such as :param blah:, :note:, and :return:, now
  have a newline before any text in them. This was already often
  but far from always done, and the style was overall inconsistent.
  Of consistent approaches that are clear and easy to write, this
  is the simplest. It also seems to substantially improve
  readability, when taken together with...

- Sections are always separated by a blank line, even if they are
  very short.

- Essentially unlimited use of `~a.b.c`, where applicable, to refer
  and link to the documentation for a.b.c while showing the text
  "a" and revealing "a.b.c" on hover. I had previously somewhat
  limited my use of this tilde notation in case readers of the
  source code itself (where it is not rendered) weren't familiar
  with it, but at the cost of less consistency in when an entity
  was referred to. There remain a couple places in git.util where
  I do not do this because the explicit form `a <a.b.c>`, which is
  equivalent, lined things up better and was thus easier to read.

Those are the major differences between the approach taken here
and in gitpython-developers#1725, but not necessarily most of the changes done here
(many of which are the same kinds of revisions as done there).

Note that this commit only modifies some git/*.py files, and there
are more git/**/*.py files that remain to be revised accordingly.
This makes it easier to read along with, and compare to, the
other overloads.
This presents it more symbolically, rather than in an example-like
style that could confuse. See discussion in gitpython-developers#1844.
So that it just describes the current situation, rather than
suggesting a future direction for IndexFile.

This is for gitpython-developers#1847.
For gitpython-developers#1847. This removes the note, and splits out some related
material from the docstring's top line into a second paragraph
for readability (since the first sentence of the top line was
complete, and described usage).
This changes "Full (relative) path" to "Complete relative path" in
the wording used to describe the branch_path initializer parameter
and property of the Submodule class. This is to prevent confusion,
since "full path" means something like "absolute path" (and is now
used as such in error messages introduced since these docstrings
were last edited).
Since it appears to refer to the write method, which it overrides,
rather that the nonpublic _write method (which is not overridden,
and whose direct calls are not affected).
The original problem where the backslash wasn't included in the
docstring at all was fixed in 7dd2095 (gitpython-developers#1725), but the backslash
still did not appear in rendered Sphinx documentation, because it
was also treated as a reStructuredText metacharacter.

Although that can be addressed by adding a further backslash to
escape it, the effect is ambiguous when the docstring is read in
the code. So this just encloses it in a double-backticked code
span instead, which is a somewhat clearer way to show it anyway.
But not within git.objects.submodule, which was done in 63c62ed.
The example code block included a Windows-style path string written
with doubled backslashes, but the docstring itself was not a raw
string literal, so these collapsed into single backslashes. This
makes the whole docstring an R-string, which is sufficient to solve
that problem (since the backslashes are in a code block, Sphinx
does not itself treat them as metacharacters).

In addition, this changes the Windows-style path to be an R-string
rather than using doubled backslashes. This is just to improve
clarity (and remind readers they can use an R-string for Windows
paths), and does not affect correctness.
It had said it returned a list of Commit objects, but it returns an
iterator of Commit objects.
This is a (very) minor improvement that uses the more common
convention of not padding parentheses on the inside with spaces in
prose, in an exception message.
And link to a specific tag (the most recent stable version tag) so
the the hyperlink won't break in the future (as long as GitHub URLs
keep working).
+ Add a missing :class: reference in _get_commit docstring.
- Single vs. double backtick error/inconsistency in one place
  (parameter names were in in doubled backticks, now single)

- Undo making "Iterator" in the phrase "Iterator yielding" a
  reference to collections.abc.Iterator, which is unnecessary and
  not done anywhere else.
@Byron
Copy link
Member

Byron commented Feb 29, 2024

Wow, what a massive amount of work!

That's over 300 queued CI jobs as well - I have never seen anything like it 😅. It's too bad that it's not possible to tell GitHub to build every commit in the PR, so one is instead forced to push each commit individually (which has side-effects).

@EliahKagan EliahKagan marked this pull request as ready for review February 29, 2024 09:12
@EliahKagan
Copy link
Contributor Author

That's over 300 queued CI jobs as well - I have never seen anything like it 😅.

Sorry--I should probably have checked with you first before pushing them that way, with this many commits!

@Byron
Copy link
Member

Byron commented Feb 29, 2024

No worries, I just wanted to comment on it because it's a first for me (at least in this scale), and it's great that GitHub can handle it :).

@EliahKagan
Copy link
Contributor Author

It looks like CodeQL complains starting in 29c63ac.

     @overload
-    def execute(self, command: Union[str, Sequence[Any]], *, as_process: Literal[True]) -> "AutoInterrupt":
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        *,
+        as_process: Literal[True],
+    ) -> "AutoInterrupt":
         ...

That change, which reformats one of the Git.execute overloads, produces new warnings about the preexisting situations where CodeQL does not see redacted_command, cmdstr (derived from redacted_command), and the expression safe_decode(stderr_value) as safe.

Those uses are all down in the body of Git.execute, of course. I presume that, rather than having detected something new, CodeQL is redetecting what it has already detected. This actually makes sense: one of the @overload stubs that contains information about the arguments that can be passed to Git.execute, which can contain sensitive information and from which values are derived that CodeQL believes may not be sanitized, is now different code, so CodeQL is detecting the cause as a different (albeit equivalent) one.

This is to say that I think the CodeQL situation is analogous to that in #1813, even though it seems stranger here. If that is the case, then I think this is not cause for alarm. It seems unlikely it could be anything else, but I suggest verifying it by checking that corresponding warnings have also gone away, i.e., that CodeQL automatically dismisses equivalent warnings to each of the new ones.

It may be easier to examine once the CodeQL jobs have run for the last commit, and I expect automatic CodeQL comments to be posted as well, as in #1813.

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.

This is incredible work! I don't even know how to express how incredible it is as I don't know how it's even humanly possible to read through this much code while doing all these small to bigger improvements, with most of them being related to something as abstract as whitespace.
I cannot imagine how a workflow around these changes must look like unless there is a way to automatically build and preview exactly the part of the file one is currently working on.

As for my own review, I tried to use the renderered docs of the PR sporadically to get an idea of how it looks like. Nice initially, it quickly turned out that plenty of functions I would have expected to be findable through search simply weren't, so a preview wasn't really possible after all.

I also admit that I skimmed most of the changes, which already take quite some amount of time.

Regarding the concern related to the format of class-links and the tradeoffs between the very usable rendered versions and the more wordy representation in text, I think favouring the rendering is the right choice (even in case it's not always shown, at least on readthedocs). It would also be my expectation that IDEs can use these docstring links to allow the user to jump to the linked classes directly, or maybe they even render the docs in-line while resolving the links. Thus, even in code only proper links should be useful.

I hope I didn't forget to address anything or skipped over something important, if that happened please do accept my apologies and let me know so I can address what's missing.

In any case, let's merge this 🙏!

@Byron Byron merged commit 7fbfc77 into gitpython-developers:main Feb 29, 2024
26 checks passed
@EliahKagan EliahKagan deleted the copyedit branch February 29, 2024 21:15
@EliahKagan
Copy link
Contributor Author

EliahKagan commented Feb 29, 2024

This is incredible work! I don't even know how to express how incredible it is as I don't know how it's even humanly possible to read through this much code while doing all these small to bigger improvements, with most of them being related to something as abstract as whitespace.

This was actually faster than #1725, in part because of its narrower scope and my greater familiarity with the code, but in part because it required much less code reading, though I did have to read docstrings. The approach I took here was different from there, which is also why the individual commits here may not have been broken up quite as nicely: I did this in more of a breadth-first fashion, in multiple passes, some reading carefully and others skimming, and each time applying things I noticed on the previous pass, both about the documentation and about what I had caught myself missing.

The biggest whitespace changes were (a) in formatting of :role:/:role args...-led sections, which were very fast to do manually, and (b) wrapping, which was simpler than in #1725 because I was applying an 88-column wrap everywhere except where it clearly worsened readability, rather than trying to infer wrapping in each place from local context.

Because single newlines (in most places equivalent to a single space when rendered) often appear (and occasionally I even added them) to improve readability or ease of editing in the docstrings themselves, and also because the wrapping tool I used (the Rewrap extension in VS Code) doesn't automatically observe all reStructuredText syntax rules when wrapping Python docstring text, I wasn't able to just select entire docstrings and auto-wrap them in most cases. But I was able to select a sizable contiguous chunks of lines at a time and do it, which also aided in keeping my place and noticing other issues to fix.

I cannot imagine how a workflow around these changes must look like unless there is a way to automatically build and preview exactly the part of the file one is currently working on.

I don't have such a tool. VS Code renders docstrings when one hovers over the symbol, but it does so in kind of a fuzzy way that mostly interprets them as Markdown. I mostly worked in the docstring source itself, but I previewed changes with make -C doc html regularly. The Live Server extension for VS Code helped here, though I probably could've instead used file:// URLs and refreshed a lot.

As for my own review, I tried to use the renderered docs of the PR sporadically to get an idea of how it looks like. Nice initially, it quickly turned out that plenty of functions I would have expected to be findable through search simply weren't, so a preview wasn't really possible after all.

The API Reference is all on one page, so shortcomings in the provided search can sometimes be overcome by the web browser's own search (Ctrl+F for me). The first match will often be a mere mention of the symbol one seeks, but now that nearly all of these mentions link to the symbol, clicking it should be sufficient to get there. In hindsight I ought to have given that as the primary rationale for making internal class (and method) names links everywhere there was not strong reason not to do so: people often search for them and find something else that mentions them, and now they can usually click through immediately to what they are really looking for.

However, that the Read the Docs search--assuming I am right in thinking that this is what you mean--was not working as well as you expected deserves attention, and may be something we can fix. When looking into this, I found a problem which I hope to open a GitPython issue for soon. But I suspect it is different from what you are describing, because the problem I encountered does not affect searching in pull request builds. Can you say more about how you searched, and what you had expected would produce good results but did not?

[...] It would also be my expectation that IDEs can use these docstring links to allow the user to jump to the linked classes directly, or maybe they even render the docs in-line while resolving the links. [...]

I don't have this functionality in VS Code for Sphinx documentation in Python docstrings, though there may be extensions that provide it, or maybe there is even something I'm unaware of that I just need to configure (but nothing in a docstring is ever treated by my editor as a symbol). I suspect I would get it if using a more IDE-ish IDE, such as PyCharm (or Writerside, a documentation IDE I've been meaning to try).

However, symbol search is fast and accurate in VS Code for most Python projects, including GitPython, so I was able to look up symbols efficiently (including by selecting them in docstrings and pressing Ctrl+T).


Regarding #1850 (comment):

I was unable to reproduce the CodeQL check failure or alerts in my own fork, after trying CodeQL checks on both the push and pull_request triggers. It also somehow went away here as of ee0301a. I don't know of any reason the content of that commit would ameliorate or otherwise affect CodeQL alerts.


Regarding #1850 (comment):

It's too bad that it's not possible to tell GitHub to build every commit in the PR, so one is instead forced to push each commit individually

I wonder if there is some way to copy the status from the corresponding run in a fork that has already occurred.

(which has side-effects).

Are there side effects of repeated pushes that I should be aware of, other than more entries in the remote (and local) reflog?

@Byron
Copy link
Member

Byron commented Mar 1, 2024

Can you say more about how you searched, and what you had expected would produce good results but did not?

I pasted the name of two functions, the second one I forgot but it was public (and pretty long), and the first one was refresh(). There is two of these, and it only finds one of them which was initially confusing as the text didn't match.
The other public method I searched for it didn't find at all. The browser search I tried to use, but it didn't work well for me.

Overall, I find the API documentation quality on a level of 'better than nothing', but it always was like that and by now I suppose I am spoiled by rustdoc.

I wonder if there is some way to copy the status from the corresponding run in a fork that has already occurred.

This would be very clever, and could save a lot of compute as well!

Are there side effects of repeated pushes that I should be aware of, other than more entries in the remote (and local) reflog?

I get one email per push, in the moment the push is received😅. It's fine though, my email is setup none-invasively to not break focus.

@Byron Byron changed the title Revise docstrings, comments, and a few messages 📣Revise docstrings, comments, and a few messages📣 Mar 1, 2024
@EliahKagan
Copy link
Contributor Author

I pasted the name of two functions, the second one I forgot but it was public (and pretty long), and the first one was refresh(). There is two of these, and it only finds one of them which was initially confusing as the text didn't match.

When I search for refresh or refresh(), whether locally, hosted by Read the Docs for a PR, or hosted by Read the Docs for the tip of the main branch (i.e., "latest"), it finds both Git.refresh and FetchInfo.refresh. The one people should actually use has not been emitted at all, as noted in #1854, but it should be visible in the PR preview build for #1855 (and in "latest" if that PR is merged).

The other public method I searched for it didn't find at all. The browser search I tried to use, but it didn't work well for me.

I have had some trouble with some other search terms. For example, TagObject doesn't always turn up particularly useful results. I still haven't reproduced the details of this and opened an issue for it, but when I do maybe that will help lead to an improvement.

I get one email per push, in the moment the push is received😅. It's fine though, my email is setup none-invasively to not break focus.

I was unaware that notifications were generated for PRs that are opened as drafts and still marked draft!

@EliahKagan
Copy link
Contributor Author

It's fine though, my email is setup none-invasively to not break focus.

I have taken this to mean that it is fine for me to continue pushing commits in the way I have been doing (in cases where they would otherwise not have CI check statuses). However, if that is not the case and you'd prefer I stop doing that, you can let me know.

EliahKagan added a commit to EliahKagan/GitPython that referenced this pull request Mar 8, 2024
In 6126997 (gitpython-developers#1850), I had meant to have the git.objects.tag module
docstring say that the module defined the TagObject class, to help
ensure no one would confuse this with the TagReference class. But I
instead had it wrongly say it defined the TagReference class! This
fixes that.
EliahKagan added a commit to EliahKagan/GitPython that referenced this pull request Mar 10, 2024
It gained an indentation level in dc95a76, so its docstrings and
comments were no longer wrapped to 88 columns as most docstrings
and comments have been (absent a reason not to) since gitpython-developers#1850.

This wraps it, but some parts may benefit from some other
adjustments.
@Byron Byron changed the title 📣Revise docstrings, comments, and a few messages📣 Revise docstrings, comments, and a few messages Mar 15, 2024
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
2 participants