feat: Switch set_ to with_ and add deprecated alias

[erichare]

Fixes #345

This pull request refactors the CollectionDefinition fluent interface to improve clarity and convey its immutable builder pattern. All set_* methods have been renamed to with_* (e.g., set_vector_dimension → with_vector_dimension) and deprecated aliases are provided for backward compatibility. Documentation and code examples throughout the codebase have been updated to match the new interface. These changes make the API more intuitive and signal that builder methods return new objects instead of mutating in place.

Refactoring of the fluent interface:

• Renamed all set_* methods in CollectionDefinition to with_*, including with_indexing, with_default_id, with_vector_dimension, with_vector_metric, with_vector_source_model, with_vector_service, with_rerank, and with_lexical. Deprecated the old set_* methods, which will be removed in version 3.0.0. (astrapy/data/info/collection_descriptor.py, [1] [2] [3] [4] [5]

Documentation and example updates:

• Updated all code examples and documentation in README.md, astrapy/data/collection.py, astrapy/data/database.py, astrapy/client.py, astrapy/admin/admin.py, and astrapy/authentication.py to use the new with_* methods instead of set_*. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24] [25]

Deprecation mechanism:

• Introduced the @deprecated_method decorator to mark old set_* methods as deprecated, providing guidance on their replacement and versioning information. (astrapy/data/info/collection_descriptor.py, [1] [2] [3] [4] [5]

These changes collectively modernize the builder API, improve code clarity, and ensure smooth migration for users.

[erichare]

Superseded by #410 — rebased onto the latest main (resolved the CHANGES conflict) and moved to a branch in datastax/astrapy (instead of my fork). Closing in favor of that PR.