Merge pull request #51 from cerbernetix/release-0.10.0

Release 0.10.0

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2024-05-01
+
+### Added
+
+-   `get_combinations(values, length, start, stop, step, offset, indexes)`: Computes combinations given a set of values and a length.
+-   `minmax(*args)`: Returns with the min and the max value from the given arguments.
+-   `quantity(quota, total)`: Gets a quantity with respect to a quota applied to a total.
+
+### Changed
+
+-   Add options to JSONFile implementation (`sort_keys`, `skip_keys`, `ensure_ascii`, `separators`, `strict`).
+-   Set the default CSV dialect to `'excel'` when writing (this reflects the default value from the Python library).
+-   Set the default CSV dialect to `'auto'` when reading (the dialect will be sniffed from the first few rows).
+
+### Fixed
+
+-   Fix the link to the documentation in the readme.
+-   Inconsistent return value in the log action.
+-   Too many branches and returns in the file checker.
+-   A few linter issues.
+-   Typo in the instructions for the installation in dev mode.
+
 ## [0.9.1] - 2023-10-27
 
 ### Fixed

README.md

@@ -49,7 +49,7 @@ pip install --upgrade git+ssh://git@github.com/cerbernetix/py-toolbox.git@develo
 
 `py-toolbox` offers several utilities per domain.
 
-Please refer to the [documentation](./docs/README.md) for more information.
+Please refer to the [documentation](https://github.com/cerbernetix/py-toolbox/blob/main/docs/README.md) for more information.
 
 ## <a name='Development'></a>Development
 
@@ -64,7 +64,7 @@ Then, create the virtual env and install the dependencies:
 ```sh
 cd py-toolbox
 python3 -m venv ".venv"
-source "./venv/bin/activate"
+source ".venv/bin/activate"
 pip install -r requirements.txt
 pip install -e .
 ```

docs/README.md

@@ -23,6 +23,7 @@
 - [`toolbox.logging.log_file`](./toolbox.logging.log_file.md#module-toolboxlogginglog_file): A custom logger that writes directly to a file.
 - [`toolbox.math`](./toolbox.math.md#module-toolboxmath): A collection of Math related tools.
 - [`toolbox.math.combination`](./toolbox.math.combination.md#module-toolboxmathcombination): A set of functions for working with combinations.
+- [`toolbox.math.utils`](./toolbox.math.utils.md#module-toolboxmathutils): A set of helper functions related to math.
 - [`toolbox.testing`](./toolbox.testing.md#module-toolboxtesting): The `testing` package provides utilities for testing purpose.
 - [`toolbox.testing.decorators`](./toolbox.testing.decorators.md#module-toolboxtestingdecorators): A collection of decorators for testing purpose.
 - [`toolbox.testing.test_case`](./toolbox.testing.test_case.md#module-toolboxtestingtest_case): Extends the default Python TestCase with more assertions.
@@ -73,6 +74,9 @@
 - [`config.setup_file_logging`](./toolbox.logging.config.md#function-setup_file_logging): Setup the application log to a file logger.
 - [`combination.get_combination_from_rank`](./toolbox.math.combination.md#function-get_combination_from_rank): Gets the combination corresponding to a particular rank.
 - [`combination.get_combination_rank`](./toolbox.math.combination.md#function-get_combination_rank): Gets the rank of a combination.
+- [`combination.get_combinations`](./toolbox.math.combination.md#function-get_combinations): Yields lists of combined values according to the combinations defined by the lengths.
+- [`utils.minmax`](./toolbox.math.utils.md#function-minmax): Returns with the min and the max value from the arguments.
+- [`utils.quantity`](./toolbox.math.utils.md#function-quantity): Gets a quantity with respect to a quota applied to a total.
 - [`decorators.test_cases`](./toolbox.testing.decorators.md#function-test_cases): Creates a decorator for parametric test cases.
 
 

docs/toolbox.files.csv_file.md

@@ -50,22 +50,23 @@ with file:
 ---------------
 - **CSV_ENCODING**
 - **CSV_DIALECT**
+- **CSV_AUTO**
 - **CSV_SAMPLE_SIZE**
 - **CSV_READER_PARAMS**
 - **CSV_WRITER_PARAMS**
 - **FILE_OPEN_PARAMS**
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L475"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L479"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_csv_file`
 
 ```python
 read_csv_file(
     filename: 'str',
     encoding: 'str' = 'utf-8',
-    dialect: 'str' = 'unix',
+    dialect: 'str' = 'auto',
     iterator: 'bool' = False,
     **kwargs
 ) → Iterable[dict | list]
@@ -81,7 +82,7 @@ The returned value can be either a list (default) or an iterator (when the itera
 
  - <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>`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_AUTO. 
  - <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. 
@@ -123,7 +124,7 @@ for row in read_csv_file('path/to/file', iterator=True):
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L547"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L551"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `write_csv_file`
 
@@ -132,7 +133,7 @@ write_csv_file(
     filename: 'str',
     data: 'Iterable[dict | list]',
     encoding: 'str' = 'utf-8',
-    dialect: 'str' = 'unix',
+    dialect: 'str' = 'excel',
     **kwargs
 ) → int
 ```
@@ -189,7 +190,7 @@ write_csv_file('path/to/file', csv_data, encoding='UTF-8', dialect='excel')
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L620"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L624"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_zip_csv`
 
@@ -199,7 +200,7 @@ read_zip_csv(
     filename: 'str' = None,
     encoding: 'str' = 'utf-8',
     decoding_errors: 'str' = 'ignore',
-    dialect: 'str' = 'unix',
+    dialect: 'str' = 'auto',
     iterator: 'bool' = False,
     **kwargs
 ) → Iterable[dict | list]
@@ -217,7 +218,7 @@ The returned value can be either a list (default) or an iterator (when the itera
  - <b>`filename`</b> (str, optional):  The name of the file to extract from the zip If omitted, the first file having a '.csv' extension will be selected. Defaults to None. 
  - <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>`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_AUTO. 
  - <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. 
@@ -265,7 +266,7 @@ with open('path/to/file.zip', 'rb') as file:
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L93"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L97"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>class</kbd> `CSVFile`
 Offers a simple API for reading and writing CSV files. 
@@ -310,7 +311,7 @@ with file(create=True):
 csv = file.read_file()
 ``` 
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L134"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L138"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `__init__`
 
@@ -322,7 +323,7 @@ __init__(
     read: 'bool' = False,
     write: 'bool' = False,
     encoding: 'str' = 'utf-8',
-    dialect: 'str' = 'unix',
+    dialect: 'str' = 'auto',
     **kwargs
 )
 ```
@@ -339,7 +340,7 @@ Creates a file manager for CSV files.
  - <b>`read`</b> (bool, optional):  Expect to also read the file. Defaults to False. 
  - <b>`write`</b> (bool, optional):  Expect to also write to the file. Defaults to False. 
  - <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>`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_AUTO for reading or to CSV_DIALECT for writing. 
  - <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 by the writer to escape the delimiter if quoting is set to QUOTE_NONE and the quotechar if doublequote is False. On reading, the escapechar removes any special meaning from the following character. Defaults to None, which disables escaping. 
@@ -566,7 +567,7 @@ size = file.size
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L263"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L267"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `close`
 
@@ -604,7 +605,7 @@ file.close()
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L363"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L367"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `read`
 
@@ -648,7 +649,7 @@ csv_data = [row for row in file]
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L294"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L298"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `read_file`
 
@@ -699,7 +700,7 @@ for row in file.read_file(iterator=True):
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L414"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L418"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>method</kbd> `write`
 
@@ -746,7 +747,7 @@ with file(create=True):
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/csv_file.py#L332"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/csv_file.py#L336"><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.file.md

@@ -9,7 +9,9 @@ A collection of utilities for accessing files.
 
 **Examples:**
  ```python
-from cerbernetix.toolbox.files import fetch_content, get_file_mode, read_file, read_zip_file, write_file
+from cerbernetix.toolbox.files import (
+     fetch_content, get_file_mode, read_file, read_zip_file, write_file
+)
 
 # get_file_mode() is used to build a file access mode.
 # For example to create a text file:
@@ -43,7 +45,7 @@ content = read_zip_file(data)
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/file.py#L43"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/file.py#L46"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `get_file_mode`
 
@@ -107,7 +109,7 @@ with open('path/to/file', get_file_mode(binary=True)) as file:
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/file.py#L121"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/file.py#L124"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_file`
 
@@ -159,7 +161,7 @@ data = read_file('path/to/file', binary=True)
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/file.py#L163"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/file.py#L166"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `write_file`
 
@@ -214,7 +216,7 @@ write_file('path/to/file', data, binary=True)
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/file.py#L208"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/file.py#L211"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `fetch_content`
 
@@ -240,7 +242,8 @@ Under the hood, it relies on requests to process the query.
  - <b>`url`</b> (str):  The URL of the content to fetch. 
  - <b>`binary`</b> (bool):  Tells if the content is binary (True) or text (False). When True, the function will return a bytes sequence, otherwise it will return a string sequence. 
  - <b>`timeout`</b> (int | tuple):  The request timeout. Defaults to (6, 30). 
- - <b>`**kwargs`</b>:  Additional parameters for the GET request. For more info, see [requests/api](https://requests.readthedocs.io/en/latest/api/). 
+ - <b>`**kwargs`</b>:  Additional parameters for the GET request. For more info, see 
+ - <b>`[requests/api](https`</b>: //requests.readthedocs.io/en/latest/api/). 
 
 
 
@@ -277,7 +280,7 @@ data = fetch_content("http://example.com/data", binary=True)
 
 ---
 
-<a href="../src/cerbernetix/toolbox/files/file.py#L259"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/cerbernetix/toolbox/files/file.py#L263"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ## <kbd>function</kbd> `read_zip_file`