From be85ca941896ec30310808d5337d551b5a84afc4 Mon Sep 17 00:00:00 2001 From: Vitor Honna Date: Tue, 13 May 2025 20:11:23 -0300 Subject: [PATCH] style: improve clarity on api-ref.md Minor changes to formatting and style to improve clarity --- docs/docs/api-ref.md | 118 +++++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 49 deletions(-) diff --git a/docs/docs/api-ref.md b/docs/docs/api-ref.md index 365634a..d1d99fd 100644 --- a/docs/docs/api-ref.md +++ b/docs/docs/api-ref.md @@ -8,39 +8,38 @@ layout: docs ## Workbooks ```python -class Workbook(filename): +class Workbook(filename) ``` The Workbook class represents a tableau workbook. It may be either a TWB or TWBX, and the library will handle packaging and unpackaging automatically. **Params:** -`filename` takes a string representing the path to the workbook file. +- `filename`: A string representing the path to the workbook file. **Raises:** -`TableauVersionNotSupportedException` if the workbook is not a supported version. -`TableauInvalidFileException` if the file is not a valid tableau workbook file. +- `TableauVersionNotSupportedException`: If the workbook is not a supported version. + +- `TableauInvalidFileException`: If the file is not a valid Tableau workbook file. **Methods:** -`Workbook.save(self):` -Saves any changes to the workbook to the existing file. +- `Workbook.save(self)`: Saves any changes to the workbook to the existing file. -`Workbook.save_as(self, new_filename):` -Saves any changes to the workbook to a new file specified by the `new_file` parameter. +- `Workbook.save_as(self, new_filename)`: Saves any changes to the workbook to a new file specified by the `new_file` parameter. **Properties:** -`self.worksheets:` Returns a list of worksheets found in the workbook. +- `self.worksheets`: Returns a list of worksheets found in the workbook. -`self.datasources:` Returns a list of Datasource objects found in the workbook. +- `self.datasources`: Returns a list of datasource objects found in the workbook. -`self.filename:` Returns the filename of the workbook. +- `self.filename`: Returns the filename of the workbook. -`self.shapes` Returns a list of strings with the names of shapes found in the workbook. +- `self.shapes`: Returns a list of strings with the names of shapes found in the workbook. -`self.dashboards:` Returns a list of strings with the names of the dashboards found in the workbook +- `self.dashboards`: Returns a list of strings with the names of the dashboards found in the workbook. ## Datasources ```python @@ -50,33 +49,39 @@ A class representing Tableau Data Sources, embedded in workbook files or in TDS **Params:** +- `dsxml` + +- `filename`: A string representing the path to the workbook file (default `None`). + **Raises:** +- + **Methods:** -`Datasource.save(self)` Saves any changes to the datasource to the existing file. +- `Datasource.save(self)`: Saves any changes to the datasource to the existing file. -`Datasource.save_as(self)` Saves any changes to the datasource to a new file specified by the `new_file` parameter. +- `Datasource.save_as(self)`: Saves any changes to the datasource to a new file specified by the `new_file` parameter. -`Datasource.add_field(self, name, datatype, role, field_type, caption)` Adds a base field object with the given values. +- `Datasource.add_field(self, name, datatype, role, field_type, caption)`: Adds a base field object with the given values. -`Datasource.remove_field(self, field)` Remove a given field. +- `Datasource.remove_field(self, field)`: Removes a given field. -`Datasource.add_calculation(self, caption, formula, datatype, role, type)` Adds a calculated field with the given values. +- `Datasource.add_calculation(self, caption, formula, datatype, role, type)`: Adds a calculated field with the given values. **Properties:** -`self.name` Returns string with the name of datasource. +- `self.name`: Returns string with the name of datasource. -`self.version` Returns string of datasource's version. +- `self.version`: Returns string of datasource's version. -`self.caption` Returns string of user defined name of datasource if exists. +- `self.caption`: Returns string of user defined name of datasource if exists. -`self.connections` Returns list of connections used in workbook. +- `self.connections`: Returns list of connections used in workbook. -`self.fields` Returns key-value result of field name and their attributes. +- `self.fields`: Returns key-value result of field name and their attributes. -`self.calculations` Returns calculated field of the workbook. +- `self.calculations`: Returns calculated field of the workbook. ## Connections ```python @@ -87,25 +92,31 @@ The Connection class represents a tableau data connection. It can be from any ty **Params:** +- `connxml` + **Raises:** +- + **Methods:** +- + **Properties:** -`self.server:` Returns a string containing the server. +- `self.server`: Returns a string containing the server. -`self.dbname:` Returns a string containing the database name. +- `self.dbname`: Returns a string containing the database name. -`self.username:` Returns a string containing the username. +- `self.username`: Returns a string containing the username. -`self.dbclass:` Returns a string containing the database class. +- `self.dbclass`: Returns a string containing the database class. -`self.port:` Returns a string containing the port. +- `self.port`: Returns a string containing the port. -`self.query_band:` Returns a string containing the query band. +- `self.query_band`: Returns a string containing the query band. -`self.initial_sql:` Returns a string containing the initial sql. +- `self.initial_sql`: Returns a string containing the initial sql. ## Fields ```python @@ -114,43 +125,52 @@ class Field(column_xml=None, metadata_xml=None) Represents a field in a datasource +**Params:** + +- `column_xml` + +- `metadata_xml` + **Raises:** +- + **Methods:** -`Field.create_field_xml()` Create field from scratch. -`Field.add_alias(self, key, value)` Add an alias for a given display value. +- `Field.create_field_xml()`: Creates a field from scratch. + +- `Field.add_alias(self, key, value)`: Adds an alias for a given display value. **Properties:** -`self.name` Returns a string providing a nice name for the field which is derived from the alias, caption, or the id. +- `self.name`: Returns a string providing a nice name for the field which is derived from the alias, caption, or the id. -`self.id` Returns a string with name of the field as specified in the file, usually surrounded by [ ]. +- `self.id`: Returns a string with name of the field as specified in the file, usually surrounded by [ ]. -`self.xml` Returns a ElementTree object which represents an XML of the field. +- `self.xml`: Returns a ElementTree object which represents an XML of the field. -`self.caption` Returns a string with the name of the field as displayed in Tableau unless an aliases is defined. +- `self.caption`: Returns a string with the name of the field as displayed in Tableau unless an aliases is defined. -`self.alias` Returns a string with the name of the field as displayed in Tableau if the default name isn't wanted. +- `self.alias`: Returns a string with the name of the field as displayed in Tableau if the default name isn't wanted. -`self.datatype` Returns a string with the type of the field within Tableau (string, integer, etc). +- `self.datatype`: Returns a string with the type of the field within Tableau (string, integer, etc). -`self.role` Returns a string which identify field as a Dimension or Measure. +- `self.role`: Returns a string which identify field as a Dimension or Measure. -`self.type` Returns a string with type of field (quantitative, ordinal, nominal). +- `self.type`: Returns a string with type of field (quantitative, ordinal, nominal). -`self.aliases` Returns Key-value mappings of all aliases that are registered under this field. +- `self.aliases`: Returns Key-value mappings of all aliases that are registered under this field. -`self.is_quantitative` Returns a boolean if field is quantitative. +- `self.is_quantitative`: Returns a boolean if field is quantitative. -`self.is_ordinal` Returns a boolean if field is categorical that has a specific order. +- `self.is_ordinal`: Returns a boolean if field is categorical that has a specific order. -`self.is_nominal` Returns a boolean if field is categorical that does not have a specific order. +- `self.is_nominal`: Returns a boolean if field is categorical that does not have a specific order. -`self.calculation` Returns a string with the formula if this field is a calculated field. +- `self.calculation`: Returns a string with the formula if this field is a calculated field. -`self.default_aggregation` Returns a string with he default type of aggregation on the field (e.g Sum, Avg). +- `self.default_aggregation`: Returns a string with he default type of aggregation on the field (e.g Sum, Avg). -`self.description` Returns a string with contents of the tag on a field. +- `self.description`: Returns a string with contents of the tag on a field. -`self.worksheets` Returns a list of strings with the worksheet's names uses this field. +- `self.worksheets`: Returns a list of strings with the worksheet's names uses this field.