[SYNPY-1872] Deprecate migrate functions

[andrewelamb]

Problem:

The migrate functions/class in synapseutils needed to be deprecated.

Solution:

These were deprecated, pointing to the new functions/class they should be using.

[linglp]

But I noticed that there's minor inconsistentcy if you check class StorageLocationConfigurableSynchronousProtocol(Protocol):

  def index_files_for_migration(
      self,
      dest_storage_location_id: int,   # <-- typed as int
      ...

this is marked as integer but here it seems like this is a string? And also, the example in the protocol also uses integer instead of string.

[andrewelamb]

But I noticed that there's minor inconsistentcy if you check class StorageLocationConfigurableSynchronousProtocol(Protocol):

  def index_files_for_migration(
      self,
      dest_storage_location_id: int,   # <-- typed as int
      ...

this is marked as integer but here it seems like this is a string? And also, the example in the protocol also uses integer instead of string.

Was this comment meant for a different PR?

[linglp]

@andrewelamb It was meant for this PR here! I saw that you have the following example:

        # The new MigrationResult is returned by the migration methods on the
        # Project and Folder models
        result = Project(id="syn123").index_files_for_migration(
            dest_storage_location_id="12345", --> string 
        )

as the new example. But when I checked class StorageLocationConfigurableSynchronousProtocol(Protocol), I saw:

    def index_files_for_migration(
        self,
        dest_storage_location_id: int, --> int
        db_path: Optional[str] = None,
        *,
        source_storage_location_ids: Optional[List[int]] = None,
        file_version_strategy: str = "new",
        include_table_files: bool = False,
        continue_on_error: bool = False,
        synapse_client: Optional[Synapse] = None,
    ) -> "MigrationResult":

Also here index_files_for_migration_async marks dest_storage_location_id as integer too :

    async def index_files_for_migration_async(
        self,
        dest_storage_location_id: int, 
        db_path: Optional[str] = None,
        *,
        source_storage_location_ids: Optional[List[int]] = None,
        file_version_strategy: str = "new",
        include_table_files: bool = False,
        continue_on_error: bool = False,
        synapse_client: Optional[Synapse] = None,
    ) -> MigrationResult:

Should we update the example docstring in your PR to use integer?

[thomasyu888]

🔥 LGTM and I defer to @danlu1 and @BryanFauble for a final review here.

Dan contributed the new migration features

[danlu1]

Thanks for working on this. Just a few comments.

[danlu1]

Suggested change

	from synapseclient.models instead. The new method is called on the model
	from synapseclient.models.services instead. The new method is called on the model