Closes #4 & minor documentation changes (see CHANGELOG.md)

Author: InspiredImpact

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Python-Multibar 4.0.1 (06.10.2022)
+
+## Features
+- Add `multibar.INPUT_VALUES_CONTRACT` (alias to `multibar.WRITE_PROGRESS_CONTRACT`)
+
+## Documentation changes
+- Add `Raises` section to `multibar.ProgressbarClient.get_progress()`
+- Add `Showcase` page with quick examples to github.io site

docs-requirements.txt

@@ -6,3 +6,4 @@ Markdown
 mkdocstrings
 mkdocstrings-python
 mkdocs-autorefs
+termynal

docs/index.md

@@ -28,8 +28,9 @@ Topic: Utilities
 !!! nav-menu "Navigation menu"
 [**FAQ**](faq.md){ .md-button }
 [**Quickstart**](quickstart.md){ .md-button }
+[**Showcase**](showcase.md){ .md-button }
 [**Python-Multibar**](about.md){ .md-button }
-[**Go to documentation**](errors.md){ .md-button }
+[**Docs**](errors.md){ .md-button }
 
 <h1 align="center">Python-Multibar Minimap</h1>
 
@@ -77,6 +78,8 @@ Topic: Utilities
 <br/>
 <a href="https://mkdocstrings.github.io/autorefs/">MkDocs auto-refs</a>
 <br/>
+<a href="https://github.com/daxartio/termynal">Mkdocs termynal</a>
+<br/>
 <a href="https://github.com/facelessuser">Isaac Muse</a>
 <br/>
 </p>

docs/showcase.md

@@ -0,0 +1,40 @@
+## Base signature example
+
+<!-- termynal -->
+
+```
+$ import multibar
+$ writer = multibar.ProgressbarWriter()
+$ progressbar = writer.write(50, 100, length=6)
++++---
+$ type(progressbar)
+[<class 'multibar.impl.progressbars.Progressbar'>](impl/progressbars.md)
+$ type(progressbar[0])
+[<class 'multibar.impl.sectors.Sector'>](impl/sectors.md)
+```
+
+## Square Emoji signature example
+
+<!-- termynal -->
+
+```
+$ from multibar import ProgressbarWriter, SquareEmojiSignature
+$ writer = ProgressbarWriter.from_signature(SquareEmojiSignature())
+$ progressbar = writer.write(50, 100, length=6)
+🟧🟧🟧⬛️⬛️⬛️  # If the environment supports emoji
+```
+
+## Square Emoji signature that supports `start` & `end` values
+
+<!-- termynal -->
+
+```
+$ from multibar import ProgressbarClient, SquareEmojiSignature, WRITER_HOOKS
+# Client configuration
+$ client = ProgressbarClient()
+$ client.writer.bind_signature(SquareEmojiSignature())
+$ client.set_hooks(WRITER_HOOKS)
+# Product
+$ progressbar = client.get_progress(100, 100, length=6)
+🔸🟧🟧🟧🟧🔸  # If the environment supports emoji
+```

mkdocs.yml

@@ -58,6 +58,9 @@ nav:
   - About:
     - about.md
 
+  - Showcase:
+    - showcase.md
+
   - "Reference":
       - "api":
         - api/math_operations.md
@@ -88,6 +91,7 @@ nav:
 plugins:
   - search
   - autorefs
+  - termynal
 
   # Plugin for diagrams
   - mermaid2:

multibar/api/progressbars.py

@@ -26,7 +26,6 @@
 
 from . import sectors
 
-
 SectorT = typing.TypeVar("SectorT", bound=sectors.AbstractSector)
 _NewValueType = typing.TypeVar("_NewValueType", bound=sectors.AbstractSector)
 _InstanceKind = typing.TypeVar("_InstanceKind", bound="ProgressbarAware[typing.Any]")

multibar/impl/clients.py

@@ -110,6 +110,21 @@ def get_progress(
         length : int = 20, *
             Length of progressbar for progressbar math operations.
 
+        Raises
+        ------
+        errors.TerminatedContractError
+            This contract is signed by default. Checks if the Start value is greater
+            than the End value, if so, an error will be raised.
+
+            !!! info
+                You can unsubscribe from this contract as follows:
+                ```py hl_lines="4"
+                import multibar
+
+                client = multibar.ProgressbarClient()
+                client.contract_manager.terminate(multibar.INPUT_VALUES_CONTRACT)
+                ```
+
         Returns
         -------
         progressbars.ProgressbarAware[sectors.AbstractSector]

multibar/impl/contracts.py

@@ -20,6 +20,7 @@
     "ContractManager",
     "WriteProgressContract",
     "WRITE_PROGRESS_CONTRACT",
+    "INPUT_VALUES_CONTRACT",
 )
 
 import typing
@@ -219,7 +220,7 @@ def check(self, *args: typing.Any, **kwargs: typing.Any) -> contracts.ContractCh
         start, end, length = meta["start_value"], meta["end_value"], meta["length"]
         if start > end:
             return contracts.ContractCheck.terminated(
-                errors=["Start value cannot be more than end value."],
+                errors=["`Start` value cannot be more than `End` value."],
                 metadata=call_metadata,
             )
 
@@ -320,3 +321,6 @@ def render_terminated_contract(
     For subscribing or unsubscribing of `WriteProgressContract` its recommended
     to use this variable, because this methods depends on object `id`.
 """
+
+INPUT_VALUES_CONTRACT = WRITE_PROGRESS_CONTRACT
+"""Alias to WRITE_PROGRESS_CONTRACT."""

pyproject.toml

@@ -30,7 +30,7 @@ src_paths = ["multibar", "tests", "examples"]
 
 [tool.poetry]
 name = "python-multibar"
-version = "4.0.0"
+version = "4.0.1"
 description = "Flexible wrapper for static progressbar writing."
 authors = ["DenyS <[email protected]>"]
 readme = "PYPI_README.md"