Support for optional pin names introduced by kubo 0.26

* Support for passing pin names via "pin add"
* Support for listing pin names with "pin ls" using the "names" boolean
* Add a unit test for pin names
* CI: Test kubo 0.26
* docs: util.car_bytes() must receive the CID of a UnixFS file

[pypi]

revbump to 0.6.6

.github/workflows/python-package.yml

@@ -32,23 +32,23 @@ jobs:
       if: startsWith(matrix.os, 'windows')
       with:
         name: ipfs.exe
-        url: "https://dist.ipfs.tech/kubo/v0.24.0/kubo_v0.24.0_windows-amd64.zip"
+        url: "https://dist.ipfs.tech/kubo/v0.26.0/kubo_v0.26.0_windows-amd64.zip"
         pathInArchive: "kubo/ipfs.exe"
 
     - name: Fetch kubo (linux)
       uses: engineerd/[email protected]
       if: startsWith(matrix.os, 'ubuntu')
       with:
         name: ipfs
-        url: "https://dist.ipfs.tech/kubo/v0.24.0/kubo_v0.24.0_linux-amd64.tar.gz"
+        url: "https://dist.ipfs.tech/kubo/v0.26.0/kubo_v0.26.0_linux-amd64.tar.gz"
         pathInArchive: "kubo/ipfs"
 
     - name: Fetch kubo (macos)
       uses: engineerd/[email protected]
       if: startsWith(matrix.os, 'macos')
       with:
         name: ipfs
-        url: "https://dist.ipfs.tech/kubo/v0.24.0/kubo_v0.24.0_darwin-amd64.tar.gz"
+        url: "https://dist.ipfs.tech/kubo/v0.26.0/kubo_v0.26.0_darwin-amd64.tar.gz"
         pathInArchive: "kubo/ipfs"
 
     - name: Test with pytest

.gitlab-ci.yml

@@ -22,7 +22,8 @@ variables:
           kubo-0.21.0,
           kubo-0.22.0,
           kubo-0.23.0,
-          kubo-0.24.0
+          kubo-0.24.0,
+          kubo-0.26.0
         ]
 
   script:

README.rst

@@ -9,7 +9,7 @@ Supported python versions: *3.6*, *3.7*, *3.8*, *3.9*, *3.10*, *3.11*, *3.12*.
 
 This library supports the
 `RPC API specifications <https://docs.ipfs.tech/reference/kubo/rpc>`_
-for kubo_ version *0.24.0*. Unit tests are run against
+for kubo_ version *0.26.0*. Unit tests are run against
 most major go-ipfs releases and all kubo_
 releases, see the *CI* section below.
 
@@ -157,7 +157,7 @@ go-ipfs/kubo releases (`go here <https://gitlab.com/cipres/aioipfs/-/jobs>`_
 for the CI jobs overview).
 
 - go-ipfs >=0.11.0,<=0.13.0
-- kubo >=0.14.0,<=0.24.0
+- kubo >=0.14.0,<=0.26.0
 
 Features
 ========

aioipfs/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.6.5'
+__version__ = '0.6.6'
 
 from yarl import URL
 from distutils.version import StrictVersion

aioipfs/apis/pin.py

@@ -145,13 +145,15 @@ def __init__(self, driver):
 
         self.remote = PinRemoteAPI(driver)
 
-    async def add(self, path, recursive=True, progress=True):
+    async def add(self, path, recursive=True, progress=True,
+                  name: str = None):
         """
         Pin objects to local storage.
 
         :param str path: Path to object(s) to be pinned
         :param bool recursive: Recursively pin the object linked to
             by the specified object(s)
+        :param str name: An optional name for the created pin(s)
         :param bool progress: Show progress
         """
 
@@ -162,12 +164,16 @@ async def add(self, path, recursive=True, progress=True):
             'progress': boolarg(progress)
         }
 
+        if isinstance(name, str) and len(name) > 0:
+            params['name'] = name
+
         async for added in self.mjson_decode(
                 self.url('pin/add'), params=params):
             yield added
 
     async def ls(self, path=None, pintype='all', quiet=False,
-                 stream: bool = False):
+                 stream: bool = False,
+                 names: bool = False):
         """
         List objects pinned to local storage.
 
@@ -176,12 +182,14 @@ async def ls(self, path=None, pintype='all', quiet=False,
             "direct", "indirect", "recursive", or "all"
         :param bool quiet: Write just hashes of objects
         :param bool stream: Enable streaming of pins as they are discovered
+        :param bool names: Enable displaying pin names
         """
 
         params = {
             'type': pintype,
             'quiet': boolarg(quiet),
-            'stream': boolarg(stream)
+            'stream': boolarg(stream),
+            'names': boolarg(names)
         }
         if path:
             params[ARG_PARAM] = path

aioipfs/util.py

@@ -32,7 +32,7 @@ async def car_bytes(stream, cid: str) -> bytes:
     CAR stream to bytes
 
     :param stream: CAR stream
-    :param str cid: CID of the UnixFS directory to export
+    :param str cid: CID of the UnixFS file to export
     :rtype: bytes
     """
 

docs/index.rst

@@ -119,8 +119,8 @@ aRchives generated by kubo, or to open .car files:
   `FileByteStream <https://github.com/kralverde/py-ipfs-car-decoder/blob/main/ipfs_car_decoder/async_stream.py#L102>`_)
 
 - Use :func:`aioipfs.util.car_bytes` to get the raw bytes content from a CAR
-  stream. The first argument is the CAR stream, the second argument is the
-  CID of the UnixFS node::
+  stream. The first argument is the CAR stream, the second argument must be the
+  CID of a UnixFS file::
 
     from pathlib import Path
     from aioipfs import util

tests/test_client.py

@@ -430,12 +430,14 @@ async def test_ignorerules(self, event_loop, ipfsdaemon, iclient,
     @pytest.mark.asyncio
     async def test_addtar(self, event_loop, ipfsdaemon, iclient,
                           tmpdir, smalltar):
-        tar, tarpath = smalltar
-        reply = await iclient.tar.add(tarpath)
-        tarhash = reply['Hash']
-        fetched = await iclient.tar.cat(tarhash)
-        f = tmpdir.join('new.tar')
-        f.write(fetched)
+        if await iclient.agent_version_get() < \
+                aioipfs.IpfsDaemonVersion('0.26.0'):
+            tar, tarpath = smalltar
+            reply = await iclient.tar.add(tarpath)
+            tarhash = reply['Hash']
+            fetched = await iclient.tar.cat(tarhash)
+            f = tmpdir.join('new.tar')
+            f.write(fetched)
 
     @pytest.mark.asyncio
     @pytest.mark.parametrize('order', ['gin', 'tonic'])
@@ -924,6 +926,34 @@ async def test_cidapi(self, event_loop, ipfsdaemon, iclient, testfile1):
         await iclient.cid.bases()
         await iclient.cid.hashes()
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize('pin_name', ['pintest'])
+    async def test_pin(self, event_loop, ipfsdaemon, iclient, pin_name):
+        entry = await iclient.add_bytes(b'Test', pin=False)
+
+        if await iclient.agent_version_get() >= \
+                aioipfs.IpfsDaemonVersion('0.26.0'):
+            """
+            kubo >= 0.26.0 supports optional pin names
+
+            Pin the object with a pin name and check that the entry
+            has the correct name when listing the pins
+            """
+
+            resp = [e async for e in iclient.pin.add(
+                entry['Hash'],
+                name=pin_name
+            )]
+            assert len(resp) > 0
+
+            pins = await iclient.pin.ls(names=True)
+            pine = pins['Keys'].get(entry['Hash'])
+
+            assert pine['Name'] == pin_name
+        else:
+            resp = [e async for e in iclient.pin.add(entry['Hash'])]
+            assert len(resp) > 0
+
     @pytest.mark.asyncio
     @pytest.mark.skip(reason='This test relies on specific network conditions')
     @pytest.mark.parametrize('srvname', ['mysrv1'])