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

[subrata-ms]

I am still not convinced about moving out from **kwargs completly.
Can we group the parameters logically with couple of parameter?

[amachanic]

I am still not convinced about moving out from **kwargs completly. Can we group the parameters logically with couple of parameter?

Hi @subrata-ms, can you please be more specific with regard to why you're not convinced here? We discussed in the thread linked above and those of us on the end user side who decided to participate seemed to agree that this is a good design. As someone who has worked with SQL Server bulk copy libraries for over 20 years in a number of different languages I feel that this is the best possible option from a usability perspective: The parameters will be obvious and easily discovered by users. Introducing a required external object here won't be especially helpful and users will just have to jump through another hoop when making small changes. And while it does seem like there are a touch more parameters here than we usually see, the real concern should be forward maintainability -- but there is none. These basic parameters haven't changed in all of the time I've been working with SQL Server and I seriously doubt they ever will.

[subrata-ms]

Hi @amachanic , I would suggest, we discuss these API design approach options in the API Design Review forum so we can gather broader feedback. ( #414 ).