1.. _rfc-17:
2
3================================================================================
4RFC 17: Python Namespaces
5================================================================================
6
7Author: Howard Butler
8
9Contact: hobu.inc@gmail.com
10
11Status: Adopted
12
13Summary
14-------
15
16| GDAL bindings for Python have historically dodged the normal Python
17  practices of using packages and namespaces to provide organization.
18| This RFC implements a new namespace for Python, called *osgeo*, where
19  the GDAL Python bindings henceforth will reside. Backward
20  compatibility is provided, so that current code will continue to run
21  unchanged, but new developments should utilize the namespace for code
22  organization and global namespace pollution reasons. As of 10/1/2007,
23  the changes described here in RFC 17 only pertain to the "next-gen"
24  Python bindings. It is expected that these bindings will be the
25  default bindings for GDAL 1.5.
26
27Objective
28---------
29
30To provide the GDAL Python bindings in a Python package that is properly
31namespaced, eliminating pollution of Python's global namespace.
32
33Past Usage
34----------
35
36GDAL's Python bindings previously used globally-aware Python modules:
37
38::
39
40   import gdal
41   import osr
42   import ogr
43   import gdalconst
44   import gdalnumeric
45
46New Usage
47---------
48
49RFC 17 now provides these modules under the *osgeo* namespace:
50
51::
52
53   from osgeo import gdal
54   from osgeo import osr
55   from osgeo import ogr
56   from osgeo import gdalconst
57   from osgeo import gdal_array
58
59Additionally, the old module-style imports continue to work with a
60deprecation warning:
61
62::
63
64   >>> import gdal
65   /Users/hobu/svn/gdal/swig/python/gdal.py:3: DeprecationWarning: gdal.py was placed in a namespace, it is now available as osgeo.gdal
66     warn('gdal.py was placed in a namespace, it is now available as osgeo.gdal', DeprecationWarning)
67
68It is planned that we will remove the GDAL-specific global modules at
69some point in the future.
70
71Other Sprint Updates
72--------------------
73
74The work for this RFC was done at the FOSS4G2007 GDAL code sprint by
75Howard Butler and Chris Barker. In addition to the Python namespacing,
76some minor issues were dealt with respect to building the GDAL bindings.
77
781. The next-gen Python bindings now use setuptools by default if it is
79   available.
802. The ./swig/python directory was slightly reorganized to separate
81   extension building from pure python modules.
823. gdal2tiles, a Google Summer of Code project by Petr Klokan, was
83   integrated into the next-gen bindings
84
85Voting History
86--------------
87
88A voice vote (our first ever!) commenced at the FOSS4G2007 sprint.
89
90-  Frank Warmerdam +1
91-  Howard Butler +1
92-  Daniel Morissette +1
93-  Tamas Szekerest +1
94