如何使用顶级函数创建 PyPi 包

Question

I am trying to get a package installed on PyPi and am having trouble getting it configured to have the desired syntax. At the end of the day, I want to be able to use a function within my module using the following syntax:

import ucal
ucal.calculate(...)

This syntax follows all the common libraries. (One could also use from ucal import calculate ).

My directory structure is as follows:

ucal/
    ucal/
        __init__.py
        ucal.py
        ucal_units.py
    setup.py

Within ucal.py:

   import ucal_units
   def calculate():
       pass

I can upload to PyPi and then install using pip:

> python setup.py bdist_wheel
> python -m twine upload dist/ucal-0.1.3-py3-none-any.whl
(wait a minute)
> pip install --user ucal

However, inside a new script, the following script yields an error:

import ucal
ucal.calculate() # <-- AttributeError: module 'ucal' has no attribute 'calculate'

It turns out that this works instead:

from ucal import ucal
ucal.calculate()

But I don't want this silly syntax. ucal should be at the top level. What changes do I need to make in order to get the desired syntax to work?

I tried moving all files in ucal/ucal to the parent directory, but this resulted in ModuleNotFoundError: No module named 'ucal' even though the module was installed (verified with pip list)

Answer 1

In ucal/ucal.py , declare public names that you want to export using the __all__ variable:

# ucal/ucal.py

__all__ = ["calculate"]

def calculate(...):
    ...

In ucal/__init__.py , pull those names up into the top-level namespace by using the * import:

# ucal/__init__.py

from ucal.ucal import *

Now, users will see calculate in the top-level namespace.

Answer 2

When importing, the namespace within the __init__.py appears to be able to be accessed by the ucal.* syntax. One option, then, is to replace __init__.py with the contents of ucal.py . This doesn't seem quite correct.

Another option is to add an import statement within __init__.py :

from ucal.ucal import calculate

This also seems messy, but perhaps that's the accepted way to do things?