added docs for datarange and cell updates

AsteroidOrangeJuice · Feb 25, 2017 · 8f6308f · 8f6308f
1 parent cc48544
commit 8f6308f
Show file tree

Hide file tree

Showing 6 changed files with 114 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -9,6 +9,8 @@ Features:
 * Open, create, delete and share spreadsheets using _title_ or _key_
 * Control permissions of spreadsheets.
 * Set format, write notes
+* NamedRanges Support
+* Work with range of cells easily with DataRange
 * Do all the updates and push the changes in a batch
 
 ## Requirements
@@ -62,6 +64,30 @@ sh.share("myFriend@gmail.com")
 
 ```
 
+Sample Scenario: you want to fill height values of students
+```python
+
+## import and open the sheet as given above
+
+header = wks.cell('A1')
+header.value = 'Names'
+header.text_format['bold'] = True # make the header bold
+header.update()
+
+# or achive the same in oneliner
+wks.cell('B1').set_text_format('bold', True).value = 'heights'
+
+# set the names
+wks.update_cells('A2:A5',[['name1'],['name2'],['name3'],['name4']])
+
+# set the heights
+heights = wks.range('B2:B5')  # get the range
+heights.name = "heights"  # name the range
+heights.update_values([[50],[60],[67],[66]]) # update the vales
+wks.update_cell('B6','=average(heights)') # set get the avg value
+
+```
+
 ## More Examples
 
 ### Opening a Spreadsheet
@@ -155,6 +181,10 @@ wks.index = 2 # index start at 1 , not 0
 
 # Update title
 wks.title = "NewTitle"
+# working with named ranges
+wks.create_named_range('A1', 'A10', 'prices')
+wks.get_named_ranges()  # will return a list of DataRange objects
+wks.delete_named_range('prices')
 
 ```
 
@@ -169,6 +199,7 @@ df = wks.get_as_df()
 
 ```
 
+
 ### Cell Object
 
 Each cell has a __value__ and coordinates (__row__, __col__, __label__) properties.
@@ -210,17 +241,27 @@ for cell in cell_list:
     cell.value = 'O_0'
 
 # add formula
-c1.formula = '=A1+C2'
+c1.formula = 'A1+C2'
 
 # get neighbouring cells
 c2 = c1.neighbour('topright') # you can also specify relative position as tuple eg (1,1)
 
 # set cell format
-c1.set_format(pygsheets.FormatType.NUMBER, '00.0000')
+c1.format = pygsheets.FormatType.NUMBER, '00.0000' # format is optional
 
 # write notes on cell
 c1.note = "yo mom"
 
+# set cell color
+c1.color = (1,1,1,1) # Red Green Blue Alpha
+
+# set text format
+c1.text_format['fontSize'] = 14
+c1.text_format['bold'] = True
+
+# sync the changes
+ c1.update()
+
 # you can unlink a cell and set all required properties and then link it
 # So yu could create a model cell and update multiple sheets
 c.unlink()
@@ -230,6 +271,35 @@ c.link(wks2, True)
 
 ```
 
+### DataRange Object
+
+The DataRange is used to represent a range of cells in a worksheet, they can be named, protected
+Almost all `get_`functions has a `returnas` param, set it to `range` to get a range object
+```python
+# Getting a Range object
+rng = wks.get_values('A1', 'C5', returnas='range')
+rng.unlink()  # linked ranges will sync the changes as they are changed
+
+# Named ranges
+rng.name = 'pricesRange'  # will make this range a named range
+rng = wks.get_named_ranges('commodityCount') # directly get a named range
+rng.name = ''  # will delete this named range
+
+# Setting Format
+ # first create a model cell with required properties
+model_cell = Cell('A1')
+model_cell.color = (1.0,0,1.0.1.0) # rose color cell
+model_cell.format = pygsheets.FormatType.PERCENT
+
+ # now set its format to all cells in the range
+rng.applay_format(model_cell)  # will make all cell in this range rose and percent format
+
+# get cells in range
+cell = rng[0][1]
+
+```
+
+
 ## How to Contribute
 
 This library is still in development phase. So there is a lot of work to be done. Checkout the [TO DO's](TODO.md).

diff --git a/docs/pygsheets.rst b/docs/pygsheets.rst
@@ -28,6 +28,14 @@ pygsheets.custom_types module
     :undoc-members:
     :show-inheritance:
 
+pygsheets.datarange module
+--------------------------
+
+.. automodule:: pygsheets.datarange
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 pygsheets.exceptions module
 ---------------------------
 

diff --git a/docs/source/datarange.rst b/docs/source/datarange.rst
@@ -0,0 +1,9 @@
+
+
+DataRange
+=========
+
+.. module:: pygsheets
+
+.. autoclass:: DataRange
+   :members:
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
@@ -32,6 +32,7 @@ The models represent common spreadsheet objects: :class:`spreadsheet <Spreadshee
 
    spreadsheet
    worksheet
+   datarange
    cell
 
 

diff --git a/pygsheets/cell.py b/pygsheets/cell.py
@@ -18,6 +18,9 @@ class Cell(object):
     """An instance of this class represents a single cell
     in a :class:`worksheet <Worksheet>`.
 
+    :param pos: position of the cell adress
+    :param val: value of the cell
+    :param worksheet: worksheet this cell belongs to
     """
 
     def __init__(self, pos, val='', worksheet=None):

diff --git a/pygsheets/datarange.py b/pygsheets/datarange.py
@@ -17,7 +17,16 @@
 
 
 class DataRange(object):
-
+    """
+    DataRange specifes a range of cells in the sheet
+
+    :param start: top left cell adress
+    :param end: bottom right cell adress
+    :param worksheet: worksheet where this range belongs
+    :param name: name of the named range
+    :param name_id: id of named range
+    :param namedjson: json representing the NamedRange from api
+    """
     def __init__(self, start=None, end=None, worksheet=None, name='', data=None, name_id=None, namedjson=None):
         self._worksheet = worksheet
         if namedjson:
@@ -69,7 +78,7 @@ def name_id(self):
 
     @property
     def protect(self):
-        """if this range is protected"""
+        """ (boolean) if this range is protected"""
         return self._protected
 
     # @TODO
@@ -105,11 +114,14 @@ def end_addr(self, addr):
 
     @property
     def range(self):
-        """Range of the cell range in format A1:C5"""
+        """Range in format A1:C5"""
         return format_addr(self._start_addr) + ':' + format_addr(self._end_addr)
 
     def link(self, update=True):
-        """link the dstarange so that all propertis are synced right after setting them"""
+        """link the dstarange so that all propertis are synced right after setting them
+
+        :param update: if the range should be synced to cloud on link
+        """
         self._linked = True
         if update:
             self.update_named_range()
@@ -122,6 +134,7 @@ def unlink(self):
     def fetch(self, only_data=True):
         """
         update the range data/ properties from cloud
+
         :param only_data: fetch only data
 
         """
@@ -132,7 +145,9 @@ def fetch(self, only_data=True):
     def applay_format(self, cell):
         """
         Change format of all cells in the range
+
         :param cell: a model :class: Cell whose format will be applied to all cells
+
         """
         request = {"repeatCell": {
             "range": self._get_gridrange(),
@@ -145,7 +160,9 @@ def applay_format(self, cell):
     def update_values(self, values=None):
         """
         Update the values of the cells in this range
+
         :param values: values as matrix
+
         """
         if values and self._linked:
             self._worksheet.update_cells(crange=self.range, values=values)
-Original file line number
+Diff line change
@@ Expand Up @@
        spreadsheet
        worksheet
+       datarange
        cell
@@ Expand Down @@