[DOP-16175] Add versionadded and vesionchanged directives

MobileTeleSystems · May 23, 2024 · 09f84d9 · 09f84d9
1 parent 22818a5
commit 09f84d9
Show file tree

Hide file tree

Showing 87 changed files with 659 additions and 88 deletions.
diff --git a/docs/changelog/0.10.0.rst b/docs/changelog/0.10.0.rst
@@ -44,7 +44,7 @@ Breaking Changes
     - ``HWM`` classes used by previous onETL versions were moved from ``etl_entities`` to ``etl_entities.old_hwm`` submodule. They are here for compatibility reasons, but are planned to be removed in ``etl-entities`` v3 release.
     - New ``HWM`` classes have flat structure instead of nested.
     - New ``HWM`` classes have mandatory ``name`` attribute (it was known as ``qualified_name`` before).
-    - Type aliases used while serializing and deserializing ``HWM`` objects to ``dict`` representation were changed too: ``int`` -> ``column_int``.
+    - Type aliases used while serializing and deserializing ``HWM`` objects to ``dict`` representation were changed too: ``int`` → ``column_int``.
 
   To make migration simpler, you can use new method:
 
@@ -53,7 +53,7 @@ Breaking Changes
     old_hwm = OldIntHWM(...)
     new_hwm = old_hwm.as_new_hwm()
 
-  Which automatically converts all fields from old structure to new one, including ``qualified_name`` -> ``name``.
+  Which automatically converts all fields from old structure to new one, including ``qualified_name`` → ``name``.
 
 - **Breaking changes:**
 

diff --git a/docs/changelog/0.8.0.rst b/docs/changelog/0.8.0.rst
@@ -62,8 +62,6 @@ Breaking Changes
       from onetl.core import DBWriter
       from onetl.core import FileDownloader
       from onetl.core import FileUploader
-      from onetl.core import FileResult
-      from onetl.core import FileSet
 
   with new modules ``onetl.db`` and ``onetl.file``:
 
@@ -76,10 +74,6 @@ Breaking Changes
       from onetl.file import FileDownloader
       from onetl.file import FileUploader
 
-      # not a public interface
-      from onetl.file.file_result import FileResult
-      from onetl.file.file_set import FileSet
-
   Imports from old module ``onetl.core`` still can be used, but marked as deprecated. Module will be removed in v1.0.0. (:github:pull:`46`)
 
 

diff --git a/docs/changelog/0.9.0.rst b/docs/changelog/0.9.0.rst
@@ -6,43 +6,43 @@ Breaking Changes
 
 - Rename methods:
 
-  * ``DBConnection.read_df`` -> ``DBConnection.read_source_as_df``
-  * ``DBConnection.write_df`` -> ``DBConnection.write_df_to_target`` (:github:pull:`66`)
+  * ``DBConnection.read_df`` → ``DBConnection.read_source_as_df``
+  * ``DBConnection.write_df`` → ``DBConnection.write_df_to_target`` (:github:pull:`66`)
 - Rename classes:
 
-  * ``HDFS.slots`` -> ``HDFS.Slots``
-  * ``Hive.slots`` -> ``Hive.Slots``
+  * ``HDFS.slots`` → ``HDFS.Slots``
+  * ``Hive.slots`` → ``Hive.Slots``
 
   Old names are left intact, but will be removed in v1.0.0 (:github:pull:`103`)
 - Rename options to make them self-explanatory:
 
-  * ``Hive.WriteOptions(mode="append")`` -> ``Hive.WriteOptions(if_exists="append")``
-  * ``Hive.WriteOptions(mode="overwrite_table")`` -> ``Hive.WriteOptions(if_exists="replace_entire_table")``
-  * ``Hive.WriteOptions(mode="overwrite_partitions")`` -> ``Hive.WriteOptions(if_exists="replace_overlapping_partitions")``
+  * ``Hive.WriteOptions(mode="append")`` → ``Hive.WriteOptions(if_exists="append")``
+  * ``Hive.WriteOptions(mode="overwrite_table")`` → ``Hive.WriteOptions(if_exists="replace_entire_table")``
+  * ``Hive.WriteOptions(mode="overwrite_partitions")`` → ``Hive.WriteOptions(if_exists="replace_overlapping_partitions")``
 
-  * ``JDBC.WriteOptions(mode="append")`` -> ``JDBC.WriteOptions(if_exists="append")``
-  * ``JDBC.WriteOptions(mode="overwrite")`` -> ``JDBC.WriteOptions(if_exists="replace_entire_table")``
+  * ``JDBC.WriteOptions(mode="append")`` → ``JDBC.WriteOptions(if_exists="append")``
+  * ``JDBC.WriteOptions(mode="overwrite")`` → ``JDBC.WriteOptions(if_exists="replace_entire_table")``
 
-  * ``Greenplum.WriteOptions(mode="append")`` -> ``Greenplum.WriteOptions(if_exists="append")``
-  * ``Greenplum.WriteOptions(mode="overwrite")`` -> ``Greenplum.WriteOptions(if_exists="replace_entire_table")``
+  * ``Greenplum.WriteOptions(mode="append")`` → ``Greenplum.WriteOptions(if_exists="append")``
+  * ``Greenplum.WriteOptions(mode="overwrite")`` → ``Greenplum.WriteOptions(if_exists="replace_entire_table")``
 
-  * ``MongoDB.WriteOptions(mode="append")`` -> ``Greenplum.WriteOptions(if_exists="append")``
-  * ``MongoDB.WriteOptions(mode="overwrite")`` -> ``Greenplum.WriteOptions(if_exists="replace_entire_collection")``
+  * ``MongoDB.WriteOptions(mode="append")`` → ``Greenplum.WriteOptions(if_exists="append")``
+  * ``MongoDB.WriteOptions(mode="overwrite")`` → ``Greenplum.WriteOptions(if_exists="replace_entire_collection")``
 
-  * ``FileDownloader.Options(mode="error")`` -> ``FileDownloader.Options(if_exists="error")``
-  * ``FileDownloader.Options(mode="ignore")`` -> ``FileDownloader.Options(if_exists="ignore")``
-  * ``FileDownloader.Options(mode="overwrite")`` -> ``FileDownloader.Options(if_exists="replace_file")``
-  * ``FileDownloader.Options(mode="delete_all")`` -> ``FileDownloader.Options(if_exists="replace_entire_directory")``
+  * ``FileDownloader.Options(mode="error")`` → ``FileDownloader.Options(if_exists="error")``
+  * ``FileDownloader.Options(mode="ignore")`` → ``FileDownloader.Options(if_exists="ignore")``
+  * ``FileDownloader.Options(mode="overwrite")`` → ``FileDownloader.Options(if_exists="replace_file")``
+  * ``FileDownloader.Options(mode="delete_all")`` → ``FileDownloader.Options(if_exists="replace_entire_directory")``
 
-  * ``FileUploader.Options(mode="error")`` -> ``FileUploader.Options(if_exists="error")``
-  * ``FileUploader.Options(mode="ignore")`` -> ``FileUploader.Options(if_exists="ignore")``
-  * ``FileUploader.Options(mode="overwrite")`` -> ``FileUploader.Options(if_exists="replace_file")``
-  * ``FileUploader.Options(mode="delete_all")`` -> ``FileUploader.Options(if_exists="replace_entire_directory")``
+  * ``FileUploader.Options(mode="error")`` → ``FileUploader.Options(if_exists="error")``
+  * ``FileUploader.Options(mode="ignore")`` → ``FileUploader.Options(if_exists="ignore")``
+  * ``FileUploader.Options(mode="overwrite")`` → ``FileUploader.Options(if_exists="replace_file")``
+  * ``FileUploader.Options(mode="delete_all")`` → ``FileUploader.Options(if_exists="replace_entire_directory")``
 
-  * ``FileMover.Options(mode="error")`` -> ``FileMover.Options(if_exists="error")``
-  * ``FileMover.Options(mode="ignore")`` -> ``FileMover.Options(if_exists="ignore")``
-  * ``FileMover.Options(mode="overwrite")`` -> ``FileMover.Options(if_exists="replace_file")``
-  * ``FileMover.Options(mode="delete_all")`` -> ``FileMover.Options(if_exists="replace_entire_directory")``
+  * ``FileMover.Options(mode="error")`` → ``FileMover.Options(if_exists="error")``
+  * ``FileMover.Options(mode="ignore")`` → ``FileMover.Options(if_exists="ignore")``
+  * ``FileMover.Options(mode="overwrite")`` → ``FileMover.Options(if_exists="replace_file")``
+  * ``FileMover.Options(mode="delete_all")`` → ``FileMover.Options(if_exists="replace_entire_directory")``
 
   Old names are left intact, but will be removed in v1.0.0 (:github:pull:`108`)
 - Rename ``onetl.log.disable_clients_logging()`` to ``onetl.log.setup_clients_logging()``. (:github:pull:`120`)

diff --git a/docs/hooks/index.rst b/docs/hooks/index.rst
@@ -3,6 +3,8 @@
 Hooks
 =====
 
+.. versionadded:: 0.6.0
+
 .. toctree::
     :maxdepth: 1
     :caption: Hooks

diff --git a/docs/plugins.rst b/docs/plugins.rst
@@ -3,6 +3,8 @@
 Plugins
 =======
 
+.. versionadded:: 0.6.0
+
 What are plugins?
 -----------------
 
@@ -82,6 +84,8 @@ like :ref:`hook-decorator`, it will be executed during this import.
 How to enable/disable plugins?
 ------------------------------
 
+.. versionadded:: 0.7.0
+
 Disable/enable all plugins
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/onetl/base/base_db_connection.py b/onetl/base/base_db_connection.py
@@ -132,6 +132,9 @@ def read_source_as_df(
     ) -> DataFrame:
         """
         Reads the source to dataframe. |support_hooks|
+
+        .. versionchanged:: 0.9.0
+            Renamed ``read_df`` → ``read_source_as_df``
         """
 
     @abstractmethod
@@ -142,4 +145,7 @@ def write_df_to_target(
     ) -> None:
         """
         Saves dataframe to a specific target. |support_hooks|
+
+        .. versionchanged:: 0.9.0
+            Renamed ``write_df`` → ``write_df_to_target``
         """
diff --git a/onetl/base/base_file_connection.py b/onetl/base/base_file_connection.py
@@ -15,13 +15,17 @@
 
 class BaseFileConnection(BaseConnection):
     """
-    Implements generic methods for files and directories manipulation on some filesystem (usually remote)
+    Implements generic methods for files and directories manipulation on some filesystem (usually remote).
+
+    .. versionadded:: 0.8.0
     """
 
     @abstractmethod
     def path_exists(self, path: os.PathLike | str) -> bool:
         """
-        Check if specified path exists on remote filesystem. |support_hooks|
+        Check if specified path exists on remote filesystem. |support_hooks|.
+
+        .. versionadded:: 0.8.0
 
         Parameters
         ----------
@@ -48,6 +52,8 @@ def is_file(self, path: os.PathLike | str) -> bool:
         """
         Check if specified path is a file. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -76,6 +82,8 @@ def is_dir(self, path: os.PathLike | str) -> bool:
         """
         Check if specified path is a directory. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -104,6 +112,8 @@ def get_stat(self, path: os.PathLike | str) -> PathStatProtocol:
         """
         Returns stats for a specific path. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -132,6 +142,8 @@ def resolve_dir(self, path: os.PathLike | str) -> PathWithStatsProtocol:
         """
         Returns directory at specific path, with stats. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -164,6 +176,8 @@ def resolve_file(self, path: os.PathLike | str) -> PathWithStatsProtocol:
         """
         Returns file at specific path, with stats. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -196,6 +210,8 @@ def create_dir(self, path: os.PathLike | str) -> PathWithStatsProtocol:
         """
         Creates directory tree on remote filesystem. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -229,6 +245,8 @@ def remove_file(self, path: os.PathLike | str) -> bool:
 
             Supports only one file removal per call. Directory removal is **NOT** supported, use :obj:`~remove_dir` instead.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -261,6 +279,8 @@ def remove_dir(self, path: os.PathLike | str, recursive: bool = False) -> bool:
 
         If directory does not exist, no exception is raised.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -305,6 +325,8 @@ def rename_file(
 
             Supports only one file move per call. Directory move/rename is **NOT** supported.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         source_file_path : str or :obj:`os.PathLike`
@@ -353,6 +375,8 @@ def list_dir(
         """
         Return list of child files/directories in a specific directory. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -400,6 +424,8 @@ def walk(
 
         Just like :obj:`os.walk`, but with additional filter/limit logic.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         root : str or :obj:`os.PathLike`
@@ -458,6 +484,8 @@ def download_file(
 
             Supports only one file download per call. Directory download is **NOT** supported, use :ref:`file-downloader` instead.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         remote_file_path : str or :obj:`os.PathLike`
@@ -518,6 +546,8 @@ def upload_file(
 
             Supports only one file upload per call. Directory upload is **NOT** supported, use :ref:`file-uploader` instead.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         local_file_path : str or :obj:`os.PathLike`
@@ -569,6 +599,8 @@ def read_text(self, path: os.PathLike | str, encoding: str = "utf-8") -> str:
         r"""
         Returns string content of a file at specific path. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -601,6 +633,8 @@ def read_bytes(self, path: os.PathLike | str) -> bytes:
         """
         Returns binary content of a file at specific path. |support_hooks|
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -639,6 +673,8 @@ def write_text(
 
             If file already exists, its content will be replaced.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`
@@ -681,6 +717,8 @@ def write_bytes(self, path: os.PathLike | str, content: bytes) -> PathWithStatsP
 
             If file already exists, its content will be replaced.
 
+        .. versionadded:: 0.8.0
+
         Parameters
         ----------
         path : str or :obj:`os.PathLike`