[SYNPY-1800] Added new sync_to_synapse method

[andrewelamb]

Problem:

The syncToSynapse function doesn't fit the new OOP model paradigm.

Solution:

• A new sync_to_synapse method was added to the StorableContainer class
• syncToSynapse was deprecated

Testing:

• Unit tests for the new helper functions
• Integration tests for the new sync_to_synapse method

[linglp]

Old syncToSynapse defaults to sendMessages=True, and new sync_to_synapse defaults to send_messages=False. Users migrating by following the deprecation example will silently stop receiving upload notifications with no warning. Is this behavior intentional?

Also, _create_local_test_file leaves cleanup to the caller. I think it will be better if clean up can happen within _create_local_test_file so that we could avoid all the scattered schedule_for_cleanup calls.

[linglp]

Thanks for the fixes! Just some small comments. Also, could you make sure that the documentation format is correct?

For example, the format here is slightly off. Also, the links in reference are not working (See here)

[linglp]

Hi @andrewelamb ! I found more problems with the documentation. Please see comments below

[linglp]

@andrewelamb Thanks for the last round of fixes. there are still some problems with tests and documentation. Could you check again?

[linglp]

Take a look at the old documentation here: https://python-docs.synapse.org/en/stable/explanations/manifest_tsv/?h=manifest#multiple-values-of-annotations-per-key, the examples here are much shorter. Is this epxected?

[andrewelamb]

Yes, I wasn't sure all the examples needed to be included. What do you think?

[linglp]

probably this needs to be fixed in a different PR. Is there a typo in the function name here? should this be topological_sort instead of topolgical_sort?

[andrewelamb]

That is correct. We would need to decide if this is a public function, and if so it would need to be deprecated first.

[linglp]

should we be using asyncio.get_event_loop() here? Based on the documentation, for Python 3.10+, we should consider using asyncio.run

[andrewelamb]

So Claude says on this :

In this context — an async test function — neither asyncio.get_event_loop() nor asyncio.run() is the right choice. 
Since the test is already running inside an async event loop (managed by pytest-asyncio), the correct approach is:                                      
                                                                                                                                                                                                                                        
  dep_future = asyncio.get_running_loop().create_future()                                                                                                                                                                               
                                                                                                                                                                                                                                        
  - get_event_loop() is deprecated for this use case in 3.10+ and emits a deprecation warning when no running loop exists.                                                                                                              
  - asyncio.run() would try to create a new event loop, which conflicts with the already-running one.
  - get_running_loop() is the correct call from within an async function — it returns the loop that's already executing the test.  

[linglp]

There are still some problems with tests and documentation. One concern that I have is that a lot of tests are relying on sync_from_synapse_async for clean up which means if the assertion failed after sync_from_synapse_async or the function itself failed, the test files won't be cleaned up at all. But overall it looks good!