Useless dichotomy between oid and commit

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?

Start with the reproducer and the repo.branches.local.create and resolve_refish entry points shown in the issue. Trace how create handles its commit argument and how an Oid is resolved, then verify the intended behavior against the displayed TypeError. Done means the API behavior for an Oid referring to a commit is defined and covered by an appropriate regression check.