Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tswicegood/flunky

Because everyone wants a flunky
https://github.com/tswicegood/flunky

Last synced: 12 days ago
JSON representation

Because everyone wants a flunky

Awesome Lists containing this project

README 

        
Flunky

======

Welcome to Flunky, your assistant to help build Python packages



Building Python packages successfully requires using a bunch of poorly

documented packages that interact in weird ways and don't always do what

you expect.  We don't need the hassle---we just need a way to easily

create and deploy our packages.



Flunky helps you by creating a package sleketon for you.  It adds a generic

``setup.py`` and uses a ``package.json`` file to handle configuring the name

of your package, your dependencies, and so on.



.. warning:: This document is speculative until this warning is removed.  Proceed with caution until that point.



Installation

------------

Flunky needs to be installed.  Do that using `pip`_:



::



    pip install flunky



You can verify that the installation went successfully by running

``flunky --version`` from the command line.  You should see this if

everything is ready to go.



::



    $ flunky --version

    flunky version 0.1.0



Usage

-----

You can initialize a new project by calling ``flunky`` and providing a

directory name.  For example, to create a package called ``awesomeness``:



::



    $ flunky ./awesomeness/

    Creating package awesomeness... [OK]

    $ 



Now you have a new directory called ``awesomeness`` that contains your new

package and the skeleton necessary to make it installable.



::



    |~awesomeness/

    | |~tests/

    | | `-__init__.py

    | `-__init__.py

    |-LICENSE

    |-MANIFEST.in

    |-README.rst

    |-package.json

    |-setup.py

    `-runtests.py



Let's look at each of these in turn.  The ``awesomeness`` directory is where

you should put the modules of your package.  Put all of your tests in

``awesomeness/tests``.  You can add new test cases to the

``awesomeness.tests.suite`` so they're picked up by ``runtests.py``.



The ``LICENSE`` file outlines the LICENSE for your code.  This defaults to

the Apache Public License, v2.  You can change the license by using the

``--license`` parameter when you run ``flunky`` or you change its default by

configuring the global defaults (see `Configuring Defaults`_).



``MANIFEST.in`` is a file needed to make sure that all of the required files

are included in the generated tarball.  You can learn more about them from

the `documentation`_.



The ``README.rst`` contains a skeleton for your package.  You need to edit it

to add the information on how to use your package.



``package.json`` contains the metadata describing your new package.  You need to

edit this file to adjust the values for your name, and so on.  You can

configure global defaults for this (see `Configuring Defaults`_).



``setup.py`` is what is used to actually build and install your package.  You

should *not* need to edit that file.



You use ``runtests.py`` to run the tests found inside your package's

``tests.suite`` module.  You can run it directly with ``python runtests.py``.



Understanding Templates

"""""""""""""""""""""""

The files are generated by the default project template: ``simple``.  Flunky

uses templates to generate all of these files for you.  You can configure

defaults to use in many of the places.  Flunky has the ability to use different

templates using the ``--template`` parameter.



You can see a list of all of the installed templates by running 

``flunky --list-templates`` from the command line like this:



::



    $ flunk --list-templates

    Installed Flunky Templates



    simple        Simple Python package

    django-app    A simple Django app that's installable

    $



Configuring Defaults

--------------------

You can interact with the settings by using ``flunky config``.  The

configuration uses an ini file located at ``~/.flunkyconfig``.  You can see the

value of a setting by calling ``flunky config `` and you can set a value

with ``flunky config  ``.



List of Configuration Values

""""""""""""""""""""""""""""

**TODO**



Adding Additional Templates

---------------------------

**TODO**



Creating Package Templates

--------------------------

**TODO**



.. _pip: http://www.pip-installer.org/

.. _documentation: http://docs.python.org/distutils/sourcedist.html#manifest-template