René's URL Explorer Experiment

Title: Improve static typing and docstrings related to git object types by EliahKagan · Pull Request #1859 · gitpython-developers/GitPython · GitHub

Open Graph Title: Improve static typing and docstrings related to git object types by EliahKagan · Pull Request #1859 · gitpython-developers/GitPython

X Title: Improve static typing and docstrings related to git object types by EliahKagan · Pull Request #1859 · gitpython-developers/GitPython

Description: Fixes #1857 Fixes #1858 Fixes #1866 Fixes #1873 Fixes #1874 Fixes #1875 Note: This pull request expanded considerably in scope since first opened, which its title reflects but the rest of this description does not. See comments for details. Main changes This expands the docstrings of Object and some of its subclasses. These revisions are, in large part, to explain the classes' relationships to the git concept of objects and to the corresponding git object types, including links to relevant definitions in gitglossary(7). This also adds docstrings to all the types introduced in git.types--those that relate directly to git object types and those that do not. Adding documentation in git.types relates topically to the docstring expansions for Object and some of its subclasses, and I tried to make all new and edited docstrings make sense whether read by themselves or together with other docstrings across modules. It also relates to the goal for git.types documentation articulated in #1854 (comment). Other changes This also includes some other changes that are less core to that scope but that seem practically useful to include. It revises the docstring for assert_never, which had been the only docstring in git.types, and modifies the string of the default exception it raises to print the repr rather than the str. It removes some long-unused nonpublic names at module level, and revises some method docstrings of classes whose class docstrings were being revised. It also expands the git.compat module docstring, toward the goal for it that was also articulated in #1854 (comment). Considerations for assert_never The change to assert_never, which includes making the docstring accurately describe the current (and established) behavior of the function, may fix #1857. However, as described there I am unsure if this is ultimately the right change there. Considerations for Commit_ish docstring (including possible inaccuracies) Even more important is the relationship of the Commit_ish docstring to #1858. I have said this PR "may" fix that issue, but I strongly suspect that either further refinement will be needed or that a significantly greater change, possibly outside the scope of this PR, may be needed. Furthermore, some of the text in that docstring may require improvement before being suitable for merging. To facilitate writing the docstrings in git.types, including related docstrings and even other parts of the Commit_ish docstring, I wrote text in two parts of the Commit_ish docstring that sound plausible but that I am not at all sure are correct. This is in regard to the question, detailed in #1858, of why Commit_ish union includes the never-commitish Tree and Blob classes. (Even if what I wrote turns out to be correct, it may need to be clarified.) I have opened review comments on those potentially inaccurate lines.

Open Graph Description: Fixes #1857 Fixes #1858 Fixes #1866 Fixes #1873 Fixes #1874 Fixes #1875 Note: This pull request expanded considerably in scope since first opened, which its title reflects but the rest of this desc...

X Description: Fixes #1857 Fixes #1858 Fixes #1866 Fixes #1873 Fixes #1874 Fixes #1875 Note: This pull request expanded considerably in scope since first opened, which its title reflects but the rest of this desc...

Opengraph URL: https://github.com/gitpython-developers/GitPython/pull/1859

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width