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(
@@ -1574,7 +1588,7 @@ def __init__(
 
         #
         self._has_acquired_1st_image = False
-        self._is_acquiring_images = False
+        self._is_acquiring = False
         self._keep_latest = True
 
         # Determine the default value:
@@ -1759,10 +1773,14 @@ 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`.
         """
-        return self._is_acquiring_images
+        return self._is_acquiring
 
     @property
     def timeout_for_image_acquisition(self):
@@ -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.
 
@@ -1909,7 +1931,7 @@ def start_image_acquisition(self):
             pass
 
         # Start image acquisition.
-        self._is_acquiring_images = True
+        self._is_acquiring = True
 
         for data_stream in self._data_streams:
             data_stream.start_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
                     )
@@ -1965,7 +1987,7 @@ def worker_image_acquisition(self, context=None):
                     if self.keep_latest:
                         # We want to keep the latest ones:
                         with MutexLocker(self.thread_image_acquisition):
-                            if not self._is_acquiring_images:
+                            if not self._is_acquiring:
                                 return
 
                             if queue and queue.full():
@@ -2007,7 +2029,7 @@ def worker_image_acquisition(self, context=None):
                         # We want to keep the oldest ones:
                         with MutexLocker(self.thread_image_acquisition):
                             #
-                            if not self._is_acquiring_images:
+                            if not self._is_acquiring:
                                 return
 
                             #
@@ -2047,7 +2069,7 @@ def worker_image_acquisition(self, context=None):
 
                     #
                     with MutexLocker(self.thread_image_acquisition):
-                        if not self._is_acquiring_images:
+                        if not self._is_acquiring:
                             return
 
     def _update_chunk_data(self, buffer=None):
@@ -2112,7 +2134,7 @@ def fetch_buffer(self, *, timeout=0, is_raw=False, cycle_s=None):
 
         """
         #
-        if not self.is_acquiring_images():
+        if not self.is_acquiring():
             # Does not make any sense. Raise TimeoutException:
             raise TimeoutException
 
@@ -2257,14 +2279,18 @@ 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.
 
         :return: None.
         """
-        if self.is_acquiring_images():
+        if self.is_acquiring():
             #
-            self._is_acquiring_images = False
+            self._is_acquiring = False
 
             #
             if self.thread_image_acquisition.is_running():  # TODO
@@ -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()