abstra 3.23.7__py3-none-any.whl → 3.23.9__py3-none-any.whl

abstra_internals/consts/filepaths.py

@@ -11,5 +11,5 @@ CREDENTIALS_FILEPATH = f"{DOT_ABSTRA_DIR}/credentials"
 TEST_DATA_FILEPATH = f"{DOT_ABSTRA_DIR}/test_data.json"
 
 GIT_DIR_PATH = ".git"
-ABSTRA_IGNORE_FILEPATH = ".abstraignore"
+ABSTRA_IGNORE_FILEPATH = ".gitignore"
 ABSTRA_TABLES_FILEPATH = "abstra-tables.json"

abstra_internals/controllers/codebase.py

@@ -20,7 +20,7 @@ from abstra_internals.contracts_generated import (
 )
 from abstra_internals.repositories.factory import Repositories
 from abstra_internals.services.file_watcher import crdt_managers
-from abstra_internals.services.fs import SKIPPED_DIRNAMES, FileSystemService
+from abstra_internals.services.fs import FileSystemService
 from abstra_internals.utils.crdt import CRDTManager
 
 
@@ -28,29 +28,20 @@ class CodebaseController:
     def __init__(self, repos: Repositories):
         self.repos = repos
 
-    def file_node(self, child_path: Path, base_path: Path) -> CommonFileNode:
-        is_dir = child_path.is_dir()
-        stats = child_path.stat()
-
-        grand_children = []
-        if is_dir:
-            grand_children = [
-                list(c.relative_to(base_path).parts)
-                for c in child_path.iterdir()
-                if c.name not in SKIPPED_DIRNAMES
-            ]
+    def file_node(self, path: Path) -> CommonFileNode:
+        is_dir = path.is_dir()
+        stats = path.stat()
 
         return CommonFileNode(
-            path_parts=list(child_path.relative_to(base_path).parts),
+            path_parts=list(path.parts),
             size=stats.st_size,
             last_modified=datetime.fromtimestamp(stats.st_mtime),
             type="directory" if is_dir else "file",
-            children=grand_children,
         )
 
     def list_files(self, path) -> AbstraLibApiEditorFilesListResponse:
         if path is None:
-            path = Path.cwd()
+            path = Path()
         elif isinstance(path, str):
             path = Path(path)
         elif not isinstance(path, Path):
@@ -60,17 +51,17 @@ class CodebaseController:
 
         return [
             AbstraLibApiEditorFilesListResponseItem(
-                file=self.file_node(child_path, path),
+                file=self.file_node(child_path),
                 stages=[
                     AbstraLibApiEditorFilesListResponseItemStagesItem(
                         id=stage.id,
-                        type=stage.type_name,  # type: ignore
+                        type=stage.type_name,
                     )
                     for stage in project.get_stages_by_file_path(child_path)
                 ],
             )
             for child_path in FileSystemService.list_files(
-                path, include_dirs=True, use_ignore=False
+                path, include_dirs=True, use_ignore=False, recursive=False
             )
         ]
 

abstra_internals/controllers/codebase_events.py

@@ -6,13 +6,12 @@ from typing import List, Optional
 import flask_sock
 from dotenv import load_dotenv
 
-from abstra_internals.contracts_generated import (
-    AbstraLibApiEditorCodebaseEventsMessage,
-)
+from abstra_internals.contracts_generated import AbstraLibApiEditorCodebaseEventsMessage
 from abstra_internals.logger import AbstraLogger
 from abstra_internals.modules import reload_module
 from abstra_internals.repositories.factory import Repositories
 from abstra_internals.services.file_watcher import FSEventType
+from abstra_internals.settings import Settings
 
 
 class CodebaseEventController:
@@ -37,8 +36,11 @@ class CodebaseEventController:
     def broadcast_changes(
         cls, filepath: Path, event: FSEventType, content: Optional[str]
     ):
+        absolute_root_path = Settings.root_path.resolve()
         message = AbstraLibApiEditorCodebaseEventsMessage(
-            filepath=str(filepath), event=event, content=content
+            filepath=str(filepath.relative_to(absolute_root_path)),
+            event=event,
+            content=content,
         )
         for listener in cls.listeners:
             try:

abstra_internals/controllers/main.py

@@ -1,6 +1,5 @@
 import datetime
 import pkgutil
-import webbrowser
 from pathlib import Path
 from shutil import move
 from tempfile import mkdtemp, mktemp
@@ -65,7 +64,7 @@ from abstra_internals.templates import (
 )
 from abstra_internals.utils.ai import AiWs
 from abstra_internals.utils.diff import compute_updated_code_from_replacements
-from abstra_internals.utils.file import module2path, path2module
+from abstra_internals.utils.file import path2module
 from abstra_internals.utils.validate import validate_json
 
 
@@ -169,7 +168,7 @@ class MainController:
 
         This method looks up and returns a single stage from the project
         based on the provided ID. The stage can be of any type (form, hook,
-        job, or script).
+        job, or tasklet).
 
         Args:
             id (str): Unique identifier of the stage to retrieve.
@@ -202,7 +201,7 @@ class MainController:
                 elif isinstance(stage, JobStage):
                     print("This is a job stage")
                 elif isinstance(stage, ScriptStage):
-                    print("This is a script stage")
+                    print("This is a tasklet stage")
             else:
                 print("Stage not found")
             ```
@@ -287,16 +286,6 @@ class MainController:
         file_path.parent.mkdir(parents=True, exist_ok=True)
         file_path.write_text(code, encoding="utf-8")
 
-    def open_file(self, file_path: str, mode: str, create_if_not_exists: bool = False):
-        if mode == "module" or mode == "package":
-            file_path = str(module2path(file_path, mode == "package"))
-        complete_file_path = Settings.root_path.joinpath(file_path)
-
-        if create_if_not_exists and not complete_file_path.is_file():
-            complete_file_path.touch()
-
-        webbrowser.open(complete_file_path.absolute().as_uri())
-
     def read_file(self, file: str):
         """
         Read the contents of a file from the project workspace.
@@ -316,13 +305,13 @@ class MainController:
             ```python
             controller = MainController(repositories)
 
-            # Read a Python script file
-            script_content = controller.read_file("scripts/data_processor.py")
-            if script_content:
-                print("Script content:")
-                print(script_content)
+            # Read a Python tasklet file
+            tasklet_content = controller.read_file("tasklet_data_processor.py")
+            if tasklet_content:
+                print("Tasklet content:")
+                print(tasklet_content)
             else:
-                print("Script file not found")
+                print("Tasklet file not found")
 
             # Read configuration files
             config_content = controller.read_file("config.json")
@@ -383,13 +372,13 @@ class MainController:
             else:
                 print("No requirements file found")
 
-            # Check script files before reading
-            script_path = "scripts/data_processor.py"
-            if controller.check_file(script_path):
-                content = controller.read_file(script_path)
-                print("Script loaded successfully")
+            # Check tasklet files before reading
+            tasklet_path = "tasklet_data_processor.py"
+            if controller.check_file(tasklet_path):
+                content = controller.read_file(tasklet_path)
+                print("Tasklet loaded successfully")
             else:
-                print(f"Script {script_path} not found")
+                print(f"Tasklet {tasklet_path} not found")
 
             # Check configuration files
             config_files = ["config.json", "settings.yaml", ".env"]
@@ -401,8 +390,8 @@ class MainController:
                 print("No configuration files found")
 
             # Directories return False
-            is_file = controller.check_file("scripts")  # Returns False (directory)
-            is_file = controller.check_file("scripts/")  # Returns False (directory)
+            is_file = controller.check_file("tasklets")  # Returns False (directory)
+            is_file = controller.check_file("tasklets/")  # Returns False (directory)
             ```
 
         Note:
@@ -499,7 +488,7 @@ class MainController:
 
         This method provides different listing modes to browse the project filesystem,
         supporting various file types and Python module discovery. It respects
-        ignore patterns defined in .abstraignore and .gitignore files.
+        ignore patterns defined in .gitignore file.
 
         Args:
             path (str, optional): Relative path from project root to list contents.
@@ -531,8 +520,8 @@ class MainController:
             for item in all_files:
                 print(f"{item['type']}: {item['name']} -> {item['path']}")
 
-            # List only Python files in scripts directory
-            python_files = controller.list_files("scripts", mode="python-file")
+            # List only Python files in tasklets directory
+            python_files = controller.list_files("tasklets", mode="python-file")
             for file in python_files:
                 if file['type'] == 'file':
                     print(f"Python file: {file['path']}")
@@ -552,7 +541,7 @@ class MainController:
             ```
 
         Note:
-            - Respects .abstraignore and .gitignore patterns when use_ignore=True
+            - Respects .gitignore and .gitignore patterns when use_ignore=True
             - Image mode supports: .png, .jpg, .jpeg, .gif, .svg, .webp, .jfif, .pjp, .pjpeg
             - Module mode uses Python's pkgutil.iter_modules for discovery
             - Paths are always relative to the project root directory
@@ -841,49 +830,49 @@ class MainController:
         id: Optional[str] = None,
     ) -> ScriptStage:
         """
-        Create a new script stage in the project workflow.
+        Create a new tasklet stage in the project workflow.
 
-        Scripts are programmatic workflow stages that execute Python code
+        Tasklets are programmatic workflow stages that execute Python code
         without user interaction. They are used for data processing, business
         logic, integrations, and automation tasks within workflows.
 
         Args:
-            title (str): Display name for the script stage.
-            file (str): Relative path where the script's Python code will be stored.
+            title (str): Display name for the tasklet stage.
+            file (str): Relative path where the tasklet's Python code will be stored.
                 Must end with .py extension.
             workflow_position (Tuple[int, int], optional): X, Y coordinates for the
-                script's position in the visual workflow editor. Defaults to (0, 0).
-            id (Optional[str], optional): Custom identifier for the script. If None,
+                tasklet's position in the visual workflow editor. Defaults to (0, 0).
+            id (Optional[str], optional): Custom identifier for the tasklet. If None,
                 a unique ID will be automatically generated.
 
         Returns:
-            ScriptStage: The newly created script stage object containing all script metadata.
+            ScriptStage: The newly created tasklet stage object containing all tasklet metadata.
 
         Example:
             ```python
             controller = MainController(repositories)
 
-            # Create a data processing script
-            processor = controller.create_script(
+            # Create a data processing tasklet
+            processor = controller.create_tasklet(
                 title="Data Processor",
-                file="scripts/process_data.py"
+                file="tasklet_process_data.py"
             )
-            print(f"Created script: {processor.id}")
+            print(f"Created tasklet: {processor.id}")
 
-            # Create script with custom positioning
-            validator = controller.create_script(
+            # Create tasklet with custom positioning
+            validator = controller.create_tasklet(
                 title="Input Validator",
-                file="scripts/validate_input.py",
+                file="tasklet_validate_input.py",
                 workflow_position=(200, 300),
                 id="input-validator"
             )
             ```
 
         Note:
-            - The script file will be initialized with default script template code
-            - Scripts can receive data from previous workflow stages
-            - Scripts can send tasks to trigger subsequent workflow stages
-            - Scripts run without user interaction and are ideal for automation
+            - The tasklet file will be initialized with default tasklet template code
+            - Tasklets can receive data from previous workflow stages
+            - Tasklets can send tasks to trigger subsequent workflow stages
+            - Tasklets run without user interaction and are ideal for automation
 
         Copywritings:
             Create a new tasklet stage
@@ -909,13 +898,13 @@ class MainController:
 
     def delete_tasklet(self, id: str, remove_file: bool = False):
         """
-        Delete a script stage from the project workflow.
+        Delete a tasklet stage from the project workflow.
 
-        This method removes a script stage from the project configuration and
+        This method removes a tasklet stage from the project configuration and
         optionally deletes the associated Python file from the filesystem.
 
         Args:
-            id (str): Unique identifier of the script stage to delete.
+            id (str): Unique identifier of the tasklet stage to delete.
             remove_file (bool, optional): Whether to also delete the associated
                 Python file from the filesystem. Defaults to False.
 
@@ -923,15 +912,15 @@ class MainController:
             ```python
             controller = MainController(repositories)
 
-            # Delete script but preserve the file
-            controller.delete_script("data-processor")
+            # Delete tasklet but preserve the file
+            controller.delete_tasklet("data-processor")
 
-            # Delete script and its file completely
-            controller.delete_script("validator-script", remove_file=True)
+            # Delete tasklet and its file completely
+            controller.delete_tasklet("validator-tasklet", remove_file=True)
             ```
 
         Warning:
-            - Deleting a script that is referenced by workflow transitions may
+            - Deleting a tasklet that is referenced by workflow transitions may
               break the workflow flow
             - If remove_file=True, the Python file will be permanently deleted
             - This operation cannot be undone
@@ -976,14 +965,14 @@ class MainController:
             # Create a simple form
             form = controller.create_form(
                 title="User Registration",
-                file="forms/registration.py"
+                file="form_registration.py"
             )
             print(f"Created form with ID: {form.id}")
 
             # Create form with custom position and ID
             custom_form = controller.create_form(
                 title="Data Input Form",
-                file="forms/data_input.py",
+                file="form_data_input.py",
                 workflow_position=(100, 200),
                 id="custom-form-id"
             )
@@ -1099,14 +1088,14 @@ class MainController:
             # Create a webhook for external API integration
             webhook = controller.create_hook(
                 title="Payment Webhook",
-                file="hooks/payment_webhook.py"
+                file="hook_payment_webhook.py"
             )
             print(f"Webhook URL: /hooks/{webhook.id}")
 
             # Create hook with custom positioning
             api_hook = controller.create_hook(
                 title="User API Endpoint",
-                file="hooks/user_api.py",
+                file="hook_user_api.py",
                 workflow_position=(300, 150),
                 id="user-api-hook"
             )
@@ -1242,14 +1231,14 @@ class MainController:
             # Create a daily data processing job
             daily_job = controller.create_job(
                 title="Daily Data Sync",
-                file="jobs/daily_sync.py"
+                file="job_daily_sync.py"
             )
             print(f"Created job: {daily_job.title}")
 
             # Create job with custom position and ID
             cleanup_job = controller.create_job(
                 title="Weekly Cleanup",
-                file="jobs/cleanup.py",
+                file="job_cleanup.py",
                 workflow_position=(500, 100),
                 id="weekly-cleanup"
             )
@@ -1390,7 +1379,7 @@ class MainController:
         Retrieve all workflow stages in the current project.
 
         This method returns a complete list of all stages (forms, hooks, jobs,
-        and scripts) that are part of the project workflow.
+        and tasklets) that are part of the project workflow.
 
         Returns:
             List[Stage]: List containing all workflow stages, including:
@@ -1760,10 +1749,10 @@ class MainController:
 
         script = self.get_script(id)
         if not script:
-            raise Exception(f"Script with id {id} not found")
+            raise Exception(f"Tasklet with id {id} not found")
 
         if not task_id:
-            raise Exception("Task ID is required for script execution")
+            raise Exception("Task ID is required for tasklet execution")
 
         return ExecutionController(
             repositories=self.repositories,

abstra_internals/entities/forms/template.py

@@ -18,7 +18,43 @@ from abstra_internals.entities.forms.widgets.widget_base import InputWidget, Wid
 @dataclass
 class Button:
     """
-    Base class for form navigation buttons.
+    Render buttons with custom functionality in your form for conditional logic and branching paths.
+
+    Buttons allow users to trigger custom Python functions, processing or different form behaviors. When a button is pressed, its key becomes `True` in the form state, enabling conditional logic to determine the next steps in your workflow. This makes buttons essential for creating approval workflows, multi-path forms, and interactive decision trees.
+
+    Unlike automatic navigation buttons (NextButton/BackButton), custom Button widgets give you full control over widget behavior within a page and can be used to implement complex conditional logic based on user choices.
+
+    ## How Button State Works
+
+    When a user clicks a button, the button's key is set to `True` in the form state. You can then check this state using `state.get("button_key")` to determine which button was pressed and conditionally render different widgets or forms.
+
+    ## Usage Pattern
+
+    Buttons are optionally returned from your Page function (a function that returns a list of widgets). You have two options:
+
+    **Option 1: Return only widgets (default behavior)**
+    ```python
+    def my_page(state):
+        return [TextOutput("Hello"), TextOutput("world!")]  # Default navigation buttons will be used
+    ```
+
+    **Option 2: Return widgets + custom buttons as a tuple**
+    ```python
+    def my_page(state):
+        widgets = [TextOutput("Hello"), TextOutput("world!")]
+        buttons = [Button("Label 1", key="key1"), Button("Label 2", key="key2")]
+        return widgets, buttons
+    ```
+
+    If you don't return buttons (Option 1), the system automatically provides default navigation buttons (Next/Back). If you want custom buttons, you must return a tuple with widgets as the first element and a list of Button objects as the second element.
+
+    ## Common Use Cases
+
+    - **Approval Workflows**: Create "Approve" and "Reject" buttons for document review processes
+    - **Data Reload**: Refresh page content with updated information from external APIs or databases
+    - **Multi-path Forms**: Allow users to choose between different information collection paths
+    - **Decision Trees**: Build complex conditional forms based on user choices
+    - **Custom Navigation**: Implement non-linear form progression with custom logic
 
     Args:
         label (str): The text displayed on the button.
@@ -50,8 +86,26 @@ class Button:
 
 class NextButton(Button):
     """
-    Button used to navigate to the next step in a form.
-    Automatically labeled with internationalized "Next" text.
+    Automatic navigation button for progressing to the next step in multi-step forms.
+
+    NextButton is automatically added to forms when using multi-step workflows created with the `run()` function. It handles forward navigation between form steps without requiring manual implementation. The button is automatically labeled with internationalized "Next" text that adapts to the user's language settings.
+
+    ## Automatic Behavior
+
+    - **Auto-added**: NextButton appears automatically on each step of a multi-step form (you don't need to import or create it)
+    - **Smart positioning**: Only shows when there are more steps ahead
+    - **Internationalized**: Button text automatically translates based on user locale
+    - **State preservation**: User input is preserved when navigating between steps
+
+    ## When to Use
+
+    NextButton is ideal for:
+    - **Linear workflows**: Step-by-step data collection processes
+    - **Wizards**: Multi-step onboarding or configuration flows
+    - **Progressive forms**: Breaking long forms into manageable sections
+    - **Data collection pipelines**: Structured information gathering processes
+
+    Unlike custom Button widgets, NextButton doesn't require state management or conditional logic - it's handled automatically by the form system.
     """
 
     def __init__(self):
@@ -61,8 +115,33 @@ class NextButton(Button):
 
 class BackButton(Button):
     """
-    Button used to navigate to the previous step in a form.
-    Automatically labeled with internationalized "Back" text.
+    Automatic navigation button for returning to previous steps in multi-step forms.
+
+    BackButton is automatically added to forms starting from step 2 onwards in multi-step workflows. It enables backward navigation while preserving all user input, allowing users to review and modify their previous responses without losing data. The button is automatically labeled with internationalized "Back" text that adapts to the user's language settings.
+
+    ## Automatic Behavior
+
+    - **Auto-added**: BackButton appears automatically from step 2 onwards in multi-step forms (you don't need to import or create it)
+    - **Smart positioning**: Only shows when there are previous steps to navigate to
+    - **Internationalized**: Button text automatically translates based on user locale
+    - **Data preservation**: All user input is maintained when navigating backwards
+    - **Seamless integration**: Works automatically with the form system's navigation logic
+
+    ## Key Features
+
+    - **Non-destructive navigation**: Users can go back without losing their progress
+    - **Form state management**: Previous inputs are automatically restored when returning
+    - **User-friendly**: Provides confidence for users to explore and correct their inputs
+
+    ## When BackButton Appears
+
+    BackButton is ideal for:
+    - **Multi-step wizards**: Allow users to review and modify previous steps
+    - **Data collection forms**: Enable correction of earlier responses
+    - **Progressive workflows**: Provide flexibility in non-linear completion
+    - **Review processes**: Allow users to double-check their inputs before submission
+
+    Unlike custom Button widgets, BackButton doesn't require any implementation - it's automatically managed by the form system.
     """
 
     def __init__(self):

abstra_internals/interface/cli/deploy.py

@@ -17,9 +17,7 @@ def _generate_zip_file() -> pathlib.Path:
     zip_path = pathlib.Path(tempfile.gettempdir(), f"{uuid.uuid4()}.zip")
 
     with zipfile.ZipFile(zip_path, "w") as zip_file:
-        for file in FileSystemService.list_files(
-            root_path, use_ignore=True, ignore_dotenv=True
-        ):
+        for file in FileSystemService.list_files(root_path, use_ignore=True):
             zip_file.write(file, file.relative_to(root_path))
 
     return zip_path

abstra_internals/modules_test.py

@@ -1,5 +1,4 @@
 import os
-import platform
 from unittest import TestCase, skipIf
 
 from abstra_internals.modules import import_as_new, reload_module
@@ -7,11 +6,12 @@ from abstra_internals.repositories.project.project import (
     LocalProjectRepository,
     ScriptStage,
 )
+from abstra_internals.utils.platform import is_windows
 from tests.fixtures import clear_dir, init_dir
 
 
 def can_create_symlinks():
-    if platform.system() != "Windows":
+    if not is_windows():
         return True
 
     try:

abstra_internals/repositories/linter/repository.py

@@ -12,7 +12,7 @@ class LinterRepository(ABC):
         pass
 
     @abstractmethod
-    def update_checks(self):
+    def update_checks(self) -> List[LinterCheck]:
         pass
 
     @abstractmethod
@@ -52,39 +52,6 @@ class LocalLinterRepository(LinterRepository):
                 - description: Human-readable description of what the rule checks
                 - issues: List of specific issues found by this rule
                 - fixes: Available automatic fixes for the issues
-
-        Example:
-            ```python
-            linter_repo = LocalLinterRepository()
-            linter_repo.update_checks()  # Run all checks first
-
-            checks = linter_repo.get_checks()
-            print(f"Found {len(checks)} linter checks")
-
-            for check in checks:
-                print(f"Rule: {check.name} ({check.type})")
-                print(f"Description: {check.description}")
-
-                if check.issues:
-                    print(f"Issues found: {len(check.issues)}")
-                    for issue in check.issues:
-                        print(f"  - {issue.message}")
-                        print(f"    File: {issue.file}:{issue.line}")
-
-                        if issue.fixes:
-                            print(f"    Available fixes: {len(issue.fixes)}")
-                            for fix in issue.fixes:
-                                print(f"      - {fix.name}: {fix.description}")
-                else:
-                    print("✓ No issues found")
-
-            # Filter by severity
-            errors = [c for c in checks if c.type == 'error']
-            warnings = [c for c in checks if c.type == 'warning']
-            security_issues = [c for c in checks if c.type == 'security']
-
-            print(f"Errors: {len(errors)}, Warnings: {len(warnings)}")
-            print(f"Security issues: {len(security_issues)}")
             ```
 
         Note:
@@ -118,6 +85,8 @@ class LocalLinterRepository(LinterRepository):
 
         self.checks = new_checks
 
+        return self.checks
+
     def fix_issue_in_codebase(self, rule_name: str, fix_name: str):
         """
         Apply a specific automatic fix for a linter issue.
@@ -216,16 +185,16 @@ class ProductionLinterRepository(LinterRepository):
     """
 
     def find_issues_in_codebase(self) -> List[LinterCheck]:
-        return []
+        raise NotImplementedError("Linters are not available in production.")
 
-    def update_checks(self):
-        pass
+    def update_checks(self) -> List[LinterCheck]:
+        raise NotImplementedError("Linters are not available in production.")
 
     def fix_issue_in_codebase(self, rule_name: str, fix_name: str) -> bool:
-        return False
+        raise NotImplementedError("Linters are not available in production.")
 
     def fix_all_linters(self):
-        pass
+        raise NotImplementedError("Linters are not available in production.")
 
     def get_blocking_checks(self) -> List[LinterCheck]:
-        return []
+        raise NotImplementedError("Linters are not available in production.")

abstra_internals/repositories/linter/rules/__init__.py

@@ -3,6 +3,7 @@ from typing import List
 
 from abstra_internals.repositories.linter.models import LinterRule
 
+from .big_py_files import BigPyFiles
 from .conflicting_name import ConflictingName
 from .conflicting_path import ConflictingPath
 from .deprecated_functions import DeprecatedFunctionUsage
@@ -30,6 +31,7 @@ core_rules: List[LinterRule] = [
     Psycopg2MustBeBinary(),
     ConflictingName(),
     DeprecatedFunctionUsage(),
+    BigPyFiles(),
 ]
 
 conditional_rules: List[LinterRule] = []