Quick Start
===========

1.  Install the package from PyPI:

    .. parsed-literal::

        $ pip install |pandex|

2.  Install a demo extension:

    .. parsed-literal::

        $ python
        Python 3.7.3 | packaged by conda-forge | (default, Jul  1 2019, 21:52:21
        [GCC 7.3.0] :: Anaconda, Inc. on linux
        Type "help", "copyright", "credits" or "license" for more information.
        >>> import |pandex| as pd
        >>> |pd.ext|.import_extension('github:|demo_repo| -> circle_calculations')

3.  The ``pd`` is an alias to the installed ``pandas`` module,
    but with extensions enabled.  A ``DataFrame`` can be created
    and the just installed extension can be called from the
    |``ext``| namespace:

    .. parsed-literal::

        >>> df = pd.DataFrame({'radius': [3,4,5]})
        >>> |df.ext|.circle_calculations()
        >>> df
           radius  circumference       area
        0       3      18.849556  28.274334
        1       4      25.132741  50.265482
        2       5      31.415927  78.539816

4.  The installed extensions can be viewed:

    .. parsed-literal::

        >>> pd.ext.show_extensions()
        |pandex| v0.1
        There is 1 extension installed:

        |df.ext|.circle_calculations(radius)

        For help on individual extensions, use help(|df.ext|.<extension name>)

5.  If there are a number of extensions to be installed, perhaps
    from different sources, it is more convenient to specify them
    in a |``import.ext``| file which can be imported.

    a.  Create a file called ``my_extensions`` |``import.ext``| in the current
        directory with the following content:

        .. parsed-literal::

                # Circle and sphere extensions
                github:|demo_repo| -> circle_calculations
                github:|demo_repo| -> sphere_calculations

                # Some library functions on github, written in a format
                # readable by pdext, but not written specifically for it
                github:aayushmnit/cookbook -> cookbook.print_dim
                github:aayushmnit/cookbook -> cookbook.print_dataunique
                github:aayushmnit/cookbook -> cookbook.do_data_profiling

    b.  This file can be imported using the ``import`` statement:

        .. parsed-literal::

                import |pandex| as pd
                import my_extensions

        If you don't have the ``pandas_profiling`` library installed then
        you will see some warning messages.  The function has still installed
        OK, but you won't be able to use it until the dependencies have been
        installed.

    c.  The extensions defined in the file can be viewed:

        .. parsed-literal::

                |pd.ext|.show_extensions()

        **NOTE:** The ``import`` and ``import_extension`` commands
        will only install if the extension is not present.  So these
        commands can be included in scripts.  When new users run the
        scripts for the first time, the extensions will install.