############# CLI Reference ############# .. meta:: :description: Python timeit CLI for the 21st century. :author: Arian Mollik Wasi :copyright: Arian Mollik Wasi :keywords: Python, Timeit, Fastero, Wasi Master, Arian Mollik Wasi :language: English :og:title: Fastero Documentation - CLI Reference :og:site_name: Fastero :og:type: website :og:url: https://fastero.readthedocs.io :og:image: https://i.ibb.co/ysbFf3b/python-http-library-benchmark.png :og:description: Python timeit CLI for the 21st century. Fastero is a beautiful and flexible timeit (cli) alternative that you have to check out :twitter:card: summary_large_image :twitter:title: Fastero Documentation - CLI Reference :twitter:image: https://i.ibb.co/ysbFf3b/python-http-library-benchmark.png :twitter:description: Python timeit CLI for the 21st century. Fastero is a beautiful and flexible timeit (cli) alternative that you have to check out This is a hand-written version of the CLI Reference. It may be outdated, if it is please kindly remind me to update it in a github issue or open a pull request. In the case of it being out of date (not having some option or argument), You may want to check out the :doc:`Automated CLI Reference <./cli_reference_automated>`. This does not cover exporting, those are covered in their own page :ref:`Exporting Reference `. They are also covered in :ref:`CLI Reference (Automated) ` Also, this version is quite long and filled with examples. :) ******* fastero ******* .. code-block:: shell fastero [CODE_SNIPPETS...] [OPTIONS] Arguments ^^^^^^^^^ These are the positional arguments, opposed to options, these don't require any prefix and are directly passed .. option:: CODE_SNIPPETS The snippets to benchmark. There may be multiple .. admonition:: Example :class: hint .. code-block:: shell fastero "str(1)" "f'{1}'" .. details:: Output If the image below looks blurry then click it to open it in fullscreen .. image:: ../_static/images/str_vs_fstring.png :width: 1161 :alt: Output image Any of these can be ``-``, to get the input later. Useful for multi-line inputs .. admonition:: Example :class: hint .. code-block:: shell fastero - - .. details:: Output If the image below looks blurry then click it to open it in fullscreen .. image:: ../_static/images/code_input_with_prompt.gif :width: 1233 :alt: Output image You can also use ``file:`` to read output from a file. If your code starts with ``file:``, you can escape this behavior by adding 2 spaces after the ``:``, e.g. ``file: foo`` .. admonition:: Example :class: hint .. code-block:: shell fastero "file: foo.py" "file: bar.py" .. details:: Output If the image below looks blurry then click it to open it in fullscreen .. image:: ../_static/images/code_input_with_file.png :width: 1233 :alt: Output image The filename for ``file:`` can also be ``stdin`` to accept output piped from another program .. admonition:: Example :class: hint .. code-block:: shell echo "str(1)" | fastero "file: stdin" All of these can also be used together. .. admonition:: Example :class: hint .. code-block:: shell fastero "str(1)" "file: bar.py" - This would mean the first argument is ``str(1)``, the second argument is the contents of bar.py, the third argument is the one given later .. TODO: Add Output (Preferably a GIF) .. .. details:: Output .. If the image below looks blurry then click it to open it in fullscreen .. .. image:: ../_static/images/code_input_with_file.png .. :width: 1233 .. :alt: Output image Options ^^^^^^^ .. option:: -v, --version Output the version of fastero that is currently being used .. option:: -h, --help Show the help message .. option:: -n, --snippet-name Assign a name to a snippet. .. admonition:: Example :class: hint .. code-block:: shell fastero "f'{1}'" -n "f-string" .. details:: Output If the image below looks blurry then click it to open it in fullscreen .. image:: ../_static/images/assigning_a_name_to_a_snippet.png :width: 1233 :alt: Output image This argument can be used multiple times .. admonition:: Example :class: hint .. code-block:: shell fastero "f'{1}'" "'{}'.format(1)" -n "f-string" -n "str.format()" .. details:: Output If the image below looks blurry then click it to open it in fullscreen .. image:: ../_static/images/assigning_names_to_multiple_snippets.png :width: 1233 :alt: Output image .. option:: -s, --setup Provide some code to use as the initial setup for the benchmark snippets. This can be used to initialize classes, set variables, import libraries etc. .. admonition:: **Default** :class: default The default value for setup is ``pass``. This is done to be consistent with `timeit `_ The format is the exact same as the ``CODE_SNIPPETS`` argument. Meaning it supports the ``file:`` directive to get from an file or stdin and the ``"-"`` parameter to enter multiline input in a prompt .. admonition:: Example :class: hint .. code-block:: shell fastero --setup "l = [0]" "a, = l" "a = l[0]" .. details:: Output If the image below looks blurry then click it to open it in fullscreen .. image:: ../_static/images/setup.png :width: 1233 :alt: Output image .. option:: -f, --from-json Get input from a json file. .. admonition:: Format :class: info If you only want to get parameters, the format should be this: .. code-block:: json { "setup": "l = [0]", "results": [ { "snippet_name": "unpacking", "snippet_code": "a, = l" }, { "snippet_name": "indexing", "snippet_code": "a = l[0]" } ] } The keys ``snippet_name`` and ``setup`` are optional! If you however, want to get other information like the :term:`mean` and :term:`standard deviation`, you have to use a json file specifically generated by fastero, or one that uses the same format as the one fastero exports .. seealso:: ``--export-json``, `\--json <#cmdoption-j>`_ .. admonition:: Example :class: hint Assuming the contents of foo.json are as above: .. code-block:: shell fastero --from-json foo.json Then the output will be the one showed at the end of the ``--setup`` section You can do a whole bunch of stuff by using this flag. For example if you want to re-preview the results from a json file, you can run .. code-block:: shell fastero --from-json foo.json --only-export Yes I know, this option name is bit unintuitive, since this doesn't have any export parameters, but when I named this option, I thought about what if people want to only export the data from the json file, I am open to renaming suggestions though If you want to export the results in one of the export formats, then you can add those export options alongside the ``--from-json`` and ``--only-export``, e.g. .. code-block:: shell fastero --from-json foo.json --only-export --export-image So now, it will get the run results from the ``foo.json`` file and then export a png file with those results .. option:: -j, --json Only print json results. This is simillar to the ``--export-json`` option but instead of exporting to a file, this outputs the json results to standard output. This is given only for scripting purposes. A better reasoning is given in `Command Line Interface Guidelines`_ .. admonition:: Example :class: hint .. code-block:: shell fastero "f'{1}'" "'{}'.format(1)" -n "f-string" -n "str.format()" --json .. details:: Output .. code-block:: json { "setup": "pass", "results": [ { "snippet_code": "f'{1}'", "snippet_name": "f-string", "runs": 55000000, "mean": 5.442414363636363e-08, "median": 5.392934e-08, "min": 5.3144839999999946e-08, "max": 6.013294000000001e-08, "stddev": 1.926783849689808e-09 }, { "snippet_code": "'{}'.format(1)", "snippet_name": "str.format()", "runs": 18000000, "mean": 1.652621666666668e-07, "median": 1.649461000000003e-07, "min": 1.6389370000000002e-07, "max": 1.6862390000000005e-07, "stddev": 1.424589255715445e-09 } ] } .. option:: -q, --quiet If used, there will be no output printed. This is useful if you are running it from a script and don't want the output polluting the user's terminal .. caution:: Running this without any exporting options or ``--json`` will just be a waste of time. .. TODO: Add an example .. option:: -e, --only-export If used alongside `\--from-json <#cmdoption-f>`_, skips the benchmarking part and just exports the data. The json file needs to to contain the exported data or else this won't work. .. option:: -w, --warmup Perform ```` warmup runs before the actual benchmark. .. admonition:: Example :class: hint .. code-block:: shell fastero "f'{1}'" "'{}'.format(1)" -n "f-string" -n "str.format()" --warmup 100_000 **Tip**: The _ is used in replacement of a comma, you can omit it. Perform this only for presistent improvements. Otherwise all performance gains are lost on each batch. This is due to how fastero benchmarking works. It relies on timeit and timeit doesn't have a warmup parameter, so I'm thinking about subclassing :py:class:`timeit.Timer` and implementing a warmup parameter myself. .. option:: -c, --code-theme Theme for code input and output, also applicable if “-” is used for any of the parameters, .. admonition:: **Default** :class: default The default theme is **one-dark** For a list of the themes see https://pygments.org/styles .. tip:: .. details:: Best Themes These are the best themes: (in my opinion of course) .. raw:: html

one-dark

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
.. raw:: html

material

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
.. raw:: html

dracula

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
.. raw::html

monokai

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
.. raw:: html

monokai

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
.. raw:: html

native

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
.. raw:: html

fruity

from typing import Iterator

            # This is an example
            class Math:
               @staticmethod
               def fib(n: int) -> Iterator[int]:
                  """ Fibonacci series up to n """
                  a, b = 0, 1
                  while a < n:
                        yield a
                        a, b = b, a + b

            result = sum(Math.fib(42))
            print("The answer is {}".format(result))
There are others such as ``solarized-dark``, ``gruvbox-dark`` and many more! .. admonition:: Demonstation :class: important .. tab:: One Dark This image is basically the console output with this theme, generated by fastero itself .. image:: ../_static/images/one_dark_theme_demo.png .. tab:: Material This image is basically the console output with this theme, generated by fastero itself .. image:: ../_static/images/material_theme_demo.png .. tab:: Dracula This image is basically the console output with this theme, generated by fastero itself .. image:: ../_static/images/dracula_theme_demo.png .. tab:: Monokai This image is basically the console output with this theme, generated by fastero itself .. image:: ../_static/images/monokai_theme_demo.png .. tab:: Native This image is basically the console output with this theme, generated by fastero itself .. image:: ../_static/images/native_theme_demo.png .. tab:: Fruity This image is basically the console output with this theme, generated by fastero itself .. image:: ../_static/images/fruity_theme_demo.png .. admonition:: Example :class: hint .. code-block:: shell fastero "f'{1}'" "'{}'.format(1)" -n "f-string" -n "str.format()" --code-theme monokai .. option:: -t, --total-time