ingestr 0.10.4__tar.gz → 0.12.2__tar.gz

{ingestr-0.10.4 → ingestr-0.12.2}/Makefile

@@ -1,5 +1,5 @@
 .ONESHELL:
-.PHONY: test lint format test-ci lint-ci build upload-release setup
+.PHONY: test lint format test-ci lint-ci build upload-release setup docker-shell
 
 venv: venv/touchfile
 
@@ -43,4 +43,8 @@ upload-release:
 
 setup:
 	@echo "installing git hooks ..."
-	@install -m 755 .githooks/pre-commit-hook.sh .git/hooks/pre-commit
+	@install -m 755 .githooks/pre-commit-hook.sh .git/hooks/pre-commit
+
+docker-shell:
+	# run a docker container to build and run ingestr
+	@docker run -v $(PWD):/root/code -w /root/code -it --rm --entrypoint /bin/bash python:3.11

{ingestr-0.10.4 → ingestr-0.12.2}/PKG-INFO

@@ -1,10 +1,11 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: ingestr
-Version: 0.10.4
+Version: 0.12.2
 Summary: ingestr is a command-line application that ingests data from various sources and stores them in any database.
 Project-URL: Homepage, https://github.com/bruin-data/ingestr
 Project-URL: Issues, https://github.com/bruin-data/ingestr/issues
 Author-email: Burak Karakan <burak.karakan@getbruin.com>
+License-File: LICENSE.md
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -13,6 +14,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Database
 Requires-Python: >=3.9
+Requires-Dist: asana==3.2.3
 Requires-Dist: confluent-kafka>=2.6.1
 Requires-Dist: databricks-sql-connector==2.9.3
 Requires-Dist: dlt==1.4.0
@@ -199,7 +201,7 @@ Pull requests are welcome. However, please open an issue first to discuss what y
     <tr>
         <td colspan="3" style='text-align:center;'><strong>Platforms</strong></td>
     </tr>
-    <td>Adjust</td>
+        <td>Adjust</td>
         <td>✅</td>
         <td>-</td>
     <tr>
@@ -207,17 +209,27 @@ Pull requests are welcome. However, please open an issue first to discuss what y
         <td>✅</td>
         <td>-</td>
     </tr>
-     <tr>
+    <tr>
         <td>AppsFlyer</td>
         <td>✅</td>
         <td>-</td>
     </tr>
+    <tr>
+        <td>Asana</td>
+        <td>✅</td>
+        <td>-</td>
+    </tr>
     <tr>
         <td>Chess.com</td>
         <td>✅</td>
         <td>-</td>
     </tr>
-     <tr>
+    <tr>
+        <td>DynamoDB</td>
+        <td>✅</td>
+        <td>-</td>
+    </tr>
+    <tr>
         <td>Facebook Ads</td>
         <td>✅</td>
         <td>-</td>

{ingestr-0.10.4 → ingestr-0.12.2}/README.md

@@ -146,7 +146,7 @@ Pull requests are welcome. However, please open an issue first to discuss what y
     <tr>
         <td colspan="3" style='text-align:center;'><strong>Platforms</strong></td>
     </tr>
-    <td>Adjust</td>
+        <td>Adjust</td>
         <td>✅</td>
         <td>-</td>
     <tr>
@@ -154,17 +154,27 @@ Pull requests are welcome. However, please open an issue first to discuss what y
         <td>✅</td>
         <td>-</td>
     </tr>
-     <tr>
+    <tr>
         <td>AppsFlyer</td>
         <td>✅</td>
         <td>-</td>
     </tr>
+    <tr>
+        <td>Asana</td>
+        <td>✅</td>
+        <td>-</td>
+    </tr>
     <tr>
         <td>Chess.com</td>
         <td>✅</td>
         <td>-</td>
     </tr>
-     <tr>
+    <tr>
+        <td>DynamoDB</td>
+        <td>✅</td>
+        <td>-</td>
+    </tr>
+    <tr>
         <td>Facebook Ads</td>
         <td>✅</td>
         <td>-</td>

{ingestr-0.10.4 → ingestr-0.12.2}/docs/.vitepress/config.mjs

@@ -88,7 +88,9 @@ export default defineConfig({
               { text: "Adjust", link: "/supported-sources/adjust.md" },
               { text: "Airtable", link: "/supported-sources/airtable.md" },
               { text: "AppsFlyer", link: "/supported-sources/appsflyer.md" },
+              { text: "Asana", link: "/supported-sources/asana.md" },
               { text: "Chess.com", link: "/supported-sources/chess.md" },
+              { text: "DynamoDB", link: "/supported-sources/dynamodb.md" },
               {
                 text: "Facebook Ads",
                 link: "/supported-sources/facebook-ads.md",

ingestr-0.12.2/docs/supported-sources/asana.md

@@ -0,0 +1,58 @@
+# Asana
+[Asana](https://asana.com/) is a software-as-a-service platform designed for team collaboration and work management. Teams can create projects, assign tasks, set deadlines, and communicate directly within Asana. It also includes reporting tools, file attachments, calendars, and goal tracking.
+
+## URI format
+
+The URI format for Asana is as follows:
+```
+asana://<workspace_id>?access_token=<access_token>
+```
+
+URI parameters:
+- `workspace_id` is the `gid` of the workspace. 
+- `access_token` is a personal access token.
+
+You can obtain `workspace_id` by going to the [admin console](https://help.asana.com/s/article/how-to-access-the-admin-console). The URL in your browser will look something like this:
+
+```
+https://app.asana.com/admin/fake-123456789/
+```
+
+In this example `fake-123456789` is your workspace id.
+
+## Setting up an Asana Integration
+
+You can obtain a personal access token from the [developer console](https://app.asana.com/0/my-apps). For more information, see [Asana developers documentation](https://developers.asana.com/docs/personal-access-token).
+
+## Example
+Let's say you have a workspace with id `workspace-1337` and you want to ingest all tasks into a duckdb database called `work.db`. For this example the value of `access_token` will be `fake_token`
+
+You can run the following to achieve this:
+```sh
+ingestr ingest \
+  --source-uri "asana://workspace-1337?access_token=fake_token" \
+  --source-table "tasks" \
+  --dest-uri "duckdb://./work.db" \
+  --dest-table "public.tasks"
+```
+
+
+## Tables
+
+Asana source allows ingesting the following sources into separate tables:
+
+| **Table**    | **Description**                                                                 |
+|---------------|---------------------------------------------------------------------------------|
+| `workspaces`  | Information about people, materials, or assets required to complete a task or project successfully. |
+| `projects`    | Collections of tasks and related information.                                   |
+| `tasks`    | Tasks within a project. Only tasks that belong to a project can be ingested. Users private tasks are not ingested, for example.      |
+| `projects`    | Collections of tasks and related information.                                   |
+| `tags`        | Labels that can be attached to tasks, projects, or conversations to help categorize and organize them. |
+| `stories`     | Updates or comments that team members can add to a task or project.             |
+| `teams`       | Groups of individuals who work together to complete projects and tasks.         |
+| `users`       | Individuals who have access to the Asana platform.                              |
+
+Use these as `--source-table` parameter in the `ingestr ingest` command.
+
+> [!WARNING]
+> Asana does not support incremental loading for many endpoints in its APIs, which means ingestr will load endpoints incrementally if they support it, and do a full-refresh if not.

ingestr-0.12.2/docs/supported-sources/dynamodb.md

@@ -0,0 +1,90 @@
+# DynamoDB
+
+Amazon [DynamoDB](https://aws.amazon.com/dynamodb/) is a managed NoSQL database service provided by Amazon Web Services (AWS). It supports key-value and document data structures and is designed to handle a wide range of applications requiring scalability and performance. 
+
+## URI format
+
+The URI format for DynamoDB is as follows:
+```plaintext
+dynamodb://dynamodb.<region>.amazonaws.com?access_key_id=<aws_access_key_id>&secret_access_key=<aws_secret_access_key>
+```
+
+URI parameters:
+
+- `access_key_id`: Identifes an IAM account. 
+- `secret_access_key`: Password for the IAM account.
+
+
+## Setting up a DynamoDB integration
+
+### Prerequisites
+* AWS IAM access key pair.
+* A DynamoDB Table that you will to load data from
+
+To obtain the access keys, use the IAM console on AWS. See [IAM Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) for more information.
+
+
+### Configuring Permissions
+To use DynamoDB source, the user account must have the following IAM permissions:
+* `dynamodb:DescribeTable`
+* `dynamodb:Scan`
+
+Following AWS Best practices, you can create an IAM policy that you can assign to the user account you wish to use with `ingestr`.
+Below is a sample policy:
+```json
+{
+	"Version": "2012-10-17",
+	"Statement": [
+		{
+			"Sid": "Statement1",
+			"Effect": "Allow",
+			"Action": [
+				"dynamodb:DescribeTable",
+				"dynamodb:Scan"
+			],
+			"Resource": [
+				"<TABLE_ARN>"
+			]
+		}
+	]
+}
+```
+
+Replace `TABLE_ARN` with the DynamoDB [Amazon Resource Name](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) of your Table. You can find the ARN for your table in the [DynamoDB console](https://console.aws.amazon.com/dynamodb/home). You can add as many tables you want in the `Resource` field. Alternatively, if you'd like to give access to all tables that you own, you can set `Resource` to `["*"]`.
+
+### Example: Simple load
+
+For this example, we'll assume the value of `access_key_id` and `secret_access_key` are `user` and `pass` respectively.
+
+Say you have a table called `absolute-armadillo` in the region `ap-south-1` and you want to load this data to a duckdb database called `animal.db`.
+
+You run the following to achieve this:
+```sh
+ingestr ingest \
+    --source-uri "dynamodb://dynamodb.ap-south-1.amazonaws.com?access_key_id=user&secret_access_key=pass" \
+    --source-table "absolute-armadillo" \
+    --dest-uri "duckdb://./animal.db" \
+    --dest-table "public.armadillo"
+```
+
+### Example: Incremental load
+`ingestr` supports incremental loading. Incremental loading is a technique whereby only rows or fields that are changed are fetched. This reduces load times of subsequent runs and improves efficiency of your pipelines.
+
+Assuming the same setup from [Simple Load](#example-simple-load), we can run incremental load with:
+```sh
+ingestr ingest \
+    --source-uri "dynamodb://dynamodb.ap-south-1.amazonaws.com?access_key_id=user&secret_access_key=pass" \
+    --source-table "absolute-armadillo" \
+    --dest-uri "duckdb://./animal.db" \
+    --dest-table "public.armadillo" \
+    --incremental-strategy "replace" \
+    --incremental-key "updated_at"
+```
+
+Assuming that `absolute-armadillo` table has a datetime field called `updated_at`, whenever you run this command, only rows with value greater than `MAX(updated_at)` from previous load will be fetched from DynamoDB.
+
+> [!WARNING]
+> DynamoDB doesn't support indexed range scans.
+> Whenever you run `ingestr ingest`, the whole table is scanned.
+> Although `ingestr` does specify a filter critiera, DynamoDB only applies
+> this _after_ running the table scan.

ingestr-0.12.2/ingestr/src/asana_source/__init__.py

@@ -0,0 +1,264 @@
+"""
+This source provides data extraction from the Asana platform via their API.
+
+It defines several functions to fetch data from different parts of Asana including
+workspaces, projects, sections, tags, tasks, stories, teams, and users. These
+functions are meant to be used as part of a data loading pipeline.
+"""
+
+import typing as t
+from typing import Any, Iterable
+
+import dlt
+from dlt.common.typing import TDataItem
+
+from .helpers import get_client
+from .settings import (
+    DEFAULT_START_DATE,
+    PROJECT_FIELDS,
+    REQUEST_TIMEOUT,
+    SECTION_FIELDS,
+    STORY_FIELDS,
+    TAG_FIELDS,
+    TASK_FIELDS,
+    TEAMS_FIELD,
+    USER_FIELDS,
+    WORKSPACE_FIELDS,
+)
+
+
+@dlt.source
+def asana_source() -> Any:  # should be Sequence[DltResource]:
+    """
+    The main function that runs all the other functions to fetch data from Asana.
+    Returns:
+        Sequence[DltResource]: A sequence of DltResource objects containing the fetched data.
+    """
+    return [
+        workspaces,
+        projects,
+        sections,
+        tags,
+        tasks,
+        stories,
+        teams,
+        users,
+    ]
+
+
+@dlt.resource(write_disposition="replace")
+def workspaces(
+    access_token: str = dlt.secrets.value, fields: Iterable[str] = WORKSPACE_FIELDS
+) -> Iterable[TDataItem]:
+    """
+    Fetches and returns a list of workspaces from Asana.
+    Args:
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Yields:
+        dict: The workspace data.
+    """
+    yield from get_client(access_token).workspaces.find_all(opt_fields=",".join(fields))
+
+
+@dlt.transformer(
+    data_from=workspaces,
+    write_disposition="replace",
+)
+@dlt.defer
+def projects(
+    workspace: TDataItem,
+    access_token: str = dlt.secrets.value,
+    fields: Iterable[str] = PROJECT_FIELDS,
+) -> Iterable[TDataItem]:
+    """
+    Fetches and returns a list of projects for a given workspace from Asana.
+    Args:
+        workspace (dict): The workspace data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Returns:
+        list[dict]: The project data for the given workspace.
+    """
+    return list(
+        get_client(access_token).projects.find_all(
+            workspace=workspace["gid"],
+            timeout=REQUEST_TIMEOUT,
+            opt_fields=",".join(fields),
+        )
+    )
+
+
+@dlt.transformer(
+    data_from=projects,
+    write_disposition="replace",
+)
+@dlt.defer
+def sections(
+    project_array: t.List[TDataItem],
+    access_token: str = dlt.secrets.value,
+    fields: Iterable[str] = SECTION_FIELDS,
+) -> Iterable[TDataItem]:
+    """
+    Fetches all sections for a given project from Asana.
+    Args:
+        project_array (list): The project data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Returns:
+        list[dict]: The sections data for the given project.
+    """
+    return [
+        section
+        for project in project_array
+        for section in get_client(access_token).sections.get_sections_for_project(
+            project_gid=project["gid"],
+            timeout=REQUEST_TIMEOUT,
+            opt_fields=",".join(fields),
+        )
+    ]
+
+
+@dlt.transformer(data_from=workspaces, write_disposition="replace")
+@dlt.defer
+def tags(
+    workspace: TDataItem,
+    access_token: str = dlt.secrets.value,
+    fields: Iterable[str] = TAG_FIELDS,
+) -> Iterable[TDataItem]:
+    """
+    Fetches all tags for a given workspace from Asana.
+    Args:
+        workspace (dict): The workspace data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Returns:
+        list[dict]: The tags data for the given workspace.
+    """
+    return [
+        tag
+        for tag in get_client(access_token).tags.find_all(
+            workspace=workspace["gid"],
+            timeout=REQUEST_TIMEOUT,
+            opt_fields=",".join(fields),
+        )
+    ]
+
+
+@dlt.transformer(data_from=projects, write_disposition="merge", primary_key="gid")
+def tasks(
+    project_array: t.List[TDataItem],
+    access_token: str = dlt.secrets.value,
+    modified_at: dlt.sources.incremental[str] = dlt.sources.incremental(
+        "modified_at", initial_value=DEFAULT_START_DATE
+    ),
+    fields: Iterable[str] = TASK_FIELDS,
+) -> Iterable[TDataItem]:
+    """
+    Fetches all tasks for a given project from Asana.
+    Args:
+        project_array (list): The project data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+
+        modified_at (str): The date from which to fetch modified tasks.
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Yields:
+        dict: The task data for the given project.
+    """
+    yield from (
+        task
+        for project in project_array
+        for task in get_client(access_token).tasks.find_all(
+            project=project["gid"],
+            timeout=REQUEST_TIMEOUT,
+            modified_since=modified_at.start_value,
+            opt_fields=",".join(fields),
+        )
+    )
+
+
+@dlt.transformer(
+    data_from=tasks,
+    write_disposition="append",
+)
+@dlt.defer
+def stories(
+    task: TDataItem,
+    access_token: str = dlt.secrets.value,
+    fields: Iterable[str] = STORY_FIELDS,
+) -> Iterable[TDataItem]:
+    """
+    Fetches stories for a task from Asana.
+    Args:
+        task (dict): The task data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Returns:
+        list[dict]: The stories data for the given task.
+    """
+    return [
+        story
+        for story in get_client(access_token).stories.get_stories_for_task(
+            task_gid=task["gid"],
+            timeout=REQUEST_TIMEOUT,
+            opt_fields=",".join(fields),
+        )
+    ]
+
+
+@dlt.transformer(
+    data_from=workspaces,
+    write_disposition="replace",
+)
+@dlt.defer
+def teams(
+    workspace: TDataItem,
+    access_token: str = dlt.secrets.value,
+    fields: Iterable[str] = TEAMS_FIELD,
+) -> Iterable[TDataItem]:
+    """
+    Fetches all teams for a given workspace from Asana.
+    Args:
+        workspace (dict): The workspace data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Returns:
+        list[dict]: The teams data for the given workspace.
+    """
+    return [
+        team
+        for team in get_client(access_token).teams.find_by_organization(
+            organization=workspace["gid"],
+            timeout=REQUEST_TIMEOUT,
+            opt_fields=",".join(fields),
+        )
+    ]
+
+
+@dlt.transformer(
+    data_from=workspaces,
+    write_disposition="replace",
+)
+@dlt.defer
+def users(
+    workspace: TDataItem,
+    access_token: str = dlt.secrets.value,
+    fields: Iterable[str] = USER_FIELDS,
+) -> Iterable[TDataItem]:
+    """
+    Fetches all users for a given workspace from Asana.
+    Args:
+        workspace (dict): The workspace data.
+        access_token (str): The access token to authenticate the Asana API client, provided in the secrets file
+        fields (Iterable[str]): The list of workspace fields to be retrieved from Asana API.
+    Returns:
+        list[dict]: The user data for the given workspace.
+    """
+    return [
+        user
+        for user in get_client(access_token).users.find_all(
+            workspace=workspace["gid"],
+            timeout=REQUEST_TIMEOUT,
+            opt_fields=",".join(fields),
+        )
+    ]

ingestr-0.12.2/ingestr/src/asana_source/helpers.py

@@ -0,0 +1,16 @@
+"""Asana source helpers"""
+
+from asana import Client as AsanaClient
+
+
+def get_client(
+    access_token: str,
+) -> AsanaClient:
+    """
+    Returns an Asana API client.
+    Args:
+        access_token (str): The access token to authenticate the Asana API client.
+    Returns:
+        AsanaClient: The Asana API client.
+    """
+    return AsanaClient.access_token(access_token)