add doctest and documentation to region.py; add new function to set region from bbox, rename bbox to get_bbox

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@54917 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/python/pygrass/gis/region.py

@@ -17,6 +17,7 @@ class Region(object):
 
             >>> default = Region(default=True)
             >>> current = Region()
+            >>> current_good = Region()
             >>> default == current
             True
             >>> current.cols
@@ -32,16 +33,11 @@ class Region(object):
             >>> current.set_current()
             >>> default == current
             False
-            >>> current.set_default()
+            >>> current.get_default()
             >>> default = Region(default=True)
             >>> default == current
             True
-            >>> default
-            Region(n=228500, s=215000, e=645000, w=630000, nsres=10, ewres=20)
-            >>> current
-            Region(n=228500, s=215000, e=645000, w=630000, nsres=10, ewres=20)
-            >>> default.ewres = 10.
-            >>> default.set_default()
+            >>> current_good.set_current()
         """
         self.c_region = ctypes.pointer(libgis.Cell_head())
         if default:
@@ -54,94 +50,116 @@ class Region(object):
 
     #----------LIMITS----------
     def _get_n(self):
+        """Private function to obtain north value"""
         return self.c_region.contents.north
 
     def _set_n(self, value):
+        """Private function to set north value"""
         self.c_region.contents.north = value
 
     north = property(fget=_get_n, fset=_set_n)
 
     def _get_s(self):
+        """Private function to obtain south value"""
         return self.c_region.contents.south
 
     def _set_s(self, value):
+        """Private function to set south value"""
         self.c_region.contents.south = value
 
     south = property(fget=_get_s, fset=_set_s)
 
     def _get_e(self):
+        """Private function to obtain east value"""
         return self.c_region.contents.east
 
     def _set_e(self, value):
+        """Private function to set east value"""
         self.c_region.contents.east = value
 
     east = property(fget=_get_e, fset=_set_e)
 
     def _get_w(self):
+        """Private function to obtain west value"""
         return self.c_region.contents.west
 
     def _set_w(self, value):
+        """Private function to set west value"""
         self.c_region.contents.west = value
 
     west = property(fget=_get_w, fset=_set_w)
 
     def _get_t(self):
+        """Private function to obtain top value"""
         return self.c_region.contents.top
 
     def _set_t(self, value):
+        """Private function to set top value"""
         self.c_region.contents.top = value
 
     top = property(fget=_get_t, fset=_set_t)
 
     def _get_b(self):
+        """Private function to obtain bottom value"""
         return self.c_region.contents.bottom
 
     def _set_b(self, value):
+        """Private function to set bottom value"""
         self.c_region.contents.bottom = value
 
     bottom = property(fget=_get_b, fset=_set_b)
 
     #----------RESOLUTION----------
     def _get_rows(self):
+        """Private function to obtain rows value"""
         return self.c_region.contents.rows
 
     def _set_rows(self, value):
+        """Private function to set rows value"""
         self.c_region.contents.rows = value
         self.adjust(rows=True)
 
     rows = property(fget=_get_rows, fset=_set_rows)
 
     def _get_cols(self):
+        """Private function to obtain columns value"""
         return self.c_region.contents.cols
 
     def _set_cols(self, value):
+        """Private function to set columns value"""
         self.c_region.contents.cols = value
         self.adjust(cols=True)
 
     cols = property(fget=_get_cols, fset=_set_cols)
 
     def _get_nsres(self):
+        """Private function to obtain north-south value"""
         return self.c_region.contents.ns_res
 
     def _set_nsres(self, value):
+        """Private function to obtain north-south value"""
         self.c_region.contents.ns_res = value
         self.adjust()
 
     nsres = property(fget=_get_nsres, fset=_set_nsres)
 
     def _get_ewres(self):
+        """Private function to obtain east-west value"""
         return self.c_region.contents.ew_res
 
     def _set_ewres(self, value):
+        """Private function to set east-west value"""
         self.c_region.contents.ew_res = value
         self.adjust()
 
     ewres = property(fget=_get_ewres, fset=_set_ewres)
 
     def _get_tbres(self):
+        """Private function to obtain top-botton 3D value"""
         return self.c_region.contents.tb_res
 
     def _set_tbres(self, value):
+        """Private function to set top-bottom 3D value"""
         self.c_region.contents.tb_res = value
         self.adjust()
 
@@ -149,10 +167,22 @@ class Region(object):
 
     @property
     def zone(self):
+        """Return the zone of projection
+        
+        >>> reg = Region()
+        >>> reg.zone
+        0
+        """
         return self.c_region.contents.zone
 
     @property
     def proj(self):
+        """Return a code for projection
+        
+        >>> reg = Region()
+        >>> reg.proj
+        99
+        """        
         return self.c_region.contents.proj
 
     #----------MAGIC METHODS----------
@@ -209,22 +239,70 @@ class Region(object):
         """
         libgis.G_adjust_Cell_head(self.c_region, bool(rows), bool(cols))
 
+    def vect(self, vector_name):
+        """Adjust bounding box of region using a vector ::
+
+        >>> reg = Region()
+        >>> reg.vect('census')
+        >>> reg.get_bbox()
+        Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
+        >>> reg.get_default()
+        """
+        from grass.pygrass.vector import VectorTopo
+        vect = VectorTopo(vector_name)
+        vect.open()
+        bbox = vect.bbox()
+        self.set_bbox(bbox)
+
     def get_current(self):
+        """Set the current GRASS region to the Region object"""
         libgis.G_get_set_window(self.c_region)
 
     def set_current(self):
+        """Set the Region object to the current GRASS region"""
         libgis.G_set_window(self.c_region)
 
     def get_default(self):
+        """Set the default GRASS region to the Region object"""
         libgis.G_get_window(self.c_region)
 
     def set_default(self):
+        """Set the Region object to the default GRASS region.
+        It works only in PERMANENT mapset"""
+        from grass.pygrass.gis import Mapset
+        mapset = Mapset()
+        if mapset.name != 'PERMANENT':
+            raise GrassError("ERROR: Unable to change default region. The " \
+                             "current mapset is not <PERMANENT>.")
         self.adjust()
         if libgis.G_put_window(self.c_region) < 0:
-            raise GrassError("Cannot change region (WIND file).")
+            raise GrassError("Cannot change region (DEFAUL_WIND file).")
 
-    def bbox(self):
+    def get_bbox(self):
+        """Return a Bbox object with the extension of the region ::
+
+        >>> reg = Region()
+        >>> reg.get_bbox()
+        Bbox(228500.0, 215000.0, 645000.0, 630000.0)
+        """
         from grass.pygrass.vector.basic import Bbox
         return Bbox(north=self.north, south=self.south,
                     east=self.east, west=self.west,
                     top=self.top, bottom=self.bottom)
+
+    def set_bbox(self, bbox):
+        """Set region from Bbox ::
+
+        >>> from grass.pygrass.vector.basic import Bbox
+        >>> b = Bbox(230963.640878, 212125.562878,
+        ...          645837.437393, 628769.374393)
+        >>> reg = Region()
+        >>> reg.set_bbox(b)
+        >>> reg.get_bbox()
+        Bbox(230963.640878, 212125.562878, 645837.437393, 628769.374393)
+        >>> reg.get_current()
+        """
+        self.north = bbox.north
+        self.south = bbox.south
+        self.east = bbox.east
+        self.west = bbox.west