From 12e4ddd669d549ea305d874ec8a991bd324f32b7 Mon Sep 17 00:00:00 2001
From: Edvard Rejthar <github@edvard.cz>
Date: Mon, 30 Dec 2024 14:24:59 +0100
Subject: [PATCH] Deployed 2954a93 with MkDocs version: 1.6.1

---
 Changelog/index.html     |  22 ++++++++++++++++++++++
 Types/index.html         |   2 +-
 index.html               |   2 +-
 search/search_index.json |   2 +-
 sitemap.xml.gz           | Bin 127 -> 127 bytes
 5 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/Changelog/index.html b/Changelog/index.html
index a96c8bc..36721de 100644
--- a/Changelog/index.html
+++ b/Changelog/index.html
@@ -640,6 +640,15 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#072" class="md-nav__link">
+    <span class="md-ellipsis">
+      0.7.2
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#071-2024-11-27" class="md-nav__link">
     <span class="md-ellipsis">
@@ -692,6 +701,15 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#072" class="md-nav__link">
+    <span class="md-ellipsis">
+      0.7.2
+    </span>
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#071-2024-11-27" class="md-nav__link">
     <span class="md-ellipsis">
@@ -729,6 +747,10 @@
 
 
 <h1 id="changelog">Changelog</h1>
+<h2 id="072">0.7.2</h2>
+<ul>
+<li>GUI calendar</li>
+</ul>
 <h2 id="071-2024-11-27">0.7.1 (2024-11-27)</h2>
 <ul>
 <li>GUI scrollbars if window is bigger than the screen</li>
diff --git a/Types/index.html b/Types/index.html
index 04ee53c..cf3f20e 100644
--- a/Types/index.html
+++ b/Types/index.html
@@ -1236,7 +1236,7 @@ <h3 id="mininterface.types.DatetimeTag.time" class="doc doc-heading">
 
 
 <h3 id="mininterface.types.DatetimeTag.full_precision" class="doc doc-heading">
-            <code class="highlight language-python"><span class="n">full_precision</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span></code>
+            <code class="highlight language-python"><span class="n">full_precision</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span></code>
 
 </h3>
 
diff --git a/index.html b/index.html
index 5ee3947..ccc728e 100644
--- a/index.html
+++ b/index.html
@@ -733,7 +733,7 @@ <h1 id="background">Background</h1>
 * Running on a remote machine? Automatic regression to the text interface.</p>
 <h1 id="installation">Installation</h1>
 <p>Install with a single command from <a href="https://pypi.org/project/mininterface/">PyPi</a>.</p>
-<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>pip<span class="w"> </span>install<span class="w"> </span>mininterface
+<div class="highlight"><pre><span></span><code><a id="__codelineno-5-1" name="__codelineno-5-1" href="#__codelineno-5-1"></a>pip<span class="w"> </span>install<span class="w"> </span>mininterface<span class="o">[</span>all<span class="o">]</span><span class="w">  </span><span class="c1"># GPLv3 and compatible</span>
 </code></pre></div>
 <h2 id="minimal-installation">Minimal installation</h2>
 <p>Should you need just the CLI part and you are happy with basic text dialogs, use these commands instead:</p>
diff --git a/search/search_index.json b/search/search_index.json
index 0c202d8..19412d3 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Mininterface \u2013 access to GUI, TUI, CLI and config files","text":"<p>Write the program core, do not bother with the input/output.</p> <p> </p> <p>Check out the code, which is surprisingly short, that displays such a window or its textual fallback.</p> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    \"\"\" This calculates something. \"\"\"\n\n    my_flag: bool = False\n    \"\"\" This switches the functionality \"\"\"\n\n    my_number: int = 4\n    \"\"\" This number is very important \"\"\"\n\nif __name__ == \"__main__\":\n    m = run(Env, prog=\"My application\")\n    m.form()\n    # Attributes are suggested by the IDE\n    # along with the hint text 'This number is very important'.\n    print(m.env.my_number)\n</code></pre>"},{"location":"#contents","title":"Contents","text":"<ul> <li>You got CLI</li> <li>You got config file management</li> <li>You got dialogues</li> <li>Background</li> <li>Installation</li> <li>Docs</li> <li>Examples</li> </ul>"},{"location":"#you-got-cli","title":"You got CLI","text":"<p>It was all the code you need. No lengthy blocks of code imposed by an external dependency. Besides the GUI/TUI, you receive powerful YAML-configurable CLI parsing.</p> <pre><code>$ ./program.py --help\nusage: My application [-h] [-v] [--my-flag | --no-my-flag] [--my-number INT]\n\nThis calculates something.\n\n\u256d\u2500 options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 -h, --help             show this help message and exit                  \u2502\n\u2502 -v, --verbose          Verbosity level. Can be used twice to increase.  \u2502\n\u2502 --my-flag, --no-my-flag                                                 \u2502\n\u2502                        This switches the functionality (default: False) \u2502\n\u2502 --my-number INT        This number is very important (default: 4)       \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre>"},{"location":"#you-got-config-file-management","title":"You got config file management","text":"<p>Loading config file is a piece of cake. Alongside <code>program.py</code>, put <code>program.yaml</code> and put there some of the arguments. They are seamlessly taken as defaults.</p> <pre><code>my_number: 555\n</code></pre> <pre><code>$ program.py --help\n...\n\u2502 --my-number INT        This number is very important (default: 555)     \u2502\n</code></pre>"},{"location":"#you-got-dialogues","title":"You got dialogues","text":"<p>Check out several useful methods to handle user dialogues. Here we bound the interface to a <code>with</code> statement that redirects stdout directly to the window.</p> <pre><code>with run(Env) as m:\n    print(f\"Your important number is {m.env.my_number}\")\n    boolean = m.is_yes(\"Is that alright?\")\n</code></pre> <p> </p>"},{"location":"#background","title":"Background","text":"<p>Wrapper between the tyro <code>argparse</code> replacement and tkinter_form that converts dicts into a GUI.</p> <p>Writing a small and useful program might be a task that takes fifteen minutes. Adding a CLI to specify the parameters is not so much overhead. But building a simple GUI around it? HOURS! Hours spent on researching GUI libraries, wondering why the Python desktop app ecosystem lags so far behind the web world. All you need is a few input fields validated through a clickable window... You do not deserve to add hundred of lines of the code just to define some editable fields. <code>Mininterface</code> is here to help.</p> <p>The config variables needed by your program are kept in cozy dataclasses. Write less! The syntax of tyro does not require any overhead (as its <code>argparse</code> alternatives do). You just annotate a class attribute, append a simple docstring and get a fully functional application: * Call it as <code>program.py --help</code> to display full help. * Use any flag in CLI: <code>program.py --my-flag</code>  causes <code>env.my_flag</code> be set to <code>True</code>. * The main benefit: Launch it without parameters as <code>program.py</code> to get a full working window with all the flags ready to be edited. * Running on a remote machine? Automatic regression to the text interface.</p>"},{"location":"#installation","title":"Installation","text":"<p>Install with a single command from PyPi.</p> <pre><code>pip install mininterface\n</code></pre>"},{"location":"#minimal-installation","title":"Minimal installation","text":"<p>Should you need just the CLI part and you are happy with basic text dialogs, use these commands instead:</p> <pre><code>pip install --no-dependencies mininterface\npip install tyro typing_extensions pyyaml\n</code></pre>"},{"location":"#docs","title":"Docs","text":"<p>See the docs overview at https://cz-nic.github.io/mininterface/.</p>"},{"location":"#examples","title":"Examples","text":"<p>A powerful <code>m.form</code> dialog method accepts either a dataclass or a dict. Take a look on both.</p>"},{"location":"#a-complex-dataclass","title":"A complex dataclass.","text":"<pre><code>from typing import Annotated\nfrom dataclasses import dataclass\nfrom mininterface.validators import not_empty\nfrom mininterface import run, Tag, Validation\n\n@dataclass\nclass NestedEnv:\n  another_number: int = 7\n  \"\"\" This field is nested \"\"\"\n\n@dataclass\nclass Env:\n  nested_config: NestedEnv\n\n  mandatory_str: str\n  \"\"\" As there is no default value, you will be prompted automatically to fill up the field \"\"\"\n\n  my_number: int | None = None\n  \"\"\" This is not just a dummy number, if left empty, it is None. \"\"\"\n\n  my_string: str = \"Hello\"\n  \"\"\" A dummy string \"\"\"\n\n  my_flag: bool = False\n  \"\"\" Checkbox test \"\"\"\n\n  my_validated: Annotated[str, Validation(not_empty)] = \"hello\"\n  \"\"\" A validated field \"\"\"\n\nm = run(Env, title=\"My program\")\n# See some values\nprint(m.env.nested_config.another_number)  # 7\nprint(m.env)\n# Env(nested_config=NestedEnv(another_number=7), my_number=5, my_string='Hello', my_flag=False, my_validated='hello')\n\n# Edit values in a dialog\nm.form()\n</code></pre> <p>As the attribute <code>mandatory_str</code> requires a value, a prompt appears automatically:</p> <p></p> <p>Then, full form appears:</p> <p></p>"},{"location":"#form-with-paths","title":"Form with paths","text":"<p>We have a dict with some paths. Here is how it looks.</p> <pre><code>from pathlib import Path\nfrom mininterface import run, Tag\n\nm = run(title=\"My program\")\nmy_dictionary = {\n  \"paths\": Tag(\"\", annotation=list[Path]),\n  \"default_paths\": Tag([Path(\"/tmp\"), Path(\"/usr\")], annotation=list[Path])\n  }\n\n# Edit values in a dialog\nm.form(my_dictionary)\n</code></pre> <p></p>"},{"location":"Changelog/","title":"Changelog","text":""},{"location":"Changelog/#071-2024-11-27","title":"0.7.1 (2024-11-27)","text":"<ul> <li>GUI scrollbars if window is bigger than the screen</li> <li>non-interactive session support</li> <li>datetime support</li> <li>nested generics support (a tuple in a list)</li> </ul>"},{"location":"Changelog/#070-2024-11-08","title":"0.7.0 (2024-11-08)","text":"<ul> <li>hidden <code>--integrate-to-system</code> argument</li> <li>interfaces migrated to <code>mininterface.interfaces</code> to save around 50 ms starting time due to lazy loading</li> <li>SubcommandPlaceholder</li> </ul>"},{"location":"Exceptions/","title":"Exceptions","text":"<p>Exceptions that might make sense to be used outside the library.</p>"},{"location":"Exceptions/#mininterface.exceptions.Cancelled","title":"<code>Cancelled</code>","text":"<p>User has cancelled. A SystemExit based exception noting that the program exits without a traceback, ex. if user hits the escape or closes the window.</p>"},{"location":"Exceptions/#mininterface.exceptions.ValidationFail","title":"<code>ValidationFail</code>","text":"<p>Signal to the form that submit failed and we want to restore it.</p>"},{"location":"Exceptions/#mininterface.exceptions.InterfaceNotAvailable","title":"<code>InterfaceNotAvailable</code>","text":"<p>Interface failed to init, ex. display not available in GUI. Or the underlying dependency was uninstalled.</p>"},{"location":"Experimental/","title":"Experimental","text":""},{"location":"Experimental/#mininterface.experimental.SubmitButton","title":"<code>SubmitButton</code>","text":"<p>Create a button. When clicked, the form submits.         If submission succeeds (validation checks pass), its value becomes True.</p> <pre><code>from pathlib import Path\nfrom mininterface import run, Tag\nfrom mininterface.experimental import SubmitButton\n\nm = run()\nout = m.form({\n    \"File name\": Tag(\"/tmp\", annotation=Path),\n    \"Append text\": {\n        \"My text\": \"\",\n        \"Append now\": SubmitButton()\n    },\n    \"Duplicate\": {\n        \"Method\": Tag(\"twice\", choices=[\"twice\", \"thrice\"]),\n        \"Duplicate now\": SubmitButton()\n    }\n})\n# Clicking on 'Append now' button\nprint(out)\n# {'File name': PosixPath('/tmp'),\n# 'Append text': {'My text': '', 'Append now': True},\n# 'Duplicate': {'Method': 'twice', 'Duplicate now': False}}\n</code></pre> <p></p>"},{"location":"Facet/","title":"Facet","text":"<p>A frontend side of the interface. While a dialog is open,     this allows to set frontend properties like the heading.</p> <p>Read <code>Tag.facet</code> to see how to access from the front-end side. Read <code>Mininterface.facet</code> to see how to access from the back-end side.</p>"},{"location":"Facet/#mininterface.facet.Facet.set_title","title":"<code>set_title(text)</code>","text":"<p>Set the main heading.</p>"},{"location":"Facet/#mininterface.facet.Facet.submit","title":"<code>submit(_post_submit=None)</code>","text":"<p>Submits the whole form.</p> <p>```python from mininterface import run, Tag</p> <p>def callback(tag: Tag):     tag.facet.submit()</p> <p>m = run() out = m.form({     \"My choice\": Tag(choices=[\"one\", \"two\"], on_change=callback) })</p>"},{"location":"Facet/#mininterface.facet.Facet.submit--continue-here-immediately-after-clicking-on-a-radio-button","title":"continue here immediately after clicking on a radio button","text":""},{"location":"Helper-types/","title":"Helper types","text":""},{"location":"Helper-types/#mininterface.tag.ValidationResult","title":"<code>ValidationResult = bool | ErrorMessage</code>","text":"<p>Callback validation result is either boolean or an error message.</p>"},{"location":"Helper-types/#mininterface.tag.ErrorMessage","title":"<code>ErrorMessage = TypeVar('ErrorMessage')</code>","text":"<p>A string, callback validation error message.</p>"},{"location":"Helper-types/#mininterface.tag.TagValue","title":"<code>TagValue = TypeVar('TagValue', bound=Any)</code>","text":"<p>Any value. It is being wrapped by a Tag.</p>"},{"location":"Helper-types/#mininterface.tag.ChoicesType","title":"<code>ChoicesType = list[TagValue] | tuple[TagValue] | set[TagValue] | dict[ChoiceLabel, TagValue] | list[Enum] | Type[Enum]</code>","text":"<p>You can denote the choices in many ways. Either put options in an iterable or to a dict <code>{labels: value}</code>. Values might be Tags as well.</p> <p>See mininterface.choice or <code>Tag.choices</code> for examples.</p>"},{"location":"Helper-types/#mininterface.form_dict.DataClass","title":"<code>DataClass = TypeVar('DataClass')</code>","text":"<p>Any dataclass. Or a pydantic model or attrs.</p>"},{"location":"Helper-types/#mininterface.form_dict.EnvClass","title":"<code>EnvClass = TypeVar('EnvClass', bound=DataClass)</code>","text":"<p>Any dataclass. Its instance will be available through [miniterface.env] after CLI parsing.</p>"},{"location":"Interfaces/","title":"Interfaces","text":""},{"location":"Interfaces/#all-possible-interfaces","title":"All possible interfaces","text":"<p>Normally, you get an interface through mininterface.run but if you do not wish to parse CLI and config file, you can invoke one directly <code>from mininterface.interfaces import *</code>.</p> <p>Apart from the default <code>Mininterface</code>, the base interface the others are fully compatible with, several interfaces exist:</p> <p>How to invoke a specific interface.</p> <pre><code>from mininterface.interfaces import TuiInterface\n\nwith TuiInterface(\"My program\") as m:\n    number = m.ask_number(\"Returns number\")\n</code></pre>"},{"location":"Interfaces/#guiinterface-tkinterface","title":"<code>GuiInterface</code> = <code>TkInterface</code>","text":"<p>A tkinter window.</p>"},{"location":"Interfaces/#tuiinterface","title":"<code>TuiInterface</code>","text":"<p>An interactive terminal.</p>"},{"location":"Interfaces/#textualinterface","title":"<code>TextualInterface</code>","text":"<p>If textual installed, rich and mouse clickable interface is used.</p>"},{"location":"Interfaces/#textinterface","title":"<code>TextInterface</code>","text":"<p>Plain text only interface with no dependency as a fallback.</p> <p>When used in a with statement, the non-interactive session becomes interactive if possible, see the Mininterface enter method.</p>"},{"location":"Interfaces/#replinterface","title":"<code>ReplInterface</code>","text":"<p>A debug terminal. Invokes a breakpoint after every dialog.</p>"},{"location":"Mininterface/","title":"Mininterface","text":"<p>The base interface.     You get one through <code>mininterface.run</code> which fills CLI arguments and config file to <code>mininterface.env</code>     or you can create one directly (without benefiting from the CLI parsing).</p> Raise <p>Cancelled: A SystemExit based exception noting that the program exits without a traceback, ex. if user hits the escape.</p> Raise <p>InterfaceNotAvailable: Interface failed to init, ex. display not available in GUI.</p>"},{"location":"Mininterface/#mininterface.Mininterface.env","title":"<code>env: EnvClass = EnvInstance</code>","text":"<p>Parsed arguments, fetched from cli.     Contains whole configuration (previously fetched from CLI and config file).</p> <pre><code>$ program.py --number 10\n</code></pre> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    number: int = 3\n    text: str = \"\"\n\nm = run(Env)\nprint(m.env.number)  # 10\n</code></pre>"},{"location":"Mininterface/#mininterface.Mininterface.facet","title":"<code>facet = Facet(None, self.env)</code>","text":"<p>Access to the UI <code>facet</code> from the back-end side. (Read <code>Tag.facet</code> to access from the front-end side.)</p> <pre><code>from mininterface import run\nwith run(title='My window title') as m:\n    m.facet.set_title(\"My form title\")\n    m.form({\"My form\": 1})\n</code></pre> <p></p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__","title":"<code>__enter__()</code>","text":"<p>Usage within the with statement makes the program to attempt for the following benefits:</p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__--continual-window","title":"Continual window","text":"<p>Do not vanish between dialogs (the GUI window stays the same)</p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__--stdout-redirection","title":"Stdout redirection","text":"<p>Redirects the stdout to a text area instead of a terminal.</p> <pre><code>from mininterface import run\n\nwith run() as m:\n    print(\"This is a printed text\")\n    m.alert(\"Alert text\")\n</code></pre> <p></p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__--make-the-session-interactive","title":"Make the session interactive","text":"<p>If run from an interactive terminal or if a GUI is used, nothing special happens.</p> <pre><code># $ ./program.py\nwith run() as m:\n    m.ask_number(\"What number\")\n</code></pre> <p></p> <p>However, when run in a non-interactive session with TUI (ex. no display), TextInterface is used which is able to turn it into an interactive one.</p> <pre><code>piped_in = int(sys.stdin.read())\n\nwith run(interface=\"tui\") as m:\n    result = m.ask_number(\"What number\") + piped_in\nprint(result)\n</code></pre> <pre><code>$ echo 2 | ./program.py\nWhat number: 3\n5\n</code></pre> <p>If the <code>with</code> statement is not used, the result is the same as if an interactive session is not available, like in a cron job. In that case, plain Mininterface is used.</p> <pre><code>piped_in = int(sys.stdin.read())\n\nm = run(interface=\"tui\")\nresult = m.ask_number(\"What number\") + piped_in\nprint(result)\n</code></pre> <pre><code>echo 2 | ./program.py\nAsking: What number\n3\n</code></pre>"},{"location":"Mininterface/#mininterface.Mininterface.alert","title":"<code>alert(text)</code>","text":"<p>Prompt the user to confirm the text.</p>"},{"location":"Mininterface/#mininterface.Mininterface.ask","title":"<code>ask(text)</code>","text":"<p>Prompt the user to input a text.</p>"},{"location":"Mininterface/#mininterface.Mininterface.ask_number","title":"<code>ask_number(text)</code>","text":"<p>Prompt the user to input a number. Empty input = 0.</p> <pre><code>m = run()  # receives a Mininterface object\nm.ask_number(\"What's your age?\")\n</code></pre> <p></p> <p>Parameters:</p> Name Type Description Default <code>text</code> <code>str</code> <p>The question text.</p> required <p>Returns:</p> Type Description <code>int</code> <p>Number</p>"},{"location":"Mininterface/#mininterface.Mininterface.choice","title":"<code>choice(choices, title='', _guesses=None, skippable=True, launch=True, _multiple=True, default=None)</code>","text":"<p>Prompt the user to select. Useful for a menu creation.</p> <p>Parameters:</p> Name Type Description Default <code>choices</code> <code>ChoicesType</code> <p>You can denote the choices in many ways. Either put options in an iterable:</p> <pre><code>from mininterface import run\nm = run()\nm.choice([1, 2])\n</code></pre> <p></p> <p>Or to a dict <code>{name: value}</code>. Then name are used as labels.</p> <pre><code>m.choice({\"one\": 1, \"two\": 2})  # returns 1\n</code></pre> <p>Alternatively, you may specify the names in <code>Tags</code>.</p> <pre><code>m.choice([Tag(1, name=\"one\"), Tag(2, name=\"two\")])  # returns 1\n</code></pre> <p></p> <p>Alternatively, you may use an Enum.</p> <pre><code>class Color(Enum):\n    RED = \"red\"\n    GREEN = \"green\"\n    BLUE = \"blue\"\n\nm.choice(Color)\n</code></pre> <p></p> <p>Alternatively, you may use an Enum instance.</p> <pre><code>class Color(Enum):\n    RED = \"red\"\n    GREEN = \"green\"\n    BLUE = \"blue\"\n\nm.choice(Color.BLUE)\n</code></pre> <p></p> <p>Alternatively, you may use an Enum instances list.</p> <pre><code>m.choice([Color.GREEN, Color.BLUE])\n</code></pre> <p></p> required <code>title</code> <code>str</code> <p>Form title</p> <code>''</code> <code>default</code> <code>str | TagValue | None</code> <p>The value of the checked choice.</p> <p><pre><code>m.choice({\"one\": 1, \"two\": 2}, default=2)  # returns 2\n</code></pre> </p> <code>None</code> <code>skippable</code> <code>bool</code> <p>If there is a single option, choose it directly, without a dialog.</p> <code>True</code> <code>launch</code> <code>bool</code> <p>If the chosen value is a callback, we directly call it and return its return value.</p> <code>True</code> <p>Returns:</p> Type Description <code>TagValue | list[TagValue] | Any</code> <p>The chosen value.</p> <code>TagValue | list[TagValue] | Any</code> <p>If launch=True and the chosen value is a callback, we call it and return its result.</p> <p>Info</p> <p>To tackle a more detailed form, see <code>Tag.choices</code>.</p>"},{"location":"Mininterface/#mininterface.Mininterface.form","title":"<code>form(form=None, title='', *, submit=True)</code>","text":"<p>Prompt the user to fill up an arbitrary form.</p> <p>Use scalars, enums, enum instances, objects like datetime, Paths or their list.</p> <pre><code>from enum import Enum\nfrom mininterface import run, Tag\n\nclass Color(Enum):\n    RED = \"red\"\n    GREEN = \"green\"\n    BLUE = \"blue\"\n\nm = run()\nout = m.form({\n    \"my_number\": 1,\n    \"my_boolean\": True,\n    \"my_enum\": Color,\n    \"my_tagged\": Tag(\"\", name='Tagged value', description='Long hint'),\n    \"my_path\": Path(\"/tmp\"),\n    \"my_paths\": [Path(\"/tmp\")],\n    \"My enum with default\": Color.BLUE\n})\n</code></pre> <p></p> <p>Parameters:</p> Name Type Description Default <code>form</code> <code>DataClass | Type[DataClass] | FormDict | None</code> <p>We accept a dataclass type, a dataclass instance, a dict or None.</p> <ul> <li>If dict, we expect a dict of <code>{labels: value}</code>. The form widget infers from the default value type. The dict can be nested, it can contain a subgroup. The value might be a <code>Tag</code> that allows you to add descriptions.</li> </ul> <p>A checkbox example: <code>{\"my label\": Tag(True, \"my description\")}</code></p> <ul> <li>If None, the <code>self.env</code> is being used as a form, allowing the user to edit whole configuration.     (Previously fetched from CLI and config file.)</li> </ul> <code>None</code> <code>title</code> <code>str</code> <p>Optional form title</p> <code>''</code> <code>submit</code> <code>str | bool</code> <p>Set the submit button text (by default 'Ok') or hide it with False.</p> <code>True</code> <p>Returns:</p> Name Type Description <code>dataclass</code> <code>FormDict | DataClass | EnvClass</code> <p>If the <code>form</code> is null, the output is <code>self.env</code>.</p> <code>dataclass</code> <code>FormDict | DataClass | EnvClass</code> <p>If the <code>form</code> is a dataclass type or a dataclass instance, the output is the dataclass instance.</p> <code>dict</code> <code>FormDict | DataClass | EnvClass</code> <p>If the <code>form</code> is a dict, the output is another dict.</p> <p>Whereas the original dict stays intact (with the values updated), we return a new raw dict with all values resolved (all <code>Tag</code> objects are resolved to their value).</p> <pre><code>original = {\"my label\": Tag(True, \"my description\")}\noutput = m.form(original)  # Sets the label to False in the dialog\n\n# Original dict was updated\nprint(original[\"my label\"])  # Tag(False, \"my description\")\n\n# Output dict is resolved, contains only raw values\nprint(output[\"my label\"])  # False\n</code></pre> <p>Why this behaviour? You need to do some validation, hence you put <code>Tag</code> objects in the input dict. Then, you just need to work with the values.</p> <pre><code>original = {\"my label\": Tag(True, \"my description\")}\noutput = m.form(original)  # Sets the label to False in the dialog\noutput[\"my_label\"]\n</code></pre> <p>In the case you are willing to re-use the dict, you need not to lose the definitions, hence you end up with accessing via the <code>.val</code>.</p> <pre><code>original = {\"my label\": Tag(True, \"my description\")}\n\nfor i in range(10):\n    m.form(original, f\"Attempt {i}\")\n    print(\"The result\", original[\"my label\"].val)\n</code></pre>"},{"location":"Mininterface/#mininterface.Mininterface.is_yes","title":"<code>is_yes(text)</code>","text":"<p>Display confirm box, focusing yes.</p> <pre><code>m = run()\nprint(m.is_yes(\"Is that alright?\"))  # True/False\n</code></pre> <p></p>"},{"location":"Mininterface/#mininterface.Mininterface.is_no","title":"<code>is_no(text)</code>","text":"<p>Display confirm box, focusing no.</p>"},{"location":"Overview/","title":"Overview","text":"<p>Via the run function you get access to the CLI, possibly enriched from the config file. Then, you receive all data as <code>m.env</code> object and dialog methods in a proper UI.</p> <pre><code>graph LR\n    subgraph mininterface\n        run --&gt; GUI\n        run --&gt; TUI\n        run --&gt; env\n        CLI --&gt; run\n        id1[config file] --&gt; CLI\n    end\n    program --&gt; run\n</code></pre>"},{"location":"Overview/#basic-usage","title":"Basic usage","text":"<p>Use a common dataclass, a Pydantic BaseModel or an attrs model to store the configuration. Wrap it to the run function that returns an interface <code>m</code>. Access the configuration via <code>m.env</code> or use it to prompt the user <code>m.is_yes(\"Is that alright?\")</code>.</p> <p>There are a lot of supported types you can use, not only scalars and well-known objects (<code>Path</code>, <code>datetime</code>), but also functions, iterables (like <code>list[Path]</code>) and union types (like <code>int | None</code>). To do even more advanced things, stick the value to a powerful <code>Tag</code> or its subclasses. Ex. for a validation only, use its <code>Validation alias</code>.</p> <p>At last, use <code>Facet</code> to tackle the interface from the back-end (<code>m</code>) or the front-end (<code>Tag</code>) side.</p>"},{"location":"Overview/#ide-suggestions","title":"IDE suggestions","text":"<p>The immediate benefit is the type suggestions you see in an IDE. Imagine following code:</p> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_paths: list[Path]\n    \"\"\" The user is forced to input Paths. \"\"\"\n\n\n@dataclass\nclass Dialog:\n    my_number: int = 2\n    \"\"\" A number \"\"\"\n</code></pre> <p>Now, accessing the main env will trigger the hint. </p> <p>Calling the form with an empty parameter will trigger editing the main env</p> <p></p> <p>Putting there a dict will return the dict too.</p> <p></p> <p>Putting there a dataclass type causes it to be resolved.</p> <p></p> <p>Should you have a resolved dataclass instance, put it there.</p> <p></p> <p>As you see, its attributes are hinted alongside their description.</p> <p></p> <p>Should the dataclass cannot be easily investigated by the IDE (i.e. a required field), just annotate the output.</p> <p></p>"},{"location":"Overview/#bash-completion","title":"Bash completion","text":"<p>Run your program with a hidden <code>--integrate-to-system</code> flag and a tutorial will install bash completion.</p> <p></p>"},{"location":"Overview/#nested-configuration","title":"Nested configuration","text":"<p>You can easily nest the configuration. (See also Tyro Hierarchical Configs).</p> <p>Just put another dataclass inside the config file:</p> <pre><code>@dataclass\nclass FurtherConfig:\n    token: str\n    host: str = \"example.org\"\n\n@dataclass\nclass Env:\n    further: FurtherConfig\n\n...\nm = run(Env)\nprint(m.env.further.host)  # example.org\n</code></pre> <p>The attributes can by defaulted by CLI:</p> <pre><code>$./program.py --further.host example.net\n</code></pre> <p>And in a YAML config file. Note that you are not obliged to define all the attributes, a subset will do. (Ex. you do not need to specify <code>token</code> too.)</p> <pre><code>further:\n  host: example.com\n</code></pre>"},{"location":"Standalone/","title":"Standalone","text":"<p>When invoked directly, it creates simple GUI dialogs.</p> <pre><code>$ mininterface  --help\nusage: Mininterface [-h] [OPTIONS]\n\nSimple GUI dialog. Outputs the value the user entered.\n\n\u256d\u2500 options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 -h, --help              show this help message and exit                                   \u2502\n\u2502 --alert STR             Display the OK dialog with text. (default: '')                    \u2502\n\u2502 --ask STR               Prompt the user to input a text. (default: '')                    \u2502\n\u2502 --ask-number STR        Prompt the user to input a number. Empty input = 0. (default: '') \u2502\n\u2502 --is-yes STR            Display confirm box, focusing yes. (default: '')                  \u2502\n\u2502 --is-no STR             Display confirm box, focusing no. (default: '')                   \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre> <p>You can fetch a value to i.e. a bash script.</p> <pre><code>$ mininterface  --ask-number \"What's your age?\"  # GUI or TUI window invoked\n18\n</code></pre> <p> </p>"},{"location":"Subcommands/","title":"Subcommands","text":"<p>Dealing with CLI subcommands, <code>from mininterface.subcommands import *</code></p>"},{"location":"Subcommands/#mininterface.subcommands.Command","title":"<code>Command</code>","text":"<p>The Command is automatically run while instantanied.</p> <p>Experimental \u2013 how should it receive _facet?</p> <p>Put list of Commands to the mininterface.run and divide your application into different sections. Alternative to argparse subcommands.</p> <p>Commands might inherit from the same parent to share the common attributes.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command--subcommandplaceholder","title":"SubcommandPlaceholder","text":"<p>What if I need to use my program Special placeholder class SubcommandPlaceholder. This special class let the user to choose the subcommands via UI, while still benefiniting from default CLI arguments.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command--the-cli-behaviour","title":"The CLI behaviour:","text":"<ul> <li><code>./program.py</code> -&gt; UI started with subcommand choice</li> <li><code>./program.py subcommand --flag</code> -&gt; special class <code>SubcommandPlaceholder</code> allows defining a common <code>--flag</code>     while still starting UI with subcommand choice</li> <li><code>./program.py subcommand1 --flag</code> -&gt; program run</li> <li><code>./program.py subcommand1</code> -&gt; fails to CLI for now</li> </ul>"},{"location":"Subcommands/#mininterface.subcommands.Command--an-example-of-command-usage","title":"An example of Command usage","text":"<pre><code>from dataclasses import dataclass, field\nfrom pathlib import Path\nfrom mininterface import run\nfrom mininterface.exceptions import ValidationFail\nfrom mininterface.subcommands import Command, SubcommandPlaceholder\nfrom tyro.conf import Positional\n\n\n@dataclass\nclass SharedArgs(Command):\n    common: int\n    files: Positional[list[Path]] = field(default_factory=list)\n\n    def init(self):\n        self.internal = \"value\"\n\n\n@dataclass\nclass Subcommand1(SharedArgs):\n    my_local: int = 1\n\n    def run(self):\n        print(\"Common:\", self.common)  # user input\n        print(\"Number:\", self.my_local)  # 1 or user input\n        print(\"Internal:\", self.internal)\n        raise ValidationFail(\"The submit button blocked!\")\n\n\n@dataclass\nclass Subcommand2(SharedArgs):\n    def run(self):\n        self._facet.set_title(\"Button clicked\")  # you can access internal self._facet: Facet\n        print(\"Common files\", self.files)\n\n\nm = run([Subcommand1, Subcommand2, SubcommandPlaceholder])\nm.alert(\"App continue\")\n</code></pre> <p>Let's start the program, passing there common flags, all HTML files in a folder and setting <code>--common</code> to 7. <pre><code>$ program.py  subcommand *.html  --common 7\n</code></pre></p> <p></p> <p>As you see, thanks to <code>SubcommandPlaceholder</code>, subcommand was not chosen yet. Click to the first button.</p> <p></p> <p>and the terminal got:</p> <pre><code>Common: 7\nNumber: 1\nInternal: value\n</code></pre> <p>Click to the second button.</p> <p></p> <p>Terminal output: <pre><code>Common files [PosixPath('page1.html'), PosixPath('page2.html')]\n</code></pre></p>"},{"location":"Subcommands/#mininterface.subcommands.Command--powerful-automation","title":"Powerful automation","text":"<p>Note we use <code>from tyro.conf import Positional</code> to denote the positional argument. We did not have to write <code>--files</code> to put there HTML files.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command.init","title":"<code>init()</code>","text":"<p>Just before the form appears. As the <code>__post_init__</code> method is not guaranteed to run just once (internal CLI behaviour), you are welcome to override this method instead. You can use self._facet from within.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command.run","title":"<code>run()</code>","text":"<p>This method is run automatically in CLI or by a button button it generates in a UI.</p>"},{"location":"Subcommands/#mininterface.subcommands.SubcommandPlaceholder","title":"<code>SubcommandPlaceholder</code>","text":"<p>Use this placeholder to choose the subcomannd via a UI.</p>"},{"location":"Tag/","title":"Tag","text":"<p>Wrapper around a value that encapsulates a description, validation etc. When you provide a value to an interface, you may instead use this object.</p> <p>Bridge between the input values and a UI widget. The widget is created with the help of this object, then transforms the value back (str to int conversion etc).</p>"},{"location":"Tag/#mininterface.Tag.val","title":"<code>val: TagValue = None</code>","text":"<p>The value wrapped by Tag. It can be any value.</p> <pre><code>from mininterface import run, Tag\n\ntag = Tag(True, \"This is my boolean\", bool)\nm = run()\nm.form({\"My boolean\": tag})\nprint(tag.val)  # True/False\nprint()\n</code></pre> <p></p> <p>The encapsulated value is <code>True</code>, <code>tag.description</code> is 'This is my boolean', <code>tag.annotation</code> is <code>bool</code> and 'My boolean' is used as <code>tag.name</code>.</p> <p>Tip</p> <p>If the Tag is nested, the info is fetched to the outer Tag. When updated, the inner Tag value updates accordingly.</p> <pre><code>tag = Tag(Tag(True))\n</code></pre>"},{"location":"Tag/#mininterface.Tag.description","title":"<code>description: str = ''</code>","text":"<p>The description displayed in the UI.</p>"},{"location":"Tag/#mininterface.Tag.annotation","title":"<code>annotation: type | None = None</code>","text":"<p>Used for validation (ex. to convert an empty string to None). If not set, will be determined automatically from the val type.</p>"},{"location":"Tag/#mininterface.Tag.name","title":"<code>name: str | None = None</code>","text":"<p>Name displayed in the UI.</p>"},{"location":"Tag/#mininterface.Tag.validation","title":"<code>validation: Callable[[Tag], ValidationResult | tuple[ValidationResult, TagValue]] | None = None</code>","text":"<p>When the user submits the form, the values are validated (and possibly transformed) with a callback function.     If the validation fails, user is prompted to edit the value.     Return True if validation succeeded or False or an error message when it failed.</p> <p>ValidationResult is a bool or the error message (that implicitly means it has failed).</p> <pre><code>def check(tag: Tag):\n    if tag.val &lt; 10:\n        return \"The value must be at least 10\"\nm.form({\"number\", Tag(12, validation=check)})\n</code></pre> <p>Either use a custom callback function or mininterface.validators.</p> <pre><code>from mininterface.validators import not_empty\nm.form({\"number\", Tag(\"\", validation=not_empty)})\n# User cannot leave the field empty.\n</code></pre> <p>You may use the validation in a type annotation. <pre><code>from mininterface import Tag, Validation\n@dataclass\nclass Env:\n    my_text: Annotated[str, Validation(not_empty) = \"will not be emtpy\"\n\n    # which is an alias for:\n    # my_text: Annotated[str, Tag(validation=not_empty)] = \"will not be emtpy\"\n</code></pre></p> <p>NOTE Undocumented feature, we can return tuple [ValidationResult, FieldValue] to set the self.val.</p>"},{"location":"Tag/#mininterface.Tag.choices","title":"<code>choices: ChoicesType | None = None</code>","text":"<p>Print the radio buttons / select box. Constraint the value.</p> <p><pre><code>from dataclasses import dataclass\nfrom typing import Annotated\nfrom mininterface import run, Choices\n\n@dataclass\nclass Env:\n    foo: Annotated[\"str\", Choices(\"one\", \"two\")] = \"one\"\n    # `Choices` is an alias for `Tag(choices=)`\n\nm = run(Env)\nm.form()  # prompts a dialog\n</code></pre> </p> <p>Info</p> <p>When dealing with a simple use case, use the mininterface.choice dialog.</p>"},{"location":"Tag/#mininterface.Tag.on_change","title":"<code>on_change: Callable[[Tag], Any] | None = None</code>","text":"<p>Accepts a callback that launches whenever the value changes (if the validation succeeds). The callback runs while the dialog is still running. The return value of the callback is currently not used.</p> <p>In the following example, we alter the heading title according to the chosen value.</p> <pre><code>from mininterface import run, Tag\n\ndef callback(tag: Tag):\n    tag.facet.set_title(f\"Value changed to {tag.val}\")\n\nm = run()\nm.facet.set_title(\"Click the checkbox\")\nm.form({\n    \"My choice\": Tag(choices=[\"one\", \"two\"], on_change=callback)\n})\n</code></pre> <p> </p>"},{"location":"Tag/#mininterface.Tag.facet","title":"<code>facet: Optional[Facet] = None</code>","text":"<p>Access to the UI <code>facet</code> from the front-end side. (Read <code>Mininterface.facet</code> to access from the back-end side.)</p> <p>Set the UI facet from within a callback, ex. a validator.</p> <pre><code>from mininterface import run, Tag\n\ndef my_check(tag: Tag):\n    tag.facet.set_title(\"My form title\")\n    return \"Validation failed\"\n\nwith run(title='My window title') as m:\n    m.form({\"My form\": Tag(1, validation=my_check)})\n</code></pre> <p>This happens when you click ok.</p> <p></p>"},{"location":"Tag/#mininterface.Tag.original_val","title":"<code>original_val = None</code>","text":"<p>Meant to be read only in callbacks. The original value, preceding UI change. Handy while validating.</p> <pre><code>def check(tag.val):\n    if tag.val != tag.original_val:\n        return \"You have to change the value.\"\nm.form({\"number\", Tag(8, validation=check)})\n</code></pre>"},{"location":"Tag/#mininterface.Tag.set_val","title":"<code>set_val</code>","text":"<p>Sets the value without any checks.</p>"},{"location":"Tag/#mininterface.Tag.update","title":"<code>update</code>","text":"<p>UI value \u2192 Tag value \u2192 original value. (With type conversion and checks.)</p> <p>Parameters:</p> Name Type Description Default <code>ui_value</code> <code>TagValue</code> <p>The value as it has been updated in a UI. Update accordingly the value in the original linked dict/object the mininterface was invoked with.</p> <p>Validates the type and do the transformation. (Ex: Some values might be nulled from \"\".)</p> required <p>Returns:</p> Type Description <code>bool</code> <p>bool, whether the value is alright or whether the revision is needed.</p>"},{"location":"Tag/#mininterface.Choices","title":"<code>Choices(*choices)</code>","text":"<p>An alias, see <code>Tag.choices</code></p>"},{"location":"Types/","title":"Types","text":"<p>Various types are supported:</p> <ul> <li>scalars</li> <li>functions</li> <li>well-known objects (<code>Path</code>, <code>datetime</code>)</li> <li>iterables (like <code>list[Path]</code>)</li> <li>custom classes (somewhat)</li> <li>union types (like <code>int | None</code>)</li> </ul> <p>Take a look how it works with the variables organized in a dataclass:</p> <pre><code>from dataclasses import dataclass\nfrom pathlib import Path\n\nfrom mininterface import run\n\n\n@dataclass\nclass Env:\n    my_number: int = 1\n    \"\"\" A dummy number \"\"\"\n    my_boolean: bool = True\n    \"\"\" A dummy boolean \"\"\"\n    my_conditional_number: int | None = None\n    \"\"\" A number that can be null if left empty \"\"\"\n    my_path: Path = Path(\"/tmp\")\n    \"\"\" A dummy path \"\"\"\n\n\nm = run(Env)  # m.env contains an Env instance\nm.form()  # Prompt a dialog; m.form() without parameter edits m.env\nprint(m.env)\n# Env(my_number=1, my_boolean=True, my_path=PosixPath('/tmp'),\n#  my_point=&lt;__main__.Point object at 0x7ecb5427fdd0&gt;)\n</code></pre> <p></p> <p>Variables organized in a dict:</p> <p>Along scalar types, there is (basic) support for common iterables or custom classes.</p> <pre><code>from mininterface import run\n\nclass Point:\n    def __init__(self, i: int):\n        self.i = i\n\n    def __str__(self):\n        return str(self.i)\n\n\nvalues = {\"my_number\": 1,\n          \"my_list\": [1, 2, 3],\n          \"my_point\": Point(10)\n          }\n\nm = run()\nm.form(values)  # Prompt a dialog\nprint(values)  # {'my_number': 2, 'my_list': [2, 3], 'my_point': &lt;__main__.Point object...&gt;}\nprint(values[\"my_point\"].i)  # 100\n</code></pre> <p></p>"},{"location":"Types/#mininterface.types.CallbackTag","title":"<code>CallbackTag</code>","text":"<p>Callback function is guaranteed to receives the Tag as a parameter.</p> <p>Warning</p> <p>Experimental. May change.</p> <p>For the following examples, we will use these custom callback functions: <pre><code>from mininterface import run\n\ndef callback_raw():\n    \"\"\" Dummy function \"\"\"\n    print(\"Priting text\")\n    return 50\n\ndef callback_tag(tag: Tag):\n    \"\"\" Receives a tag \"\"\"\n    print(\"Printing\", type(tag))\n    return 100\n\nm = run()\n</code></pre></p> <p>Use as buttons in a form: <pre><code>m.form({\"Button\": callback_raw})\nm.form({\"Button\": CallbackTag(callback_tag)})\n</code></pre></p> <p></p> <p>Via form, we receive the function handler: <pre><code>out = m.form({\n    \"My choice\": Tag(choices=[callback_raw, CallbackTag(callback_tag)])\n})\nprint(out)  # {'My choice': &lt;function callback_raw at 0x7ae5b3e74ea0&gt;}\n</code></pre></p> <p>Via choice, we receive the function output:</p> <pre><code>out = m.choice({\n    \"My choice1\": callback_raw,\n    \"My choice2\": CallbackTag(callback_tag),\n    # Not supported: \"My choice3\": Tag(callback_tag, annotation=CallbackTag),\n})\nprint(out)  # output of callback0 or callback_tag, ex:\n#    Printing &lt;class 'mininterface.types.CallbackTag'&gt;\n#    100\n</code></pre> <p></p> <p>You may use callback in a dataclass. <pre><code>@dataclass\nclass Callbacks:\n    p1: Callable = callback0\n    p2: Annotated[Callable, CallbackTag(description=\"Foo\")] = callback_tag\n    # Not supported: p3: CallbackTag = callback_tag\n    # Not supported: p4: CallbackTag = field(default_factory=CallbackTag(callback_tag))\n    # Not supported: p5: Annotated[Callable, Tag(description=\"Bar\", annotation=CallbackTag)] = callback_tag\n\nm = run(Callbacks)\nm.form()\n</code></pre></p>"},{"location":"Types/#mininterface.types.PathTag","title":"<code>PathTag</code>","text":"<p>Contains a Path or their list. Use this helper object to select files.</p> <p>In the following example, we see that it is not always needed to use this object.</p> <ul> <li>File 1 \u2013 plain detection, button to a file picker appeared.</li> <li>File 2 \u2013 the same.</li> <li>File 3 \u2013 we specified multiple paths can be selected.</li> </ul> <pre><code>from pathlib import Path\nfrom mininterface import run, Tag\nfrom mininterface.aliases import PathTag\n\nm = run()\nout = m.form({\n    \"File 1\": Path(\"/tmp\"),\n    \"File 2\": Tag(\"\", annotation=Path),\n    \"File 3\": PathTag([Path(\"/tmp\")], multiple=True),\n})\nprint(out)\n# {'File 1': PosixPath('/tmp'), 'File 2': PosixPath('.'), 'File 3': [PosixPath('/tmp')]}\n</code></pre> <p></p>"},{"location":"Types/#mininterface.types.PathTag.multiple","title":"<code>multiple: bool = False</code>","text":"<p>The user can select multiple files.</p>"},{"location":"Types/#mininterface.types.DatetimeTag","title":"<code>DatetimeTag</code>","text":"<p>Warning</p> <p>Experimental. Still in development.</p> <p>Datetime is supported.</p> <pre><code>from datetime import datetime\nfrom dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_date: datetime\n\nm = run(Env)\n</code></pre> <p>The arrows change the day (or the datetime part the keyboard caret is currently editing).</p> <p></p> <p>In this code, we want only the date part.</p> <pre><code>from datetime import date\nfrom dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_date: date\n\nm = run(Env)\n</code></pre> <p>After clicking the button (or hitting <code>Ctrl+Shift+C</code>), a calendar appear.</p> <p></p>"},{"location":"Types/#mininterface.types.DatetimeTag.date","title":"<code>date: bool = False</code>","text":"<p>The date part is active</p>"},{"location":"Types/#mininterface.types.DatetimeTag.time","title":"<code>time: bool = False</code>","text":"<p>The time part is active</p>"},{"location":"Types/#mininterface.types.DatetimeTag.full_precision","title":"<code>full_precision: Optional[bool] = None</code>","text":"<p>Include full time precison, seconds, microseconds.</p>"},{"location":"Types/#mininterface.types.Validation","title":"<code>Validation(check)</code>","text":"<p>Alias to <code>Tag(validation=...)</code></p> <pre><code>from mininterface import Tag, Validation\n@dataclass\nclass Env:\n    my_text: Annotated[str, Validation(not_empty) = \"will not be emtpy\"\n\n    # which is an alias for:\n    # my_text: Annotated[str, Tag(validation=not_empty)] = \"will not be emtpy\"\n</code></pre> <p>Parameters:</p> Name Type Description Default <code>check</code> <code>Callable[[Tag], ValidationResult | tuple[ValidationResult, TagValue]]</code> <p>Callback function.</p> required"},{"location":"Types/#mininterface.types.Choices","title":"<code>Choices(*choices)</code>","text":"<p>An alias, see <code>Tag.choices</code></p>"},{"location":"Validation/","title":"Validation","text":"<p>We recommend to use the dataclass and validate with the <code>Annotated</code> keyword. We use a Validation type here.</p> <pre><code>from typing import Annotated\nfrom mininterface.validators import not_empty\nfrom mininterface import Validation\n\n@dataclass\nclass Env:\n    test: Annotated[str, Validation(not_empty)] = \"hello\"\n</code></pre> <p>Under the hood, this is just a <code>Tag</code>.</p> <pre><code>@dataclass\nclass Env:\n    test: Annotated[str, Tag(validation=not_empty)] = \"hello\"\n</code></pre> <p>Why we used it in an Annotated statement? To preserve the date type.</p> <pre><code>@dataclass\nclass Env:\n    my_string: Tag = Tag(\"hello\", validation=not_empty)\n\nm = run(Env)\nprint(type(m.env.my_string))  # Tag\nprint(m.env.my_string.val)  # hello\n</code></pre>"},{"location":"Validation/#validators","title":"validators","text":"<p>Functions suitable for Tag validation. When the user submits a value whose validation fails, they are prompted to edit the value.</p> <pre><code>m = run()\nmy_dict = m.form({\"my_text\", Tag(\"\", validation=validators.not_empty)})\nmy_dict[\"my_text\"]  # You can be sure the value is not empty here.\n</code></pre> <p>Note that alternatively to this module, you may validate with Pydantic or an attrs model.</p> <pre><code>from pydantic import BaseModel, Field\n\nclass MyModel(BaseModel):\n    restrained: str = Field(default=\"hello\", max_length=5)\n</code></pre> <pre><code>import attr\nfrom attr.validators import max_len\n\n@attr.s\nclass AttrsModel:\n    restrained: str = attr.ib(default=\"hello\", validator=max_len(5))\n</code></pre>"},{"location":"Validation/#mininterface.validators.not_empty","title":"<code>not_empty(tag)</code>","text":"<p>Assures that Tag the user has written a value and did not let the field empty.</p> <pre><code>from mininterface import Tag, validators, run\n\nm = run()\nm.form({\"my_text\": Tag(\"\", validation=validators.not_empty)})\n# User cannot leave the string field empty.\n</code></pre> <p>When submitting an empty value, a warning appears:</p> <p></p> <p>Note that for Path, an empty string is converted to an empty Path('.'), hence '.' too is considered as an empty input and the user is not able to set '.' as a value. This does not seem to me as a bad behaviour as in CLI you clearly see the CWD, whereas in a UI the CWD is not evident.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>Tag</code> required"},{"location":"Validation/#mininterface.validators.limit","title":"<code>limit(maxOrMin=None, max_=None, lt=None, gt=None, transform=False)</code>","text":"<p>Limit a number range or a string length.</p> <p>Either use as <code>limit(maximum)</code> or <code>limit(minimum, maximum)</code>.</p> <p>Parameters:</p> Name Type Description Default <code>maximum</code> <code>int</code> <p><code>limit(maximum)</code> \u2013 from zero (including) to maximum (including)</p> required <code>minimum</code> <code>int</code> <p><code>limit(minimum, maximum)</code> \u2013 From minimum (including) to maximum (including)</p> required <code>lt</code> <code>float | None</code> <p>lesser than</p> <code>None</code> <code>gt</code> <code>float | None</code> <p>greater than</p> <code>None</code> <code>transform</code> <code>bool</code> <p>If the value is not within the limit, transform it to a boundary. <pre><code>from mininterface import run, Tag\nfrom mininterface.validators import limit\n\nm = run()\nm.form({\"my_number\": Tag(2, validation=limit(1, 10, transform=True))})\n# Put there '50' \u2192 transformed to 10 and dialog reappears\n# with 'Value must be between 1 and 10.'\n</code></pre></p> <p></p> <code>False</code>"},{"location":"run/","title":"Run","text":"<p>The main access, start here. Wrap your configuration dataclass into <code>run</code> to access the interface. An interface is chosen automatically, with the preference of the graphical one, regressed to a text interface for machines without display. Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly with the default from a config file if such exists. It searches the config file in the current working directory, with the program name ending on .yaml, ex: <code>program.py</code> will fetch <code>./program.yaml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>env_or_list</code> <code>Type[EnvClass] | list[Type[Command]] | None</code> <ul> <li><code>dataclass</code> Dataclass with the configuration. Their values will be modified with the CLI arguments.</li> <li><code>list</code> of Commands let you create multiple commands within a single program, each with unique options.</li> <li><code>None</code> You need just the dialogs, no CLI/config file parsing.</li> </ul> <code>None</code> <code>ask_on_empty_cli</code> <code>bool</code> <p>If program was launched with no arguments (empty CLI), invokes self.form() to edit the fields. (Withdrawn when <code>ask_for_missing</code> happens.) <pre><code>@dataclass\nclass Env:\nnumber: int = 3\ntext: str = \"\"\nm = run(Env, ask_on_empty=True)\n</code></pre></p> <pre><code>$ program.py  #  omitting all parameters\n# Dialog for `number` and `text` appears\n$ program.py --number 3\n# No dialog appears\n</code></pre> <code>False</code> <code>title</code> <code>str</code> <p>The main title. If not set, taken from <code>prog</code> or program name.</p> <code>''</code> <code>config_file</code> <code>Path | str | bool</code> <p>File to load YAML to be merged with the configuration. You do not have to re-define all the settings in the config file, you can choose a few. If set to True (default), we try to find one in the current working dir, whose name stem is the same as the program's. Ex: <code>program.py</code> will search for <code>program.yaml</code>. If False, no config file is used.</p> <code>True</code> <code>add_verbosity</code> <code>bool</code> <p>Adds the verbose flag that automatically sets the level to <code>logging.INFO</code> (-v) or <code>logging.DEBUG</code> (-vv).</p> <pre><code>import logging\nlogger = logging.getLogger(__name__)\n\nm = run(Env, add_verbosity=True)\nlogger.info(\"Info shown\") # needs `-v` or `--verbose`\nlogger.debug(\"Debug not shown\")  # needs `-vv`\n# $ program.py --verbose\n# Info shown\n</code></pre> <pre><code>$ program.py --verbose\nInfo shown\n</code></pre> <code>True</code> <code>ask_for_missing</code> <code>bool</code> <p>If some required fields are missing at startup, we ask for them in a UI instead of program exit.</p> <pre><code>@dataclass\nclass Env:\n    required_number: int\nm = run(Env, ask_for_missing=True)\n</code></pre> <pre><code>$ program.py  # omitting --required-number\n# Dialog for `required_number` appears\n</code></pre> <code>True</code> <code>interface</code> <code>Type[Mininterface] | Literal['gui'] | Literal['tui'] | None</code> <p>Which interface to prefer. By default, we use the GUI, the fallback is the TUI. You may write \"gui\" or \"tui\" literal or pass a specific Mininterface type, see the full list of possible interfaces.</p> <code>None</code> <code>args</code> <code>Optional[Sequence[str]]</code> <p>Parse arguments from a sequence instead of the command line.</p> <code>None</code> <p>Kwargs:     The same as for argparse.ArgumentParser.</p> <p>Returns:</p> Type Description <code>Mininterface[EnvClass]</code> <p>An interface, ready to be used.</p> <p>You cay context manager the function by a <code>with</code> statement. The stdout will be redirected to the interface (ex. a GUI window).</p> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_number: int = 4\n\nwith run(Env) as m:\n    print(f\"Your important number is {m.env.my_number}\")\n    boolean = m.is_yes(\"Is that alright?\")\n</code></pre> <p> </p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Mininterface \u2013 access to GUI, TUI, CLI and config files","text":"<p>Write the program core, do not bother with the input/output.</p> <p> </p> <p>Check out the code, which is surprisingly short, that displays such a window or its textual fallback.</p> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    \"\"\" This calculates something. \"\"\"\n\n    my_flag: bool = False\n    \"\"\" This switches the functionality \"\"\"\n\n    my_number: int = 4\n    \"\"\" This number is very important \"\"\"\n\nif __name__ == \"__main__\":\n    m = run(Env, prog=\"My application\")\n    m.form()\n    # Attributes are suggested by the IDE\n    # along with the hint text 'This number is very important'.\n    print(m.env.my_number)\n</code></pre>"},{"location":"#contents","title":"Contents","text":"<ul> <li>You got CLI</li> <li>You got config file management</li> <li>You got dialogues</li> <li>Background</li> <li>Installation</li> <li>Docs</li> <li>Examples</li> </ul>"},{"location":"#you-got-cli","title":"You got CLI","text":"<p>It was all the code you need. No lengthy blocks of code imposed by an external dependency. Besides the GUI/TUI, you receive powerful YAML-configurable CLI parsing.</p> <pre><code>$ ./program.py --help\nusage: My application [-h] [-v] [--my-flag | --no-my-flag] [--my-number INT]\n\nThis calculates something.\n\n\u256d\u2500 options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 -h, --help             show this help message and exit                  \u2502\n\u2502 -v, --verbose          Verbosity level. Can be used twice to increase.  \u2502\n\u2502 --my-flag, --no-my-flag                                                 \u2502\n\u2502                        This switches the functionality (default: False) \u2502\n\u2502 --my-number INT        This number is very important (default: 4)       \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre>"},{"location":"#you-got-config-file-management","title":"You got config file management","text":"<p>Loading config file is a piece of cake. Alongside <code>program.py</code>, put <code>program.yaml</code> and put there some of the arguments. They are seamlessly taken as defaults.</p> <pre><code>my_number: 555\n</code></pre> <pre><code>$ program.py --help\n...\n\u2502 --my-number INT        This number is very important (default: 555)     \u2502\n</code></pre>"},{"location":"#you-got-dialogues","title":"You got dialogues","text":"<p>Check out several useful methods to handle user dialogues. Here we bound the interface to a <code>with</code> statement that redirects stdout directly to the window.</p> <pre><code>with run(Env) as m:\n    print(f\"Your important number is {m.env.my_number}\")\n    boolean = m.is_yes(\"Is that alright?\")\n</code></pre> <p> </p>"},{"location":"#background","title":"Background","text":"<p>Wrapper between the tyro <code>argparse</code> replacement and tkinter_form that converts dicts into a GUI.</p> <p>Writing a small and useful program might be a task that takes fifteen minutes. Adding a CLI to specify the parameters is not so much overhead. But building a simple GUI around it? HOURS! Hours spent on researching GUI libraries, wondering why the Python desktop app ecosystem lags so far behind the web world. All you need is a few input fields validated through a clickable window... You do not deserve to add hundred of lines of the code just to define some editable fields. <code>Mininterface</code> is here to help.</p> <p>The config variables needed by your program are kept in cozy dataclasses. Write less! The syntax of tyro does not require any overhead (as its <code>argparse</code> alternatives do). You just annotate a class attribute, append a simple docstring and get a fully functional application: * Call it as <code>program.py --help</code> to display full help. * Use any flag in CLI: <code>program.py --my-flag</code>  causes <code>env.my_flag</code> be set to <code>True</code>. * The main benefit: Launch it without parameters as <code>program.py</code> to get a full working window with all the flags ready to be edited. * Running on a remote machine? Automatic regression to the text interface.</p>"},{"location":"#installation","title":"Installation","text":"<p>Install with a single command from PyPi.</p> <pre><code>pip install mininterface[all]  # GPLv3 and compatible\n</code></pre>"},{"location":"#minimal-installation","title":"Minimal installation","text":"<p>Should you need just the CLI part and you are happy with basic text dialogs, use these commands instead:</p> <pre><code>pip install --no-dependencies mininterface\npip install tyro typing_extensions pyyaml\n</code></pre>"},{"location":"#docs","title":"Docs","text":"<p>See the docs overview at https://cz-nic.github.io/mininterface/.</p>"},{"location":"#examples","title":"Examples","text":"<p>A powerful <code>m.form</code> dialog method accepts either a dataclass or a dict. Take a look on both.</p>"},{"location":"#a-complex-dataclass","title":"A complex dataclass.","text":"<pre><code>from typing import Annotated\nfrom dataclasses import dataclass\nfrom mininterface.validators import not_empty\nfrom mininterface import run, Tag, Validation\n\n@dataclass\nclass NestedEnv:\n  another_number: int = 7\n  \"\"\" This field is nested \"\"\"\n\n@dataclass\nclass Env:\n  nested_config: NestedEnv\n\n  mandatory_str: str\n  \"\"\" As there is no default value, you will be prompted automatically to fill up the field \"\"\"\n\n  my_number: int | None = None\n  \"\"\" This is not just a dummy number, if left empty, it is None. \"\"\"\n\n  my_string: str = \"Hello\"\n  \"\"\" A dummy string \"\"\"\n\n  my_flag: bool = False\n  \"\"\" Checkbox test \"\"\"\n\n  my_validated: Annotated[str, Validation(not_empty)] = \"hello\"\n  \"\"\" A validated field \"\"\"\n\nm = run(Env, title=\"My program\")\n# See some values\nprint(m.env.nested_config.another_number)  # 7\nprint(m.env)\n# Env(nested_config=NestedEnv(another_number=7), my_number=5, my_string='Hello', my_flag=False, my_validated='hello')\n\n# Edit values in a dialog\nm.form()\n</code></pre> <p>As the attribute <code>mandatory_str</code> requires a value, a prompt appears automatically:</p> <p></p> <p>Then, full form appears:</p> <p></p>"},{"location":"#form-with-paths","title":"Form with paths","text":"<p>We have a dict with some paths. Here is how it looks.</p> <pre><code>from pathlib import Path\nfrom mininterface import run, Tag\n\nm = run(title=\"My program\")\nmy_dictionary = {\n  \"paths\": Tag(\"\", annotation=list[Path]),\n  \"default_paths\": Tag([Path(\"/tmp\"), Path(\"/usr\")], annotation=list[Path])\n  }\n\n# Edit values in a dialog\nm.form(my_dictionary)\n</code></pre> <p></p>"},{"location":"Changelog/","title":"Changelog","text":""},{"location":"Changelog/#072","title":"0.7.2","text":"<ul> <li>GUI calendar</li> </ul>"},{"location":"Changelog/#071-2024-11-27","title":"0.7.1 (2024-11-27)","text":"<ul> <li>GUI scrollbars if window is bigger than the screen</li> <li>non-interactive session support</li> <li>datetime support</li> <li>nested generics support (a tuple in a list)</li> </ul>"},{"location":"Changelog/#070-2024-11-08","title":"0.7.0 (2024-11-08)","text":"<ul> <li>hidden <code>--integrate-to-system</code> argument</li> <li>interfaces migrated to <code>mininterface.interfaces</code> to save around 50 ms starting time due to lazy loading</li> <li>SubcommandPlaceholder</li> </ul>"},{"location":"Exceptions/","title":"Exceptions","text":"<p>Exceptions that might make sense to be used outside the library.</p>"},{"location":"Exceptions/#mininterface.exceptions.Cancelled","title":"<code>Cancelled</code>","text":"<p>User has cancelled. A SystemExit based exception noting that the program exits without a traceback, ex. if user hits the escape or closes the window.</p>"},{"location":"Exceptions/#mininterface.exceptions.ValidationFail","title":"<code>ValidationFail</code>","text":"<p>Signal to the form that submit failed and we want to restore it.</p>"},{"location":"Exceptions/#mininterface.exceptions.InterfaceNotAvailable","title":"<code>InterfaceNotAvailable</code>","text":"<p>Interface failed to init, ex. display not available in GUI. Or the underlying dependency was uninstalled.</p>"},{"location":"Experimental/","title":"Experimental","text":""},{"location":"Experimental/#mininterface.experimental.SubmitButton","title":"<code>SubmitButton</code>","text":"<p>Create a button. When clicked, the form submits.         If submission succeeds (validation checks pass), its value becomes True.</p> <pre><code>from pathlib import Path\nfrom mininterface import run, Tag\nfrom mininterface.experimental import SubmitButton\n\nm = run()\nout = m.form({\n    \"File name\": Tag(\"/tmp\", annotation=Path),\n    \"Append text\": {\n        \"My text\": \"\",\n        \"Append now\": SubmitButton()\n    },\n    \"Duplicate\": {\n        \"Method\": Tag(\"twice\", choices=[\"twice\", \"thrice\"]),\n        \"Duplicate now\": SubmitButton()\n    }\n})\n# Clicking on 'Append now' button\nprint(out)\n# {'File name': PosixPath('/tmp'),\n# 'Append text': {'My text': '', 'Append now': True},\n# 'Duplicate': {'Method': 'twice', 'Duplicate now': False}}\n</code></pre> <p></p>"},{"location":"Facet/","title":"Facet","text":"<p>A frontend side of the interface. While a dialog is open,     this allows to set frontend properties like the heading.</p> <p>Read <code>Tag.facet</code> to see how to access from the front-end side. Read <code>Mininterface.facet</code> to see how to access from the back-end side.</p>"},{"location":"Facet/#mininterface.facet.Facet.set_title","title":"<code>set_title(text)</code>","text":"<p>Set the main heading.</p>"},{"location":"Facet/#mininterface.facet.Facet.submit","title":"<code>submit(_post_submit=None)</code>","text":"<p>Submits the whole form.</p> <p>```python from mininterface import run, Tag</p> <p>def callback(tag: Tag):     tag.facet.submit()</p> <p>m = run() out = m.form({     \"My choice\": Tag(choices=[\"one\", \"two\"], on_change=callback) })</p>"},{"location":"Facet/#mininterface.facet.Facet.submit--continue-here-immediately-after-clicking-on-a-radio-button","title":"continue here immediately after clicking on a radio button","text":""},{"location":"Helper-types/","title":"Helper types","text":""},{"location":"Helper-types/#mininterface.tag.ValidationResult","title":"<code>ValidationResult = bool | ErrorMessage</code>","text":"<p>Callback validation result is either boolean or an error message.</p>"},{"location":"Helper-types/#mininterface.tag.ErrorMessage","title":"<code>ErrorMessage = TypeVar('ErrorMessage')</code>","text":"<p>A string, callback validation error message.</p>"},{"location":"Helper-types/#mininterface.tag.TagValue","title":"<code>TagValue = TypeVar('TagValue', bound=Any)</code>","text":"<p>Any value. It is being wrapped by a Tag.</p>"},{"location":"Helper-types/#mininterface.tag.ChoicesType","title":"<code>ChoicesType = list[TagValue] | tuple[TagValue] | set[TagValue] | dict[ChoiceLabel, TagValue] | list[Enum] | Type[Enum]</code>","text":"<p>You can denote the choices in many ways. Either put options in an iterable or to a dict <code>{labels: value}</code>. Values might be Tags as well.</p> <p>See mininterface.choice or <code>Tag.choices</code> for examples.</p>"},{"location":"Helper-types/#mininterface.form_dict.DataClass","title":"<code>DataClass = TypeVar('DataClass')</code>","text":"<p>Any dataclass. Or a pydantic model or attrs.</p>"},{"location":"Helper-types/#mininterface.form_dict.EnvClass","title":"<code>EnvClass = TypeVar('EnvClass', bound=DataClass)</code>","text":"<p>Any dataclass. Its instance will be available through [miniterface.env] after CLI parsing.</p>"},{"location":"Interfaces/","title":"Interfaces","text":""},{"location":"Interfaces/#all-possible-interfaces","title":"All possible interfaces","text":"<p>Normally, you get an interface through mininterface.run but if you do not wish to parse CLI and config file, you can invoke one directly <code>from mininterface.interfaces import *</code>.</p> <p>Apart from the default <code>Mininterface</code>, the base interface the others are fully compatible with, several interfaces exist:</p> <p>How to invoke a specific interface.</p> <pre><code>from mininterface.interfaces import TuiInterface\n\nwith TuiInterface(\"My program\") as m:\n    number = m.ask_number(\"Returns number\")\n</code></pre>"},{"location":"Interfaces/#guiinterface-tkinterface","title":"<code>GuiInterface</code> = <code>TkInterface</code>","text":"<p>A tkinter window.</p>"},{"location":"Interfaces/#tuiinterface","title":"<code>TuiInterface</code>","text":"<p>An interactive terminal.</p>"},{"location":"Interfaces/#textualinterface","title":"<code>TextualInterface</code>","text":"<p>If textual installed, rich and mouse clickable interface is used.</p>"},{"location":"Interfaces/#textinterface","title":"<code>TextInterface</code>","text":"<p>Plain text only interface with no dependency as a fallback.</p> <p>When used in a with statement, the non-interactive session becomes interactive if possible, see the Mininterface enter method.</p>"},{"location":"Interfaces/#replinterface","title":"<code>ReplInterface</code>","text":"<p>A debug terminal. Invokes a breakpoint after every dialog.</p>"},{"location":"Mininterface/","title":"Mininterface","text":"<p>The base interface.     You get one through <code>mininterface.run</code> which fills CLI arguments and config file to <code>mininterface.env</code>     or you can create one directly (without benefiting from the CLI parsing).</p> Raise <p>Cancelled: A SystemExit based exception noting that the program exits without a traceback, ex. if user hits the escape.</p> Raise <p>InterfaceNotAvailable: Interface failed to init, ex. display not available in GUI.</p>"},{"location":"Mininterface/#mininterface.Mininterface.env","title":"<code>env: EnvClass = EnvInstance</code>","text":"<p>Parsed arguments, fetched from cli.     Contains whole configuration (previously fetched from CLI and config file).</p> <pre><code>$ program.py --number 10\n</code></pre> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    number: int = 3\n    text: str = \"\"\n\nm = run(Env)\nprint(m.env.number)  # 10\n</code></pre>"},{"location":"Mininterface/#mininterface.Mininterface.facet","title":"<code>facet = Facet(None, self.env)</code>","text":"<p>Access to the UI <code>facet</code> from the back-end side. (Read <code>Tag.facet</code> to access from the front-end side.)</p> <pre><code>from mininterface import run\nwith run(title='My window title') as m:\n    m.facet.set_title(\"My form title\")\n    m.form({\"My form\": 1})\n</code></pre> <p></p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__","title":"<code>__enter__()</code>","text":"<p>Usage within the with statement makes the program to attempt for the following benefits:</p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__--continual-window","title":"Continual window","text":"<p>Do not vanish between dialogs (the GUI window stays the same)</p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__--stdout-redirection","title":"Stdout redirection","text":"<p>Redirects the stdout to a text area instead of a terminal.</p> <pre><code>from mininterface import run\n\nwith run() as m:\n    print(\"This is a printed text\")\n    m.alert(\"Alert text\")\n</code></pre> <p></p>"},{"location":"Mininterface/#mininterface.Mininterface.__enter__--make-the-session-interactive","title":"Make the session interactive","text":"<p>If run from an interactive terminal or if a GUI is used, nothing special happens.</p> <pre><code># $ ./program.py\nwith run() as m:\n    m.ask_number(\"What number\")\n</code></pre> <p></p> <p>However, when run in a non-interactive session with TUI (ex. no display), TextInterface is used which is able to turn it into an interactive one.</p> <pre><code>piped_in = int(sys.stdin.read())\n\nwith run(interface=\"tui\") as m:\n    result = m.ask_number(\"What number\") + piped_in\nprint(result)\n</code></pre> <pre><code>$ echo 2 | ./program.py\nWhat number: 3\n5\n</code></pre> <p>If the <code>with</code> statement is not used, the result is the same as if an interactive session is not available, like in a cron job. In that case, plain Mininterface is used.</p> <pre><code>piped_in = int(sys.stdin.read())\n\nm = run(interface=\"tui\")\nresult = m.ask_number(\"What number\") + piped_in\nprint(result)\n</code></pre> <pre><code>echo 2 | ./program.py\nAsking: What number\n3\n</code></pre>"},{"location":"Mininterface/#mininterface.Mininterface.alert","title":"<code>alert(text)</code>","text":"<p>Prompt the user to confirm the text.</p>"},{"location":"Mininterface/#mininterface.Mininterface.ask","title":"<code>ask(text)</code>","text":"<p>Prompt the user to input a text.</p>"},{"location":"Mininterface/#mininterface.Mininterface.ask_number","title":"<code>ask_number(text)</code>","text":"<p>Prompt the user to input a number. Empty input = 0.</p> <pre><code>m = run()  # receives a Mininterface object\nm.ask_number(\"What's your age?\")\n</code></pre> <p></p> <p>Parameters:</p> Name Type Description Default <code>text</code> <code>str</code> <p>The question text.</p> required <p>Returns:</p> Type Description <code>int</code> <p>Number</p>"},{"location":"Mininterface/#mininterface.Mininterface.choice","title":"<code>choice(choices, title='', _guesses=None, skippable=True, launch=True, _multiple=True, default=None)</code>","text":"<p>Prompt the user to select. Useful for a menu creation.</p> <p>Parameters:</p> Name Type Description Default <code>choices</code> <code>ChoicesType</code> <p>You can denote the choices in many ways. Either put options in an iterable:</p> <pre><code>from mininterface import run\nm = run()\nm.choice([1, 2])\n</code></pre> <p></p> <p>Or to a dict <code>{name: value}</code>. Then name are used as labels.</p> <pre><code>m.choice({\"one\": 1, \"two\": 2})  # returns 1\n</code></pre> <p>Alternatively, you may specify the names in <code>Tags</code>.</p> <pre><code>m.choice([Tag(1, name=\"one\"), Tag(2, name=\"two\")])  # returns 1\n</code></pre> <p></p> <p>Alternatively, you may use an Enum.</p> <pre><code>class Color(Enum):\n    RED = \"red\"\n    GREEN = \"green\"\n    BLUE = \"blue\"\n\nm.choice(Color)\n</code></pre> <p></p> <p>Alternatively, you may use an Enum instance.</p> <pre><code>class Color(Enum):\n    RED = \"red\"\n    GREEN = \"green\"\n    BLUE = \"blue\"\n\nm.choice(Color.BLUE)\n</code></pre> <p></p> <p>Alternatively, you may use an Enum instances list.</p> <pre><code>m.choice([Color.GREEN, Color.BLUE])\n</code></pre> <p></p> required <code>title</code> <code>str</code> <p>Form title</p> <code>''</code> <code>default</code> <code>str | TagValue | None</code> <p>The value of the checked choice.</p> <p><pre><code>m.choice({\"one\": 1, \"two\": 2}, default=2)  # returns 2\n</code></pre> </p> <code>None</code> <code>skippable</code> <code>bool</code> <p>If there is a single option, choose it directly, without a dialog.</p> <code>True</code> <code>launch</code> <code>bool</code> <p>If the chosen value is a callback, we directly call it and return its return value.</p> <code>True</code> <p>Returns:</p> Type Description <code>TagValue | list[TagValue] | Any</code> <p>The chosen value.</p> <code>TagValue | list[TagValue] | Any</code> <p>If launch=True and the chosen value is a callback, we call it and return its result.</p> <p>Info</p> <p>To tackle a more detailed form, see <code>Tag.choices</code>.</p>"},{"location":"Mininterface/#mininterface.Mininterface.form","title":"<code>form(form=None, title='', *, submit=True)</code>","text":"<p>Prompt the user to fill up an arbitrary form.</p> <p>Use scalars, enums, enum instances, objects like datetime, Paths or their list.</p> <pre><code>from enum import Enum\nfrom mininterface import run, Tag\n\nclass Color(Enum):\n    RED = \"red\"\n    GREEN = \"green\"\n    BLUE = \"blue\"\n\nm = run()\nout = m.form({\n    \"my_number\": 1,\n    \"my_boolean\": True,\n    \"my_enum\": Color,\n    \"my_tagged\": Tag(\"\", name='Tagged value', description='Long hint'),\n    \"my_path\": Path(\"/tmp\"),\n    \"my_paths\": [Path(\"/tmp\")],\n    \"My enum with default\": Color.BLUE\n})\n</code></pre> <p></p> <p>Parameters:</p> Name Type Description Default <code>form</code> <code>DataClass | Type[DataClass] | FormDict | None</code> <p>We accept a dataclass type, a dataclass instance, a dict or None.</p> <ul> <li>If dict, we expect a dict of <code>{labels: value}</code>. The form widget infers from the default value type. The dict can be nested, it can contain a subgroup. The value might be a <code>Tag</code> that allows you to add descriptions.</li> </ul> <p>A checkbox example: <code>{\"my label\": Tag(True, \"my description\")}</code></p> <ul> <li>If None, the <code>self.env</code> is being used as a form, allowing the user to edit whole configuration.     (Previously fetched from CLI and config file.)</li> </ul> <code>None</code> <code>title</code> <code>str</code> <p>Optional form title</p> <code>''</code> <code>submit</code> <code>str | bool</code> <p>Set the submit button text (by default 'Ok') or hide it with False.</p> <code>True</code> <p>Returns:</p> Name Type Description <code>dataclass</code> <code>FormDict | DataClass | EnvClass</code> <p>If the <code>form</code> is null, the output is <code>self.env</code>.</p> <code>dataclass</code> <code>FormDict | DataClass | EnvClass</code> <p>If the <code>form</code> is a dataclass type or a dataclass instance, the output is the dataclass instance.</p> <code>dict</code> <code>FormDict | DataClass | EnvClass</code> <p>If the <code>form</code> is a dict, the output is another dict.</p> <p>Whereas the original dict stays intact (with the values updated), we return a new raw dict with all values resolved (all <code>Tag</code> objects are resolved to their value).</p> <pre><code>original = {\"my label\": Tag(True, \"my description\")}\noutput = m.form(original)  # Sets the label to False in the dialog\n\n# Original dict was updated\nprint(original[\"my label\"])  # Tag(False, \"my description\")\n\n# Output dict is resolved, contains only raw values\nprint(output[\"my label\"])  # False\n</code></pre> <p>Why this behaviour? You need to do some validation, hence you put <code>Tag</code> objects in the input dict. Then, you just need to work with the values.</p> <pre><code>original = {\"my label\": Tag(True, \"my description\")}\noutput = m.form(original)  # Sets the label to False in the dialog\noutput[\"my_label\"]\n</code></pre> <p>In the case you are willing to re-use the dict, you need not to lose the definitions, hence you end up with accessing via the <code>.val</code>.</p> <pre><code>original = {\"my label\": Tag(True, \"my description\")}\n\nfor i in range(10):\n    m.form(original, f\"Attempt {i}\")\n    print(\"The result\", original[\"my label\"].val)\n</code></pre>"},{"location":"Mininterface/#mininterface.Mininterface.is_yes","title":"<code>is_yes(text)</code>","text":"<p>Display confirm box, focusing yes.</p> <pre><code>m = run()\nprint(m.is_yes(\"Is that alright?\"))  # True/False\n</code></pre> <p></p>"},{"location":"Mininterface/#mininterface.Mininterface.is_no","title":"<code>is_no(text)</code>","text":"<p>Display confirm box, focusing no.</p>"},{"location":"Overview/","title":"Overview","text":"<p>Via the run function you get access to the CLI, possibly enriched from the config file. Then, you receive all data as <code>m.env</code> object and dialog methods in a proper UI.</p> <pre><code>graph LR\n    subgraph mininterface\n        run --&gt; GUI\n        run --&gt; TUI\n        run --&gt; env\n        CLI --&gt; run\n        id1[config file] --&gt; CLI\n    end\n    program --&gt; run\n</code></pre>"},{"location":"Overview/#basic-usage","title":"Basic usage","text":"<p>Use a common dataclass, a Pydantic BaseModel or an attrs model to store the configuration. Wrap it to the run function that returns an interface <code>m</code>. Access the configuration via <code>m.env</code> or use it to prompt the user <code>m.is_yes(\"Is that alright?\")</code>.</p> <p>There are a lot of supported types you can use, not only scalars and well-known objects (<code>Path</code>, <code>datetime</code>), but also functions, iterables (like <code>list[Path]</code>) and union types (like <code>int | None</code>). To do even more advanced things, stick the value to a powerful <code>Tag</code> or its subclasses. Ex. for a validation only, use its <code>Validation alias</code>.</p> <p>At last, use <code>Facet</code> to tackle the interface from the back-end (<code>m</code>) or the front-end (<code>Tag</code>) side.</p>"},{"location":"Overview/#ide-suggestions","title":"IDE suggestions","text":"<p>The immediate benefit is the type suggestions you see in an IDE. Imagine following code:</p> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_paths: list[Path]\n    \"\"\" The user is forced to input Paths. \"\"\"\n\n\n@dataclass\nclass Dialog:\n    my_number: int = 2\n    \"\"\" A number \"\"\"\n</code></pre> <p>Now, accessing the main env will trigger the hint. </p> <p>Calling the form with an empty parameter will trigger editing the main env</p> <p></p> <p>Putting there a dict will return the dict too.</p> <p></p> <p>Putting there a dataclass type causes it to be resolved.</p> <p></p> <p>Should you have a resolved dataclass instance, put it there.</p> <p></p> <p>As you see, its attributes are hinted alongside their description.</p> <p></p> <p>Should the dataclass cannot be easily investigated by the IDE (i.e. a required field), just annotate the output.</p> <p></p>"},{"location":"Overview/#bash-completion","title":"Bash completion","text":"<p>Run your program with a hidden <code>--integrate-to-system</code> flag and a tutorial will install bash completion.</p> <p></p>"},{"location":"Overview/#nested-configuration","title":"Nested configuration","text":"<p>You can easily nest the configuration. (See also Tyro Hierarchical Configs).</p> <p>Just put another dataclass inside the config file:</p> <pre><code>@dataclass\nclass FurtherConfig:\n    token: str\n    host: str = \"example.org\"\n\n@dataclass\nclass Env:\n    further: FurtherConfig\n\n...\nm = run(Env)\nprint(m.env.further.host)  # example.org\n</code></pre> <p>The attributes can by defaulted by CLI:</p> <pre><code>$./program.py --further.host example.net\n</code></pre> <p>And in a YAML config file. Note that you are not obliged to define all the attributes, a subset will do. (Ex. you do not need to specify <code>token</code> too.)</p> <pre><code>further:\n  host: example.com\n</code></pre>"},{"location":"Standalone/","title":"Standalone","text":"<p>When invoked directly, it creates simple GUI dialogs.</p> <pre><code>$ mininterface  --help\nusage: Mininterface [-h] [OPTIONS]\n\nSimple GUI dialog. Outputs the value the user entered.\n\n\u256d\u2500 options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 -h, --help              show this help message and exit                                   \u2502\n\u2502 --alert STR             Display the OK dialog with text. (default: '')                    \u2502\n\u2502 --ask STR               Prompt the user to input a text. (default: '')                    \u2502\n\u2502 --ask-number STR        Prompt the user to input a number. Empty input = 0. (default: '') \u2502\n\u2502 --is-yes STR            Display confirm box, focusing yes. (default: '')                  \u2502\n\u2502 --is-no STR             Display confirm box, focusing no. (default: '')                   \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n</code></pre> <p>You can fetch a value to i.e. a bash script.</p> <pre><code>$ mininterface  --ask-number \"What's your age?\"  # GUI or TUI window invoked\n18\n</code></pre> <p> </p>"},{"location":"Subcommands/","title":"Subcommands","text":"<p>Dealing with CLI subcommands, <code>from mininterface.subcommands import *</code></p>"},{"location":"Subcommands/#mininterface.subcommands.Command","title":"<code>Command</code>","text":"<p>The Command is automatically run while instantanied.</p> <p>Experimental \u2013 how should it receive _facet?</p> <p>Put list of Commands to the mininterface.run and divide your application into different sections. Alternative to argparse subcommands.</p> <p>Commands might inherit from the same parent to share the common attributes.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command--subcommandplaceholder","title":"SubcommandPlaceholder","text":"<p>What if I need to use my program Special placeholder class SubcommandPlaceholder. This special class let the user to choose the subcommands via UI, while still benefiniting from default CLI arguments.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command--the-cli-behaviour","title":"The CLI behaviour:","text":"<ul> <li><code>./program.py</code> -&gt; UI started with subcommand choice</li> <li><code>./program.py subcommand --flag</code> -&gt; special class <code>SubcommandPlaceholder</code> allows defining a common <code>--flag</code>     while still starting UI with subcommand choice</li> <li><code>./program.py subcommand1 --flag</code> -&gt; program run</li> <li><code>./program.py subcommand1</code> -&gt; fails to CLI for now</li> </ul>"},{"location":"Subcommands/#mininterface.subcommands.Command--an-example-of-command-usage","title":"An example of Command usage","text":"<pre><code>from dataclasses import dataclass, field\nfrom pathlib import Path\nfrom mininterface import run\nfrom mininterface.exceptions import ValidationFail\nfrom mininterface.subcommands import Command, SubcommandPlaceholder\nfrom tyro.conf import Positional\n\n\n@dataclass\nclass SharedArgs(Command):\n    common: int\n    files: Positional[list[Path]] = field(default_factory=list)\n\n    def init(self):\n        self.internal = \"value\"\n\n\n@dataclass\nclass Subcommand1(SharedArgs):\n    my_local: int = 1\n\n    def run(self):\n        print(\"Common:\", self.common)  # user input\n        print(\"Number:\", self.my_local)  # 1 or user input\n        print(\"Internal:\", self.internal)\n        raise ValidationFail(\"The submit button blocked!\")\n\n\n@dataclass\nclass Subcommand2(SharedArgs):\n    def run(self):\n        self._facet.set_title(\"Button clicked\")  # you can access internal self._facet: Facet\n        print(\"Common files\", self.files)\n\n\nm = run([Subcommand1, Subcommand2, SubcommandPlaceholder])\nm.alert(\"App continue\")\n</code></pre> <p>Let's start the program, passing there common flags, all HTML files in a folder and setting <code>--common</code> to 7. <pre><code>$ program.py  subcommand *.html  --common 7\n</code></pre></p> <p></p> <p>As you see, thanks to <code>SubcommandPlaceholder</code>, subcommand was not chosen yet. Click to the first button.</p> <p></p> <p>and the terminal got:</p> <pre><code>Common: 7\nNumber: 1\nInternal: value\n</code></pre> <p>Click to the second button.</p> <p></p> <p>Terminal output: <pre><code>Common files [PosixPath('page1.html'), PosixPath('page2.html')]\n</code></pre></p>"},{"location":"Subcommands/#mininterface.subcommands.Command--powerful-automation","title":"Powerful automation","text":"<p>Note we use <code>from tyro.conf import Positional</code> to denote the positional argument. We did not have to write <code>--files</code> to put there HTML files.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command.init","title":"<code>init()</code>","text":"<p>Just before the form appears. As the <code>__post_init__</code> method is not guaranteed to run just once (internal CLI behaviour), you are welcome to override this method instead. You can use self._facet from within.</p>"},{"location":"Subcommands/#mininterface.subcommands.Command.run","title":"<code>run()</code>","text":"<p>This method is run automatically in CLI or by a button button it generates in a UI.</p>"},{"location":"Subcommands/#mininterface.subcommands.SubcommandPlaceholder","title":"<code>SubcommandPlaceholder</code>","text":"<p>Use this placeholder to choose the subcomannd via a UI.</p>"},{"location":"Tag/","title":"Tag","text":"<p>Wrapper around a value that encapsulates a description, validation etc. When you provide a value to an interface, you may instead use this object.</p> <p>Bridge between the input values and a UI widget. The widget is created with the help of this object, then transforms the value back (str to int conversion etc).</p>"},{"location":"Tag/#mininterface.Tag.val","title":"<code>val: TagValue = None</code>","text":"<p>The value wrapped by Tag. It can be any value.</p> <pre><code>from mininterface import run, Tag\n\ntag = Tag(True, \"This is my boolean\", bool)\nm = run()\nm.form({\"My boolean\": tag})\nprint(tag.val)  # True/False\nprint()\n</code></pre> <p></p> <p>The encapsulated value is <code>True</code>, <code>tag.description</code> is 'This is my boolean', <code>tag.annotation</code> is <code>bool</code> and 'My boolean' is used as <code>tag.name</code>.</p> <p>Tip</p> <p>If the Tag is nested, the info is fetched to the outer Tag. When updated, the inner Tag value updates accordingly.</p> <pre><code>tag = Tag(Tag(True))\n</code></pre>"},{"location":"Tag/#mininterface.Tag.description","title":"<code>description: str = ''</code>","text":"<p>The description displayed in the UI.</p>"},{"location":"Tag/#mininterface.Tag.annotation","title":"<code>annotation: type | None = None</code>","text":"<p>Used for validation (ex. to convert an empty string to None). If not set, will be determined automatically from the val type.</p>"},{"location":"Tag/#mininterface.Tag.name","title":"<code>name: str | None = None</code>","text":"<p>Name displayed in the UI.</p>"},{"location":"Tag/#mininterface.Tag.validation","title":"<code>validation: Callable[[Tag], ValidationResult | tuple[ValidationResult, TagValue]] | None = None</code>","text":"<p>When the user submits the form, the values are validated (and possibly transformed) with a callback function.     If the validation fails, user is prompted to edit the value.     Return True if validation succeeded or False or an error message when it failed.</p> <p>ValidationResult is a bool or the error message (that implicitly means it has failed).</p> <pre><code>def check(tag: Tag):\n    if tag.val &lt; 10:\n        return \"The value must be at least 10\"\nm.form({\"number\", Tag(12, validation=check)})\n</code></pre> <p>Either use a custom callback function or mininterface.validators.</p> <pre><code>from mininterface.validators import not_empty\nm.form({\"number\", Tag(\"\", validation=not_empty)})\n# User cannot leave the field empty.\n</code></pre> <p>You may use the validation in a type annotation. <pre><code>from mininterface import Tag, Validation\n@dataclass\nclass Env:\n    my_text: Annotated[str, Validation(not_empty) = \"will not be emtpy\"\n\n    # which is an alias for:\n    # my_text: Annotated[str, Tag(validation=not_empty)] = \"will not be emtpy\"\n</code></pre></p> <p>NOTE Undocumented feature, we can return tuple [ValidationResult, FieldValue] to set the self.val.</p>"},{"location":"Tag/#mininterface.Tag.choices","title":"<code>choices: ChoicesType | None = None</code>","text":"<p>Print the radio buttons / select box. Constraint the value.</p> <p><pre><code>from dataclasses import dataclass\nfrom typing import Annotated\nfrom mininterface import run, Choices\n\n@dataclass\nclass Env:\n    foo: Annotated[\"str\", Choices(\"one\", \"two\")] = \"one\"\n    # `Choices` is an alias for `Tag(choices=)`\n\nm = run(Env)\nm.form()  # prompts a dialog\n</code></pre> </p> <p>Info</p> <p>When dealing with a simple use case, use the mininterface.choice dialog.</p>"},{"location":"Tag/#mininterface.Tag.on_change","title":"<code>on_change: Callable[[Tag], Any] | None = None</code>","text":"<p>Accepts a callback that launches whenever the value changes (if the validation succeeds). The callback runs while the dialog is still running. The return value of the callback is currently not used.</p> <p>In the following example, we alter the heading title according to the chosen value.</p> <pre><code>from mininterface import run, Tag\n\ndef callback(tag: Tag):\n    tag.facet.set_title(f\"Value changed to {tag.val}\")\n\nm = run()\nm.facet.set_title(\"Click the checkbox\")\nm.form({\n    \"My choice\": Tag(choices=[\"one\", \"two\"], on_change=callback)\n})\n</code></pre> <p> </p>"},{"location":"Tag/#mininterface.Tag.facet","title":"<code>facet: Optional[Facet] = None</code>","text":"<p>Access to the UI <code>facet</code> from the front-end side. (Read <code>Mininterface.facet</code> to access from the back-end side.)</p> <p>Set the UI facet from within a callback, ex. a validator.</p> <pre><code>from mininterface import run, Tag\n\ndef my_check(tag: Tag):\n    tag.facet.set_title(\"My form title\")\n    return \"Validation failed\"\n\nwith run(title='My window title') as m:\n    m.form({\"My form\": Tag(1, validation=my_check)})\n</code></pre> <p>This happens when you click ok.</p> <p></p>"},{"location":"Tag/#mininterface.Tag.original_val","title":"<code>original_val = None</code>","text":"<p>Meant to be read only in callbacks. The original value, preceding UI change. Handy while validating.</p> <pre><code>def check(tag.val):\n    if tag.val != tag.original_val:\n        return \"You have to change the value.\"\nm.form({\"number\", Tag(8, validation=check)})\n</code></pre>"},{"location":"Tag/#mininterface.Tag.set_val","title":"<code>set_val</code>","text":"<p>Sets the value without any checks.</p>"},{"location":"Tag/#mininterface.Tag.update","title":"<code>update</code>","text":"<p>UI value \u2192 Tag value \u2192 original value. (With type conversion and checks.)</p> <p>Parameters:</p> Name Type Description Default <code>ui_value</code> <code>TagValue</code> <p>The value as it has been updated in a UI. Update accordingly the value in the original linked dict/object the mininterface was invoked with.</p> <p>Validates the type and do the transformation. (Ex: Some values might be nulled from \"\".)</p> required <p>Returns:</p> Type Description <code>bool</code> <p>bool, whether the value is alright or whether the revision is needed.</p>"},{"location":"Tag/#mininterface.Choices","title":"<code>Choices(*choices)</code>","text":"<p>An alias, see <code>Tag.choices</code></p>"},{"location":"Types/","title":"Types","text":"<p>Various types are supported:</p> <ul> <li>scalars</li> <li>functions</li> <li>well-known objects (<code>Path</code>, <code>datetime</code>)</li> <li>iterables (like <code>list[Path]</code>)</li> <li>custom classes (somewhat)</li> <li>union types (like <code>int | None</code>)</li> </ul> <p>Take a look how it works with the variables organized in a dataclass:</p> <pre><code>from dataclasses import dataclass\nfrom pathlib import Path\n\nfrom mininterface import run\n\n\n@dataclass\nclass Env:\n    my_number: int = 1\n    \"\"\" A dummy number \"\"\"\n    my_boolean: bool = True\n    \"\"\" A dummy boolean \"\"\"\n    my_conditional_number: int | None = None\n    \"\"\" A number that can be null if left empty \"\"\"\n    my_path: Path = Path(\"/tmp\")\n    \"\"\" A dummy path \"\"\"\n\n\nm = run(Env)  # m.env contains an Env instance\nm.form()  # Prompt a dialog; m.form() without parameter edits m.env\nprint(m.env)\n# Env(my_number=1, my_boolean=True, my_path=PosixPath('/tmp'),\n#  my_point=&lt;__main__.Point object at 0x7ecb5427fdd0&gt;)\n</code></pre> <p></p> <p>Variables organized in a dict:</p> <p>Along scalar types, there is (basic) support for common iterables or custom classes.</p> <pre><code>from mininterface import run\n\nclass Point:\n    def __init__(self, i: int):\n        self.i = i\n\n    def __str__(self):\n        return str(self.i)\n\n\nvalues = {\"my_number\": 1,\n          \"my_list\": [1, 2, 3],\n          \"my_point\": Point(10)\n          }\n\nm = run()\nm.form(values)  # Prompt a dialog\nprint(values)  # {'my_number': 2, 'my_list': [2, 3], 'my_point': &lt;__main__.Point object...&gt;}\nprint(values[\"my_point\"].i)  # 100\n</code></pre> <p></p>"},{"location":"Types/#mininterface.types.CallbackTag","title":"<code>CallbackTag</code>","text":"<p>Callback function is guaranteed to receives the Tag as a parameter.</p> <p>Warning</p> <p>Experimental. May change.</p> <p>For the following examples, we will use these custom callback functions: <pre><code>from mininterface import run\n\ndef callback_raw():\n    \"\"\" Dummy function \"\"\"\n    print(\"Priting text\")\n    return 50\n\ndef callback_tag(tag: Tag):\n    \"\"\" Receives a tag \"\"\"\n    print(\"Printing\", type(tag))\n    return 100\n\nm = run()\n</code></pre></p> <p>Use as buttons in a form: <pre><code>m.form({\"Button\": callback_raw})\nm.form({\"Button\": CallbackTag(callback_tag)})\n</code></pre></p> <p></p> <p>Via form, we receive the function handler: <pre><code>out = m.form({\n    \"My choice\": Tag(choices=[callback_raw, CallbackTag(callback_tag)])\n})\nprint(out)  # {'My choice': &lt;function callback_raw at 0x7ae5b3e74ea0&gt;}\n</code></pre></p> <p>Via choice, we receive the function output:</p> <pre><code>out = m.choice({\n    \"My choice1\": callback_raw,\n    \"My choice2\": CallbackTag(callback_tag),\n    # Not supported: \"My choice3\": Tag(callback_tag, annotation=CallbackTag),\n})\nprint(out)  # output of callback0 or callback_tag, ex:\n#    Printing &lt;class 'mininterface.types.CallbackTag'&gt;\n#    100\n</code></pre> <p></p> <p>You may use callback in a dataclass. <pre><code>@dataclass\nclass Callbacks:\n    p1: Callable = callback0\n    p2: Annotated[Callable, CallbackTag(description=\"Foo\")] = callback_tag\n    # Not supported: p3: CallbackTag = callback_tag\n    # Not supported: p4: CallbackTag = field(default_factory=CallbackTag(callback_tag))\n    # Not supported: p5: Annotated[Callable, Tag(description=\"Bar\", annotation=CallbackTag)] = callback_tag\n\nm = run(Callbacks)\nm.form()\n</code></pre></p>"},{"location":"Types/#mininterface.types.PathTag","title":"<code>PathTag</code>","text":"<p>Contains a Path or their list. Use this helper object to select files.</p> <p>In the following example, we see that it is not always needed to use this object.</p> <ul> <li>File 1 \u2013 plain detection, button to a file picker appeared.</li> <li>File 2 \u2013 the same.</li> <li>File 3 \u2013 we specified multiple paths can be selected.</li> </ul> <pre><code>from pathlib import Path\nfrom mininterface import run, Tag\nfrom mininterface.aliases import PathTag\n\nm = run()\nout = m.form({\n    \"File 1\": Path(\"/tmp\"),\n    \"File 2\": Tag(\"\", annotation=Path),\n    \"File 3\": PathTag([Path(\"/tmp\")], multiple=True),\n})\nprint(out)\n# {'File 1': PosixPath('/tmp'), 'File 2': PosixPath('.'), 'File 3': [PosixPath('/tmp')]}\n</code></pre> <p></p>"},{"location":"Types/#mininterface.types.PathTag.multiple","title":"<code>multiple: bool = False</code>","text":"<p>The user can select multiple files.</p>"},{"location":"Types/#mininterface.types.DatetimeTag","title":"<code>DatetimeTag</code>","text":"<p>Warning</p> <p>Experimental. Still in development.</p> <p>Datetime is supported.</p> <pre><code>from datetime import datetime\nfrom dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_date: datetime\n\nm = run(Env)\n</code></pre> <p>The arrows change the day (or the datetime part the keyboard caret is currently editing).</p> <p></p> <p>In this code, we want only the date part.</p> <pre><code>from datetime import date\nfrom dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_date: date\n\nm = run(Env)\n</code></pre> <p>After clicking the button (or hitting <code>Ctrl+Shift+C</code>), a calendar appear.</p> <p></p>"},{"location":"Types/#mininterface.types.DatetimeTag.date","title":"<code>date: bool = False</code>","text":"<p>The date part is active</p>"},{"location":"Types/#mininterface.types.DatetimeTag.time","title":"<code>time: bool = False</code>","text":"<p>The time part is active</p>"},{"location":"Types/#mininterface.types.DatetimeTag.full_precision","title":"<code>full_precision: bool = False</code>","text":"<p>Include full time precison, seconds, microseconds.</p>"},{"location":"Types/#mininterface.types.Validation","title":"<code>Validation(check)</code>","text":"<p>Alias to <code>Tag(validation=...)</code></p> <pre><code>from mininterface import Tag, Validation\n@dataclass\nclass Env:\n    my_text: Annotated[str, Validation(not_empty) = \"will not be emtpy\"\n\n    # which is an alias for:\n    # my_text: Annotated[str, Tag(validation=not_empty)] = \"will not be emtpy\"\n</code></pre> <p>Parameters:</p> Name Type Description Default <code>check</code> <code>Callable[[Tag], ValidationResult | tuple[ValidationResult, TagValue]]</code> <p>Callback function.</p> required"},{"location":"Types/#mininterface.types.Choices","title":"<code>Choices(*choices)</code>","text":"<p>An alias, see <code>Tag.choices</code></p>"},{"location":"Validation/","title":"Validation","text":"<p>We recommend to use the dataclass and validate with the <code>Annotated</code> keyword. We use a Validation type here.</p> <pre><code>from typing import Annotated\nfrom mininterface.validators import not_empty\nfrom mininterface import Validation\n\n@dataclass\nclass Env:\n    test: Annotated[str, Validation(not_empty)] = \"hello\"\n</code></pre> <p>Under the hood, this is just a <code>Tag</code>.</p> <pre><code>@dataclass\nclass Env:\n    test: Annotated[str, Tag(validation=not_empty)] = \"hello\"\n</code></pre> <p>Why we used it in an Annotated statement? To preserve the date type.</p> <pre><code>@dataclass\nclass Env:\n    my_string: Tag = Tag(\"hello\", validation=not_empty)\n\nm = run(Env)\nprint(type(m.env.my_string))  # Tag\nprint(m.env.my_string.val)  # hello\n</code></pre>"},{"location":"Validation/#validators","title":"validators","text":"<p>Functions suitable for Tag validation. When the user submits a value whose validation fails, they are prompted to edit the value.</p> <pre><code>m = run()\nmy_dict = m.form({\"my_text\", Tag(\"\", validation=validators.not_empty)})\nmy_dict[\"my_text\"]  # You can be sure the value is not empty here.\n</code></pre> <p>Note that alternatively to this module, you may validate with Pydantic or an attrs model.</p> <pre><code>from pydantic import BaseModel, Field\n\nclass MyModel(BaseModel):\n    restrained: str = Field(default=\"hello\", max_length=5)\n</code></pre> <pre><code>import attr\nfrom attr.validators import max_len\n\n@attr.s\nclass AttrsModel:\n    restrained: str = attr.ib(default=\"hello\", validator=max_len(5))\n</code></pre>"},{"location":"Validation/#mininterface.validators.not_empty","title":"<code>not_empty(tag)</code>","text":"<p>Assures that Tag the user has written a value and did not let the field empty.</p> <pre><code>from mininterface import Tag, validators, run\n\nm = run()\nm.form({\"my_text\": Tag(\"\", validation=validators.not_empty)})\n# User cannot leave the string field empty.\n</code></pre> <p>When submitting an empty value, a warning appears:</p> <p></p> <p>Note that for Path, an empty string is converted to an empty Path('.'), hence '.' too is considered as an empty input and the user is not able to set '.' as a value. This does not seem to me as a bad behaviour as in CLI you clearly see the CWD, whereas in a UI the CWD is not evident.</p> <p>Parameters:</p> Name Type Description Default <code>tag</code> <code>Tag</code> required"},{"location":"Validation/#mininterface.validators.limit","title":"<code>limit(maxOrMin=None, max_=None, lt=None, gt=None, transform=False)</code>","text":"<p>Limit a number range or a string length.</p> <p>Either use as <code>limit(maximum)</code> or <code>limit(minimum, maximum)</code>.</p> <p>Parameters:</p> Name Type Description Default <code>maximum</code> <code>int</code> <p><code>limit(maximum)</code> \u2013 from zero (including) to maximum (including)</p> required <code>minimum</code> <code>int</code> <p><code>limit(minimum, maximum)</code> \u2013 From minimum (including) to maximum (including)</p> required <code>lt</code> <code>float | None</code> <p>lesser than</p> <code>None</code> <code>gt</code> <code>float | None</code> <p>greater than</p> <code>None</code> <code>transform</code> <code>bool</code> <p>If the value is not within the limit, transform it to a boundary. <pre><code>from mininterface import run, Tag\nfrom mininterface.validators import limit\n\nm = run()\nm.form({\"my_number\": Tag(2, validation=limit(1, 10, transform=True))})\n# Put there '50' \u2192 transformed to 10 and dialog reappears\n# with 'Value must be between 1 and 10.'\n</code></pre></p> <p></p> <code>False</code>"},{"location":"run/","title":"Run","text":"<p>The main access, start here. Wrap your configuration dataclass into <code>run</code> to access the interface. An interface is chosen automatically, with the preference of the graphical one, regressed to a text interface for machines without display. Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly with the default from a config file if such exists. It searches the config file in the current working directory, with the program name ending on .yaml, ex: <code>program.py</code> will fetch <code>./program.yaml</code>.</p> <p>Parameters:</p> Name Type Description Default <code>env_or_list</code> <code>Type[EnvClass] | list[Type[Command]] | None</code> <ul> <li><code>dataclass</code> Dataclass with the configuration. Their values will be modified with the CLI arguments.</li> <li><code>list</code> of Commands let you create multiple commands within a single program, each with unique options.</li> <li><code>None</code> You need just the dialogs, no CLI/config file parsing.</li> </ul> <code>None</code> <code>ask_on_empty_cli</code> <code>bool</code> <p>If program was launched with no arguments (empty CLI), invokes self.form() to edit the fields. (Withdrawn when <code>ask_for_missing</code> happens.) <pre><code>@dataclass\nclass Env:\nnumber: int = 3\ntext: str = \"\"\nm = run(Env, ask_on_empty=True)\n</code></pre></p> <pre><code>$ program.py  #  omitting all parameters\n# Dialog for `number` and `text` appears\n$ program.py --number 3\n# No dialog appears\n</code></pre> <code>False</code> <code>title</code> <code>str</code> <p>The main title. If not set, taken from <code>prog</code> or program name.</p> <code>''</code> <code>config_file</code> <code>Path | str | bool</code> <p>File to load YAML to be merged with the configuration. You do not have to re-define all the settings in the config file, you can choose a few. If set to True (default), we try to find one in the current working dir, whose name stem is the same as the program's. Ex: <code>program.py</code> will search for <code>program.yaml</code>. If False, no config file is used.</p> <code>True</code> <code>add_verbosity</code> <code>bool</code> <p>Adds the verbose flag that automatically sets the level to <code>logging.INFO</code> (-v) or <code>logging.DEBUG</code> (-vv).</p> <pre><code>import logging\nlogger = logging.getLogger(__name__)\n\nm = run(Env, add_verbosity=True)\nlogger.info(\"Info shown\") # needs `-v` or `--verbose`\nlogger.debug(\"Debug not shown\")  # needs `-vv`\n# $ program.py --verbose\n# Info shown\n</code></pre> <pre><code>$ program.py --verbose\nInfo shown\n</code></pre> <code>True</code> <code>ask_for_missing</code> <code>bool</code> <p>If some required fields are missing at startup, we ask for them in a UI instead of program exit.</p> <pre><code>@dataclass\nclass Env:\n    required_number: int\nm = run(Env, ask_for_missing=True)\n</code></pre> <pre><code>$ program.py  # omitting --required-number\n# Dialog for `required_number` appears\n</code></pre> <code>True</code> <code>interface</code> <code>Type[Mininterface] | Literal['gui'] | Literal['tui'] | None</code> <p>Which interface to prefer. By default, we use the GUI, the fallback is the TUI. You may write \"gui\" or \"tui\" literal or pass a specific Mininterface type, see the full list of possible interfaces.</p> <code>None</code> <code>args</code> <code>Optional[Sequence[str]]</code> <p>Parse arguments from a sequence instead of the command line.</p> <code>None</code> <p>Kwargs:     The same as for argparse.ArgumentParser.</p> <p>Returns:</p> Type Description <code>Mininterface[EnvClass]</code> <p>An interface, ready to be used.</p> <p>You cay context manager the function by a <code>with</code> statement. The stdout will be redirected to the interface (ex. a GUI window).</p> <pre><code>from dataclasses import dataclass\nfrom mininterface import run\n\n@dataclass\nclass Env:\n    my_number: int = 4\n\nwith run(Env) as m:\n    print(f\"Your important number is {m.env.my_number}\")\n    boolean = m.is_yes(\"Is that alright?\")\n</code></pre> <p> </p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index f6a4791d85c965adc5761913d25849aca506188e..b1e84316aebfac56064f89e1cac1e71ccf970e3b 100644
GIT binary patch
delta 13
Ucmb=gXP58h;AnVMIFY>q03NvnqW}N^

delta 13
Ucmb=gXP58h;9y8}o5)@P02qh^cK`qY