Yuio
====

Yuio is everything you'll ever need to write a good CLI, deps-free.

Forget searching for *that one progressbar library*,
figuring out how to keep loading configs DRY,
or having headaches because autocompletion was just an afterthought.
Yuio got you.

.. vhs:: /_tapes/demo.tape
    :alt: Demonstration of yuio capabilities.
    :scale: 50%


.. invisible-code-block: python

    import io
    import pathlib
    import sys
    import yuio.app
    import yuio.config
    import yuio.term
    import yuio.io

    yuio.io.setup(term=yuio.term.Term(io.StringIO(), io.StringIO()))


Features
--------

-   Easy to setup CLI apps with autocompletion out of the box:

    .. code-block:: python

        @yuio.app.app
        def main(
              #: input files for the program.
              inputs: list[pathlib.Path] = yuio.app.positional(),
        ):
              ...

        if __name__ == "__main__":
              main.run()

-   Colored output with inline tags and markdown:

    .. code-block:: python

        yuio.io.info('<c bold>Yuio</c>: a user-friendly io library!')

-   Status indication with progress bars that don't break your console:

    .. invisible-code-block: python

        sources = []

    .. code-block:: python

        with yuio.io.Task('Loading sources') as task:
              for source in task.iter(sources):
                   ...

-   User interactions, input parsing and simple widgets:

    .. invisible-code-block: python

        ostream = yuio.io.get_term().ostream
        ostream.write("foobar\n")
        ostream.seek(0)
        del ostream

    .. code-block:: python

        answer = yuio.io.ask("What's your favorite treat?", default="waffles")

-   Loading configs from all sorts of places:

    .. skip: next

    .. code-block:: python

        class AppConfig(yuio.config.Config):
            #: number of threads to use, default is auto-detect.
            n_threads: int | None = None

        config = AppConfig()
        config.update(AppConfig.load_from_toml_file(path))
        config.update(AppConfig.load_from_env(prefix="APP"))
        ...

-   No dependencies, perfect for use in un-configured environments.

-   And many more!


Requirements
------------

The only requirement is ``python >= 3.10``.


Installation
------------

Install ``yuio`` with pip:

.. code-block:: console

    $ pip install yuio

Or just copy-paste the ``yuio`` directory to somewhere in the ``PYTHONPATH`` of your project.


Examples
--------

See examples at `taminomara/yuio`_.

.. _taminomara/yuio: https://github.com/taminomara/yuio/blob/main/examples/


Contents
--------

.. toctree::
    :maxdepth: 2

    by_example/index
    main_features/index
    internals/index
