Confused about packing python projects

Question

I've been coding in Python for long, but never actually tried to pack a piece of code so that I can share it. I started reading https://python-packaging.readthedocs.io/en/latest/.

I started with the simplest possible case, say I want to share a module named 'clipper', and the only important thing is a class called Clipper. It seems in case I use setuptools I should create somewhere folders

clipper/clipper

and inside the inner clipper, place a file __init__.py

with the definition of class Clipper. So far so good. Theoretically, after installing the package, the way to use the class would be:

import clipper
cl = clipper.Clipper()

My problem is, I am assuming that while I am developing and before any installation, the same code should work. I mean, the previous code should create an instance of the object. But how would that work? How should I set PYTHONPATH so that the previous import would actually work?

Maybe I got something really wrong, I thought packing would be easier compared to coding, but I've spent some time and I don't get it. Any help, please?

Are you interested in turning it into an executable? What is your target platform? — 23k, Nov 01 '17 at 16:45
No, I don't need an executable. Platform: currently it is Python 3.5 on Windows. — zeycus, Nov 01 '17 at 16:48
I don't want to self advertise, but I've got a project set up exactly how you want to set yours up. You might find something useful in my setup.py file. I use virtualenv to automatically set PYTHONPATH during development. When I use `pip install` to download the package from pypi, I'm able to import modules easily. https://github.com/byxor/limp — byxor, Nov 01 '17 at 16:57

score 2 · Accepted Answer · answered Nov 01 '17 at 17:01

Rather than modifying your Python path, install the packaged module as an editable version and your environment will handle this for you. When you have it running as an editable version you'll be able to make changes to the code on your local development instance.

For example, assuming you have Pip you can run the following command in the first 'clipper' folder (the same folder as the setup.py file you created during packaging):

pip install -e .

-e means editable
the . means install the package located in the current folder.

More detail here in an SO answer from 2015: "pip install --editable ./" vs "python setup.py develop"

thank you, that seems exactly what I needed! I'll take a good look at it. — zeycus, Nov 01 '17 at 17:15

score 1 · Answer 2 · answered Nov 01 '17 at 17:08

Your directory tree would look a bit like this:

~/clipper/
    setup.py
    clipper/
        __init__.py
        clipper.py

The setup.py file contains information telling Python how to 'parse' your package. Things like the name of your project, the version and what packages to include are defined here. For your example, setup.py may look like this:

from distutils.core import setup

setup(
    name="Clipper",
    # A name for your package, typically your project name
    description="My first package",
    # A short description
    version="1.0.0",
    # A version specification
    packages=["clipper"]
    # A list of packages to include
)

Within clipper, clipper.py contains the actual Clipper class:

class Clipper(object):
    def __init__(self):
        pass

    def foo(self):
        print("Invoked foo!")

__init__.py is a special type of file. It defines the public interface for interacting with your package. Typically, it imports all public functions and classes:

from .clipper import Clipper

Finally, to turn this into a proper package, run python3 setup.py sdist. This creates the source distribution for your package and allows you to import it ¹. Let's try that now. Navigate back to ~/clipper/ and start Python:

>>> from clipper import Clipper
>>> c = Clipper()
>>> c.foo()
Invoked foo!
>>>

And here's 'real' example of what a package directory would look like:

~/calculator/
    setup.py
    calculator/
        __init__.py
        add.py
        substract.py

setup.py

from distutils.core import setup

setup(
    name="Calculator",
    description="Calculate stuff!",
    version="1.0.0",
    packages=["calculator"]
)

__init__.py

from .add import *
from .substract import *

add.py

def add(a, b):
    """Return `a` + `b`."""
    return a + b

substract.py

def substract(a, b):
    """Return `a` - `b`."""
    return a - b

For more information, see the Python tutorial on packaging.

¹ You may get some warnings about missing information, but you can ignore that for now.

nice example, and tutorial reference. – zeycus Nov 01 '17 at 17:17 — zeycus, Nov 01 '17 at 17:17

Confused about packing python projects

2 Answers2