FEAT: Explicit parameters and improved type hints for bulkcopy

[bewithgaurav]

Work Item / Issue Reference

AB#41884

---

Summary

Implements Revision 2 of the BulkCopy API spec from community feedback in #414.

Replaces **kwargs with explicit, type-hinted parameters for better IDE autocomplete and discoverability

Changes

API Signature

def _bulkcopy(
    self,
    table_name: str,
    data: Iterable[Union[Tuple, List]],
    batch_size: int = 0,
    timeout: int = 30,
    column_mappings: Optional[Union[List[str], List[Tuple[int, str]]]] = None,
    keep_identity: bool = False,
    check_constraints: bool = False,
    table_lock: bool = False,
    keep_nulls: bool = False,
    fire_triggers: bool = False,
    use_internal_transaction: bool = False,
) -> Dict[str, Any]

What Changed

Aspect	Before	After
Parameter style	**kwargs	Explicit parameters
IDE support	No autocomplete	✅ Full autocomplete
Type safety	Optional[bool] = None	bool = False
batch_size	Optional[int] = None	int = 0 (0 = server optimal)
column_mappings	List[Tuple[Union[str, int], str]]	Union[List[str], List[Tuple[int, str]]]

Column Mappings

Per @amachanic's feedback, now supports simpler format:

Simple - List[str]:

column_mappings = ['UserID', 'FirstName', 'Email']

Advanced - List[Tuple[int, str]]:

column_mappings = [(0, 'UserID'), (1, 'FirstName'), (3, 'Email')]

[Copilot]

Pull request overview

Refactors Cursor._bulkcopy to replace **kwargs bulk-copy options with an explicit, type-hinted parameter list and updated docstring.

Changes:

• Replaced **kwargs in _bulkcopy with explicit parameters (e.g., batch_size, timeout, column_mappings, and bulk-copy flags).
• Expanded _bulkcopy docstring to document supported bulk copy options.
• Updated the pycore_cursor.bulkcopy(...) invocation to pass the new explicit parameters.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

batch_size is typed as Optional[int], but the validation accepts floats (isinstance(batch_size, (int, float))) while the error message says “positive integer”. Please align the type hint, validation, and message (either require an int, or explicitly support non-integer values and document why).

Suggested change

	batch_size: Optional[int] = None,
	batch_size: Optional[Union[int, float]] = None,

[github-actions]

📊 Code Coverage Report

🔥 Diff Coverage 100%

🎯 Overall Coverage 76%

📈 Total Lines Covered: 5472 out of 7137 📁 Project: mssql-python

---

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

No lines with coverage information in this diff.

---

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.hpp: 58.8%
mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.row.py: 66.2%
mssql_python.pybind.ddbc_bindings.cpp: 69.3%
mssql_python.pybind.ddbc_bindings.h: 69.7%
mssql_python.pybind.connection.connection.cpp: 75.3%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 79.6%
mssql_python.connection.py: 84.1%
mssql_python.cursor.py: 84.7%

---

🔗 Quick Links

⚙️ Build Summary	📋 Coverage Details
View Azure DevOps Build	Browse Full Coverage Report

[subrata-ms]

Could you please provide more details in the PR summary for this change?
This API change may not be scalable in future as any new parameter addition need to go through the API contract change which is not advisable.

[bewithgaurav]

The conversation around new API spec is happening in Github Discussions topic #414
I'll update the PR summary with the new spec details and link to the above discussion shortly
will ping once done

[bewithgaurav]

done - updated, pls recheck and let me know if you have any comments