Merge pull request #23 from jsconan/release-0.7.0

Release 0.7.0

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2023-09-14
+
+### Changed
+
+-   `read_pickle_file(...)` and `PickleFile.read_file()` - Can either return a list (default) or an iterator (when the iterator parameter is True).
+-   `read_csv_file(...)` and `CSVFile.read_file()` - Can either return a list (default) or an iterator (when the iterator parameter is True).
+-   `read_zip_csv(buffer, ...)` - Can either return a list (default) or an iterator (when the iterator parameter is True).
+
 ## [0.6.0] - 2023-09-14
 
 ### Added

docs/toolbox.config.config.md

@@ -632,7 +632,7 @@ set_option(
     value: Any = None,
     default: Any = None,
     description: str = None,
-    mapper: Callable = <function passthrough at 0x1030c9580>,
+    mapper: Callable = <function passthrough at 0x101b45580>,
     choices: list = None
 ) → None
 ```

docs/toolbox.config.config_option.md

@@ -125,7 +125,7 @@ __init__(
     value: 'Any' = None,
     default: 'Any' = None,
     description: 'str' = '',
-    mapper: 'ValueMapper' = <function passthrough at 0x1030c9580>,
+    mapper: 'ValueMapper' = <function passthrough at 0x101b45580>,
     choices: 'Iterable' = None
 ) → None
 ```

docs/toolbox.files.csv_file.md

@@ -57,7 +57,7 @@ with file:
 
 ---
 
-<a href="../toolbox/files/csv_file.py#L461"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/csv_file.py#L475"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_csv_file`
 
@@ -66,19 +66,23 @@ read_csv_file(
     filename: 'str',
     encoding: 'str' = 'utf-8',
     dialect: 'str' = 'unix',
+    iterator: 'bool' = False,
     **kwargs
-) → list[dict | list]
+) → Iterable[dict | list]
 ```
 
 Reads a CSV content from a file. 
 
+The returned value can be either a list (default) or an iterator (when the iterator parameter is True). 
+
 
 
 **Args:**
 
  - <b>`filename`</b> (str):  The path to the file to read. 
  - <b>`encoding`</b> (str, optional):  The file encoding. Defaults to CSV_ENCODING. 
  - <b>`dialect`</b> (str, optional):  The CSV dialect to use. If 'auto' is given, the reader will try detecting the CSV dialect by reading a sample at the head of the file. Defaults to CSV_DIALECT. 
+ - <b>`iterator`</b> (bool, optional):  When True, the function will return an iterator instead of a list. Defaults to False. 
  - <b>`delimiter`</b> (str, optional):  A one-character string used to separate fields. Defaults to ','. 
  - <b>`doublequote`</b> (bool, optional):  Controls how instances of quotechar appearing inside a field should themselves be quoted. When True, the character is doubled. When False, the escapechar is used as a prefix to the quotechar. Defaults to True. 
  - <b>`escapechar`</b> (str, optional):   A one-character string used to removes any special meaning from the following character. Defaults to None, which disables escaping. 
@@ -101,7 +105,7 @@ For reading headless CSV, set fieldnames to False.
 
 **Returns:**
 
- - <b>`list[dict | list]`</b>:  The data read from the CSV file. 
+ - <b>`Iterable[dict | list]`</b>:  The data read from the CSV file. 
 
 
 
@@ -110,12 +114,16 @@ For reading headless CSV, set fieldnames to False.
 from toolbox.files import read_csv_file
 
 csv_data = read_csv_file('path/to/file', encoding='UTF-8', dialect='excel')
+
+# An iterator can be returned instead of a list
+for row in read_csv_file('path/to/file', iterator=True):
+    print(row)
 ``` 
 
 
 ---
 
-<a href="../toolbox/files/csv_file.py#L523"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/csv_file.py#L547"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `write_csv_file`
 
@@ -181,7 +189,7 @@ write_csv_file('path/to/file', csv_data, encoding='UTF-8', dialect='excel')
 
 ---
 
-<a href="../toolbox/files/csv_file.py#L596"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/csv_file.py#L620"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_zip_csv`
 
@@ -192,12 +200,15 @@ read_zip_csv(
     encoding: 'str' = 'utf-8',
     decoding_errors: 'str' = 'ignore',
     dialect: 'str' = 'unix',
+    iterator: 'bool' = False,
     **kwargs
-) → list[dict | list]
+) → Iterable[dict | list]
 ```
 
 Reads a CSV content from a Zip. 
 
+The returned value can be either a list (default) or an iterator (when the iterator parameter is True). 
+
 
 
 **Args:**
@@ -207,6 +218,7 @@ Reads a CSV content from a Zip.
  - <b>`encoding`</b> (str, optional):  The file encoding. Defaults to CSV_ENCODING. 
  - <b>`decoding_errors`</b> (str, optional):  Controls how decoding errors are handled. If 'strict', a UnicodeError exception is raised. Other possible values are 'ignore', 'replace', and any other name registered via codecs.register_error(). See Error Handlers for details. Defaults to "ignore". 
  - <b>`dialect`</b> (str, optional):  The CSV dialect to use. If 'auto' is given, the reader will try detecting the CSV dialect by reading a sample at the head of the file. Defaults to CSV_DIALECT. 
+ - <b>`iterator`</b> (bool, optional):  When True, the function will return an iterator instead of a list. Defaults to False. 
  - <b>`delimiter`</b> (str, optional):  A one-character string used to separate fields. Defaults to ','. 
  - <b>`doublequote`</b> (bool, optional):  Controls how instances of quotechar appearing inside a field should themselves be quoted. When True, the character is doubled. When False, the escapechar is used as a prefix to the quotechar. Defaults to True. 
  - <b>`escapechar`</b> (str, optional):   A one-character string used to removes any special meaning from the following character. Defaults to None, which disables escaping. 
@@ -228,7 +240,7 @@ For reading headless CSV, set fieldnames to False.
 
 **Returns:**
 
- - <b>`list[dict | list]`</b>:  The data read from the CSV file. 
+ - <b>`Iterable[dict | list]`</b>:  The data read from the CSV file. 
 
 
 
@@ -244,6 +256,10 @@ with open('path/to/file.zip', 'rb') as file:
 
     # The specified CSV file will be extracted from the archive
     csv_data = read_zip_csv(zip, 'foo.csv')
+
+    # An iterator can be returned instead of a list
+    for row in read_zip_csv(zip, iterator=True):
+         print(row)
 ``` 
 
 
@@ -588,7 +604,7 @@ file.close()
 
 ---
 
-<a href="../toolbox/files/csv_file.py#L349"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/csv_file.py#L363"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `read`
 
@@ -637,15 +653,23 @@ csv_data = [row for row in file]
 ### <kbd>method</kbd> `read_file`
 
 ```python
-read_file() → list[dict | list]
+read_file(iterator: 'bool' = False) → Iterable[dict | list]
 ```
 
 Reads all the content from the file. 
 
+The returned value can be either a list (default) or an iterator (when the iterator parameter is True). 
+
 Note: If the file was already opened, it is first closed, then opened in read mode. 
 
 
 
+**Args:**
+
+ - <b>`iterator`</b> (bool, optional):  When True, the function will return an iterator instead of a list. Defaults to False. 
+
+
+
 **Raises:**
 
  - <b>`OSError`</b>:  If the file cannot be read. 
@@ -655,7 +679,7 @@ Note: If the file was already opened, it is first closed, then opened in read mo
 
 **Returns:**
 
- - <b>`list[dict | list]`</b>:  The content read from the file. 
+ - <b>`Iterable[dict | list]`</b>:  The content read from the file. 
 
 
 
@@ -667,11 +691,15 @@ file = CSVFile('path/to/filename')
 
 # A file can be read all at once
 data = file.read_file()
+
+# An iterator can be returned instead of a list
+for row in file.read_file(iterator=True):
+    print(row)
 ``` 
 
 ---
 
-<a href="../toolbox/files/csv_file.py#L400"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/csv_file.py#L414"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `write`
 
@@ -718,7 +746,7 @@ with file(create=True):
 
 ---
 
-<a href="../toolbox/files/csv_file.py#L318"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/csv_file.py#L332"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `write_file`
 

docs/toolbox.files.pickle_file.md

@@ -54,21 +54,24 @@ with file:
 
 ---
 
-<a href="../toolbox/files/pickle_file.py#L328"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/pickle_file.py#L342"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_pickle_file`
 
 ```python
-read_pickle_file(filename: 'str', **kwargs) → list
+read_pickle_file(filename: 'str', iterator: 'bool' = False, **kwargs) → Iterable
 ```
 
 Loads a list of objects from a file. 
 
+The returned value can be either a list (default) or an iterator (when the iterator parameter is True). 
+
 
 
 **Args:**
 
  - <b>`filename`</b> (str):  The path to the file to read. 
+ - <b>`iterator`</b> (bool, optional):  When True, the function will return an iterator instead of a list. Defaults to False. 
  - <b>`fix_imports`</b> (bool, optional):  If fix_imports is true and protocol is less than 3, pickle will try to map the new Python 3 names to the old module names used in Python 2, so that the pickle data stream is readable with Python 2. Defaults to True. 
  - <b>`encoding`</b> (str, optional):  Tell pickle how to decode 8-bit string instances pickled by Python 2. The encoding can be ‘bytes’ to read these 8-bit string instances as bytes objects. Using encoding='latin1' is required for unpickling NumPy arrays and instances of datetime, date and time pickled by Python 2. Defaults to ‘ASCII’. 
  - <b>`errors`</b> (str, optional):  Tell pickle how to decode 8-bit string instances pickled by Python 2. Defaults to ‘strict’. 
@@ -85,7 +88,7 @@ Loads a list of objects from a file.
 
 **Returns:**
 
- - <b>`list`</b>:  The list of objects read from the file. 
+ - <b>`Iterable`</b>:  The list of objects read from the file. 
 
 
 
@@ -94,12 +97,16 @@ Loads a list of objects from a file.
 from toolbox.files import read_pickle_file
 
 data = read_pickle_file('path/to/file')
+
+# An iterator can be returned instead of a list
+for obj in read_pickle_file('path/to/file', iterator=True):
+    print(obj
 ``` 
 
 
 ---
 
-<a href="../toolbox/files/pickle_file.py#L369"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/pickle_file.py#L392"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `write_pickle_file`
 
@@ -432,7 +439,7 @@ size = file.size
 
 ---
 
-<a href="../toolbox/files/pickle_file.py#L260"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/pickle_file.py#L274"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `read`
 
@@ -481,15 +488,23 @@ data = [obj for obj in file]
 ### <kbd>method</kbd> `read_file`
 
 ```python
-read_file() → list
+read_file(iterator: 'bool' = False) → Iterable
 ```
 
 Reads all the content from the file. 
 
+The returned value can be either a list (default) or an iterator (when the iterator parameter is True). 
+
 Note: If the file was already opened, it is first closed, then opened in read mode. 
 
 
 
+**Args:**
+
+ - <b>`iterator`</b> (bool, optional):  When True, the function will return an iterator instead of a list. Defaults to False. 
+
+
+
 **Raises:**
 
  - <b>`OSError`</b>:  If the file cannot be read. 
@@ -499,7 +514,7 @@ Note: If the file was already opened, it is first closed, then opened in read mo
 
 **Returns:**
 
- - <b>`list`</b>:  The content read from the file. 
+ - <b>`Iterable`</b>:  The content read from the file. 
 
 
 
@@ -511,11 +526,15 @@ file = PickleFile('path/to/filename')
 
 # A file can be read all at once
 data = file.read_file()
+
+# An iterator can be returned instead of a list
+for obj in file.read_file(iterator=True):
+    print(obj)
 ``` 
 
 ---
 
-<a href="../toolbox/files/pickle_file.py#L295"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/pickle_file.py#L309"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `write`
 
@@ -562,7 +581,7 @@ with file(create=True):
 
 ---
 
-<a href="../toolbox/files/pickle_file.py#L229"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../toolbox/files/pickle_file.py#L243"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `write_file`
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "py-toolbox"
-version = "0.6.0"
+version = "0.7.0"
 authors = [{ name = "Jean-Sébastien CONAN", email = "jsconan@gmail.com" }]
 description = "A set of utilities for Python projects"
 readme = "README.md"