From 1b078642b78be20cc2be2f5a2689982b360b3a1d Mon Sep 17 00:00:00 2001
From: Michael Hanke <michael.hanke@gmail.com>
Date: Fri, 27 Oct 2023 09:43:07 +0200
Subject: [PATCH] Make `ZipFileDirPath` a private class

It has an very narrow purpose, and should never be used for anything
else. I see no reason why a user should use it directly.

I made a few minor changes to the implementation itself (f-strings,
and using `super()`) for a lbit leaner code.
---
 .../iter_collections/tests/test_iterzip.py     | 12 ++++++------
 datalad_next/iter_collections/zipfile.py       | 18 ++++++++++++------
 2 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/datalad_next/iter_collections/tests/test_iterzip.py b/datalad_next/iter_collections/tests/test_iterzip.py
index eac32ea8..cc38faa9 100644
--- a/datalad_next/iter_collections/tests/test_iterzip.py
+++ b/datalad_next/iter_collections/tests/test_iterzip.py
@@ -4,7 +4,7 @@
 
 from ..zipfile import (
     FileSystemItemType,
-    ZipFileDirPath,
+    _ZipFileDirPath,
     ZipfileItem,
     iter_zip,
 )
@@ -51,7 +51,7 @@ def test_iter_zip(sample_zip):
     root = PurePosixPath('test-archive')
     targets = [
         ZipfileItem(
-            name=ZipFileDirPath(root),
+            name=_ZipFileDirPath(root),
             type=FileSystemItemType.directory,
             size=0,
         ),
@@ -61,7 +61,7 @@ def test_iter_zip(sample_zip):
             size=8,
         ),
         ZipfileItem(
-            name=ZipFileDirPath(root, 'subdir'),
+            name=_ZipFileDirPath(root, 'subdir'),
             type=FileSystemItemType.directory,
             size=0,
         ),
@@ -92,9 +92,9 @@ def test_iter_zip(sample_zip):
 
 
 def test_zip_dir_path():
-    zp1 = ZipFileDirPath("a/b")
-    zp2 = ZipFileDirPath("a/b")
-    zp3 = ZipFileDirPath("a/c")
+    zp1 = _ZipFileDirPath("a/b")
+    zp2 = _ZipFileDirPath("a/b")
+    zp3 = _ZipFileDirPath("a/c")
     pp = PurePosixPath("a/b")
 
     assert zp1.as_posix()[-1] == '/'
diff --git a/datalad_next/iter_collections/zipfile.py b/datalad_next/iter_collections/zipfile.py
index 9b7dafec..c7dc860f 100644
--- a/datalad_next/iter_collections/zipfile.py
+++ b/datalad_next/iter_collections/zipfile.py
@@ -21,15 +21,21 @@
 )
 
 
-class ZipFileDirPath(PurePosixPath):
-    """Used to create proper names for directories in zip-archives"""
+class _ZipFileDirPath(PurePosixPath):
+    """PurePosixPath variant that appends a '/' to the str-representation
+
+    This is used by class:`ZipfileItem` to represent directory members in
+    ZIP archives, in order to streamline archive member tests via a
+    ``item.name in zipfile.ZipFile(...)`` pattern. ``ZipFile`` requires
+    directory members to be identified with a trailing slash.
+    """
     def __str__(self) -> str:
-        return PurePosixPath.__str__(self) + '/'
+        return f'{super().__str__()}/'
 
     def __eq__(self, other):
-        if not isinstance(other, ZipFileDirPath):
+        if not isinstance(other, _ZipFileDirPath):
             return False
-        return PurePosixPath.__eq__(self, other)
+        return super().__eq__(other)
 
 
 @dataclass
@@ -83,7 +89,7 @@ def _get_zipfile_item(zip_info: zipfile.ZipInfo) -> ZipfileItem:
     return ZipfileItem(
         **(
             dict(
-                name=ZipFileDirPath(zip_info.filename),
+                name=_ZipFileDirPath(zip_info.filename),
                 type=FileSystemItemType.directory)
             if zip_info.is_dir()
             else dict(