Merge pull request #136 from genicam/_issue_127

Resolve issue #127

src/harvesters/core.py

@@ -31,6 +31,7 @@
 from threading import current_thread, main_thread
 import time
 from urllib.parse import urlparse
+from warnings import warn
 import weakref
 import tempfile
 
@@ -68,6 +69,21 @@
 _sleep_duration_default = 0.000001  # s
 
 
+def _deprecated(deprecated: object, alternative: object) -> None:
+    #
+    items = []
+    for obj in (deprecated, alternative):
+        items.append(obj.__name__ + '()' if callable(obj) else obj)
+
+    keys = {'deprecated': 0, 'alternative': 1}
+    warn(
+        '{0} will be deprecated shortly. Use {1} instead.'.format(
+            items[keys['deprecated']], items[keys['alternative']]
+        ),
+        DeprecationWarning, stacklevel=3
+    )
+
+
 class Module:
     def __init__(self, module=None, node_map=None, parent=None):
         self._module = module
@@ -602,7 +618,6 @@ def mutex(self):
         return self._mutex
 
 
-
 class ComponentBase:
     """
     Is a base class of various data component types.
@@ -1478,7 +1493,6 @@ def __init__(
         else:
             self._xml_dir = None
 
-
         #
         try:
             node_map = _get_port_connected_node_map(
@@ -1759,6 +1773,10 @@ def system(self):
         return self._system
 
     def is_acquiring_images(self):
+        _deprecated(self.is_acquiring_images, self.is_acquiring)
+        return self.is_acquiring()
+
+    def is_acquiring(self):
         """
         :return: :const:`True` if it's acquiring images. Otherwise :const:`False`.
         """
@@ -1836,6 +1854,10 @@ def _setup_data_streams(self):
                 )
 
     def start_image_acquisition(self):
+        _deprecated(self.start_image_acquisition, self.start_acquisition)
+        self.start_acquisition()
+
+    def start_acquisition(self):
         """
         Starts image acquisition.
 
@@ -1934,7 +1956,7 @@ def start_image_acquisition(self):
     def worker_image_acquisition(self, context=None):
         for event_manager in self._event_new_buffer_managers:
             try:
-                if self.is_acquiring_images():
+                if self.is_acquiring():
                     event_manager.update_event_data(
                         self._timeout_for_image_acquisition
                     )
@@ -2257,6 +2279,10 @@ def _queue_announced_buffers(self, data_stream=None, buffers=None):
             )
 
     def stop_image_acquisition(self):
+        _deprecated(self.stop_image_acquisition, self.stop_acquisition)
+        self.stop_acquisition()
+
+    def stop_acquisition(self):
         """
         Stops image acquisition.
 
@@ -2580,6 +2606,11 @@ def reset(self):
 
     @property
     def cti_files(self):
+        _deprecated('cti_files', 'files')
+        return self.files
+
+    @property
+    def files(self):
         """
         :return: A :class:`list` object containing :class:`str` objects.
         """
@@ -2730,6 +2761,10 @@ def create_image_acquirer(
         return ia
 
     def add_cti_file(self, file_path: str):
+        _deprecated(self.add_cti_file, self.add_file)
+        self.add_file(file_path)
+
+    def add_file(self, file_path: str):
         """
         Adds a CTI file to work with to the CTI file list.
 
@@ -2749,6 +2784,10 @@ def add_cti_file(self, file_path: str):
             )
 
     def remove_cti_file(self, file_path: str):
+        _deprecated(self.remove_cti_file, self.remove_file)
+        self.remove_file(file_path)
+
+    def remove_file(self, file_path: str):
         """
         Removes the specified CTI file from the CTI file list.
 
@@ -2763,6 +2802,10 @@ def remove_cti_file(self, file_path: str):
             )
 
     def remove_cti_files(self):
+        _deprecated(self.remove_cti_files, self.remove_files)
+        self.remove_files()
+
+    def remove_files(self):
         """
         Removes all CTI files in the CTI file list.
 
@@ -2820,7 +2863,7 @@ def _reset(self):
 
         #
         self._logger.info('Started resetting the Harvester object.')
-        self.remove_cti_files()
+        self.remove_files()
         self._release_gentl_producers()
 
         if self._profiler:
@@ -2883,6 +2926,10 @@ def _release_device_info_list(self):
         self._logger.info('Discarded the device information list.')
 
     def update_device_info_list(self):
+        _deprecated(self.update_device_info_list, self.update)
+        self.update()
+
+    def update(self):
         """
         Updates the device information list. You'll have to call this method
         every time you added CTI files or plugged/unplugged devices.
@@ -2935,7 +2982,7 @@ def _destroy_image_acquirer(self, ia):
         id_ = None
         if ia.device:
             #
-            ia.stop_image_acquisition()
+            ia.stop_acquisition()
 
             #
             ia._release_data_streams()

src/harvesters/test/base_harvester.py

@@ -76,8 +76,8 @@ def setUp(self):
 
         #
         self._harvester = Harvester(logger=self._logger)
-        self._harvester.add_cti_file(self._cti_file_path)
-        self._harvester.update_device_info_list()
+        self._harvester.add_file(self._cti_file_path)
+        self._harvester.update()
 
     def tearDown(self):
         #

src/harvesters/test/test_acq_frame_rate.py

@@ -75,7 +75,7 @@ def _test_performance_on_image_acquisition(self, sleep_duration=0.0):
         )
 
         # Then start image acquisition.
-        self.ia.start_image_acquisition()
+        self.ia.start_acquisition()
 
         # Run the image acquisition thread:
         thread = ThreadImageAcquisitionStatistics(
@@ -85,7 +85,7 @@ def _test_performance_on_image_acquisition(self, sleep_duration=0.0):
         thread.join()
 
         # Stop image acquisition:
-        self.ia.stop_image_acquisition()
+        self.ia.stop_acquisition()
 
         # Destroy the image acquirer:
         self.ia.destroy()

src/harvesters/test/test_harvester_core.py

@@ -77,15 +77,15 @@ def test_basic_usage_2(self):
 
     def _basic_usage(self, ia: ImageAcquirer):
         # Start image acquisition.
-        ia.start_image_acquisition()
+        ia.start_acquisition()
 
         # Fetch a buffer that is filled with image data.
         with ia.fetch_buffer() as buffer:
             # Reshape it.
             self._logger.info('{0}'.format(buffer))
 
         # Stop image acquisition.
-        ia.stop_image_acquisition()
+        ia.stop_acquisition()
 
     def test_multiple_image_acquirers(self):
         num_devices = len(self.harvester.device_info_list)
@@ -113,7 +113,7 @@ def _test_image_acquirers(self, num_ias=1):
             #
             self._logger.info('---> Round {0}: Set up'.format(i))
             for index, ia in enumerate(ias):
-                ia.start_image_acquisition()
+                ia.start_acquisition()
                 self._logger.info(
                     'Device #{0} has started image acquisition.'.format(index)
                 )
@@ -153,7 +153,7 @@ def _test_image_acquirers(self, num_ias=1):
             #
             self._logger.info('<--- Round {0}: Tear down'.format(i))
             for index, ia in enumerate(ias):
-                ia.stop_image_acquisition()
+                ia.stop_acquisition()
                 self._logger.info(
                     'Device #{0} has stopped image acquisition.'.format(index)
                 )
@@ -196,7 +196,7 @@ def test_timeout_on_fetching_buffer(self):
         ia = self.harvester.create_image_acquirer(0)
 
         # We do not start image acquisition:
-        #ia.start_image_acquisition()
+        #ia.start_acquisition()
 
         timeout = 3  # sec
 
@@ -210,7 +210,7 @@ def test_timeout_on_fetching_buffer(self):
         ia.remote_device.node_map.TriggerSource.value = 'Software'
 
         # We're ready to start image acquisition:
-        ia.start_image_acquisition()
+        ia.start_acquisition()
 
         with self.assertRaises(TimeoutException):
             # Try to fetch a buffer but the IA will raise TimeoutException
@@ -228,7 +228,7 @@ def test_timeout_on_fetching_buffer(self):
         buffer.queue()
 
         # Now we stop image acquisition:
-        ia.stop_image_acquisition()
+        ia.stop_acquisition()
         ia.destroy()
 
     def test_stop_start_and_stop(self):
@@ -237,17 +237,17 @@ def test_stop_start_and_stop(self):
 
         # It's not necessary but we stop image acquisition first;
         #
-        ia.stop_image_acquisition()
+        ia.stop_acquisition()
 
         # Then start it:
-        ia.start_image_acquisition()
+        ia.start_acquisition()
 
         # Fetch a buffer to make sure it's working:
         with ia.fetch_buffer() as buffer:
             self._logger.info('{0}'.format(buffer))
 
         # Then stop image acquisition:
-        ia.stop_image_acquisition()
+        ia.stop_acquisition()
 
         # And destroy the ImageAcquirer:
         ia.destroy()
@@ -272,13 +272,13 @@ def test_num_holding_filled_buffers(self):
                 self.ia.num_filled_buffers_to_hold = num_images
 
                 # Start image acquisition:
-                self.ia.start_image_acquisition()
+                self.ia.start_acquisition()
 
                 # Run a test:
                 test(num_images)
 
                 # Stop image acquisition:
-                self.ia.stop_image_acquisition()
+                self.ia.stop_acquisition()
 
     def _test_issue_120_1(self, num_images):
         # Make sure num_holding_filled_buffers is incremented every trigger:
@@ -387,7 +387,7 @@ def test_issue_61(self):
         self.assertEqual(0, len(self._buffers))
 
         # Start image acquisition:
-        self.ia.start_image_acquisition()
+        self.ia.start_acquisition()
 
         # Trigger the target device:
         num_images = self.ia.num_buffers
@@ -408,7 +408,7 @@ def test_issue_61(self):
         self._buffers.clear()
 
         # Then stop image acquisition:
-        self.ia.stop_image_acquisition()
+        self.ia.stop_acquisition()
 
     def _callback_on_new_buffer_arrival(self):
         # Fetch a buffer and keep it:
@@ -537,16 +537,16 @@ def __init__(self, message_queue=None, cti_file_path=None):
 
     def run(self):
         h = Harvester()
-        h.add_cti_file(self._cti_file_path)
-        h.update_device_info_list()
+        h.add_file(self._cti_file_path)
+        h.update()
         try:
             ia = h.create_image_acquirer(0)
         except:
             # Transfer the exception anyway:
             self._message_queue.put(sys.exc_info())
         else:
-            ia.start_image_acquisition()
-            ia.stop_image_acquisition()
+            ia.start_acquisition()
+            ia.stop_acquisition()
             ia.destroy()
             h.reset()
 
@@ -605,8 +605,8 @@ def test_issue_85(self):
 
         #
         with Harvester() as h:
-            h.add_cti_file(self._cti_file_path)
-            h.update_device_info_list()
+            h.add_file(self._cti_file_path)
+            h.update()
             with h.create_image_acquirer(0):
                 # Check if XML files have been stored in the expected
                 # directory: