Merge pull request #7 from delameter/dev

v1.8.0

.env.dist

@@ -1,3 +1,3 @@
-VERSION=1.7.4
+VERSION=1.8.0
 PYPI_USERNAME=__token__
 PYPI_PASSWORD= #api token

Makefile

@@ -18,7 +18,7 @@ GREEN  := $(shell tput -Txterm setaf 2)
 YELLOW := $(shell tput -Txterm setaf 3)
 RESET  := $(shell tput -Txterm sgr0)
 
-help:
+help:   ## Show this help
 	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v @fgrep | sed -Ee 's/^##\s*([^#]+)#*\s*(.*)/${YELLOW}\1${RESET}#\2/' -e 's/(.+):(#|\s)+(.+)/##   ${GREEN}\1${RESET}#\3/' | column -t -s '#'
 
 cleanup:
@@ -27,8 +27,22 @@ cleanup:
 prepare:
 	python3 -m pip install --upgrade build twine
 
+init-venv:
+	python3 -m venv venv
+	. venv/bin/activate
+	pip3 install -r requirements-dev.txt
+
 test: ## Run tests
-	PYTHONPATH=${PWD} python3 -s -m unittest -v
+	. venv/bin/activate
+	PYTHONPATH=${PWD} python3 -s tests/run.py
+
+test-verbose: ## Run tests with detailed output
+	. venv/bin/activate
+	PYTHONPATH=${PWD} python3 -s tests/run.py -v
+
+test-debug: ## Debug tests
+	. venv/bin/activate
+	PYTHONPATH=${PWD} python3 -s tests/run.py -vv
 
 set-version: ## Set new package version
 	@echo "Current version: ${YELLOW}${VERSION}${RESET}"
@@ -39,9 +53,11 @@ set-version: ## Set new package version
 	echo "Updated version: ${GREEN}$$VERSION${RESET}"
 
 generate-readme: ## Generate README file
+	. venv/bin/activate
 	PYTHONPATH=${PWD} python3 -s dev/readme/generate.py
 
 generate-thumbs: ## Generate README examples' thumbnails
+	. venv/bin/activate
 	PYTHONPATH=${PWD} python3 -s dev/readme/generate_thumbs.py
 
 build: ## Build module

README.md

@@ -146,9 +146,9 @@ print(orig_text, '\n', updated_text)
 As you can see, the update went well — we kept all the previously applied formatting. Of course, this method cannot be 100% applicable — for example, imagine that original text was colored blue. After the update "string" word won't be blue anymore, as we used `COLOR_OFF` escape sequence to neutralize our own yellow color. But it still can be helpful for a majority of cases (especially when text is generated and formatted by the same program and in one go).
 
 
-## API: module
+## API: pytermor
 
-### autof
+### > `autof`
 
 Signature: `autof(*params str|int|SequenceSGR) -> Format`
 
@@ -161,21 +161,21 @@ Each sequence param can be specified as:
 - integer param value
 - existing _SequenceSGR_ instance (params will be extracted)
 
-### build
+### > `build`
 
 Signature: `build(*params str|int|SequenceSGR) -> SequenceSGR`
 
 Create new _SequenceSGR_ with specified params. Resulting sequence params order is the same as argument order. Parameter specification is the same as for `autof`.
 
 _SequenceSGR_ with zero params was specifically implemented to translate into empty string and not into `\e[m`, which wolud make sense, but also would be very entangling, as it's equivavlent of `\e[0m` — **hard reset** sequence.
 
-### build_c256
+### > `build_c256`
 
 Signature:`build_c256(color: int, bg: bool = False) -> SequenceSGR`
 
 Create new _SequenceSGR_ that sets foreground color or background color, depending on `bg` value, in 256-color mode. Valid values for `color` are [0; 255], see more at [↗ xterm-256 colors](https://www.ditig.com/256-colors-cheat-sheet) page.
 
-### build_rgb
+### > `build_rgb`
 
 Signature:`build_rgb(r: int, g: int, b: int, bg: bool = False) -> SequenceSGR`
 
@@ -184,7 +184,7 @@ Create new _SequenceSGR_ that sets foreground color or background color, dependi
 
 ## API: SGR sequences
 
-Class representing SGR-mode ANSI escape sequence with varying amount of parameters.
+Class representing SGR-type ANSI escape sequence with varying amount of parameters.
 
 <details>
 <summary><b>Details</b> <i>(click)</i></summary>
@@ -262,7 +262,7 @@ print(msg)
 </details>
 
 
-## API: String filters
+## API: strf.StringFilter
 
 _StringFilter_ is common string modifier interface with dynamic configuration support.
 
@@ -293,7 +293,7 @@ print(formatted, '\n', replaced)
 
 ### Usage with helper
 
-Helper function `apply_filters` accepts both `StringFilter` implementation instances and types, but latter is not configurable and will be invoked using default settings.
+Helper function `apply_filters` accepts both `StringFilter` instances and types, but latter is not configurable and will be invoked using default settings.
 
 ```python3
 from pytermor import apply_filters, ReplaceNonAsciiBytes
@@ -307,6 +307,98 @@ print(ascii_and_binary, '\n', result)
 </details>
 
 
+## API: strf.fmtd
+
+Set of methods to make working with SGR sequences a bit easier.
+
+- `ljust_fmtd()`   SGR-formatting-aware implementation of str.ljust()
+- `rjust_fmtd()`  same, but for _str.rjust()_
+- `center_fmtd()` same, but for _str.center()_
+
+
+## API: numf.*
+
+`pytermor` also includes a few helper formatters for numbers.
+
+<details>
+<summary><b>Details</b> <i>(click)</i></summary>
+
+### &gt; `format_auto_float`
+
+Dynamically adjust decimal digit amount to fill the output string up with significant digits as much as possible. Universal solution for situations when you don't know exaclty what values will be displayed, but have fixed output width. Invocation: `format_auto_float(value, 4)`.
+
+| value       |  result    |
+| ----------: | ---------- |
+| **1&nbsp;234.56** |  `"1235"`  |
+| **123.56**  |  `" 124"`  |
+| **12.56**   |  `"12.6"`  |
+| **1.56**    |  `"1.56"`  |
+                               
+
+### &gt; `format_prefixed_unit`
+
+Similar to previous method, but this one also supports metric prefixes and is highly customizable. Invocation: `format_prefixed_unit(value)`.
+
+| value  | **631**   | **1&nbsp;080**    | **45&nbsp;200**    | **1&nbsp;257&nbsp;800** |  4,31×10⁷ | 7,00×10⁸ | 2,50×10⁹ | 
+| :------: | :--------: | :--------: | :--------: | :--------: |  :--------: | :--------: | :--------: | 
+| result | <code>631&nbsp;b</code> | <code>1.05&nbsp;kb</code> | <code>44.14&nbsp;kb</code> | <code>1.20&nbsp;Mb</code> |  <code>41.11&nbsp;Mb</code> | <code>668.0&nbsp;Mb</code>  | <code>2.33&nbsp;Gb</code>    |
+
+Settings:
+```python
+PrefixedUnitPreset(
+    max_value_len=5, integer_input=True,
+    unit='b', unit_separator=' ',
+    mcoef=1024.0,
+    prefixes=[None, 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y'],
+    prefix_zero_idx=0,
+)
+```
+
+Example #2 illustrating small numbers: 
+
+| value  | **-1.2345×10⁻¹¹**   | **1.2345×10⁻⁸**    |  **1.2345×10⁻⁴** | **0.01234** | **1.23456** | **123.456** | **−12 345** |
+| :------: | :--------: | :--------: |  :---: | :---: | :---: | :---: | :---: |
+| result | <code>-0.012nm</code> | <code>0.0123μm</code> | <code>0.1235mm</code> | <code>0.0123m</code> | <code>1.2346m</code> | <code>123.46m</code> | <code>-12.35km</code>
+
+```python
+PrefixedUnitPreset(
+    max_value_len=6, integer_input=False,
+    unit='m', unit_separator='',
+    mcoef=1000.0,
+    prefixes=['y', 'z', 'a', 'f', 'p', 'n', 'μ', 'm', None],
+    prefix_zero_idx=8,
+)
+```
+
+### &gt; `format_time_delta`
+
+Formats time interval in 4 different variants - 3-char, 4-char, 6-char and 10-char width output. Usage: `format_time_delta(seconds, max_len)`.
+
+| width   | 2 | 10 | 60 | 2700 | 32&nbsp;340 | 273&nbsp;600 | 4&nbsp;752&nbsp;000 | 8,64×10⁸ |
+| ------:  | --- | --- | --- | --- | --- | --- | --- | --- |
+| **3&nbsp;chars**  | <code>2s</code>| <code>10s</code>| <code>1m</code>| <code>45m</code>| <code>8h</code>| <code>3d</code>| <code>55d</code>| -- |
+| **4&nbsp;chars**  | <code>2&nbsp;s </code>| <code>10&nbsp;s </code>| <code>1&nbsp;m </code>| <code>45&nbsp;m </code>| <code>8&nbsp;h </code>| <code>3&nbsp;d </code>| <code>1&nbsp;M </code>| <code>27&nbsp;y </code>|                  
+| **6&nbsp;chars**  | <code>2&nbsp;sec </code>| <code>10&nbsp;sec </code>| <code>1&nbsp;min </code>| <code>45&nbsp;min</code>| <code>8h&nbsp;59m </code>| <code>3d&nbsp;4h </code>| <code>1&nbsp;mon </code>| <code>27&nbsp;yr </code>|
+| **10&nbsp;chars** | <code>2&nbsp;secs </code>| <code>10&nbsp;secs </code>| <code>1&nbsp;min</code> | <code>45&nbsp;mins</code>| <code>8h&nbsp;59m </code>| <code>3d&nbsp;4h </code>| <code>1&nbsp;months </code>| <code>27&nbsp;years </code>|
+
+Settings example (for 10-char mode):
+```python
+TimeDeltaPreset([
+    TimeUnit('sec', 60), 
+    TimeUnit('min', 60, custom_short='min'), 
+    TimeUnit('hour', 24, collapsible_after=24),
+    TimeUnit('day', 30, collapsible_after=10),
+    TimeUnit('month', 12),
+    TimeUnit('year', overflow_afer=999),
+], allow_negative=True,
+    unit_separator=' ',
+    plural_suffix='s',
+    overflow_msg='OVERFLOW',
+),
+```
+
+</details>
+
 ## API: Registries
 
 <details>
@@ -827,6 +919,16 @@ You can of course create your own sequences and formats, but with one limitation
 
 ## Changelog
 
+### v1.8.0
+
+- `format_prefixed_unit` extended for working with decimal and binary metric prefixes;
+- `format_time_delta` extended with new settings;
+- Value rounding transferred from  `format_auto_float` to `format_prefixed_unit`;
+- Utility classes reorganization;
+- Unit tests output formatting;
+- `noop` SGR sequence and `noop` format;
+- Max decimal points for `auto_float` extended from (2) to (max-2).
+- 
 ### v1.7.4
 
 - Added 3 formatters: `fmt_prefixed_unit`, `fmt_time_delta`, `fmt_auto_float`.