Commits

ericvsmith committed b0ad3d1

Added examples.

Comments (0)

Files changed (1)

 directory on ``sys.path``, and have the "foo.baz" portion provided in
 a zip file, also on ``sys.path``.
 
+
+Examples
+========
+
+Nested namespace packages
+-------------------------
+
+This example uses the following directory structure::
+
+   Lib/test/namspace_pkgs
+       parent1
+           parent
+               child
+                   one.py
+       parent2
+           parent
+               child
+                   two.py
+
+Here, both parent and child are namespace packages: Portions of them
+exist in different directories, and they do not have ``__init__.py``
+files.
+
+Here we add the parent directories to ``sys.path``, and show that the
+portions are correctly found::
+
+    >>> import sys
+    >>> sys.path += ['Lib/test/namespace_pkgs/parent1/parent', 'Lib/test/namespace_pkgs/parent2/parent']
+    >>> import parent.child.one
+    >>> parent.__path__
+    _NamespacePath(['/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent1/parent', '/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent2/parent'])
+    >>> parent.child.__path__
+    _NamespacePath(['/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent1/parent/child', '/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent2/parent/child'])
+    >>> import parent.child.two
+
+Dynamic path computation
+------------------------
+
+This example uses a similar directory structure, but adds a third
+portion::
+
+   Lib/test/namspace_pkgs
+       parent1
+           parent
+               child
+                   one.py
+       parent2
+           parent
+               child
+                   two.py
+       parent3
+           parent
+               child
+                   three.py
+
+We add the first two parent paths to ``sys.path``. The third portion
+is added dynamically to the parent's ``__path__``, and the third
+portion is found when it is imported::
+
+    # add the first two parent paths to sys.path
+    >>> import sys
+    >>> sys.path += ['Lib/test/namespace_pkgs/parent1/parent', 'Lib/test/namespace_pkgs/parent2/parent']
+
+    # parent.child.one can be imported, because parent1/parent was added to sys.path:
+    >>> import parent.child.one
+    >>> parent.__path__
+    _NamespacePath(['/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent1/parent', '/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent2/parent'])
+
+    # parent.child.__path__ contains parent1/parent/child and parent2/parent/child, but not parent3/parent/child:
+    >>> parent.child.__path__
+    _NamespacePath(['/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent1/parent/child', '/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent2/parent/child'])
+
+    # parent.child.two can be imported, because parent2/parent was added to sys.path:
+    >>> import parent.child.two
+
+    # we cannot import parent.child.three, because parent3 is not in the path:
+    >>> import parent.child.three
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "<frozen importlib._bootstrap>", line 1286, in _find_and_load
+      File "<frozen importlib._bootstrap>", line 1250, in _find_and_load_unlocked
+    ImportError: No module named 'parent.child.three'
+
+    # now add parent3 to the parent's __path__:
+    >>> parent.__path__.append('Lib/test/namespace_pkgs/parent3/parent')
+
+    # and now parent.child.three can be imported:
+    >>> import parent.child.three
+
+    # and parent3/parent/child has dynamically been added to parent.child.__path__
+    >>> parent.child.__path__
+    _NamespacePath(['/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent1/parent/child', '/home/eric/local/python/pep-420/Lib/test/namespace_pkgs/parent2/parent/child', 'Lib/test/namespace_pkgs/parent3/parent/child'])
+
+
 Discussion
 ==========