feat: Separate ID and name params for Actor.open_xxx (#56)

Author: jirimoravcik

docs/docs.md

@@ -144,7 +144,7 @@ That’s useful if you want to use the client as a different Apify user than the
 
 ***
 
-#### async classmethod open_dataset(dataset_id_or_name=None, \*, force_cloud=False)
+#### async classmethod open_dataset(\*, id=None, name=None, force_cloud=False)
 
 Open a dataset.
 
@@ -154,8 +154,11 @@ The actual data is stored either on the local filesystem or in the Apify cloud.
 
 * **Parameters**
 
-  * **dataset_id_or_name** (`str`, *optional*) – ID or name of the dataset to be opened.
-  If not provided, the method returns the default dataset associated with the actor run.
+  * **id** (`str`, *optional*) – ID of the dataset to be opened.
+  If neither id nor name are provided, the method returns the default dataset associated with the actor run.
+
+  * **name** (`str`, *optional*) – Name of the dataset to be opened.
+  If neither id nor name are provided, the method returns the default dataset associated with the actor run.
 
   * **force_cloud** (`bool`, *optional*) – If set to True then the Apify cloud storage is always used.
   This way it is possible to combine local and cloud storage.
@@ -170,7 +173,7 @@ The actual data is stored either on the local filesystem or in the Apify cloud.
 
 ***
 
-#### async classmethod open_key_value_store(key_value_store_id_or_name=None, \*, force_cloud=False)
+#### async classmethod open_key_value_store(\*, id=None, name=None, force_cloud=False)
 
 Open a key-value store.
 
@@ -180,8 +183,11 @@ The actual data is stored either on a local filesystem or in the Apify cloud.
 
 * **Parameters**
 
-  * **key_value_store_id_or_name** (`str`, *optional*) – ID or name of the key-value store to be opened.
-  If not provided, the method returns the default key-value store associated with the actor run.
+  * **id** (`str`, *optional*) – ID of the key-value store to be opened.
+  If neither id nor name are provided, the method returns the default key-value store associated with the actor run.
+
+  * **name** (`str`, *optional*) – Name of the key-value store to be opened.
+  If neither id nor name are provided, the method returns the default key-value store associated with the actor run.
 
   * **force_cloud** (`bool`, *optional*) – If set to True then the Apify cloud storage is always used.
   This way it is possible to combine local and cloud storage.
@@ -196,7 +202,7 @@ The actual data is stored either on a local filesystem or in the Apify cloud.
 
 ***
 
-#### async classmethod open_request_queue(request_queue_id_or_name=None, \*, force_cloud=False)
+#### async classmethod open_request_queue(\*, id=None, name=None, force_cloud=False)
 
 Open a request queue.
 
@@ -207,8 +213,11 @@ and depth-first crawling orders.
 
 * **Parameters**
 
-  * **request_queue_id_or_name** (`str`, *optional*) – ID or name of the request queue to be opened.
-  If not provided, the method returns the default request queue associated with the actor run.
+  * **id** (`str`, *optional*) – ID of the request queue to be opened.
+  If neither id nor name are provided, the method returns the default request queue associated with the actor run.
+
+  * **name** (`str`, *optional*) – Name of the request queue to be opened.
+  If neither id nor name are provided, the method returns the default request queue associated with the actor run.
 
   * **force_cloud** (`bool`, *optional*) – If set to True then the Apify cloud storage is always used.
   This way it is possible to combine local and cloud storage.

src/apify/actor.py

@@ -478,56 +478,68 @@ def _get_storage_client(self, force_cloud: bool) -> Optional[ApifyClientAsync]:
         return self._apify_client if force_cloud else None
 
     @classmethod
-    async def open_dataset(cls, dataset_id_or_name: Optional[str] = None, *, force_cloud: bool = False) -> Dataset:
+    async def open_dataset(cls, *, id: Optional[str] = None, name: Optional[str] = None, force_cloud: bool = False) -> Dataset:
         """Open a dataset.
 
         Datasets are used to store structured data where each object stored has the same attributes,
         such as online store products or real estate offers.
         The actual data is stored either on the local filesystem or in the Apify cloud.
 
         Args:
-            dataset_id_or_name (str, optional): ID or name of the dataset to be opened.
-                If not provided, the method returns the default dataset associated with the actor run.
+            id (str, optional): ID of the dataset to be opened.
+                If neither `id` nor `name` are provided, the method returns the default dataset associated with the actor run.
+            name (str, optional): Name of the dataset to be opened.
+                If neither `id` nor `name` are provided, the method returns the default dataset associated with the actor run.
             force_cloud (bool, optional): If set to `True` then the Apify cloud storage is always used.
                 This way it is possible to combine local and cloud storage.
 
         Returns:
             Dataset: An instance of the `Dataset` class for the given ID or name.
 
         """
-        return await cls._get_default_instance().open_dataset(dataset_id_or_name=dataset_id_or_name, force_cloud=force_cloud)
+        return await cls._get_default_instance().open_dataset(id=id, name=name, force_cloud=force_cloud)
 
-    async def _open_dataset_internal(self, dataset_id_or_name: Optional[str] = None, *, force_cloud: bool = False) -> Dataset:
+    async def _open_dataset_internal(self, *, id: Optional[str] = None, name: Optional[str] = None, force_cloud: bool = False) -> Dataset:
         self._raise_if_not_initialized()
 
+        dataset_id_or_name = id or name
         return await StorageManager.open_storage(Dataset, dataset_id_or_name, self._get_storage_client(force_cloud), self._config)
 
     @classmethod
-    async def open_key_value_store(cls, key_value_store_id_or_name: Optional[str] = None, *, force_cloud: bool = False) -> KeyValueStore:
+    async def open_key_value_store(cls, *, id: Optional[str] = None, name: Optional[str] = None, force_cloud: bool = False) -> KeyValueStore:
         """Open a key-value store.
 
         Key-value stores are used to store records or files, along with their MIME content type.
         The records are stored and retrieved using a unique key.
         The actual data is stored either on a local filesystem or in the Apify cloud.
 
         Args:
-            key_value_store_id_or_name (str, optional): ID or name of the key-value store to be opened.
-                If not provided, the method returns the default key-value store associated with the actor run.
+            id (str, optional): ID of the key-value store to be opened.
+                If neither `id` nor `name` are provided, the method returns the default key-value store associated with the actor run.
+            name (str, optional): Name of the key-value store to be opened.
+                If neither `id` nor `name` are provided, the method returns the default key-value store associated with the actor run.
             force_cloud (bool, optional): If set to `True` then the Apify cloud storage is always used.
                 This way it is possible to combine local and cloud storage.
 
         Returns:
             KeyValueStore: An instance of the `KeyValueStore` class for the given ID or name.
         """
-        return await cls._get_default_instance().open_key_value_store(key_value_store_id_or_name=key_value_store_id_or_name, force_cloud=force_cloud)
+        return await cls._get_default_instance().open_key_value_store(id=id, name=name, force_cloud=force_cloud)
 
-    async def _open_key_value_store_internal(self, key_value_store_id_or_name: Optional[str] = None, *, force_cloud: bool = False) -> KeyValueStore:
+    async def _open_key_value_store_internal(
+        self,
+        *,
+        id: Optional[str] = None,
+        name: Optional[str] = None,
+        force_cloud: bool = False,
+    ) -> KeyValueStore:
         self._raise_if_not_initialized()
 
+        key_value_store_id_or_name = id or name
         return await StorageManager.open_storage(KeyValueStore, key_value_store_id_or_name, self._get_storage_client(force_cloud), self._config)
 
     @classmethod
-    async def open_request_queue(cls, request_queue_id_or_name: Optional[str] = None, *, force_cloud: bool = False) -> RequestQueue:
+    async def open_request_queue(cls, *, id: Optional[str] = None, name: Optional[str] = None, force_cloud: bool = False) -> RequestQueue:
         """Open a request queue.
 
         Request queue represents a queue of URLs to crawl, which is stored either on local filesystem or in the Apify cloud.
@@ -536,24 +548,28 @@ async def open_request_queue(cls, request_queue_id_or_name: Optional[str] = None
         and depth-first crawling orders.
 
         Args:
-            request_queue_id_or_name (str, optional): ID or name of the request queue to be opened.
-                If not provided, the method returns the default request queue associated with the actor run.
+            id (str, optional): ID of the request queue to be opened.
+                If neither `id` nor `name` are provided, the method returns the default request queue associated with the actor run.
+            name (str, optional): Name of the request queue to be opened.
+                If neither `id` nor `name` are provided, the method returns the default request queue associated with the actor run.
             force_cloud (bool, optional): If set to `True` then the Apify cloud storage is always used.
                 This way it is possible to combine local and cloud storage.
 
         Returns:
             RequestQueue: An instance of the `RequestQueue` class for the given ID or name.
         """
-        return await cls._get_default_instance().open_request_queue(request_queue_id_or_name=request_queue_id_or_name, force_cloud=force_cloud)
+        return await cls._get_default_instance().open_request_queue(id=id, name=name, force_cloud=force_cloud)
 
     async def _open_request_queue_internal(
         self,
-        request_queue_id_or_name: Optional[str] = None,
         *,
+        id: Optional[str] = None,
+        name: Optional[str] = None,
         force_cloud: bool = False,
     ) -> RequestQueue:
         self._raise_if_not_initialized()
 
+        request_queue_id_or_name = id or name
         return await StorageManager.open_storage(RequestQueue, request_queue_id_or_name, self._get_storage_client(force_cloud), self._config)
 
     @classmethod

src/apify/storages/dataset.py

@@ -47,7 +47,7 @@ class Dataset:
     def __init__(self, id: str, name: Optional[str], client: Union[ApifyClientAsync, MemoryStorage]) -> None:
         """Create a `Dataset` instance.
 
-        Do not use the constructor directly, use the `Dataset.open` function instead.
+        Do not use the constructor directly, use the `Actor.open_dataset()` function instead.
 
         Args:
             id (str): ID of the dataset.

src/apify/storages/key_value_store.py

@@ -53,7 +53,7 @@ class KeyValueStore:
     def __init__(self, id: str, name: Optional[str], client: Union[ApifyClientAsync, MemoryStorage]) -> None:
         """Create a `KeyValueStore` instance.
 
-        Do not use the constructor directly, use the `KeyValueStore.open` function instead.
+        Do not use the constructor directly, use the `Actor.open_key_value_store()` function instead.
 
         Args:
             id (str): ID of the key-value store.

src/apify/storages/request_queue.py

@@ -97,7 +97,7 @@ class RequestQueue:
     def __init__(self, id: str, name: Optional[str], client: Union[ApifyClientAsync, MemoryStorage]) -> None:
         """Create a `RequestQueue` instance.
 
-        Do not use the constructor directly, use the `RequestQueue.open` function instead.
+        Do not use the constructor directly, use the `Actor.open_request_queue()` function instead.
 
         Args:
             id (str): ID of the request queue.
@@ -499,8 +499,10 @@ async def open(cls, request_queue_id_or_name: Optional[str] = None, config: Opti
         and depth-first crawling orders.
 
         Args:
-            request_queue_id_or_name (str, optional): ID or name of the request queue to be opened.
-                If not provided, the method returns the default request queue associated with the actor run.
+            id (str, optional): ID of the request queue to be opened.
+                If neither `id` nor `name` are provided, the method returns the default request queue associated with the actor run.
+            name (str, optional): Name of the request queue to be opened.
+                If neither `id` nor `name` are provided, the method returns the default request queue associated with the actor run.
             config (Configuration, optional): A `Configuration` instance, uses global configuration if omitted.
 
         Returns:

tests/integration/test_actor_dataset.py

@@ -47,8 +47,8 @@ async def main() -> None:
             async with Actor:
                 input_object = await Actor.get_input()
                 dataset_name = input_object['datasetName']
-                dataset1 = await Actor.open_dataset(dataset_name)
-                dataset2 = await Actor.open_dataset(dataset_name)
+                dataset1 = await Actor.open_dataset(name=dataset_name)
+                dataset2 = await Actor.open_dataset(name=dataset_name)
                 assert dataset1 is dataset2
                 await dataset1.drop()
 

tests/integration/test_actor_key_value_store.py

@@ -25,8 +25,8 @@ async def main() -> None:
             async with Actor:
                 input_object = await Actor.get_input()
                 kvs_name = input_object['kvsName']
-                kvs1 = await Actor.open_key_value_store(kvs_name)
-                kvs2 = await Actor.open_key_value_store(kvs_name)
+                kvs1 = await Actor.open_key_value_store(name=kvs_name)
+                kvs2 = await Actor.open_key_value_store(name=kvs_name)
                 assert kvs1 is kvs2
                 await kvs1.drop()
 
@@ -75,7 +75,7 @@ async def main_get() -> None:
             async with Actor:
                 input_object = await Actor.get_input()
                 # Access KVS of the previous 'set' run
-                kvs = await Actor.open_key_value_store(input_object['kvs-id'])
+                kvs = await Actor.open_key_value_store(name=input_object['kvs-id'])
                 value = await kvs.get_value('test')
                 assert value['number'] == 123
                 assert value['string'] == 'a string'

tests/integration/test_actor_request_queue.py

@@ -25,8 +25,8 @@ async def main() -> None:
             async with Actor:
                 input_object = await Actor.get_input()
                 rq_name = input_object['rqName']
-                rq1 = await Actor.open_request_queue(rq_name)
-                rq2 = await Actor.open_request_queue(rq_name)
+                rq1 = await Actor.open_request_queue(name=rq_name)
+                rq2 = await Actor.open_request_queue(name=rq_name)
                 assert rq1 is rq2
                 await rq1.drop()
 

tests/unit/actor/test_actor_dataset.py

@@ -20,8 +20,8 @@ async def test_same_references(self) -> None:
             dataset2 = await Actor.open_dataset()
             assert dataset1 is dataset2
             dataset_name = 'non-default'
-            dataset_named1 = await Actor.open_dataset(dataset_name)
-            dataset_named2 = await Actor.open_dataset(dataset_name)
+            dataset_named1 = await Actor.open_dataset(name=dataset_name)
+            dataset_named2 = await Actor.open_dataset(name=dataset_name)
             assert dataset_named1 is dataset_named2
 
     async def test_open_datatset_based_env_var(

tests/unit/actor/test_actor_key_value_store.py

@@ -18,8 +18,8 @@ async def test_same_references(self) -> None:
             kvs2 = await Actor.open_key_value_store()
             assert kvs1 is kvs2
             kvs_name = 'non-default'
-            kvs_named1 = await Actor.open_key_value_store(kvs_name)
-            kvs_named2 = await Actor.open_key_value_store(kvs_name)
+            kvs_named1 = await Actor.open_key_value_store(name=kvs_name)
+            kvs_named2 = await Actor.open_key_value_store(name=kvs_name)
             assert kvs_named1 is kvs_named2