How I organize my python projects
=================================

This is applicable to both OS X and Linux. I use the same tools on both systems. In this guide, I'm going to set up an environment for a Flask app.

Setup
-----
1. I start by installing [pip](http://pip.readthedocs.org/en/latest/), [virtualenv](http://virtualenv.readthedocs.org/en/latest/), then [virtualenvwrapper](http://virtualenvwrapper.readthedocs.org/en/latest/). I seldom use virtualenv directly; I use the wrapper tools instead.
2. I create a virtualenv for my project:

    ```
    $ mkvirtualenv myflaskapp
    New python executable in myflaskapp/bin/python
    Installing setuptools............done.
    Installing pip...............done.
    ```

3. I then use `pip` to install any libraries that I need, e.g.:

    ```
    $ pip install flask
    $ pip install Flask-WTF
    ```

4. I then create a directory for my own python files (you can do this anywhere. I often just put this in my home directory).

    ```
    $ mkdir -p myflaskapp
    ```

5. And if I'm just building a simple project, or just doing some exploratory programming, I'll just write all of my code in a single `main.py` file.

    ```
    $ cd myflaskapp && touch main.py
    ```

6. Do some work in that file!


Coming back
-----------

Once I've stopped working on this project for a while, I'll come back to it, and reactivate my virtualenv:

```
workon myflaskapp
```

Now, If I need to install any other tools (like Flask-Mail), I can use pip to do so!

```
pip install Flask-Mail
```

And because I'm working in a project-specific virtual environment, my installed python libraries are separate from other projects.


Freezing & Re-creating your virtualenv
--------------------------------------

If you want to distribute your app, or if you want to work on another system, it's nice to be able to recreate your virtualenv.  You do this by:

1. Freezing your requirements (with `pip freeze`)
2. Creating a new virtualenv and re-loading from a requirements file.

First, let's see what `pip freeze` does:

```
$ cd myflaskapp
$ pip freeze
Flask==0.10.1
Flask-WTF==0.9.5
Jinja2==2.7.2
MarkupSafe==0.23
WTForms==1.0.5
Werkzeug==0.9.4
dulwich==0.9.5
hg-git==0.5.0
itsdangerous==0.24
numpy==1.7.1
wsgiref==0.1.2
```

It just lists all of our install libraries (*and* their dependencies). You can save this in a *requirements.txt* file:

```
$ pip freeze > requirements.txt
```

Now, on any other system, you can create a new virtual environment:

```
mkvirtualenv myflaskapp
```

Then, re-install all of your libraries from a requirements file.


```
$ pip install -r requirements.txt
```

Thats it!

You can also take a look at `pip help` to see what else pip can do for you!