v3.0.0

pyTooling · Mar 10, 2023 · d5a34a7 · d5a34a7
2 parents 4c6d0a4 + d97d224
commit d5a34a7
Show file tree

Hide file tree

Showing 11 changed files with 896 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -165,6 +165,46 @@ A set of helper functions to describe a Python package for setuptools.
   * `DescribePythonPackageHostedOnGitHub`  
     tbd
 
+
+### Terminal
+
+A set of helpers to implement a text user interface (TUI) in a terminal.
+
+#### Features
+
+* Colored command line outputs based on `colorama`.
+* Message classification in `fatal`, `error`, `warning`, `normal`, `quiet`, ...
+* Get information like terminal dimensions from underlying terminal window.
+
+
+#### Simple Terminal Application
+
+This is a minimal terminal application example which inherits from `LineTerminal`.
+
+```python
+from pyTooling.TerminalUI import LineTerminal
+
+class Application(LineTerminal):
+  def __init__(self):
+    super().__init__()
+
+  def run(self):
+    self.WriteNormal("This is a simple application.")
+    self.WriteWarning("This is a warning message.")
+    self.WriteError("This is an error message.")
+
+# entry point
+if __name__ == "__main__":
+  Application.versionCheck((3, 6, 0))
+  app = Application()
+  app.run()
+  app.exit()
+```
+
+### Timer
+
+*tbd*
+
 ## Examples
 
 ### `@export` Decorator

diff --git a/doc/Dependency.rst b/doc/Dependency.rst
@@ -44,6 +44,15 @@ When installed as ``pyTooling``:
 +-----------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 
+When installed as ``pyTooling[terminal]``:
+
++-----------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+| **Package**                                                     | **Version** | **License**                                                                               | **Dependencies**                                                                                                                                       |
++=================================================================+=============+===========================================================================================+========================================================================================================================================================+
+| `colorama <https://GitHub.com/tartley/colorama>`__              | ≥0.4.6      | `BSD-3-Clause  <https://GitHub.com/tartley/colorama/blob/master/LICENSE.txt>`__           | None                                                                                                                                                   |
++-----------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
 When installed as ``pyTooling[yaml]``:
 
 +-----------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -86,7 +95,7 @@ the mandatory dependencies too.
 +--------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
 | `Coverage <https://GitHub.com/nedbat/coveragepy>`__                | ≥7.2        | `Apache License, 2.0 <https://GitHub.com/nedbat/coveragepy/blob/master/LICENSE.txt>`__ | *Not yet evaluated.* |
 +--------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
-| `mypy <https://GitHub.com/python/mypy>`__                          | ≥1.0.1      | `MIT <https://GitHub.com/python/mypy/blob/master/LICENSE>`__                           | *Not yet evaluated.* |
+| `mypy <https://GitHub.com/python/mypy>`__                          | ≥1.1.1      | `MIT <https://GitHub.com/python/mypy/blob/master/LICENSE>`__                           | *Not yet evaluated.* |
 +--------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
 | `lxml <https://GitHub.com/lxml/lxml>`__                            | ≥4.9        | `BSD 3-Clause <https://GitHub.com/lxml/lxml/blob/master/LICENSE.txt>`__                | *Not yet evaluated.* |
 +--------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------+----------------------+
@@ -116,7 +125,7 @@ the mandatory dependencies too.
 +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | **Package**                                                                                     | **Version**  | **License**                                                                                              | **Dependencies**                                                                                                                                     |
 +=================================================================================================+==============+==========================================================================================================+======================================================================================================================================================+
-| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__                                          | ≥2.11.0      | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__                    | *None*                                                                                                                                               |
+| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__                                          | ≥2.13.0      | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__                    | *None*                                                                                                                                               |
 +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `Sphinx <https://GitHub.com/sphinx-doc/sphinx>`__                                               | ≥5.3.0       | `BSD 3-Clause <https://GitHub.com/sphinx-doc/sphinx/blob/master/LICENSE>`__                              | *Not yet evaluated.*                                                                                                                                 |
 +-------------------------------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -157,7 +166,7 @@ install the mandatory dependencies too.
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | **Package**                                                                | **Version**  | **License**                                                                                              | **Dependencies**                                                                                                                                     |
 +============================================================================+==============+==========================================================================================================+======================================================================================================================================================+
-| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__                     | ≥2.11.0      | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__                    | *None*                                                                                                                                               |
+| `pyTooling <https://GitHub.com/pyTooling/pyTooling>`__                     | ≥2.13.0      | `Apache License, 2.0 <https://GitHub.com/pyTooling/pyTooling/blob/main/LICENSE.md>`__                    | *None*                                                                                                                                               |
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
 | `wheel <https://GitHub.com/pypa/wheel>`__                                  | ≥0.38.1      | `MIT <https://github.com/pypa/wheel/blob/main/LICENSE.txt>`__                                            | *Not yet evaluated.*                                                                                                                                 |
 +----------------------------------------------------------------------------+--------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+

diff --git a/doc/Terminal/index.rst b/doc/Terminal/index.rst
@@ -0,0 +1,55 @@
+.. _TERM:
+
+Terminal
+########
+
+A set of helpers to implement a text user interface (TUI) in a terminal.
+
+Introduction
+************
+
+This package offers a :py:class:`pyTooling.TerminalUI.LineTerminal` implementation, derived from a basic
+:py:class:`pyTooling.TerminalUI.Terminal` class. It eases the creation of simple terminal/console applications. It
+includes colored outputs based on `colorama`.
+
+List of base-classes
+********************
+
+* :py:class:`pyTooling.TerminalUI.Terminal`
+* :py:class:`pyTooling.TerminalUI.LineTerminal`
+
+
+Example
+*******
+
+.. code-block:: Python
+
+   from pyTooling.TerminalUI import LineTerminal
+
+   class Application(LineTerminal):
+     def __init__(self):
+       super().__init__(verbose=True, debug=True, quiet=False)
+
+     def run(self):
+       self.WriteQuiet("This is a quiet message.")
+       self.WriteNormal("This is a normal message.")
+       self.WriteInfo("This is an info message.")
+       self.WriteDebug("This is a debug message.")
+       self.WriteWarning("This is a warning message.")
+       self.WriteError("This is an error message.")
+       self.WriteFatal("This is a fatal message.")
+
+   # entry point
+   if __name__ == "__main__":
+     Application.versionCheck((3,6,0))
+     app = Application()
+     app.run()
+     app.exit()
+
+
+Line
+####
+
+``Line`` represents a single line in a line-based terminal application. If a
+line is visible, depends on the :class:`~pyTooling.TerminalUI.Severity`-level of a
+``Line`` object.
diff --git a/doc/index.rst b/doc/index.rst
@@ -125,7 +125,6 @@ Decorators
   * Register the given function or class as publicly accessible in a module via :py:class:`~pyTooling.Decorators.export`.
 
 
-
 Exceptions
 ==========
 
@@ -185,6 +184,12 @@ A set of helper functions to describe a Python package for setuptools.
   * :py:func:`pyTooling.Packaging.DescribePythonPackageHostedOnGitHub` |br|
     tbd
 
+
+Terminal
+========
+
+*tbd*
+
 Timer
 =====
 
@@ -283,6 +288,12 @@ License
 
    Packaging
 
+.. toctree::
+   :caption: Terminal
+   :hidden:
+
+   Terminal/index
+
 .. toctree::
    :caption: Timer
    :hidden:

diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,6 +1,6 @@
 -r ../requirements.txt
 
-pyTooling>=2.11.0
+pyTooling>=2.13.0, <3.0
 
 # Enforce latest version on ReadTheDocs
 sphinx >=5.3, <6.0

diff --git a/pyTooling/Common/__init__.py b/pyTooling/Common/__init__.py
@@ -37,7 +37,7 @@
 __email__ =     "Paebbels@gmail.com"
 __copyright__ = "2017-2022, Patrick Lehmann"
 __license__ =   "Apache License, Version 2.0"
-__version__ =   "2.13.0"
+__version__ =   "3.0.0"
 __keywords__ =  ["decorators", "meta-classes", "exceptions", "platform", "versioning", "licensing", "overloading",
 								"singleton", "tree", "graph", "timer", "data structure", "setuptools", "wheel", "installation",
 								"packaging", "path", "generic path", "generic library", "url"]