How to write a Python module package

Question

I ve been making Python scripts for simple tasks at work and never really bothered packaging them for others to use  Now I have been assigned to make a Python wrapper for a REST API  I have absolutely no idea on how to start and I need help   What I have    Just want to be specific as possible  I have the virtualenv ready  it s also up in github  the  gitignore file for python is there as well  plus  the requests library for interacting with the REST API  That s it   Here s the current directory tree     -- bin         --  the usual stuff   -- include         --  the usual stuff   -- lib         -- python2 7             --  the usual stuff   -- local         --  the usual stuff   -- README md  27 directories  280 files   I don t even know where to put the  py files  if I ever make one   What I wanted to do   Make a python module install-able with  pip install       If possible  I want a general step by step process on writing Python modules

User · Accepted Answer

A module is a file containing Python definitions and statements. The file name is the module name with the suffix .py

create hello.py then write the following function as its content:

def helloworld():
   print "hello"

Then you can import hello:

>>> import hello
>>> hello.helloworld()
'hello'
>>>

To group many .py files put them in a folder. Any folder with an __init__.py is considered a module by python and you can call them a package

|-HelloModule
  |_ __init__.py
  |_ hellomodule.py

You can go about with the import statement on your module the usual way.

For more information, see 6.4. Packages.

User · Answer

Python 3 - UPDATED 18th November 2015  Found the accepted answer useful  yet wished to expand on several points for the benefit of others based on my own experiences    Module  A module is a file containing Python definitions and statements  The file name is the module name with the suffix  py appended   Module Example  Assume we have a single python script in the current directory  here I am calling it mymodule py  The file mymodule py contains the following code   def myfunc        print  Hello      If we run the python3 interpreter from the current directory  we can import and run the function myfunc in the following different ways  you would typically just choose one of the following     gt  gt  gt  import mymodule  gt  gt  gt  mymodule myfunc   Hello   gt  gt  gt  from mymodule import myfunc  gt  gt  gt  myfunc   Hello   gt  gt  gt  from mymodule import    gt  gt  gt  myfunc   Hello    Ok  so that was easy enough    Now assume you have the need to put this module into its own dedicated folder to provide a module namespace  instead of just running it ad-hoc from the current working directory  This is where it is worth explaining the concept of a package   Package  Packages are a way of structuring Python   s module namespace by using    dotted module names     For example  the module name A B designates a submodule named B in a package named A  Just like the use of modules saves the authors of different modules from having to worry about each other   s global variable names  the use of dotted module names saves the authors of multi-module packages like NumPy or the Python Imaging Library from having to worry about each other   s module names   Package Example  Let s now assume we have the following folder and files  Here  mymodule py is identical to before  and   init   py is an empty file      -- mypackage      --   init   py      -- mymodule py   The   init   py files are required to make Python treat the directories as containing packages  For further information  please see the Modules documentation link provided later on   Our current working directory is one level above the ordinary folder called mypackage    ls mypackage   If we run the python3 interpreter now  we can import and run the module mymodule py containing the required function myfunc in the following different ways  you would typically just choose one of the following     gt  gt  gt  import mypackage  gt  gt  gt  from mypackage import mymodule  gt  gt  gt  mymodule myfunc   Hello   gt  gt  gt  import mypackage mymodule  gt  gt  gt  mypackage mymodule myfunc   Hello   gt  gt  gt  from mypackage import mymodule  gt  gt  gt  mymodule myfunc   Hello   gt  gt  gt  from mypackage mymodule import myfunc  gt  gt  gt  myfunc   Hello   gt  gt  gt  from mypackage mymodule import    gt  gt  gt  myfunc   Hello    Assuming Python 3  there is excellent documentation at  Modules  In terms of naming conventions for packages and modules  the general guidelines are given in PEP-0008 - please see Package and Module Names  Modules should have short  all-lowercase names  Underscores can be used in the module name if it improves readability  Python packages should also have short  all-lowercase names  although the use of underscores is discouraged

User · Answer

Since nobody did cover this question of the OP yet      What I wanted to do       Make a python module install-able with  pip install        Here is an absolute minimal example  showing the basic steps of preparing and uploading your package to PyPI using setuptools and twine   This is by no means a substitute for reading at least the tutorial  there is much more to it than covered in this very basic example   Creating the package itself is already covered by other answers here  so let us assume we have that step covered and our project structure like this      -- hellostackoverflow       --   init   py      -- hellostackoverflow py   In order to use setuptools for packaging  we need to add a file setup py  this goes into the root folder of our project      -- setup py  -- hellostackoverflow       --   init   py      -- hellostackoverflow py   At the minimum  we specify the metadata for our package  our setup py would look like this   from setuptools import setup  setup      name  hellostackoverflow       version  0 0 1       description  a pip-installable package example       license  MIT       packages   hellostackoverflow        author  Benjamin Gerfelder       author email  benjamin gerfelder gmail com       keywords   example        url  https   github com bgse hellostackoverflow      Since we have set license  MIT   we include a copy in our project as LICENCE txt  alongside a readme file in reStructuredText as README rst      -- LICENCE txt  -- README rst  -- setup py  -- hellostackoverflow       --   init   py      -- hellostackoverflow py   At this point  we are ready to go to start packaging using setuptools  if we do not have it already installed  we can install it with pip   pip install setuptools   In order to do that and create a source distribution  at our project root folder we call our setup py from the command line  specifying we want sdist   python setup py sdist   This will create our distribution package and egg-info  and result in a folder structure like this  with our package in dist      -- dist   -- hellostackoverflow egg-info   -- LICENCE txt  -- README rst  -- setup py  -- hellostackoverflow       --   init   py      -- hellostackoverflow py   At this point  we have a package we can install using pip  so from our project root  assuming you have all the naming like in this example    pip install   dist hellostackoverflow-0 0 1 tar gz   If all goes well  we can now open a Python interpreter  I would say somewhere outside our project directory to avoid any confusion  and try to use our shiny new package   Python 3 5 2  default  Sep 14 2017  22 51 06    GCC 5 4 0 20160609  on linux Type  help    copyright    credits  or  license  for more information   gt  gt  gt  from hellostackoverflow import hellostackoverflow  gt  gt  gt  hellostackoverflow greeting    Hello Stack Overflow     Now that we have confirmed the package installs and works  we can upload it to PyPI   Since we do not want to pollute the live repository with our experiments  we create an account for the testing repository  and install twine for the upload process   pip install twine   Now we re almost there  with our account created we simply tell twine to upload our package  it will ask for our credentials and upload our package to the specified repository   twine upload --repository-url https   test pypi org legacy  dist     We can now log into our account on the PyPI test repository and marvel at our freshly uploaded package for a while  and then grab it using pip   pip install --index-url https   test pypi org simple  hellostackoverflow   As we can see  the basic process is not very complicated  As I said earlier  there is a lot more to it than covered here  so go ahead and read the tutorial for more in-depth explanation

User · Answer

Make a file named  hello py   If you are using Python 2 x  def func        print  Hello    If you are using Python 3 x  def func        print  Hello     Run the file  Then  you can try the following    gt  gt  gt  import hello  gt  gt  gt  hello func   Hello   If you want a little bit hard  you can use the following   If you are using Python 2 x  def say text       print text   If you are using Python 3 x  def say text       print text    See the one on the parenthesis beside the define  That is important  It is the one that you can use within the define   Text - You can use it when you want the program to say what you want  According to its name  it is text  I hope you know what text means  It means  words  or  sentences    Run the file  Then  you can try the following if you are using Python 3 x    gt  gt  gt  import hello  gt  gt  gt  hello say  hi   hi  gt  gt  gt  from hello import say  gt  gt  gt  say  test   test   For Python 2 x - I guess same thing with Python 3  No idea  Correct me if I made a mistake on Python 2 x  I know Python 2 but I am used with Python 3

User · Answer

Once you have defined your chosen commands  you can simply drag and drop the saved file into the Lib folder in your python program files     gt  gt  gt  import mymodule   gt  gt  gt  mymodule myfunc

User · Answer

I created a project to easily initiate a project skeleton from scratch  https   github com MacHu-GWU pygitrepo-project   And you can create a test project  let s say  learn creating py package   You can learn what component you should have for different purpose like    create virtualenv install itself run unittest run code coverage build document deploy document run unittest in different python version deploy to PYPI   The advantage of using pygitrepo is that those tedious are automatically created itself and adapt your package name  project name  github account  document host service  windows or macos or linux   It is a good place to learn develop a python project like a pro   Hope this could help   Thank you

User · Answer

A module is a file containing Python definitions and statements. The file name is the module name with the suffix .py

create hello.py then write the following function as its content:

def helloworld():
   print "hello"

Then you can import hello:

>>> import hello
>>> hello.helloworld()
'hello'
>>>

To group many .py files put them in a folder. Any folder with an __init__.py is considered a module by python and you can call them a package

|-HelloModule
  |_ __init__.py
  |_ hellomodule.py

You can go about with the import statement on your module the usual way.

For more information, see 6.4. Packages.

[python] How to write a Python module/package?

Examples related to python

Examples related to python-2.7

Examples related to python-module