Metadata-Version: 2.1
Name: plac
Version: 1.3.1
Summary: The smartest command line arguments parser in the world
Home-page: https://github.com/ialbert/plac
Author: Michele Simionato
Author-email: michele.simionato@gmail.com
License: BSD License
Keywords: command line arguments parser
Platform: All
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities

Plac: Parsing the Command Line the Easy Way
-------------------------------------------

``plac`` is a Python package that can generate command line parameters from function signatures.

``plac`` works on Python 2.6 through all versions of Python 3

``plac`` has no dependencies beyond modules already present in the Python standard library.

``plac`` implements most if its functionality in a single file that may be included in your source code.

Quickstart
----------

Here is how to turn a script that does some processing on a database table into a full, command-line enabled program:

.. code-block:: python

   # updatedb.py
   from datetime import datetime

   def main(dsn, table='product', today=datetime.today()):
       "Do something on the database"
       print(dsn, table, today)

   if __name__ == '__main__':
       import plac;
       plac.call(main)

Here is the help message automatically generated by plac::

  $ python updatedb.py -h
  usage: updatedb.py [-h] dsn [table] [today]

  Do something on the database

  positional arguments:
    dsn
    table       [product]
    today       [2019-07-28 07:18:20.054708]

  optional arguments:
    -h, --help  show this help message and exit

Advanced features
-----------------

Often we need more control over how parameters are handled. ``plac`` offers simple decorator helpers for positional, option and flag type parameters:

.. code-block:: python

    import plac

    from pathlib import Path

    @plac.pos('model', "Model name", choices=['A', 'B', 'C'])
    @plac.opt('output_dir', "Optional output directory", type=Path)
    @plac.opt('n_iter', "Number of training iterations", type=int)
    @plac.flg('debug', "Enable debug mode")
    def main(model, output_dir='.', n_iter=100, debug=False):
        """A script for machine learning"""
        pass

    if __name__ == '__main__':
        plac.call(main)

Running the script with ``$ python example.py -h`` will give you
the following help message: ::

    usage: example.py [-h] [-o .] [-n 100] [-d] {A,B,C}

    A script for machine learning

    positional arguments:
      {A,B,C}               Model name

    optional arguments:
      -h, --help            show this help message and exit
      -o ., --output-dir .  Optional output directory
      -n 100, --n-iter 100  Number of training iterations
      -d, --debug           Enable debug mode


Quick reference
---------------

The following decorator reference helps you recall what parameters are valid for each decorator type:

.. code-block:: python

    # Positional parameters.
    def pos(arg, help=None, type=None, choices=None, metavar=None):

    # Option parameters.
    def opt(arg, help=None, type=None, abbrev=None, choices=None, metavar=None):

    # Flag parameters.
    def flg(arg, help=None, abbrev=None):

Notably, the main functionality of ``plac`` is implemented in a single module called ``plac_core.py`` that, if necessary, may be included and distributed with your source code thus reducing external dependencies in your code.

Documentation
--------------

In addition, plac can do a lot more, up to the creation of
domain-specific languages(!). See the full documentation for more details.

* https://plac.readthedocs.io/en/latest/

Avoiding name clashes
---------------------

Python syntax, or your variable naming may impose constraints on what words may be used as parameters. To circumvent that limitation append a trailing underscore to the name. ``plac`` will strip that underscore from the command line parameter name:

.. code-block:: python

    import plac

    @plac.flg('list_')  # avoid clash with builtin
    @plac.flg('yield_')  # avoid clash with keyword
    @plac.opt('sys_')  # avoid clash with a very common name
    def main(list_, yield_=False, sys_=100):
        print(list_)
        print(yield_)
        print(sys_)

    if __name__ == '__main__':
        plac.call(main)

::

    $ python doc/example13.py -h
    usage: example13.py [-h] [-l] [-y] [-s 100]

    optional arguments:
      -h, --help         show this help message and exit
      -l, --list
      -y, --yield        [False]
      -s 100, --sys 100  [100]

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

If you wish to install the package do

::

 $ pip install plac

If you prefer to install the full distribution from source, including
the documentation, download the tarball_, unpack it and run

::

 $ python setup.py install

.. _tarball: https://pypi.org/project/plac/#files


Testing
--------

Run

::

 $ python doc/test_plac.py

You will see several apparent errors, but this is right, since the tests
are checking for several error conditions. The important thing is that
you get at the a line like

``Executed XX tests OK``

Code
----

* https://github.com/ialbert/plac

Author: Michele Simionato, michele.simionato@gmail.com

Maintainer: Istvan Albert, istvan.albert@gmail.com

Issues
------

* https://github.com/ialbert/plac/issues

License
-------

BSD License


