fastmssql 0.2.7__cp310-cp310-win_amd64.whl → 0.3.2__cp310-cp310-win_amd64.whl

fastmssql/__init__.py

@@ -23,18 +23,25 @@ Basic Usage (Async):
     >>> 
     >>> async def main():
     ...     async with Connection("Server=localhost;Database=test;Trusted_Connection=yes") as conn:
-    ...         # Simple query
-    ...         result = await conn.execute("SELECT * FROM users")
+    ...         # SELECT queries - use query() method
+    ...         result = await conn.query("SELECT * FROM users")
     ...         async for row in result:
     ...             print(f"User: {row['name']}, Age: {row['age']}")
     ...         
-    ...         # Parameterized query
-    ...         result = await conn.execute(
+    ...         # Parameterized SELECT query
+    ...         result = await conn.query(
     ...             "SELECT * FROM users WHERE age > @P1 AND city = @P2", 
     ...             [18, "New York"]
     ...         )
     ...         rows = await result.fetchall()
     ...         print(f"Found {len(rows)} users")
+    ...         
+    ...         # INSERT/UPDATE/DELETE - use execute() method
+    ...         affected = await conn.execute(
+    ...             "INSERT INTO users (name, email, age) VALUES (@P1, @P2, @P3)",
+    ...             ["John Doe", "john@example.com", 30]
+    ...         )
+    ...         print(f"Inserted {affected} rows")
     >>> 
     >>> asyncio.run(main())
 
@@ -42,11 +49,9 @@ Basic Usage (Sync):
     >>> from fastmssql import Connection
     >>> 
     >>> with Connection("Server=localhost;Database=test;Trusted_Connection=yes") as conn:
-    ...     result = conn.execute_with_python_params(
-    ...         "SELECT COUNT(*) as count FROM users WHERE active = ?", 
-    ...         [True]
-    ...     )
-    ...     print(f"Active users: {result[0]['count']}")
+    ...     # For SELECT queries, you would typically use the async API
+    ...     # Sync usage is primarily for simple operations
+    ...     pass  # Connection established and will be closed on exit
 
 Advanced Configuration:
     >>> from fastmssql import Connection, PoolConfig, SslConfig, EncryptionLevel
@@ -232,13 +237,19 @@ class Connection:
             trusted_connection=trusted_connection
         )
     
-    async def execute(self, query, parameters=None):
+    async def query(self, query, parameters=None):
         """
-        Execute a SQL query asynchronously and return a FastExecutionResult.
+        Execute a SQL query that returns rows (SELECT statements) asynchronously.
         
-        This method executes SQL queries with optional parameterization for security
-        and performance. It supports all types of SQL statements including SELECT,
-        INSERT, UPDATE, DELETE, and stored procedure calls.
+        This method is specifically designed for SELECT queries and other statements
+        that return result sets. It uses the optimized query() method internally
+        for maximum performance when fetching data.
+        
+        Use this method for:
+            - SELECT statements
+            - Stored procedures that return result sets
+            - SHOW commands
+            - Any query that returns tabular data
         
         Parameter Binding:
             Parameters are bound using positional placeholders (@P1, @P2, etc.) in the
@@ -258,7 +269,7 @@ class Connection:
             - uuid.UUID (uniqueidentifier)
         
         Args:
-            query (str): SQL query to execute. Use @P1, @P2, etc. for parameters.
+            query (str): SQL SELECT query to execute. Use @P1, @P2, etc. for parameters.
                 Example: "SELECT * FROM users WHERE age > @P1 AND city = @P2"
                 
             parameters (list, optional): List of parameter values in order.
@@ -280,143 +291,167 @@ class Connection:
             
         Examples:
             # Simple SELECT query
-            >>> result = await conn.execute("SELECT * FROM users")
+            >>> result = await conn.query("SELECT * FROM users")
             >>> async for row in result:
             ...     print(f"User ID: {row['id']}, Name: {row['name']}")
             
             # Parameterized query
-            >>> result = await conn.execute(
+            >>> result = await conn.query(
             ...     "SELECT * FROM orders WHERE created_date > @P1 AND amount > @P2",
             ...     [datetime(2023, 1, 1), 100.0]
             ... )
             >>> rows = await result.fetchall()
             >>> print(f"Found {len(rows)} orders")
             
-            # INSERT with parameters
-            >>> result = await conn.execute(
-            ...     "INSERT INTO users (name, email, age) VALUES (@P1, @P2, @P3)",
-            ...     ["John Doe", "john@example.com", 30]
+            # Complex SELECT with joins
+            >>> result = await conn.query(
+            ...     \"\"\"SELECT u.name, u.email, COUNT(o.id) as order_count
+            ...        FROM users u 
+            ...        LEFT JOIN orders o ON u.id = o.user_id 
+            ...        WHERE u.created_date > @P1
+            ...        GROUP BY u.id, u.name, u.email
+            ...        ORDER BY order_count DESC\"\"\",
+            ...     [datetime(2023, 1, 1)]
             ... )
-            >>> print(f"Inserted {result.rowcount} row(s)")
+            >>> async for row in result:
+            ...     print(f"{row['name']}: {row['order_count']} orders")
             
-            # Stored procedure call
-            >>> result = await conn.execute(
+            # Stored procedure that returns data
+            >>> result = await conn.query(
             ...     "EXEC GetUsersByDepartment @P1, @P2",
             ...     ["Engineering", True]  # department, active_only
             ... )
             >>> users = await result.fetchall()
-            
-            # Complex query with multiple data types
-            >>> from decimal import Decimal
-            >>> from datetime import datetime
-            >>> import uuid
-            >>> 
-            >>> result = await conn.execute(
-            ...     \"\"\"UPDATE products 
-            ...        SET price = @P1, updated_date = @P2, active = @P3 
-            ...        WHERE product_id = @P4\"\"\",
-            ...     [Decimal('29.99'), datetime.now(), True, uuid.uuid4()]
-            ... )
         
         Performance Tips:
-            - Use parameterized queries instead of string formatting for better performance
+            - Use this method instead of execute() for SELECT queries for better performance
             - For large result sets, iterate asynchronously rather than calling fetchall()
             - Reuse Connection instances to benefit from connection pooling
-            - Consider batch operations for bulk data manipulation
-        
-        Security Notes:
-            - Always use parameterized queries to prevent SQL injection attacks
-            - Parameter values are automatically escaped and type-checked
-            - Never concatenate user input directly into SQL query strings
+            - Use appropriate indexes on filtered columns
         """
-        # The Rust implementation now returns results directly
-        return await self._conn.execute(query, parameters)
+        return await self._conn.query(query, parameters)
     
-    def execute_with_python_params(self, query, params):
+    async def execute(self, query, parameters=None):
         """
-        Execute a SQL query synchronously with Python-style parameter substitution.
+        Execute a SQL command that doesn't return rows (INSERT/UPDATE/DELETE/DDL) asynchronously.
+        
+        This method is specifically designed for SQL commands that modify data or database
+        structure but don't return result sets. It uses the optimized execute() method 
+        internally for maximum performance when performing data modifications.
         
-        This method provides a synchronous interface for executing SQL queries with
-        parameter substitution using Python's DB-API 2.0 style placeholders (?).
-        It's designed for compatibility with existing Python database code and
-        simple synchronous operations.
+        Use this method for:
+            - INSERT statements
+            - UPDATE statements
+            - DELETE statements
+            - DDL commands (CREATE, ALTER, DROP)
+            - Stored procedures that don't return result sets
+            - MERGE statements
         
         Parameter Binding:
-            Uses question mark (?) placeholders in the query string, with parameters
-            provided as a list in the same order as the placeholders appear.
+            Parameters are bound using positional placeholders (@P1, @P2, etc.) in the
+            query string. The parameter values are provided as a list in the same order.
             
-        Note:
-            This is a synchronous method that blocks until the query completes.
-            For better performance in async applications, prefer the async execute() method.
+        Supported Parameter Types:
+            - None (NULL)
+            - bool
+            - int (32-bit and 64-bit)
+            - float (32-bit and 64-bit)
+            - str (varchar, nvarchar, text)
+            - bytes (varbinary, image)
+            - datetime.datetime (datetime, datetime2)
+            - datetime.date (date)
+            - datetime.time (time)
+            - decimal.Decimal (decimal, money)
+            - uuid.UUID (uniqueidentifier)
         
         Args:
-            query (str): SQL query with ? placeholders for parameters.
-                Example: "SELECT * FROM users WHERE age > ? AND city = ?"
+            query (str): SQL command to execute. Use @P1, @P2, etc. for parameters.
+                Example: "INSERT INTO users (name, email, age) VALUES (@P1, @P2, @P3)"
                 
-            params (list): List of parameter values in order of appearance.
+            parameters (list, optional): List of parameter values in order.
                 Values are automatically converted to appropriate SQL types.
-                Example: [18, "New York"]
+                Example: ["John Doe", "john@example.com", 30]
         
         Returns:
-            list: A list of dictionaries representing the result rows.
-                Each dictionary maps column names to values.
-                For non-SELECT queries, returns an empty list.
+            int: Number of rows affected by the command.
+                - For INSERT: Number of rows inserted
+                - For UPDATE: Number of rows updated
+                - For DELETE: Number of rows deleted
+                - For DDL: Usually 0 (structure changes don't affect rows)
         
         Raises:
-            SqlError: If the SQL query contains syntax errors or constraint violations.
-            ConnectionError: If the database connection is not available.
+            SqlError: If the SQL command contains syntax errors or constraint violations.
+            ConnectionError: If the database connection is lost during execution.
+            TimeoutError: If the command execution exceeds configured timeouts.
             ParameterError: If parameter types cannot be converted or are invalid.
             
         Examples:
-            # Simple SELECT query
-            >>> rows = conn.execute_with_python_params(
-            ...     "SELECT id, name, email FROM users WHERE active = ?", 
-            ...     [True]
+            # INSERT with parameters
+            >>> affected = await conn.execute(
+            ...     "INSERT INTO users (name, email, age) VALUES (@P1, @P2, @P3)",
+            ...     ["John Doe", "john@example.com", 30]
             ... )
-            >>> for row in rows:
-            ...     print(f"User: {row['name']} ({row['email']})")
+            >>> print(f"Inserted {affected} row(s)")
             
-            # INSERT operation
-            >>> conn.execute_with_python_params(
-            ...     "INSERT INTO logs (message, level, timestamp) VALUES (?, ?, ?)",
-            ...     ["Application started", "INFO", datetime.now()]
+            # UPDATE with conditions
+            >>> affected = await conn.execute(
+            ...     "UPDATE users SET age = @P1, updated_date = @P2 WHERE id = @P3",
+            ...     [31, datetime.now(), 123]
             ... )
+            >>> print(f"Updated {affected} user(s)")
             
-            # UPDATE with multiple parameters
-            >>> conn.execute_with_python_params(
-            ...     "UPDATE users SET last_login = ?, login_count = login_count + 1 WHERE id = ?",
-            ...     [datetime.now(), 12345]
+            # DELETE with parameters
+            >>> affected = await conn.execute(
+            ...     "DELETE FROM users WHERE age < @P1 AND last_login < @P2",
+            ...     [18, datetime(2020, 1, 1)]
             ... )
+            >>> print(f"Deleted {affected} inactive users")
             
-            # Complex query with various data types
-            >>> from decimal import Decimal
-            >>> rows = conn.execute_with_python_params(
-            ...     \"\"\"SELECT p.name, p.price, c.name as category
-            ...        FROM products p 
-            ...        JOIN categories c ON p.category_id = c.id
-            ...        WHERE p.price BETWEEN ? AND ? AND p.discontinued = ?\"\"\",
-            ...     [Decimal('10.00'), Decimal('100.00'), False]
+            # DDL commands
+            >>> affected = await conn.execute(
+            ...     \"\"\"CREATE TABLE temp_data (
+            ...         id INT IDENTITY(1,1) PRIMARY KEY,
+            ...         name NVARCHAR(100) NOT NULL,
+            ...         created_date DATETIME2 DEFAULT GETDATE()
+            ...     )\"\"\"
             ... )
-        
-        Migration from DB-API 2.0:
-            This method is designed to be compatible with Python's DB-API 2.0
-            specification, making it easier to migrate from libraries like pyodbc
-            or pymssql with minimal code changes.
+            >>> print(f"Table created (affected rows: {affected})")
             
-            # Old pyodbc code:
-            # cursor.execute("SELECT * FROM users WHERE id = ?", [user_id])
-            # rows = cursor.fetchall()
+            # Stored procedure that modifies data
+            >>> affected = await conn.execute(
+            ...     "EXEC UpdateUserPreferences @P1, @P2",
+            ...     [user_id, json.dumps(preferences)]
+            ... )
+            >>> print(f"Updated preferences for {affected} user(s)")
             
-            # New fastmssql code:
-            # rows = conn.execute_with_python_params("SELECT * FROM users WHERE id = ?", [user_id])
-        
-        Performance Considerations:
-            - This method is synchronous and will block the calling thread
-            - For high-throughput applications, use the async execute() method instead
-            - Connection pooling is still utilized for efficient resource management
-            - Results are loaded entirely into memory, so be cautious with large result sets
+            # Batch operations
+            >>> users_to_insert = [
+            ...     ["Alice Johnson", "alice@example.com", 28],
+            ...     ["Bob Smith", "bob@example.com", 32],
+            ...     ["Carol Davis", "carol@example.com", 25]
+            ... ]
+            >>> total_affected = 0
+            >>> for user_data in users_to_insert:
+            ...     affected = await conn.execute(
+            ...         "INSERT INTO users (name, email, age) VALUES (@P1, @P2, @P3)",
+            ...         user_data
+            ...     )
+            ...     total_affected += affected
+            >>> print(f"Inserted {total_affected} users total")
+        
+        Performance Tips:
+            - Use this method instead of query() for data modification commands
+            - For bulk operations, consider using batch processing or table-valued parameters
+            - Use transactions for multiple related operations
+            - Monitor the returned affected row count for validation
+        
+        Security Notes:
+            - Always use parameterized queries to prevent SQL injection attacks
+            - Validate affected row counts match expectations
+            - Consider using transactions for data consistency
         """
-        return self._conn.execute_with_python_params(query, params)
+        return await self._conn.execute(query, parameters)
+    
     
     async def is_connected(self):
         """