Skip to content

nspkg

Jump to bottom
Carter Tinney edited this page Sep 9, 2019 · 1 revision

Azure IoT Namespace Package

The Azure IoT Namespace package, azure-iot-nspkg, allows for PEP420-style implict namespacing in our Python 2 releases.

The Problem

PEP420 only applies to Python 3.3+, so while it is valid for all of our Python 3 releases (we only support 3.5+), it doesn't cover our Python 2.7 legacy release.

However, it is very necessary for us to support implict namespacing, as the libraries we release are part of a shared namespace. For instance, our device-side clients live in azure.iot.device, which is a package named device accessed via two nested namespaces, azure and iot.

In order to be compatible with Python 2.7, we must make sure both azure and iot are implicitly defined namespaces.

The Solution

By releasing empty packages that simply define namespaces (an "nspkg" or "NameSpace Package"), we can create a implict namespaces in Python 2. These packages then can be taken on as a conditional dependency - only install if running Python 2.

The azure namespace is not maintained or managed by us, and so we need to do be a part of it is take a dependency on azure-nspkg.

However, the azure.iot namespace DOES belong to us, and thus we need to maintain the equivalent nspkg, azure-iot-nspkg. It will provide a shared implicit namespace for all packages we distribute in our azure.iot namespace.

All that azure-iot-nspkg contains are directories azure and iot, each with an __init__.py file, containing the following line:

__path__ = __import__("pkgutil").extend_path(__path__, __name__)

For more information about nspkgs, see the guide to Azure packaging

Details

  • Note that in the setup.py file for azure-iot-nspkg, the azure package is not included, only azure.iot. This is because there is the aforementioned dependency on azure-nspkg, which defines the azure namespace. Thus, the only thing our actual packages (e.g. azure-iot-device) need to take a namespace dependency on is azure-iot-nspkg.

  • Note also in the setup.py, that packages are only included at all if using Python 2.

  • azure-iot-nspkg only needs to be released if there has been a change to its configuration. This should rarely, if ever, be necessary.

  • NOTE WELL that azure-iot-nspkg cannot be built as a universal wheel file. In order to distribute, generate a py2 wheel, a py3 wheel, and a sdist.

Clone this wiki locally