Useless dichotomy between oid and commit

[hramrach]

code

import tempfile
import pygit2
import subprocess
import shutil
import sys

print(f"python: {sys.version}")
print(f"libgit2: {pygit2.LIBGIT2_VERSION}")
print(f"pygit2: {pygit2.__version__}")


repodir = tempfile.mkdtemp()
repo = pygit2.init_repository(repodir, bare=True)

sig = pygit2.Signature('Test User', 'testuser@nowhere.net')

data = 'blah blah master'
tree = repo.TreeBuilder()
tree.insert('file', repo.create_blob(data.encode()), pygit2.GIT_FILEMODE_BLOB)

master_commit_oid = repo.create_commit('HEAD', sig, sig, 'master commit', tree.write(), [])

repo.lookup_branch('master').set_target(master_commit_oid)

print(f"dullahan: {repo.head_is_detached}")

repo.head.set_target(master_commit_oid) # no effect?

print(f"dullahan: {repo.head_is_detached}")

subprocess.run(['cat', repodir + '/HEAD'])

data = 'blah blah feature'
tree = repo.TreeBuilder()
tree.insert('file', repo.create_blob(data.encode()), pygit2.GIT_FILEMODE_BLOB)

feature_commit_oid = repo.create_commit('HEAD', sig, sig, 'feature commit', tree.write(), [master_commit_oid])

feature_commit = repo.resolve_refish(feature_commit_oid.hex)[0] # why is this needed?!

repo.branches.local.create('feature', feature_commit_oid)

subprocess.run(['git', '--no-pager', '--git-dir', repodir, 'log'])
hutil.rmtree(repodir)

output

python: 3.11.8 (main, Feb 29 2024, 12:19:47) [GCC]
libgit2: 1.8.0
pygit2: 1.14.1
dullahan: False
dullahan: False
ref: refs/heads/master
Traceback (most recent call last):
  File "/home/hramrach/kbuild/testrepo.py", line 41, in <module>
    repo.branches.local.create('feature', feature_commit_oid)
  File "/usr/lib64/python3.11/site-packages/pygit2/branches.py", line 78, in create
    return self._repository.create_branch(name, commit, force)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: argument 2 must be _pygit2.Commit, not _pygit2.Oid

Why?!

Clearly the Oid can be deterministically converted to a commit so long as it refers to one. The code already needs to access the on-disk repository and is inspecting the parameter, throwing an exception when it does not like it. Why can't it determine if the Oid refers to a commit, and convert it automatically when it does?

[hramrach]

Docs say:

The pygit2 API always returns, and accepts, Oid objects.

This is in conflict with the docs, create_branch does not.