DOC: pytables natural name docs

Author: jreback

doc/source/io.rst

@@ -2600,6 +2600,14 @@ Notes & Caveats
      (e.g. *columns* or *minor_axis*) are determined as the maximum size
      of the elements in that axis or by passing the parameter
 
+.. warning::
+
+   ``PyTables`` will show a ``NaturalNameWarning`` if a  column name
+   cannot be used as an attribute selector. Generally identifiers that
+   have spaces, start with numbers, or ``_``, or have ``-`` embedded are not considered
+   *natural*. These types of identifiers cannot be used in a ``where`` clause
+   and are generally a bad idea.
+
 DataTypes
 ~~~~~~~~~
 
@@ -2911,9 +2919,9 @@ Google BigQuery (Experimental)
 ------------------------------
 
 The :mod:`pandas.io.gbq` module provides a wrapper for Google's BigQuery
-analytics web service to simplify retrieving results from BigQuery tables 
-using SQL-like queries. Result sets are parsed into a pandas 
-DataFrame with a shape derived from the source table. Additionally, 
+analytics web service to simplify retrieving results from BigQuery tables
+using SQL-like queries. Result sets are parsed into a pandas
+DataFrame with a shape derived from the source table. Additionally,
 DataFrames can be uploaded into BigQuery datasets as tables
 if the source datatypes are compatible with BigQuery ones. The general
 structure of this module and its provided functions are based loosely on those in
@@ -2930,26 +2938,26 @@ into BigQuery and pull it into a DataFrame.
    from pandas.io import gbq
    data_frame = gbq.read_gbq('SELECT * FROM test_dataset.test_table')
 
-The user will then be authenticated by the `bq` command line client - 
+The user will then be authenticated by the `bq` command line client -
 this usually involves the default browser opening to a login page,
 though the process can be done entirely from command line if necessary.
 Datasets and additional parameters can be either configured with `bq`,
 passed in as options to `read_gbq`, or set using Google's gflags (this
 is not officially supported by this module, though care was taken
 to ensure that they should be followed regardless of how you call the
-method). 
+method).
 
 Additionally, you can define which column to use as an index as well as a preferred column order as follows:
 
 .. code-block:: python
 
-   data_frame = gbq.read_gbq('SELECT * FROM test_dataset.test_table', index_col='index_column_name', col_order='[col1, col2, col3,...]') 
+   data_frame = gbq.read_gbq('SELECT * FROM test_dataset.test_table', index_col='index_column_name', col_order='[col1, col2, col3,...]')
 
 Finally, if you would like to create a BigQuery table, `my_dataset.my_table`, from the rows of DataFrame, `df`:
 
 .. code-block:: python
 
-   df = pandas.DataFrame({'string_col_name' : ['hello'], 
+   df = pandas.DataFrame({'string_col_name' : ['hello'],
          'integer_col_name' : [1],
          'boolean_col_name' : [True]})
    schema = ['STRING', 'INTEGER', 'BOOLEAN']
@@ -2959,7 +2967,7 @@ To add more rows to this, simply:
 
 .. code-block:: python
 
-   df2 = pandas.DataFrame({'string_col_name' : ['hello2'], 
+   df2 = pandas.DataFrame({'string_col_name' : ['hello2'],
          'integer_col_name' : [2],
          'boolean_col_name' : [False]})
    data_frame = gbq.to_gbq(df2, 'my_dataset.my_table', if_exists='append')
@@ -2970,7 +2978,7 @@ To add more rows to this, simply:
 
    * There is a hard cap on BigQuery result sets, at 128MB compressed. Also, the BigQuery SQL query language has some oddities,
    see: <https://developers.google.com/bigquery/query-reference>
-   
+
 STATA Format
 ------------