The entry point must be a function that may be invoked using exactly zero arguments. If you want to pass in arguments from the command line, say you want to invoke it like:

$ pypy a1 a2

You need to read them from sys.argv instead. So your python module should contain this:

def program(arg1, arg2):
    print(arg1, arg2)

def main():
    import sys
    arg1, arg2 = sys.argv[1], sys.argv[2]
    program(arg1, arg2)

if __name__ == "__main__":
    main()

Alternatively, the main function may instead take an argv argument that defaults to sys.argv if importing sys is desirable at the top level of the module:

def main(argv=sys.argv):
    program(argv[1], argv[2])

Running that command as above should print out a1 a2 into the console. Error handling on user input is your own exercise.

According to setuptools' documentation on "Automatic Script Creation" this is not possible:

The functions you specify are called with no arguments

Alternatively you could do such a thing:

In __main__.py:

def main_true():
    return main(print_me=True)

In setup.py:

entry_points={
    'console_scripts': [
        'test = mypackage.__main__:main_true'
     ],
},

But in this particular case since True is already the default argument for the parameter print_me, this is probably not necessary, and changing 'test = mypackage.__main__:main(print_me=True)' to 'test = mypackage.__main__:main' should be enough.

If there is not a good reason to not do so, I would definitely advocate a spin on option 3. As @jonsharp mentions, breaking up your utility into clean units of functionality is a good way to ensure testability. Even the smallest scripts can eventually morph into a much larger program and making sure that you have an extensible API sooner rather than later will alleviate much headache down the road.

The way I'd approach this is:

1. Break up your code into logical methods with clean and clear I/O
2. Add unit tests. Having them is never a bad thing.
3. Rather than using if __name__ == '__main__', create a main() (or similar) method containing your entry point
4. Use setuptool's setup() function to define the script entry point in your setup.py file.

For example:

from setuptools import setup
setup(
    name='mypackage',
    version='0.1',
    entry_points={
        'console_scripts': [ 'myscript = mypackage.mymodule:main' ],
    }
)

Now, not only is all of your code (including main()) is easily unit testable, but you can still have your console entry point once you've done a python setup.py install|develop.

Any validation I do using, say, ArgumentParser.add_mutually_exclusive_group will not apply when my tool is run as a library instead of a command line script.

Depending on how your API is designed, you may need to add some extra validation to input parameters, but that should likely be there to prevent unexpected input anyways.

Edit: The only time I would use generally use subprocess is when I'm calling into a non-Python application or another Python script that I don't own or have the time to refactor, but the latter only being as a last resort. Most well-written Python utilities will expose both command line utilities and internal API.

The docs for the (awesome) Click package suggest a few reasons to use entry points instead of scripts, including

1. cross-platform compatibility and
2. avoiding having the interpreter assign __name__ to __main__, which could cause code to be imported twice (if another module imports your script)

Click is a nice way to implement functions for use as entry_points, btw.

How can I use entry_points to generate a binary that calls python -m mypackage (and passes *args, **kwargs) ?

I think this is the wrong way to look at the problem. You don't want your script to call python -m mypackage, but you want the script to have the same entry point as python -m mypackage

Consider this simple example:

script_proj/
├── script_proj
│   ├── __init__.py
│   └── __main__.py
└── setup.py

and the minimalistic setup.py:

from setuptools import setup

setup(
    name="script_proj",
    packages=["script_proj"],
    entry_points = {
        "console_scripts": [
            "myscript = script_proj.__main__:main",
        ]
    }
)

__main__.py is a dummy module and contains the main method.

def main():
    print("Hello world!")

if __name__ == "__main__":
    main()

After installing, you have the executable myscript, which calls the main method in __main__.py. In this package design python -m script_proj also calls the same main method.

I just realised part of the answer:

in the case where the module executes everything at the top-level, i.e. on import, it's therefore ok to define a dummy "no-op" main function, like so:

# Content of mypkg/myscript.py

print("myscript being executed!")

def main():
    pass  # Do nothing!

This solution will still force me to add this line to the existing scripts, but I think it's a quick but cautious solution.

No solution if the code is under a if __name__=='__main__' though...