Metadata-Version: 1.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
Description: 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
        
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
