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.

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

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.

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
$

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 <name> and you can set a value with flunky config <name> <foo>.

TODO

TODO

TODO