Updating readme to reflect updates to tableau_documents

README.md

@@ -1289,64 +1289,86 @@ Ex.
                                      username_or_luid: str, wb_name_or_luid: Optional[str] = None)
 
 ## 2 tableau_documents: Modifying Tableau Documents (for Template Publishing)
-tableau_documents implements some features that go beyond the Tableau REST API, but are extremely useful when dealing with a large number of workbooks or datasources, particularly for multi-tenented Sites. These methods actually allow unsupported changes to the Tableau workbook or datasource XML. If something breaks with them, blame the author of the library and not Tableau Support, who won't help you with them.
+tableau_documents implements some features that go beyond the Tableau REST API, but are extremely useful when dealing with a large number of workbooks or datasources, particularly for multi-tenented Sites. It also provides a mechanism for utilizing newly updated Hyper files generated by Extract API or Hyper API to update existing TWBX and TDSX files. These methods actually allow unsupported changes to the Tableau workbook or datasource XML. If something breaks with them, blame the author of the library and not Tableau Support, who won't help you with them.
 
-### 2.1 Document classes
-The tableau_documents library is a hierarchical set of classes which model Tablea's files and the data structures within them. The model looks slightly different whether a workbook or a datasource, because workbooks can embed multiple datasources:
+### 2.0 Getting Started with tableau_documents: TableauFileOpener class
+tableau_documents is a sub-package of the main tableau_tools library. It is only imported if you need it, using:
+
+    from tableau_tools.tableau_documents import *
+
+The class you will use to handle existing classes is TableauFileOpener. This is a class full of static methods for detecting if something is a Tableau file and opening it as the correct object type, among other features. Use the `.open(filename)` method to get back one of the objects that represents a Tableau file. If you know the file type, you can annotate the variable for code completion. If not, don't worry, there ways to handle all files without knowing ahead of time:
+
+    from tableau_tools.tableau_documents import *
+    t_file: TDS = TableauFileManager.open(filename='Live PostgreSQL Connection.tds')
+    if isinstance(t_file, DatasourceFileInterface):
+       
+
+### 2.1 tableau_documents basic model
+In 5.0+, tableau_documents has been updated considerably with a more consistent model than in the past. There is a hierarchy of the objects, which reflects a model of "Tableau XML File on Disk" -> "Object that manipulates the XML, built from File". For Tableau's packaged file types (the ones that end in X), there is an additional layer, which is the ZIP file that contains the XML File.  
 
 Datasource:
 
-* TableauFile
-    * TableauDatasource (TableauDocument)
+* TDS (TableauXmlFile, DatasourceFileInterface)
+    * TableauDatasource
         * [TableauConnection]
         * TableauColumns
-
-Workbook:
 
-* TableauFile
-    * TableauWorkbook (TableauDocument)
-        * [TableauDatasource]
+* TDSX (TableauPackagedFile, DatasourceFileInterface)
+    * TDS (TableauXmlFile, DatasourceFileInterface)
+        * TableauDatasource
             * [TableauConnection]
             * TableauColumns
 
+Workbooks:
 
-### 2.2 TableauFile Class
-The TableauFile class represents an actual existing Tableau file on the local storage (.tds, .tdsx, .twb, .twbx). It is initialized with:
-
-`TableauFile(filename, logger_obj=None, create_new=False, ds_version='10')`
+* TWB (TableauXmlFile, DatasourceFileInterface)
+    * TableauWorkbook
+        * [TableauDatasource]
+            * [TableauConnection]
+            * TableauColumns
 
-TableauFile determines what type of file has been opened, and if it is a packaged workbook or datasource, it extracts the embedded TWB or TDS file temporarily to disk so that it can be accessed as a file. All of this is done to disk so that everything is not loaded and kept in memory.      
+* TWBX (TableauPackagedFile, DatasourceFileInterface)
+    * TWB (TableauXmlFile, DatasourceFileInterface)
+        * TableauWorkbook
+            * [TableauDatasource]
+                * [TableauConnection]
+                * TableauColumns
 
-TableauFile.file_type property  returns one of `['twb', 'twbx, 'tds', 'tdsx']`, which allows you to determine a particular set of actions to take depending on the file type. 
+Flows:
+ (not available and tested yet)    
 
-`TableauFile.tableau_document` property retrieves the `TableauDocument` object within. This will actually be either a `TableauWorkbook` or `TableauDatasource` object, which is why the file_type is useful. 
+You'll note in parentheses that some of these classes do descend from the same abastract parent classes. This means they have the same methods available, despite being different classes. In particular, DatasourceFileInterface allows you to access the datasource objects stored within any of the object types without worrying about the hierarchy of the individual object. We'll explore the effects of this in one of the next sections.
 
-TableauFile also allows you to create a new datasource from scratch. To implement, initialize without a file name like:
+### 2.2 TableauXmlFile Classes (TDS, TWB, TFL)
+The TableauXmlFile class represents one single existing Tableau file on disk (.tds, .twb, .tfl ). Use `TableauFileOpener.open()` to return the correct object for the type of file you are opening. The main function of the TableauXmlFile objects is to handle reading from and writing to disk correctly.
 
-    tf = TableauFile(None, logger_obj, create_new=True, ds_version='10') # ds_version='9' for a 9.0 style datasource
+There is a `tableau_document` property to any TableauXmlFile object which gives access to the TableauWorkbook, TableauDatasource, or TableauFlow object inside. Other than the `TableauParameters` object of a TableauWorkbook (allowing you to set or changed Parameter definitions), you will most likely use the `.datasources` property rather than traversing the full object tree (since this has different depth depending on the object type).
+
 
-The `TableauFile.tableau_document` object will be a new `TableauDatasource` object, ready to be set built up.
+You can save a new file (including any changes you would have made to the underlying tableau_document objects) using 
 
-`TableauFile` allows you to save to a new file based on any modifications made in the documents contained within using:
+    TableauXmlFile.save_new_file(filename_no_extension: str, save_to_directory: Optional[str] = None)
 
-    TableauFile.save_new_file(new_filename_no_extension)  # returns new filename
 
-It automatically appends the correct extension based on whether the documents have extracts attached.
+It automatically appends the correct extension, so you don't need to include when giving the save name.
 
 If a file is found on disk with the same name, a number will be appended to the end.
 
 ex.
 
-    tf = TableauFile('A Workbook.twb')
+    tf = TableauFileOpener('A Workbook.twb')
     file_1 = tf.save_new_file('A Workbook')
     file_2 = tf.save_new_file('A Workbook')
     print(file_1)
     # 'A Workbook (1).twb'
     print(file_2)
     # 'A Workbook (2).twb'
 
-#### 2.2.1 Replacing Static Data Files
-`TableauFile` has an optional argument on the save_new_file method to allow swapping in new data files (CSV, XLS or Hyper) into an existing TWBX or TDSX. 
+### 2.3 TableauPackagedFile Classes (TDSX, TWBX, TFLX)
+When publishing to the REST API, the most common file type is actually a Tableau Packaged file, which is really just a ZIP file with a particular structure and a different file ending. 
+
+#### 2.3.1 Replacing Static Data Files
+`TableauPackagedFile` has an optional argument on the save_new_file method to allow swapping in new data files (CSV, XLS or Hyper) into an existing TWBX or TDSX. 
 
     TableauFile.save_new_file(new_filename_no_extension, data_file_replacement_map=None)  # returns new filename