encoding: drop public to_str, rename internal helper to path_to_str

Replace the C-boundary uses of to_str in options.py with decode_string,
which decodes the char pointer directly (no manual ffi.string call) and
handles NULL.

Remove pygit2.to_str from the public API; it was an undocumented
accidental public helper, like to_bytes. Rename the remaining internal
helper to path_to_str, which better describes its only remaining job:
normalizing a user-supplied path argument to str in init_repository.

Add a TODO noting the decode/encode asymmetry: decode_string uses
surrogateescape while encode_string defaults to strict, so a value read
from libgit2 with bad bytes cannot be written back without raising.

Update changelog.

Assisted-by: Kimi K3

Author: jdavid

CHANGELOG.md

@@ -41,7 +41,8 @@ Breaking changes:
 - Remove deprecated `Remote.ls_remotes(...)`, use `Remote.list_heads(...)`
   instead
 
-- Remove `pygit2.to_bytes`; it was an undocumented accidental public API
+- Remove `pygit2.to_bytes` and `pygit2.to_str`; they were undocumented
+  accidental public APIs
 
 
 # 1.19.3 (2026-06-13)

pygit2/__init__.py

@@ -366,7 +366,6 @@
 from .settings import Settings
 from .submodules import Submodule
 from .transaction import ReferenceTransaction
-from .utils import to_str
 
 # Features
 features = enums.Feature(C.git_libgit2_features())
@@ -456,7 +455,7 @@ def init_repository(
     check_error(err)
 
     # Ok
-    return Repository(to_str(path))
+    return Repository(utils.path_to_str(path))
 
 
 def clone_repository(
@@ -938,7 +937,6 @@ def filter_unregister(name: str) -> None:
     'transaction',
     'ReferenceTransaction',
     'utils',
-    'to_str',
     # __init__ module defined symbols
     'features',
     'LIBGIT2_VER',

pygit2/options.py

@@ -34,7 +34,7 @@
 
 from .errors import check_error
 from .ffi import C, ffi
-from .utils import decode_fs_path, encode_fs_path, encode_string, to_str
+from .utils import decode_fs_path, decode_string, encode_fs_path, encode_string
 
 if TYPE_CHECKING:
     from ._libgit2.ffi import NULL_TYPE, ArrayC, char, char_pointer
@@ -507,10 +507,7 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
         check_error(err)
 
         try:
-            if buf.ptr != ffi.NULL:
-                result = to_str(ffi.string(buf.ptr))
-            else:
-                result = None
+            result = decode_string(buf.ptr)
         finally:
             C.git_buf_dispose(buf)
 
@@ -643,8 +640,9 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
                 # Cast to the non-NULL type for type checking
                 strings = cast('ArrayC[char_pointer]', strarray.strings)
                 for i in range(strarray.count):
-                    if strings[i] != ffi.NULL:
-                        result.append(to_str(ffi.string(strings[i])))
+                    s = decode_string(strings[i])
+                    if s is not None:
+                        result.append(s)
         finally:
             # Must dispose of the strarray to free the memory
             C.git_strarray_dispose(strarray)
@@ -767,10 +765,7 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
         check_error(err)
 
         try:
-            if buf.ptr != ffi.NULL:
-                result = to_str(ffi.string(buf.ptr))
-            else:
-                result = None
+            result = decode_string(buf.ptr)
         finally:
             C.git_buf_dispose(buf)
 

pygit2/utils.py

@@ -84,6 +84,11 @@ def encode_fs_path(
     return os.fsencode(s)  # type: ignore[arg-type]
 
 
+# TODO decode_string uses errors='surrogateescape', but encode_string defaults
+# to errors='strict', so a value read from libgit2 with bad bytes cannot be
+# written back without raising. Decide whether encode_string should default to
+# 'surrogateescape' too, and audit every caller to make sure that's safe
+# (this is a behavior change, not just a rename).
 @overload
 def encode_string(
     s: str | bytes | os.PathLike[str] | os.PathLike[bytes],
@@ -113,7 +118,7 @@ def encode_string(
     return s.encode(encoding, errors)  # type: ignore[union-attr]
 
 
-def to_str(s: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> str:
+def path_to_str(s: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> str:
     if hasattr(s, '__fspath__'):
         s = os.fspath(s)