We Keep Coding

How can I setup a python CLI application so that I can use it without directly referring to the interpreter?

I want to build an application, say it's called helloworld, with a command line interface in python. My application as multiple nested modules and a top level module main.py.
Say the layout is :
helloworld/
helloworld/
__init__.py
module1/
module2/
module3/
setup.py
main.py
At this point, once my project is installed I can run it using
#> python path/to/helloworld/main.py arg1 arg2 arg3
I want to be able to interact with the program using commands such as :
#> helloworld arg1 arg2 arg3, in a similar manner as for example, the Flask framework comes with a command line application I can use with #> flask run.
I looked around and found questions suggesting using a shebang. As far as I can tell, this is not what I want.
I want a self contained application I can install using pip and then launch directly without any reference to the python interpreter.
How should I go about this ?
EDIT
It is an important requirement to me that the package can be installed using pip and the command line interface is immediately available. Shebangs/fiddling manually with the path/creating an additional shell script do not solve my problem.

You should add main.py to your PATH. What happens when you are running flask run is that your teminal looks up the command flask in PATH and runs the program that it is pointing to. You could see it as a kind of shortcut to the program Flask.
By adding your program to your PATH, you can tell the computer that if you type helloworld in your terminal, the terminal should run /my/path/to/helloworld.py.
I don't know what OS you are on, so here are links for most common OS on how to add a PATH variable.
Windows
Linux
Mac OSX
Edit: After you gave more explanation, setuptools is what you are looking for. Please look at this reference to see how to use it.

There's an explanation here of how to tell setuptools to add a script to the Python Scripts-folder during the pip installation. You can then make that script be for example a bat-file that calls your Python-script. In that way you achieve both that you do not need to write .py for your script to run, and that it happens automatically.

I know this has already been answered, but just in case someone comes across this in the future..
Here's what worked for a new package I'm developing after reading up on this from many different sources.
tldr; use setuptools and add your command as a console_scripts option under [options.entry_points] in setup.cfg.
You will also need some other fields in setup.cfg or setup.py for package discovery to work. Check out the setuptools docs for that.
Example entry point:
[options.entry_points]
console_scripts =
mycmd = mypackage.mymodule:myfunc
For local development, you can install the package in editable (development) mode with pip install -e . which will allow you to test the command as if you pip intalled it.
Alternatively, you could create a __main__.py that initializes your module when you run python -m mypackage from the root.
from mypackage import app
if __name__ == '__main__':
app.main()
I personally opted for both. Usually your main.py (or app.py in my example) belongs in your package not project level dir. Then you would create __main__.py there as well.

Python Package on GitHub

I made a python (3) package and I have been trying to upload it on Github. I also know how to push and install a git using pip. To test if it works as anticipated, I made a virtual environment on my local computer (linux) and pip installed my already pushed private package in there without a problem.
The issue is that I don't know how to access it!!! (I know how to activate and use virtualenvs; I don't know how to call my package) My package has a main interface that one would need to call it in terminal as follows:
python3 myui.py some_args *.data
and it's supposed to create some files where it's called. In other words, it's not exactly a module like numpy to be imported. I have watched/read many tutorials and documentations on the web and tbh I'm lost here.

You are looking for the -m flag. If you installed everything correctly, then the following command should allow you to run your script (based on your example). Note that you shouldn't add the file extension '.py'.
python3 -m myui some args *.data
If you have an actual package (directory with __init__.py file and more) instead of a module (a single .py file), then you can add a __main__.py file to that package. Python will execute this script when you use the -m flag with the package's name, in the same way as shown above.
python3 -m mypackage some args *.data
If you want to run a different script that is nested somewhere inside of that package, you can still run it by specifying its module name:
python3 -m mypackage.subpackage.myscript some args *.data
Another common way to make your script available uses the setup script (setup.py) or setup configuration file (setup.cfg) that is used to install the module or package. In that case, you can add an entry point to map a command to a specific module/function/etc. (as described in this Python packaging tutorial) so that you can run that command instead of having to use the -m flag with Python.
$ mycommand some args *.data

What does the -m option stand for in python?

When creating a virtual environment, I run:
python3 -m venv env
I understand that -m executes a module (venv in this case). However, what does the -m flag actually stand for?
Is it -m for module, or -m for __main__?
I couldn't find an unambiguous explanation. Here are some resources I investigated:
https://docs.python.org/2/using/cmdline.html#cmdoption-m
https://www.python.org/dev/peps/pep-0547/
Execution of Python code with -m option or not

in
section 1.1.1
It clearly says -m is the module name, here.
Quoting from the docs :
"since the argument is a module name, you must not give a file extension (.py). The module-name should be a valid Python module name"
Although -m is arbitrary as in the backend It is an argparser doing all the work.
When called with -m module-name, the given module is located on the Python module path and executed as a script
Package names are also permitted. When a package name is supplied instead of a normal module, the interpreter will execute <pkg>.__main__ And I guess the main also starting with 'm' is a coincidence.

It runs the module following -m. See the official documentation
The documentation says -m <module-name>, as well as "Since the argument is a module name...", so it makes sense to assume that "m" stands for module.

PYTHONPATH conflict

I am trying to import ZipCodeDatabase in helloworld.py.
helloworld.py exists at /google-app-engine/helloworld
ZipCodeDatabase module exists /usr/local/lib/python/python2.7/dist-packages
PYTHONPATH = /usr/local/lib/python/python2.7/dist-packages;/usr/local/lib/python/
When compiling helloworld I am still getting "ZipCodeDatabase module not found". Why isn't it being picked from the PYTHONPATH?

I highly doubt you've got a module called ZipCodeDatabase. That naming convention is typically reserved for a class that resides within a module. Modules are usually lowercase or lower_snake_case, to represent the file containing the module. I'm assuming you've installed pyzipcode here, but it may be a different module.
# assuming pyzipcode.py in the dist-packages directory
$ python -c 'from pyzipcode import ZipCodeDatabase'
If I'm wrong above, then are you sure you're running the version of python that has the ZipCodeDatabase module installed?
Some troubleshooting steps:
$ which python
$ python --version
$ python -c 'import ZipCodeDatabase'
$ ls -l /usr/local/lib/python2.7/dist-packages/ | grep -i zip
Also, is it really necessary for you to specify the PYTHONPATH line? Typically, the site-packages folder (and by extension I assume the dist-packages folder on Ubuntu) is included in the default PYTHONPATH, along with the current directory of the python module you're using.
How did you install the ZipCodeDatabase? Did you just drop the file in there? Try putting it alongside your helloworld.py file and try importing it then. Also, a full stack trace is useful information here, especially when others are trying to diagnose the problem you're having.
Edit:
Ok, now that I know you're using google app engine (should have been obvious from your use of paths - I'm sorry), it looks like it doesn't use the site-packages or dist-packages to load modules. You should create a sub-directory in your project with the relevant third party libraries, and add that sub-directory to your path. Disclaimer: I've never used GAE so I might be missing the mark with this.
Check out this answer for how to structure your project and add the extra directory to your path from within the application.

How to run Python egg files directly without installing them?

Is it possible to run Python egg files directly as you can run jar files with Java?
For example, with Java you might dos something like:
$ java -jar jar-file

A python egg is a "a single-file importable distribution format". Which is typically a python package.
You can import the package in the egg as long as you know it's name and it's in your path.
You can execute a package using the "-m" option and the package name.
However, python packages generally do not do anything when executed, and you may get an error. The -c option can be used to run code. (See http://docs.python.org/using/cmdline.html for details on command line options)
> python -m sphinx
sphinx is a package and cannot be directly executed
> python -c "import <package in an egg>; <function>();"
> python -c "import sphinx; print sphinx.package_dir"
C:\Python26\lib\site-packages\sphinx-0.6.1-py2.6.egg\sphinx

As of Python 2.6, you can use python some.egg and it will be executed if it includes a module named __main__.
For earlier versions of Python, you can use PYTHONPATH=some.egg python -m some module, and somemodule from the egg will be run as the main module. (Note: if you're on Windows, you'd need to do a separate SET PYTHONPATH=some.egg.)

For example, if you want to import the suds module which is available as .egg file:
egg_path='/home/shahid/suds_2.4.egg'
sys.path.append(egg_path)
import suds
#... rest of code

Python Egg file direct execution steps
Suppose if you have egg file and driver file to run through below command.
PYTHONPATH=eggfilename.egg python driverfile.py
above command for without install egg file with python code.