DP-2433: adding exporting documentation

docs/content/en/docs/execution/_index.html

@@ -0,0 +1,7 @@
+---
+title: "Execution"
+linkTitle: "Execution"
+weight: 40
+no_list: true
+navigationLabel: true
+---

docs/content/en/docs/execution/exports/_index.md

@@ -0,0 +1,82 @@
+---
+title: "Dashboard Export"
+linkTitle: "Dashboard Export"
+weight: 23
+no_list: true
+---
+
+Create dashboard exports or automate your pipelines. Can be for [example](#example) be used to report .pdf via e-mail each week.
+
+## Methods
+
+* [export_pdf](./export_pdf/)
+* [export_tabular](./export_tabular/)
+* [export_tabular_by_insight_id](./export_tabular_by_insight_id/)
+
+
+## Example
+
+```python
+from gooddata_sdk import GoodDataSdk
+import schedule
+import smtplib
+from os.path import basename
+from email.mime.application import MIMEApplication
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.utils import COMMASPACE, formatdate
+
+
+# GoodData base URL, e.g. "https://www.example.com"
+host = "https://www.example.com"
+token = "<your_personal_access_token>"
+sdk = GoodDataSdk.create(host, token)
+
+
+def send_mail(send_from, send_to, subject, text, files, server):
+   msg = MIMEMultipart()
+   msg["From"] = send_from
+   msg["To"] = send_to
+   msg["Date"] = formatdate(localtime=True)
+   msg["Subject"] = subject
+
+   msg.attach(MIMEText(text))
+
+   # Open CSV / XLSX file(s) and add it to email attachment
+   for f in files or []:
+       with open(f, "rb") as fil:
+           part = MIMEApplication(
+               fil.read(),
+               Name=basename(f)
+           )
+       part["Content-Disposition"] = "attachment; filename=\"%s\"" % basename(f)
+       msg.attach(part)
+
+   smtp = smtplib.SMTP(server)
+   smtp.sendmail(send_from, send_to, msg.as_string())
+   smtp.close()
+
+
+def export_tabular():
+    # Export a particular insight in the desired format (CSV / XLSX)
+    sdk.export.export_tabular_by_insight_id(
+        workspace_id = "demo",
+        insight_id = "revenue",
+        file_format = "CSV",
+        file_name = "revenue_export.csv"
+    )
+
+    send_mail(
+        send_from = "[email protected]",
+        send_to = "[email protected]",
+        subject = "Scheduled export",
+        text = "Scheduled export of dashboard 'dashboard_overview'",
+        # Name of exported file from the method call 'export_pdf'
+        files = "revenue_export.csv",
+        server = "<your_smtp_server>"
+    )
+
+
+# Schedule call to export visualization in CSV and sent via e-email every morning at 8:00.
+schedule.every().day.at("8:00").do(export_tabular)
+```

docs/content/en/docs/execution/exports/export_pdf.md

@@ -0,0 +1,58 @@
+---
+title: "export_pdf"
+linkTitle: "export_pdf"
+weight: 110
+superheading: "export."
+---
+
+``export_pdf(workspace_id: str,
+        dashboard_id: str,
+        file_name: str,
+        store_path: Union[str, Path] = Path.cwd(),
+        timeout: float = 60.0,
+        retry: float = 0.2,
+        max_retry: float = 5.0,
+    )``
+
+Export a PDF of the specified GoodData Dashboard and save it to the specified file path.
+
+
+{{% parameters-block  title="Parameters" %}}
+{{< parameter p_name="workspace_id" p_type="string" >}}
+The ID of the GoodData Workspace.
+{{< /parameter >}}
+{{< parameter p_name="dashboard_id" p_type="string" >}}
+The ID of the GoodData Dashboard.
+{{< /parameter >}}
+{{< parameter p_name="file_name" p_type="String" >}}
+The name of the PDF file (excluding the file extension).
+{{< /parameter >}}
+{{< parameter p_name="store_path" p_type="Union[String, Path]" >}}
+The name of the PDF file (excluding the file extension).
+{{< /parameter >}}
+{{< parameter p_name="timeout" p_type="float" >}}
+The maximum amount of time (in seconds) to wait for the server to process the export. Defaults to 60.0.
+{{< /parameter >}}
+{{< parameter p_name="retry" p_type="float" >}}
+Initial wait time (in seconds) before retrying to get the exported content. Defaults to 0.2.
+{{< /parameter >}}
+{{< parameter p_name="max_retry" p_type="float" >}}
+The maximum retry wait time (in seconds). Defaults to 5.0.
+{{< /parameter >}}
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="true"%}}
+{{% /parameters-block %}}
+
+
+## Example
+
+```python
+
+host = "https://www.example.com"
+token = "<your_personal_access_token>"
+sdk = GoodDataSdk.create(host, token)
+
+
+sdk.export.export_pdf(workspace_id="demo",  dashboard_id="campaign", file_name="test")
+```

docs/content/en/docs/execution/exports/export_tabular.md

@@ -0,0 +1,79 @@
+---
+title: "export_tabular"
+linkTitle: "export_tabular"
+weight: 110
+superheading: "export."
+---
+
+``export_tabular(workspace_id: str,
+        dashboard_id: str,
+        file_name: str,
+        store_path: Union[str, Path] = Path.cwd(),
+        timeout: float = 60.0,
+        retry: float = 0.2,
+        max_retry: float = 5.0,
+    )``
+
+    Export Tabular (CSV, XLSX) data from the specified GoodData Dashboard report, saved to the specified file path.
+
+
+{{% parameters-block  title="Parameters" %}}
+{{< parameter p_name="workspace_id" p_type="string" >}}
+The ID of the GoodData Workspace.
+{{< /parameter >}}
+{{< parameter p_name="dashboard_id" p_type="string" >}}
+The ID of the GoodData Dashboard.
+{{< /parameter >}}
+{{< parameter p_name="store_path" p_type="Union[String, Path]" >}}
+The path to save the exported tabular data. Defaults to Path.cwd().
+{{< /parameter >}}
+{{< parameter p_name="timeout" p_type="float" >}}
+The maximum amount of time (in seconds) to wait for the server to process the export. Defaults to 60.0.
+{{< /parameter >}}
+{{< parameter p_name="retry" p_type="float" >}}
+Initial wait time (in seconds) before retrying to get the exported content. Defaults to 0.2.
+{{< /parameter >}}
+{{< parameter p_name="max_retry" p_type="float" >}}
+The maximum retry wait time (in seconds). Defaults to 5.0.
+{{< /parameter >}}
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="true"%}}
+{{% /parameters-block %}}
+
+
+## Example
+
+```python
+
+host = "https://www.example.com"
+token = "<your_personal_access_token>"
+sdk = GoodDataSdk.create(host, token)
+
+workspace_id = "demo"
+exec_def = ExecutionDefinition(
+        attributes=[Attribute(local_id="region", label="region"), Attribute(local_id="state", label="state")],
+        metrics=[
+            SimpleMetric(local_id="price", item=ObjId(id="price", type="fact")),
+            SimpleMetric(local_id="order_amount", item=ObjId(id="order_amount", type="metric")),
+        ],
+        filters=[],
+        dimensions=[["state", "region"], ["measureGroup"]],
+    )
+execution_result=sdk.compute.for_exec_def(workspace_id, exec_def).result_id
+export_request = ExportRequest(
+        format="CSV",
+        execution_result=execution_result,
+        file_name="my_file",
+        custom_override=ExportCustomOverride(
+            labels={"region": ExportCustomLabel(title="Custom Title Region")},
+            metrics={
+                "price": ExportCustomMetric(title="Sum Of Price", format=""),
+                "order_amount": ExportCustomMetric(title="Order Amount Metric", format="#,##0.00"),
+            },
+        ),
+    )
+
+
+sdk.export.export_tabular(workspace_id, export_request, _exports_dir)
+```

docs/content/en/docs/execution/exports/export_tabular_by_insight_id.md

@@ -0,0 +1,69 @@
+---
+title: "export_tabular_by_insight_id"
+linkTitle: "export_tabular_by_insight_id"
+weight: 110
+superheading: "export."
+---
+
+``export_tabular_by_insight_id(
+        workspace_id: str,
+        insight_id: str,
+        file_format: str,
+        file_name: Optional[str] = None,
+        settings: Optional[ExportSettings] = None,
+        store_path: Union[str, Path] = Path.cwd(),
+        timeout: float = 60.0,
+        retry: float = 0.2,
+        max_retry: float = 5.0,
+    )``
+
+    Exports the tabular data for an Insight by its ID.
+
+
+
+{{% parameters-block  title="Parameters" %}}
+{{< parameter p_name="workspace_id" p_type="string" >}}
+The ID of the GoodData Workspace.
+{{< /parameter >}}
+{{< parameter p_name="insight_id" p_type="string" >}}
+The ID of the GoodData Insight.
+{{< /parameter >}}
+{{< parameter p_name="file_format" p_type="string" >}}
+The format of the file to be exported.
+{{< /parameter >}}
+{{< parameter p_name="file_name" p_type="String" >}}
+The name which the exported file should have. Defaults to None.
+{{< /parameter >}}
+{{< parameter p_name="settings" p_type="Optional[ExportSettings]" >}}
+Any additional settings for the export. Defaults to None.
+{{< /parameter >}}
+{{< parameter p_name="store_path" p_type="Union[String, Path]" >}}
+The path to store the exported file. Defaults to Path.cwd().
+{{< /parameter >}}
+{{< parameter p_name="timeout" p_type="float" >}}
+The maximum amount of time (in seconds) to wait for the server to process the export. Defaults to 60.0.
+{{< /parameter >}}
+{{< parameter p_name="retry" p_type="float" >}}
+Initial wait time (in seconds) before retrying to get the exported content. Defaults to 0.2.
+{{< /parameter >}}
+{{< parameter p_name="max_retry" p_type="float" >}}
+The maximum retry wait time (in seconds). Defaults to 5.0.
+{{< /parameter >}}
+{{% /parameters-block %}}
+
+{{% parameters-block title="Returns" None="true" %}}
+{{% /parameters-block %}}
+
+
+## Example
+
+```python
+
+host = "https://www.example.com"
+token = "<your_personal_access_token>"
+sdk = GoodDataSdk.create(host, token)
+
+sdk.export.export_tabular_by_insight_id(
+        workspace_id="demo", insight_id="campaign_spend", file_format="CSV")
+
+```

gooddata-sdk/gooddata_sdk/catalog/export/request.py

@@ -52,14 +52,26 @@ def client_class() -> Type[ApiSettings]:
 
 @attr.s(auto_attribs=True, kw_only=True)
 class ExportRequest(Base):
+    """
+    ExportRequest class is used to create an export request in the desired format, filename, and settings.
+    Attributes:
+        format (str): The format of the output file (CSV, XLSX).
+        execution_result (str): Execution result id from backend.
+        file_name (str): The name of the output file.
+        settings (Optional[Dict[str, bool]]): Optional dictionary containing settings for the export request.
+        custom_override (Optional[Dict[str, Any]]): Optional dictionary containing custom settings.
+    """
+
     format: str
-    # execution result id from backend
     execution_result: str
     file_name: str
     settings: Optional[ExportSettings] = None
     custom_override: Optional[ExportCustomOverride] = None
 
     def __attrs_post_init__(self) -> None:
+        """
+        Validates that the provided format is supported and raises ValueError if not.
+        """
         supported_formats = ["CSV", "XLSX"]
         if self.format not in supported_formats:
             raise ValueError(
@@ -68,8 +80,18 @@ def __attrs_post_init__(self) -> None:
 
     @staticmethod
     def client_class() -> Type[TabularExportRequest]:
+        """
+        Returns the appropriate client class for the tabular export request.
+        Returns:
+            Type[TabularExportRequest]: TabularExportRequest class
+        """
         return TabularExportRequest
 
     @property
     def file(self) -> str:
+        """
+        Generates the full filename with the format extension.
+        Returns:
+            str: Full filename with the format extension.
+        """
         return f"{self.file_name}.{self.format.lower()}"