MAINT: io: migration to use sparray in IO

[dschult]

This PR migrates sparse.io to use sparse arrays internally and to read files into either sparray or spmatrix.
The primary functions that can (depending on the file contents) return sparse containers are:
scipy.io.loadmat, scipy.io.hb_read, scipy.io.mmread.
These can also be accessed via scipy.io.matlab.loadmat, scipy._harwell_boeing.hb_read scipy.io._fast_matrix_market.mmread, and alternate version of mmread is available at scipy.io._mmio.mmread.

Each of those functions currently returns a sparse matrix. This PR adds a kwarg sparray=None indicating (bool) whether this should return a sparray or an spmatrix. The default is None indicating a preference has not been provided.
The default value is set to None, but is deprecated in release 1.15 with a change of default to sparray coming in 1.17.

The deprecation in the doc_strings is:

    .. deprecated:: 1.15.0
        The default sparse return type of ``coo_matrix`` has been deprecated
        in favour of ``coo_array``. Default will be changed in SciPy 1.17.0.
        Use new argument ``sparray=True`` to anticipate the future, or
        ``False`` to silence the warning and return ``coo_matrix`` even
        after the change in default.

And the DeprecationWarning message is shown when a sparse container is returned and sparray is None. The warning message is:

                msg = ("The default sparse return type, ``coo_matrix``, has"
                       " been deprecated in favour of ``coo_array``."
                       " Default will be changed in SciPy 1.17.0."
                       " Use new argument ``sparray=True`` to anticipate"
                       " the future, or ``False`` to silence the warning and"
                       " return ``coo_matrix`` even after the change in default.")
                warnings.warn(msg, DeprecationWarning, stacklevel=2)

I hope I have the stack levels correct. It seems to be OK because the tests picked up the warnings before I updated them to avoid it.

Outside of those functions, the helper functions and classes/methods and the tests now work with sparse arrays.

After the deprecation period for the deault return value, the default will shift to returning sparse arrays, though folks who choose to quite the deprecation warning by setting sparray=False will still get spmatrix.

The dev.py smoke-docs doesn't reach all doc_tests in this subpackage. But dev.py smoke-docs -t scipy/io/_mmio.py showed a number of errors that I corrected here (hopefully those fixes will work with the CI doctests too).

One test in sparse.csgraph uses mmread and had to be updated.

[rgommers]

Thanks @dschult! Before looking at the details, my main comment here is about the migration strategy, which doesn't look ideal. The current approach shows every user of these functions a deprecation warning, and then to avoid it they have a choice between:

1. Explicitly add sparray=False, or
2. Write an if scipy_version>=1.15: sparray=True else: leave-out-sparray-kw

(2) is quite awkward and in addition it doesn't get you the same behavior for your code for older and newer SciPy. Hence most users probably need to go with (1).

It seems much cleaner to just add an sparray=False keyword, which lets users opt into returning arrays and otherwise it gets you the same outcome as (1) but without all users needing to change their code. And then when the matrix classes themselves get deprecated, those users will see a deprecation warning. That's a few releases away, so the if-else dance is then no longer needed.

[dschult]

Done. I've set the new keyword to be sparray=False. This will avoid making users check scipy_version for the ability to use sparray.

[dschult]

Perhaps a better name for the keyword is spmatrix=True rather than sparray=False. The name makes the eventual removal of the keyword feel more natural.

[rgommers]

Perhaps a better name for the keyword is spmatrix=True rather than sparray=False. The name makes the eventual removal of the keyword feel more natural.

Sure, that sounds fine to me. I suspect it comes down to the same thing - one has to start using the keyword at some point to avoid a deprecation warning.

[dschult]

I've switched the kwarg name from sparray=False to spmatrix=True.

The lint errors are UP031 due to the new ruff version (format strings). And the changes are subtle in the io subpackage. I think some of these changes are good examples for why Python needs to keep %. So let's make those in a different PR so we pay close attention.

[rgommers]

The lint errors are UP031 due to the new ruff version (format strings

Yeah it'd be nice to turn those off ....

[dschult]

I think this is ready to merge. @rgommers did you want to look at this one more time?

[rgommers]

My comments were addressed, changes look good, and CI is happy - let's give this a go. Thanks @dschult!