atlan-application-sdk 0.1.1rc25__tar.gz → 0.1.1rc26__tar.gz

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/.cursor/BUGBOT.md

@@ -14,6 +14,7 @@
 - **Cognitive Load**: Can a new developer understand this change with less cognitive load?
 - **Magic Numbers/Strings**: All constants properly defined and named in @application_sdk/constants.py
 - **Spell Check**: No typos in code, comments, docstrings, or documentation
+- **Exception Handling Standards**: All exception handling must follow these principles. See detailed guidelines in [exception-handling.mdc](mdc:.cursor/rules/exception-handling.mdc).
 
 ### 🏗️ Architecture & Design
 
@@ -42,8 +43,14 @@
 - **Input Validation**: All external inputs validated and sanitized
 - **Secrets Management**: No secrets in code; proper credential handling
 - **SQL Injection**: Parameterized queries used for all SQL operations
-- **Performance Impact**: Resource-intensive operations benchmarked
-- **Memory Leaks**: Long-running processes properly manage memory
+- **Performance Standards**: All performance considerations must follow these principles. See detailed guidelines in [performance.mdc](mdc:.cursor/rules/performance.mdc).
+- **Memory Management**: Resources properly closed, large datasets processed in chunks
+- **DataFrame Optimization**: Appropriate dtypes, avoid unnecessary copies, use chunked processing
+- **SQL Query Efficiency**: Use LIMIT, specific columns, proper WHERE clauses, connection pooling
+- **Serialization Performance**: Use orjson for large datasets, implement compression
+- **Algorithm Efficiency**: Use appropriate data structures, avoid O(n²) when O(n) alternatives exist
+- **Caching Strategy**: Cache expensive operations and database queries
+- **Async Usage**: Use async for I/O operations, sync for CPU-bound tasks
 
 ### 📊 Observability & Logging
 

atlan_application_sdk-0.1.1rc26/.cursor/rules/exception-handling.mdc

@@ -0,0 +1,198 @@
+---
+alwaysApply: false
+globs: application_sdk/**/*.py
+---
+# Exception Handling Standards
+
+## Core Principles
+
+**Default Behavior: Re-raise Exceptions** - Exceptions should be re-raised by default unless explicitly handled for a specific reason. Silent exception swallowing is not allowed.
+
+## Critical Rules
+
+### **Exception Propagation**
+- **Rule**: Always re-raise exceptions after logging unless in non-critical operations
+- **Anti-pattern**: `except Exception as e: logger.error(f"Error: {e}")` - This swallows exceptions
+- **Correct pattern**: `except Exception as e: logger.error(f"Error: {e}"); raise`
+
+### **Specific Exception Types**
+- **Use specific exception types** instead of generic `Exception`
+- **Examples**: `ValueError`, `ConnectionError`, `TimeoutError`, `FileNotFoundError`
+- **Create custom exceptions** in `application_sdk/common/error_codes.py` for domain-specific errors
+- **Anti-pattern**: `except Exception:` - Too broad, masks real issues
+
+## Exception Handling Patterns
+
+### **✅ DO: Proper exception handling with re-raising**
+```python
+try:
+    result = some_operation()
+    return result
+except ValueError as e:
+    logger.error(f"Invalid input: {e}")
+    raise  # Re-raise to propagate the error
+except ConnectionError as e:
+    logger.error(f"Connection failed: {e}")
+    raise  # Re-raise to propagate the error
+except Exception as e:
+    logger.error(f"Unexpected error: {e}")
+    raise  # Re-raise to propagate the error
+```
+
+### **❌ DON'T: Swallowing exceptions**
+```python
+try:
+    result = some_operation()
+    return result
+except Exception as e:
+    logger.error(f"Error: {e}")
+    # Missing raise - this swallows the exception!
+```
+
+## Context-Specific Guidelines
+
+### **1. Critical Operations (Database, Network, File I/O)**
+- **Always re-raise** exceptions after logging
+- **Include context** in error messages
+- **Use specific exception types**
+
+### **2. Non-Critical Operations (Logging, Metrics, Observability)**
+- **May swallow exceptions** to prevent cascading failures
+- **Log the failure** for debugging
+- **Continue operation** if possible
+
+### **3. Resource Cleanup**
+- **Use try/finally** for guaranteed cleanup
+- **Log cleanup failures** but don't re-raise (to avoid masking original error)
+
+## Common Anti-patterns to Reject
+
+### **❌ Silent Exception Swallowing**
+```python
+try:
+    operation()
+except Exception:
+    pass  # REJECT: Silent failure
+```
+
+### **❌ Generic Exception Catching Without Re-raising**
+```python
+try:
+    operation()
+except Exception as e:
+    logger.error(f"Error: {e}")  # REJECT: Swallows exception
+```
+
+### **❌ Overly Broad Exception Handling**
+```python
+try:
+    operation()
+except Exception as e:  # REJECT: Too broad
+    logger.error(f"Error: {e}")
+    raise
+```
+
+### **❌ Exception Handling Without Context**
+```python
+try:
+    operation()
+except Exception as e:
+    logger.error(f"Error: {e}")  # REJECT: No context about what failed
+    raise
+```
+
+## Best Practices
+
+### **✅ DO: Proper exception handling with context**
+```python
+try:
+    result = database_connection.execute_query(query)
+    return result
+except ConnectionError as e:
+    logger.error(f"Database connection failed for query {query[:50]}...: {e}")
+    raise
+except ValueError as e:
+    logger.error(f"Invalid query parameters: {e}")
+    raise
+except Exception as e:
+    logger.error(f"Unexpected error during database operation: {e}")
+    raise
+```
+
+### **✅ DO: Resource cleanup with exception handling**
+```python
+file_handle = None
+try:
+    file_handle = open(filename, 'r')
+    return file_handle.read()
+except FileNotFoundError as e:
+    logger.error(f"File not found: {filename}")
+    raise
+finally:
+    if file_handle:
+        try:
+            file_handle.close()
+        except Exception as e:
+            logger.warning(f"Failed to close file {filename}: {e}")
+            # Don't re-raise cleanup errors
+```
+
+### **✅ DO: Non-critical operation exception handling**
+```python
+try:
+    metrics.record_metric("operation_success", 1)
+except Exception as e:
+    logger.warning(f"Failed to record metric: {e}")
+    # Don't re-raise for non-critical operations
+```
+
+## Module-Specific Guidelines
+
+### **Handlers (`application_sdk/handlers/`)**
+- **Critical**: Always re-raise exceptions after logging
+- **Include operation context** in error messages
+- **Use specific exception types** for different error scenarios
+
+### **Outputs (`application_sdk/outputs/`)**
+- **Critical**: Re-raise exceptions for data writing operations
+- **Non-critical**: May swallow exceptions for metrics/logging operations
+- **Resource cleanup**: Ensure files/connections are properly closed
+
+### **Inputs (`application_sdk/inputs/`)**
+- **Critical**: Re-raise exceptions for data reading operations
+- **Include file/connection context** in error messages
+- **Handle specific I/O exceptions** appropriately
+
+### **Observability (`application_sdk/observability/`)**
+- **Non-critical**: May swallow exceptions to prevent cascading failures
+- **Log all failures** for debugging
+- **Continue operation** when possible
+
+### **Workflows (`application_sdk/workflows/`)**
+- **Critical**: Re-raise exceptions to trigger workflow retry logic
+- **Include workflow context** in error messages
+- **Handle Temporal-specific exceptions** appropriately
+
+### **Server (`application_sdk/server/`)**
+- **Critical**: Re-raise exceptions to return proper HTTP error responses
+- **Include request context** in error messages
+- **Handle HTTP-specific exceptions** appropriately
+
+## Review Checklist
+
+When reviewing code, check for:
+
+1. **Exception Propagation**: Are exceptions properly re-raised when they should be?
+2. **Specific Exception Types**: Are specific exception types used instead of generic `Exception`?
+3. **Error Context**: Do error messages include sufficient context for debugging?
+4. **Resource Cleanup**: Are resources properly cleaned up in finally blocks?
+5. **Non-Critical Operations**: Are non-critical operations (logging, metrics) handled appropriately?
+6. **Custom Exceptions**: Are domain-specific exceptions defined in `error_codes.py`?
+7. **Exception Documentation**: Are exceptions documented in function docstrings?
+
+## Implementation Notes
+
+- **Custom Exceptions**: Define domain-specific exceptions in `application_sdk/common/error_codes.py`
+- **Logging**: Use `AtlanLoggerAdapter` for all logging with proper context
+- **Context**: Always include relevant context in error messages (query, filename, operation, etc.)
+- **Documentation**: Document all exceptions that functions can raise in docstrings

atlan_application_sdk-0.1.1rc26/.cursor/rules/performance.mdc

@@ -0,0 +1,294 @@
+---
+alwaysApply: false
+globs: application_sdk/**/*.py
+---
+# Performance Standards
+
+## Core Principles
+
+**Performance is a Feature** - Performance issues are bugs that affect user experience and system reliability. All code must be written with performance considerations in mind.
+
+## Critical Performance Areas
+
+### **Memory Management**
+
+#### **Memory Leaks Prevention**
+- **Rule**: Always close resources (files, connections, iterators) in finally blocks
+- **Anti-pattern**: Opening resources without proper cleanup
+- **Correct pattern**: Use context managers or try/finally
+
+**✅ DO: Proper resource management**
+```python
+# Using context manager
+with open(filename, 'r') as f:
+    data = f.read()
+
+# Using try/finally
+file_handle = None
+try:
+    file_handle = open(filename, 'r')
+    data = file_handle.read()
+finally:
+    if file_handle:
+        file_handle.close()
+```
+
+**❌ DON'T: Resource leaks**
+```python
+# REJECT: No cleanup
+file_handle = open(filename, 'r')
+data = file_handle.read()
+# Missing file_handle.close()
+```
+
+#### **Large Object Management**
+- **Rule**: Process large datasets in chunks, not all at once
+- **Anti-pattern**: Loading entire dataset into memory
+- **Correct pattern**: Use generators, iterators, or chunked processing
+
+**✅ DO: Chunked processing**
+```python
+def process_large_file(filename: str, chunk_size: int = 1000):
+    """Process large file in chunks to avoid memory issues."""
+    with open(filename, 'r') as f:
+        chunk = []
+        for line in f:
+            chunk.append(line.strip())
+            if len(chunk) >= chunk_size:
+                yield process_chunk(chunk)
+                chunk = []
+        if chunk:  # Process remaining items
+            yield process_chunk(chunk)
+```
+
+**❌ DON'T: Load everything into memory**
+```python
+# REJECT: Memory intensive
+def process_large_file(filename: str):
+    with open(filename, 'r') as f:
+        all_lines = f.readlines()  # Loads entire file into memory
+        return process_all_lines(all_lines)
+```
+
+### **DataFrame Performance**
+
+#### **Memory-Efficient DataFrame Operations**
+- **Rule**: Use appropriate data types and avoid unnecessary copies
+- **Anti-pattern**: Creating multiple copies of large DataFrames
+- **Correct pattern**: Use inplace operations and proper dtypes
+
+**✅ DO: Memory-efficient DataFrame operations**
+```python
+# Use appropriate dtypes
+df = pd.read_csv('large_file.csv', dtype={
+    'id': 'int32',
+    'category': 'category',  # More memory efficient than object
+    'value': 'float32'
+})
+
+# Use inplace operations when possible
+df.dropna(inplace=True)  # Instead of df = df.dropna()
+df.reset_index(drop=True, inplace=True)
+
+# Use query() for filtering (more memory efficient)
+filtered_df = df.query('value > 100 and category == "A"')
+```
+
+**❌ DON'T: Inefficient DataFrame operations**
+```python
+# REJECT: Creates unnecessary copies
+df = df.dropna()  # Creates copy
+df = df.reset_index()  # Creates another copy
+df = df[df['value'] > 100]  # Creates another copy
+df = df[df['category'] == 'A']  # Creates another copy
+```
+
+#### **DataFrame Chunking**
+- **Rule**: Process large DataFrames in chunks
+- **Anti-pattern**: Processing entire DataFrame at once
+- **Correct pattern**: Use chunked reading and processing
+
+**✅ DO: Chunked DataFrame processing**
+```python
+def process_large_dataframe(filename: str, chunk_size: int = 10000):
+    """Process large CSV file in chunks."""
+    for chunk in pd.read_csv(filename, chunksize=chunk_size):
+        # Process each chunk
+        processed_chunk = process_chunk(chunk)
+        yield processed_chunk
+```
+
+**❌ DON'T: Load entire DataFrame**
+```python
+# REJECT: Memory intensive for large files
+df = pd.read_csv('very_large_file.csv')  # Loads entire file
+process_dataframe(df)
+```
+
+### **SQL Query Performance**
+
+#### **Query Optimization**
+- **Rule**: Write efficient SQL queries with proper indexing and limiting
+- **Anti-pattern**: SELECT * without LIMIT on large tables
+- **Correct pattern**: Use specific columns, LIMIT, and proper WHERE clauses
+
+**✅ DO: Optimized SQL queries**
+```python
+# Use specific columns instead of SELECT *
+query = "SELECT id, name, created_at FROM users WHERE status = 'active' LIMIT 1000"
+
+# Use parameterized queries for security and performance
+query = "SELECT * FROM users WHERE age > %s AND city = %s LIMIT %s"
+params = (18, 'New York', 100)
+
+# Use appropriate indexes in WHERE clauses
+query = "SELECT * FROM orders WHERE user_id = %s AND created_at > %s"
+```
+
+**❌ DON'T: Inefficient SQL queries**
+```python
+# REJECT: No LIMIT on large table
+query = "SELECT * FROM users"  # Could return millions of rows
+
+# REJECT: No WHERE clause on indexed columns
+query = "SELECT * FROM orders WHERE amount > 0"  # Should use user_id or date
+
+# REJECT: String concatenation (SQL injection risk)
+query = f"SELECT * FROM users WHERE name = '{user_input}'"
+```
+
+#### **Connection and Transaction Management**
+- **Rule**: Use connection pooling and proper transaction management
+- **Anti-pattern**: Creating new connections for each query
+- **Correct pattern**: Reuse connections and use transactions
+
+**✅ DO: Proper connection management**
+```python
+# Use connection pooling
+async def execute_queries():
+    async with get_db_connection() as conn:
+        async with conn.transaction():
+            await conn.execute("INSERT INTO logs (message) VALUES ($1)", "info")
+            await conn.execute("UPDATE counters SET value = value + 1")
+```
+
+**❌ DON'T: Poor connection management**
+```python
+# REJECT: Creating new connection for each query
+for query in queries:
+    conn = create_new_connection()  # Expensive
+    conn.execute(query)
+    conn.close()
+```
+
+### **Serialization/Deserialization Performance**
+
+#### **JSON Serialization Optimization**
+- **Rule**: Use efficient serialization libraries and avoid unnecessary conversions
+- **Anti-pattern**: Using default json module for large datasets
+- **Correct pattern**: Use orjson, ujson, or custom serializers
+
+**✅ DO: Efficient JSON serialization**
+```python
+import orjson  # Much faster than json
+
+# Use orjson for better performance
+data = orjson.dumps(large_dict, option=orjson.OPT_APPEND_NEWLINE)
+
+# Use streaming for large datasets
+def serialize_large_dataset(data_iterator):
+    for item in data_iterator:
+        yield orjson.dumps(item) + b'\n'
+```
+
+**❌ DON'T: Inefficient serialization**
+```python
+# REJECT: Using default json for large datasets
+import json
+data = json.dumps(large_dict)  # Slower than orjson
+
+# REJECT: Converting to string unnecessarily
+data = str(orjson.dumps(large_dict))  # Unnecessary conversion
+```
+
+
+### **CPU Performance**
+
+#### **Algorithm Efficiency**
+- **Rule**: Use appropriate algorithms and data structures
+- **Anti-pattern**: O(n²) algorithms when O(n) or O(log n) alternatives exist
+- **Correct pattern**: Choose efficient algorithms and data structures
+
+**✅ DO: Efficient algorithms**
+```python
+# Use set for O(1) lookups
+def find_duplicates(items):
+    seen = set()
+    duplicates = set()
+    for item in items:
+        if item in seen:
+            duplicates.add(item)
+        else:
+            seen.add(item)
+    return list(duplicates)
+
+# Use list comprehension instead of loops when appropriate
+squares = [x**2 for x in range(1000)]  # More efficient than loop
+```
+
+**❌ DON'T: Inefficient algorithms**
+```python
+# REJECT: O(n²) algorithm
+def find_duplicates(items):
+    duplicates = []
+    for i, item in enumerate(items):
+        if item in items[i+1:]:  # O(n) lookup
+            duplicates.append(item)
+    return duplicates
+```
+
+#### **Async/Await Performance**
+- **Rule**: Use async/await for I/O operations, not CPU-bound tasks
+- **Anti-pattern**: Using async for CPU-intensive operations
+- **Correct pattern**: Use async for I/O, sync for CPU-bound tasks
+
+**✅ DO: Proper async usage**
+```python
+import asyncio
+import aiofiles
+
+# Async for I/O operations
+async def read_files_async(filenames):
+    async def read_single_file(filename):
+        async with aiofiles.open(filename, 'r') as f:
+            return await f.read()
+
+    tasks = [read_single_file(filename) for filename in filenames]
+    return await asyncio.gather(*tasks)
+
+# Sync for CPU-bound operations
+def process_data_cpu_intensive(data):
+    # CPU-intensive processing
+    return [x * 2 for x in data]
+```
+
+**❌ DON'T: Misusing async**
+```python
+# REJECT: Using async for CPU-bound operations
+async def process_data_cpu_intensive(data):
+    # This should be sync
+    return [x * 2 for x in data]
+```
+
+## Performance Review Checklist
+
+When reviewing code for performance, check for:
+
+1. **Memory Management**: Are resources properly closed? Are large datasets processed in chunks?
+2. **DataFrame Operations**: Are appropriate dtypes used? Are unnecessary copies avoided?
+3. **SQL Queries**: Are queries optimized with LIMIT and proper WHERE clauses?
+4. **Serialization**: Are efficient libraries (orjson) used for large datasets?
+5. **Algorithm Efficiency**: Are appropriate data structures and algorithms used?
+6. **Async Usage**: Is async used for I/O operations, not CPU-bound tasks?
+7. **Connection Pooling**: Are database connections reused?
+8. **Batch Processing**: Are operations batched when possible?

atlan_application_sdk-0.1.1rc26/.github/release_notes.md

@@ -0,0 +1,11 @@
+## v0.1.1rc26 (August 07, 2025)
+
+Full Changelog: https://github.com/atlanhq/application-sdk/compare/v0.1.1rc25...v0.1.1rc26
+
+### Features
+
+- add cursor and bugbot rules (#636) (by @Amit Prabhu in [cbbecd9](https://github.com/atlanhq/application-sdk/commit/cbbecd9))
+
+### Bug Fixes
+
+- handle str and dict types in preflight checks (#638) (by @Nishchith Shetty in [57ee9a0](https://github.com/atlanhq/application-sdk/commit/57ee9a0))

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+
+## v0.1.1rc26 (August 07, 2025)
+
+Full Changelog: https://github.com/atlanhq/application-sdk/compare/v0.1.1rc25...v0.1.1rc26
+
+### Features
+
+- add cursor and bugbot rules (#636) (by @Amit Prabhu in [cbbecd9](https://github.com/atlanhq/application-sdk/commit/cbbecd9))
+
+### Bug Fixes
+
+- handle str and dict types in preflight checks (#638) (by @Nishchith Shetty in [57ee9a0](https://github.com/atlanhq/application-sdk/commit/57ee9a0))
+
 ## v0.1.1rc25 (August 05, 2025)
 
 Full Changelog: https://github.com/atlanhq/application-sdk/compare/v0.1.1rc24...v0.1.1rc25

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atlan-application-sdk
-Version: 0.1.1rc25
+Version: 0.1.1rc26
 Summary: Atlan Application SDK is a Python library for developing applications on the Atlan Platform
 Project-URL: Repository, https://github.com/atlanhq/application-sdk
 Project-URL: Documentation, https://github.com/atlanhq/application-sdk/README.md

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/application_sdk/common/utils.py

@@ -195,6 +195,38 @@ def prepare_query(
         return None
 
 
+def parse_filter_input(
+    filter_input: Union[str, Dict[str, Any], None],
+) -> Dict[str, Any]:
+    """
+    Robustly parse filter input from various formats.
+
+    Args:
+        filter_input: Can be None, empty string, JSON string, or dict
+
+    Returns:
+        Dict[str, Any]: Parsed filter dictionary (empty dict if input is invalid/empty)
+    """
+    # Handle None or empty cases
+    if not filter_input:
+        return {}
+
+    # If already a dict, return as-is
+    if isinstance(filter_input, dict):
+        return filter_input
+
+    # If it's a string, try to parse as JSON
+    if isinstance(filter_input, str):
+        # Handle empty string
+        if not filter_input.strip():
+            return {}
+        try:
+            return json.loads(filter_input)
+        except json.JSONDecodeError as e:
+            logger.warning(f"Invalid filter JSON: '{filter_input}', error: {str(e)}")
+            raise CommonError(f"Invalid filter JSON: {str(e)}")
+
+
 def prepare_filters(
     include_filter_str: str, exclude_filter_str: str
 ) -> Tuple[str, str]:
@@ -212,15 +244,8 @@ def prepare_filters(
     Raises:
         CommonError: If JSON parsing fails for either filter.
     """
-    try:
-        include_filter = json.loads(include_filter_str)
-    except json.JSONDecodeError as e:
-        raise CommonError(f"Invalid include filter JSON: {str(e)}")
-
-    try:
-        exclude_filter = json.loads(exclude_filter_str)
-    except json.JSONDecodeError as e:
-        raise CommonError(f"Invalid exclude filter JSON: {str(e)}")
+    include_filter = parse_filter_input(include_filter_str)
+    exclude_filter = parse_filter_input(exclude_filter_str)
 
     normalized_include_filter_list = normalize_filters(include_filter, True)
     normalized_exclude_filter_list = normalize_filters(exclude_filter, False)

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/application_sdk/handlers/sql.py

@@ -1,5 +1,4 @@
 import asyncio
-import json
 import re
 from enum import Enum
 from typing import Any, Dict, List, Optional, Set, Tuple
@@ -7,7 +6,11 @@ from typing import Any, Dict, List, Optional, Set, Tuple
 from packaging import version
 
 from application_sdk.clients.sql import BaseSQLClient
-from application_sdk.common.utils import prepare_query, read_sql_files
+from application_sdk.common.utils import (
+    parse_filter_input,
+    prepare_query,
+    read_sql_files,
+)
 from application_sdk.constants import SQL_QUERIES_PATH, SQL_SERVER_MIN_VERSION
 from application_sdk.handlers import HandlerInterface
 from application_sdk.inputs.sql_query import SQLQueryInput
@@ -220,10 +223,10 @@ class BaseSQLHandler(HandlerInterface):
         """
         try:
             schemas_results: List[Dict[str, str]] = await self.prepare_metadata()
-
-            include_filter = json.loads(
-                payload.get("metadata", {}).get("include-filter", "{}")
+            include_filter = parse_filter_input(
+                payload.get("metadata", {}).get("include-filter", {})
             )
+
             allowed_databases, allowed_schemas = self.extract_allowed_schemas(
                 schemas_results
             )

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/application_sdk/version.py

@@ -2,4 +2,4 @@
 Version information for the application_sdk package.
 """
 
-__version__ = "0.1.1rc25"
+__version__ = "0.1.1rc26"

{atlan_application_sdk-0.1.1rc25 → atlan_application_sdk-0.1.1rc26}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atlan-application-sdk"
-version = "0.1.1rc25"
+version = "0.1.1rc26"
 description = "Atlan Application SDK is a Python library for developing applications on the Atlan Platform"
 license = "Apache-2.0"
 authors = [