You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[GEN-2381] Pandas handling of nullable cells, [SYNPY-1690] Adding support for Python 3.14 and dropping support for python 3.9 (#1272)
[GEN-2381] Pandas handling of nullable cells
[SYNPY-1690] Adding support for Python 3.14 and dropping support for python 3.9
---------
Co-authored-by: danlu1 <dan.lu@sagebase.org>
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+59-1Lines changed: 59 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -93,7 +93,7 @@ copied to forks).
93
93
#### Installing the Python Client in a virtual environment with pipenv
94
94
Perform the following one-time steps to set up your local environment.
95
95
96
-
1. This package uses Python, if you have not already, please install [pyenv](https://github.com/pyenv/pyenv#installation) to manage your Python versions. Versions supported by this package are all versions >=3.9 and <=3.13. If you do not install `pyenv` make sure that Python and `pip` are installed correctly and have been added to your PATH by running `python3 --version` and `pip3 --version`. If your installation was successful, your terminal will return the versions of Python and `pip` that you installed. **Note**: If you have `pyenv` it will install a specific version of Python for you.
96
+
1. This package uses Python, if you have not already, please install [pyenv](https://github.com/pyenv/pyenv#installation) to manage your Python versions. Versions supported by this package are all versions >=3.10 and <=3.14. If you do not install `pyenv` make sure that Python and `pip` are installed correctly and have been added to your PATH by running `python3 --version` and `pip3 --version`. If your installation was successful, your terminal will return the versions of Python and `pip` that you installed. **Note**: If you have `pyenv` it will install a specific version of Python for you.
97
97
98
98
2. Install `pipenv` by running `pip install pipenv`.
99
99
- If you already have `pipenv` installed, ensure that the version is >=2023.9.8 to avoid compatibility issues.
@@ -223,6 +223,64 @@ When integration tests are ran in the Github CI/CD pipeline it will upload the t
223
223
#### Integration testing for external collaborators
224
224
As an external collaborator you will not have access to a development account and environment to run the integration tests against. Either request that a Sage Bionetworks staff member run your integration tests via a pull request, or, contact us via the [Service Desk](https://sagebionetworks.jira.com/servicedesk/customer/portal/9) to requisition a development account for integration testing only.
225
225
226
+
### Managing Python version changes
227
+
228
+
When adding support for a new Python version or dropping support for an old version, several files across the codebase and CI/CD pipelines must be updated to ensure consistency and proper testing coverage.
229
+
230
+
#### Adding a new Python version
231
+
232
+
When adding support for a new Python version (e.g., adding Python 3.15), update the following:
233
+
234
+
**Code configuration files:**
235
+
1. **`setup.cfg`**:
236
+
- Add the new version to the `classifiers` list under `[metadata]` (e.g., `Programming Language :: Python :: 3.15`)
237
+
- Update the `python_requires` constraint under `[options]` to include the new version (e.g., `>=3.10, <3.16`)
238
+
239
+
2. **`pyproject.toml`**:
240
+
- Update the `target-version` list in the `[tool.black]` section to include the new version if needed
241
+
242
+
3. **`Dockerfile`**:
243
+
- Update the base image to use the new Python version (e.g., `FROM python:3.15-slim`)
244
+
245
+
**CI/CD configuration files:**
246
+
1. **`.github/workflows/build.yml`**:
247
+
- Add the new version to the `python` matrix under the `test` job strategy
248
+
- Ensure the new version is included in integration test runs (typically the latest version should be tested)
249
+
- Update any Python version comments or documentation within the workflow
250
+
251
+
**Testing:**
252
+
- Run the full test suite (both unit and integration tests) on the new Python version locally before submitting a PR
253
+
- Verify that all CI/CD pipelines pass with the new version included
254
+
255
+
#### Dropping an old Python version
256
+
257
+
When dropping support for an old Python version (e.g., removing Python 3.10), update the following:
258
+
259
+
**Code configuration files:**
260
+
1. **`setup.cfg`**:
261
+
- Remove the old version from the `classifiers` list under `[metadata]`
262
+
- Update the `python_requires` constraint under `[options]` to reflect the new minimum version (e.g., `>=3.11, <3.15`)
263
+
264
+
2. **`pyproject.toml`**:
265
+
- Update the `target-version` list in the `[tool.black]` section to remove the old version
266
+
267
+
3. **`Dockerfile`**:
268
+
- Ensure the base image uses a supported Python version
269
+
270
+
**CI/CD configuration files:**
271
+
1. **`.github/workflows/build.yml`**:
272
+
- Remove the old version from the `python` matrix under the `test` job strategy
273
+
- Update the cache key version (e.g., increment `v28` to `v29`) to invalidate old caches
274
+
275
+
**Documentation:**
276
+
- Update the README.md and any getting started documentation to reflect the new supported Python version range
277
+
- Update CONTRIBUTING.md (this file) if it mentions specific Python versions in examples
278
+
279
+
**Important considerations:**
280
+
- Python version changes should be coordinated with a release and clearly communicated in release notes
281
+
- Breaking compatibility with a Python version is a significant change and should typically coincide with a major or minor version bump
282
+
- Always test thoroughly on the minimum and maximum supported Python versions before release
283
+
226
284
### Asynchronous methods
227
285
[Asyncio](https://docs.python.org/3/library/asyncio.html) is the future of the Synapse
228
286
Python Client. As such, the expectation is that all future methods that rely on async
Starting with Python 3.14, changes to the asyncio implementation affect how the Synapse Python Client works in Jupyter notebooks and other async contexts. This document explains what changed, why, and how it impacts your code.
6
+
7
+
**TL;DR:** Python 3.14+ breaks the `nest_asyncio` workaround. In Jupyter notebooks, you must now use async methods with `await` (e.g., `await obj.get_async()` instead of `obj.get()`). Regular scripts are unaffected.
8
+
9
+
## Background: How Jupyter Notebooks Run Code
10
+
11
+
Jupyter notebooks run all code within an active asyncio event loop. This means:
12
+
13
+
-**Async functions** must be called with `await my_async_function()`
14
+
-**Synchronous functions** can be called normally with `my_function()`
15
+
-**You cannot use**`asyncio.run()` because asyncio intentionally prevents nested event loops (to avoid threading and deadlock issues)
16
+
17
+
## What Changed in Python 3.14
18
+
19
+
### Previous Behavior (Python 3.13 and earlier)
20
+
21
+
The Synapse Python Client used a library called `nest_asyncio` to work around asyncio's nested event loop restriction. This allowed us to:
22
+
23
+
1. Detect whether code was running in a notebook (with an active event loop) or a regular script
24
+
2. Automatically call async functions from synchronous wrapper functions
25
+
3. Provide a seamless synchronous API that worked in both environments
26
+
27
+
**This meant you could write:**
28
+
```python
29
+
from synapseclient import Synapse
30
+
from synapseclient.models import Project
31
+
32
+
syn = Synapse()
33
+
syn.login()
34
+
35
+
# This worked in notebooks AND regular scripts
36
+
my_project = Project(name="My Project").get()
37
+
```
38
+
39
+
### New Behavior (Python 3.14+)
40
+
41
+
Python 3.14 changed the asyncio implementation in ways that break `nest_asyncio`. The library can no longer safely monkey-patch asyncio.
42
+
43
+
**Impact:** The automatic async-to-sync conversion no longer works in notebooks on Python 3.14+.
44
+
45
+
> **Why the change?** Python 3.14 improved asyncio's safety to prevent deadlocks and race conditions. The `nest_asyncio` workaround bypassed these safety mechanisms and now causes failures in HTTP connection pooling. Rather than risk silent failures, the library raises clear errors when async methods should be used.
46
+
47
+
## How This Affects Your Code
48
+
49
+
### In Regular Python Scripts
50
+
51
+
**No changes needed.** Synchronous methods continue to work as before:
52
+
53
+
```python
54
+
from synapseclient import Synapse
55
+
from synapseclient.models import Project
56
+
57
+
syn = Synapse()
58
+
syn.login()
59
+
60
+
# This still works in regular scripts
61
+
my_project = Project(name="My Project").get()
62
+
```
63
+
64
+
### In Jupyter Notebooks (Python 3.14+)
65
+
66
+
**You must use async methods directly** with `await`:
0 commit comments