how to read a syntax diagram

[MRAB]

On 2018-05-27 22:17, Paul wrote:
> hi,
>     I'm using the Google Sheets API (the client library rather than the
> RESTful interface) and I'm confused about the meaning of the syntax
> diagrams.  This is from
> https://developers.google.com/resources/api-libraries/documentation/sheets/v4/python/latest/sheets_v4.spreadsheets.values.html#update
> 
> efaults to ROWS.
>    }
> 
> update(spreadsheetId=*, range=*, body=*, valueInputOption=None,
> x__xgafv=None, responseValueRenderOption=None,
> includeValuesInResponse=None, responseDateTimeRenderOption=None)
> 
> Sets values in a range of a spreadsheet.
> The caller must specify the spreadsheet ID, range, and
> a valueInputOption.
> 
> Args:
>    spreadsheetId: string, The ID of the spreadsheet to update. (required)
>    range: string, The A1 notation of the values to update. (required)
>    body: object, The request body. (required)
>      The object takes the form of:
> 
> { # Data within a range of the spreadsheet.
>    "range": "A String", # The range the values cover, in A1 notation.
>        # For output, this range indicates the entire requested range,
>        # even though the values will exclude trailing rows and columns.
>        # When appending values, this field represents the range to search for a
>        # table, after which values will be appended.


[snip]
> 
> My specific questions are:
>     1) is this standard (python?) syntax notation?  I haven't found a key to
> this form of documentation.

Note quite.

>     1)  What does  '=*' mean?

In the descriptions that follow, those that have '=*' also have 
'(required)', so I think it means that the parameter is required. That's 
not standard Python notation, AFAIK.

>     2)  What does '=None' mean?    [my guess is that this means "no default
> value"].

In standard Python notation it means that the default is None, which 
usually means that there's some kind of default. For example, if the 
parameter is for defining a date format, None would mean to use a 
standard date format, such as ISO-whatever or the system-defined date 
format for the current locale.

>     3)  Note that it says that range is required.  Through trial, I see that
> *one* of the 'range' specifications is required.  I.E., I can specify
> 'range' outside body, or 'range' as part of body, or both, but I must have
> 'range' someplace.   This is a bit confusing to me ( as opposed to my usual
> understanding of "required").  Also, what does range mean, in these two
> different spots, and what does it mean if two different values of range are
> specified?
> 
For range it mentions "A1 notation". In spreadsheet applications, 
columns are labelled by letter (A, B, C, etc.) and rows by number (1, 2, 
3, etc.), so the top-left cell is "A1". You specify a range by giving 
the labels of 2 opposite corners, e.g. "A1B3".