synapseclient 4.7.0__tar.gz → 4.9.0__tar.gz

{synapseclient-4.7.0/synapseclient.egg-info → synapseclient-4.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: synapseclient
-Version: 4.7.0
+Version: 4.9.0
 Summary: A client for Synapse, a collaborative, open-source research platform that allows teams to share data, track analyses, and collaborate.
 Home-page: https://www.synapse.org
 Author: The Synapse Engineering Team
@@ -9,7 +9,7 @@ License: Apache-2.0
 Project-URL: Source, https://github.com/Sage-Bionetworks/synapsePythonClient
 Project-URL: Tracker, https://github.com/Sage-Bionetworks/synapsePythonClient/issues
 Project-URL: Documentation, https://python-docs.synapse.org
-Project-URL: Changelog, https://python-docs.synapse.org/build/html/index.html#release-notes
+Project-URL: Changelog, https://python-docs.synapse.org/en/stable/news/
 Platform: any
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Python
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: Unix
@@ -27,7 +28,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
-Requires-Python: <3.13,>=3.9
+Requires-Python: <3.14,>=3.9
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Requires-Dist: requests<3.0,>=2.22.0
 Requires-Dist: urllib3<2,>=1.26.18
@@ -41,15 +42,16 @@ Requires-Dist: opentelemetry-instrumentation-threading>=0.48b0
 Requires-Dist: opentelemetry-instrumentation-urllib>=0.48b0
 Requires-Dist: nest-asyncio~=1.6.0
 Requires-Dist: asyncio-atexit~=1.0.1
-Requires-Dist: httpx~=0.27.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: httpcore>=1.0.9
 Requires-Dist: tqdm<5.0,>=4.66.2
 Requires-Dist: async-lru~=2.0.4
 Requires-Dist: psutil~=5.9.8
 Provides-Extra: dev
-Requires-Dist: pytest<8.0,>=7.0.0; extra == "dev"
+Requires-Dist: pytest~=8.2.0; extra == "dev"
 Requires-Dist: pytest-mock<4.0,>=3.0; extra == "dev"
 Requires-Dist: pytest-socket~=0.6.0; extra == "dev"
-Requires-Dist: pytest-asyncio<1.0,>=0.23.6; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0,>=0.25.0; extra == "dev"
 Requires-Dist: flake8<4.0,>=3.7.0; extra == "dev"
 Requires-Dist: pytest-xdist[psutil]<3.0.0,>=2.2; extra == "dev"
 Requires-Dist: pytest-rerunfailures~=12.0; extra == "dev"
@@ -59,10 +61,10 @@ Requires-Dist: black; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pandas<3.0,>=1.5; extra == "dev"
 Provides-Extra: tests
-Requires-Dist: pytest<8.0,>=7.0.0; extra == "tests"
+Requires-Dist: pytest~=8.2.0; extra == "tests"
 Requires-Dist: pytest-mock<4.0,>=3.0; extra == "tests"
 Requires-Dist: pytest-socket~=0.6.0; extra == "tests"
-Requires-Dist: pytest-asyncio<1.0,>=0.23.6; extra == "tests"
+Requires-Dist: pytest-asyncio<1.0,>=0.25.0; extra == "tests"
 Requires-Dist: flake8<4.0,>=3.7.0; extra == "tests"
 Requires-Dist: pytest-xdist[psutil]<3.0.0,>=2.2; extra == "tests"
 Requires-Dist: pytest-rerunfailures~=12.0; extra == "tests"
@@ -88,7 +90,7 @@ Python Synapse Client
 =====================
 
 Branch  | Build Status
---------|-------------
+--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 develop | [![Build Status develop branch](https://github.com/Sage-Bionetworks/synapsePythonClient/workflows/build/badge.svg?branch=develop)](https://github.com/Sage-Bionetworks/synapsePythonClient/actions?query=branch%3Adevelop)
 master  | [![Build Status master branch](https://github.com/Sage-Bionetworks/synapsePythonClient/workflows/build/badge.svg?branch=master)](https://github.com/Sage-Bionetworks/synapsePythonClient/actions?query=branch%3Amaster)
 
@@ -122,7 +124,7 @@ or by sending an email to [python-announce+subscribe@sagebase.org](mailto:python
 Installation
 ------------
 
-The Python Synapse client has been tested on versions 3.9, 3.10, 3.11 and 3.12 on Mac OS X, Ubuntu Linux and Windows.
+The Python Synapse client has been tested on versions 3.9, 3.10, 3.11, 3.12 and 3.13 on Mac OS X, Ubuntu Linux and Windows.
 
 **Starting from Synapse Python client version 3.0, Synapse Python client requires Python >= 3.9**
 
@@ -359,7 +361,7 @@ The purpose of synapseutils is to create a space filled with convenience functio
 
 OpenTelemetry (OTEL)
 --------------------------------
-[OpenTelemetry](https://opentelemetry.io/) helps support the analysis of traces and spans which can provide insights into latency, errors, and other performance metrics. The synapseclient is ready to provide traces should you want them. The Synapse Python client supports OTLP Exports and can be configured via environment variables as defined [here](https://opentelemetry-python.readthedocs.io/en/stable/exporter/otlp/otlp.html).
+[OpenTelemetry](https://opentelemetry.io/) helps support the analysis of traces and spans which can provide insights into latency, errors, and other performance metrics. The synapseclient is ready to provide traces should you want them. The Synapse Python client supports OTLP Exports and can be configured via environment variables as defined [here](https://opentelemetry.io/docs/specs/otel/protocol/exporter/).
 
 Read more about OpenTelemetry in Python [here](https://opentelemetry.io/docs/instrumentation/python/)
 
@@ -376,47 +378,87 @@ docker run --name jaeger \
   jaegertracing/all-in-one:latest
 ```
 Explanation of ports:
-* `4318` HTTP
-* `16686` Jaeger UI
+* `4318` HTTP port for OTLP data collection
+* `16686` Jaeger UI for visualizing traces
 
 Once the docker container is running you can access the Jaeger UI via: `http://localhost:16686`
 
-#### Example
-By default the OTEL exporter sends trace data to `http://localhost:4318/v1/traces`, however you may override this by setting the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable.
+#### Environment Variable Configuration
 
-```
+By default, the OTEL exporter sends trace data to `http://localhost:4318/v1/traces`. You can customize the behavior through environment variables:
+
+* `OTEL_SERVICE_NAME`: Defines a unique identifier for your application or service in telemetry data (defaults to 'synapseclient'). Set this to a descriptive name that represents your specific implementation, making it easier to filter and analyze traces in your monitoring system.
+* `OTEL_EXPORTER_OTLP_ENDPOINT`: Specifies the destination URL for sending telemetry data (defaults to 'http://localhost:4318'). Configure this to direct data to your preferred OpenTelemetry collector or monitoring service.
+* `OTEL_DEBUG_CONSOLE`: Controls local visibility of telemetry data. Set to 'true' to output trace information to the console, which is useful for development and troubleshooting without an external collector.
+* `OTEL_SERVICE_INSTANCE_ID`: Distinguishes between multiple instances of the same service (e.g., 'prod', 'development', 'local'). This helps identify which specific deployment or environment generated particular traces.
+* `OTEL_EXPORTER_OTLP_HEADERS`: Configures authentication and metadata for telemetry exports. Use this to add API keys, authentication tokens, or custom metadata when sending traces to secured collectors or third-party monitoring services.
+
+
+#### Enabling OpenTelemetry in your code
+To enable OpenTelemetry with the Synapse Python client, simply call the
+`enable_open_telemetry()` method on the Synapse class. Additionally you can access an
+instance of the OpenTelemetry tracer via the `get_tracer()` call. This will allow you
+to create new spans for your code.
+
+```python
 import synapseclient
-from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-from opentelemetry.sdk.resources import SERVICE_NAME, Resource
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-
-trace.set_tracer_provider(
-    TracerProvider(
-        resource=Resource(attributes={SERVICE_NAME: "my_own_code_above_synapse_client"})
-    )
-)
-trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
-tracer = trace.get_tracer("my_tracer")
-synapseclient.Synapse.enable_open_telemetry(True)
 
-@tracer.start_as_current_span("my_span_name")
-def main():
+# Enable OpenTelemetry with default settings
+synapseclient.Synapse.enable_open_telemetry()
+tracer = synapseclient.Synapse.get_tracer()
+
+# Then create and use the Synapse client as usual
+with tracer.start_as_current_span("my_function_span"):
     syn = synapseclient.Synapse()
-    syn.login()
-    my_entity = syn.get("syn52569429")
-    print(my_entity)
+    syn.login(authToken='auth_token')
+```
 
-main()
+#### Advanced Configuration
+
+You can pass additional resource attributes to `enable_open_telemetry()`:
+
+```python
+import synapseclient
+
+# Enable with custom resource attributes
+synapseclient.Synapse.enable_open_telemetry(
+    resource_attributes={
+        "deployment.environment": "development",
+        "service.version": "1.2.3", # Overrides the `OTEL_SERVICE_NAME` environment variable
+        "service.instance.id": "4.5.6",  # Overrides the `OTEL_SERVICE_INSTANCE_ID` environment variable
+        "custom.attribute": "value"
+    }
+)
 ```
 
+When OpenTelemetry is enabled in the Synapse client, the following happens automatically:
+
+1. Instrumentation is set up for:
+   - **Threading** (via `ThreadingInstrumentor`): Ensures proper context propagation across threads, which is essential for maintaining trace continuity in multi-threaded applications
+   - **HTTP libraries**:
+     - `requests` (via `RequestsInstrumentor`): Captures all HTTP requests made using the requests library, including methods, URLs, status codes, and timing information
+     - `httpx` (via `HTTPXClientInstrumentor`): Tracks both synchronous and asynchronous HTTP requests made with the httpx library
+     - `urllib` (via `URLLibInstrumentor`): Monitors lower-level HTTP operations made directly with Python's standard library
+   - Each instrumented HTTP library includes custom hooks that extract Synapse entity IDs from URLs when possible and add them as span attributes
+
+2. Traces are configured to collect spans across your application:
+   - Spans automatically capture operation duration, status, and errors.
+   - An attribute propagation mechanism ensures that certain attributes (like `synapse.transfer.direction` and `synapse.operation.category`) are properly passed to child spans for uploads/downloads.
+   - Trace data is exported via OTLP (OpenTelemetry Protocol).
+
+3. Resource information is automatically added to your traces, including:
+   - Python version
+   - OS type
+   - Synapse client version
+   - Service name (defaults to "synapseclient" but can be customized via environment variables)
+   - Service instance ID
 
+Note that once enabled, OpenTelemetry cannot be disabled in the same process - you would need to restart your Python interpreter to disable it.
 
 
 License and Copyright
 ---------------------
 
-&copy; Copyright 2013-23 Sage Bionetworks
+&copy; Copyright 2013-25 Sage Bionetworks
 
 This software is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

{synapseclient-4.7.0 → synapseclient-4.9.0}/README.md

@@ -2,7 +2,7 @@ Python Synapse Client
 =====================
 
 Branch  | Build Status
---------|-------------
+--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 develop | [![Build Status develop branch](https://github.com/Sage-Bionetworks/synapsePythonClient/workflows/build/badge.svg?branch=develop)](https://github.com/Sage-Bionetworks/synapsePythonClient/actions?query=branch%3Adevelop)
 master  | [![Build Status master branch](https://github.com/Sage-Bionetworks/synapsePythonClient/workflows/build/badge.svg?branch=master)](https://github.com/Sage-Bionetworks/synapsePythonClient/actions?query=branch%3Amaster)
 
@@ -36,7 +36,7 @@ or by sending an email to [python-announce+subscribe@sagebase.org](mailto:python
 Installation
 ------------
 
-The Python Synapse client has been tested on versions 3.9, 3.10, 3.11 and 3.12 on Mac OS X, Ubuntu Linux and Windows.
+The Python Synapse client has been tested on versions 3.9, 3.10, 3.11, 3.12 and 3.13 on Mac OS X, Ubuntu Linux and Windows.
 
 **Starting from Synapse Python client version 3.0, Synapse Python client requires Python >= 3.9**
 
@@ -273,7 +273,7 @@ The purpose of synapseutils is to create a space filled with convenience functio
 
 OpenTelemetry (OTEL)
 --------------------------------
-[OpenTelemetry](https://opentelemetry.io/) helps support the analysis of traces and spans which can provide insights into latency, errors, and other performance metrics. The synapseclient is ready to provide traces should you want them. The Synapse Python client supports OTLP Exports and can be configured via environment variables as defined [here](https://opentelemetry-python.readthedocs.io/en/stable/exporter/otlp/otlp.html).
+[OpenTelemetry](https://opentelemetry.io/) helps support the analysis of traces and spans which can provide insights into latency, errors, and other performance metrics. The synapseclient is ready to provide traces should you want them. The Synapse Python client supports OTLP Exports and can be configured via environment variables as defined [here](https://opentelemetry.io/docs/specs/otel/protocol/exporter/).
 
 Read more about OpenTelemetry in Python [here](https://opentelemetry.io/docs/instrumentation/python/)
 
@@ -290,47 +290,87 @@ docker run --name jaeger \
   jaegertracing/all-in-one:latest
 ```
 Explanation of ports:
-* `4318` HTTP
-* `16686` Jaeger UI
+* `4318` HTTP port for OTLP data collection
+* `16686` Jaeger UI for visualizing traces
 
 Once the docker container is running you can access the Jaeger UI via: `http://localhost:16686`
 
-#### Example
-By default the OTEL exporter sends trace data to `http://localhost:4318/v1/traces`, however you may override this by setting the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable.
+#### Environment Variable Configuration
 
-```
+By default, the OTEL exporter sends trace data to `http://localhost:4318/v1/traces`. You can customize the behavior through environment variables:
+
+* `OTEL_SERVICE_NAME`: Defines a unique identifier for your application or service in telemetry data (defaults to 'synapseclient'). Set this to a descriptive name that represents your specific implementation, making it easier to filter and analyze traces in your monitoring system.
+* `OTEL_EXPORTER_OTLP_ENDPOINT`: Specifies the destination URL for sending telemetry data (defaults to 'http://localhost:4318'). Configure this to direct data to your preferred OpenTelemetry collector or monitoring service.
+* `OTEL_DEBUG_CONSOLE`: Controls local visibility of telemetry data. Set to 'true' to output trace information to the console, which is useful for development and troubleshooting without an external collector.
+* `OTEL_SERVICE_INSTANCE_ID`: Distinguishes between multiple instances of the same service (e.g., 'prod', 'development', 'local'). This helps identify which specific deployment or environment generated particular traces.
+* `OTEL_EXPORTER_OTLP_HEADERS`: Configures authentication and metadata for telemetry exports. Use this to add API keys, authentication tokens, or custom metadata when sending traces to secured collectors or third-party monitoring services.
+
+
+#### Enabling OpenTelemetry in your code
+To enable OpenTelemetry with the Synapse Python client, simply call the
+`enable_open_telemetry()` method on the Synapse class. Additionally you can access an
+instance of the OpenTelemetry tracer via the `get_tracer()` call. This will allow you
+to create new spans for your code.
+
+```python
 import synapseclient
-from opentelemetry import trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-from opentelemetry.sdk.resources import SERVICE_NAME, Resource
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-
-trace.set_tracer_provider(
-    TracerProvider(
-        resource=Resource(attributes={SERVICE_NAME: "my_own_code_above_synapse_client"})
-    )
-)
-trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
-tracer = trace.get_tracer("my_tracer")
-synapseclient.Synapse.enable_open_telemetry(True)
 
-@tracer.start_as_current_span("my_span_name")
-def main():
+# Enable OpenTelemetry with default settings
+synapseclient.Synapse.enable_open_telemetry()
+tracer = synapseclient.Synapse.get_tracer()
+
+# Then create and use the Synapse client as usual
+with tracer.start_as_current_span("my_function_span"):
     syn = synapseclient.Synapse()
-    syn.login()
-    my_entity = syn.get("syn52569429")
-    print(my_entity)
+    syn.login(authToken='auth_token')
+```
 
-main()
+#### Advanced Configuration
+
+You can pass additional resource attributes to `enable_open_telemetry()`:
+
+```python
+import synapseclient
+
+# Enable with custom resource attributes
+synapseclient.Synapse.enable_open_telemetry(
+    resource_attributes={
+        "deployment.environment": "development",
+        "service.version": "1.2.3", # Overrides the `OTEL_SERVICE_NAME` environment variable
+        "service.instance.id": "4.5.6",  # Overrides the `OTEL_SERVICE_INSTANCE_ID` environment variable
+        "custom.attribute": "value"
+    }
+)
 ```
 
+When OpenTelemetry is enabled in the Synapse client, the following happens automatically:
+
+1. Instrumentation is set up for:
+   - **Threading** (via `ThreadingInstrumentor`): Ensures proper context propagation across threads, which is essential for maintaining trace continuity in multi-threaded applications
+   - **HTTP libraries**:
+     - `requests` (via `RequestsInstrumentor`): Captures all HTTP requests made using the requests library, including methods, URLs, status codes, and timing information
+     - `httpx` (via `HTTPXClientInstrumentor`): Tracks both synchronous and asynchronous HTTP requests made with the httpx library
+     - `urllib` (via `URLLibInstrumentor`): Monitors lower-level HTTP operations made directly with Python's standard library
+   - Each instrumented HTTP library includes custom hooks that extract Synapse entity IDs from URLs when possible and add them as span attributes
+
+2. Traces are configured to collect spans across your application:
+   - Spans automatically capture operation duration, status, and errors.
+   - An attribute propagation mechanism ensures that certain attributes (like `synapse.transfer.direction` and `synapse.operation.category`) are properly passed to child spans for uploads/downloads.
+   - Trace data is exported via OTLP (OpenTelemetry Protocol).
+
+3. Resource information is automatically added to your traces, including:
+   - Python version
+   - OS type
+   - Synapse client version
+   - Service name (defaults to "synapseclient" but can be customized via environment variables)
+   - Service instance ID
 
+Note that once enabled, OpenTelemetry cannot be disabled in the same process - you would need to restart your Python interpreter to disable it.
 
 
 License and Copyright
 ---------------------
 
-© Copyright 2013-23 Sage Bionetworks
+© Copyright 2013-25 Sage Bionetworks
 
 This software is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).

{synapseclient-4.7.0 → synapseclient-4.9.0}/setup.cfg

@@ -12,7 +12,7 @@ project_urls =
 	Source = https://github.com/Sage-Bionetworks/synapsePythonClient
 	Tracker = https://github.com/Sage-Bionetworks/synapsePythonClient/issues
 	Documentation = https://python-docs.synapse.org
-	Changelog = https://python-docs.synapse.org/build/html/index.html#release-notes
+	Changelog = https://python-docs.synapse.org/en/stable/news/
 platforms = any
 classifiers = 
 	Development Status :: 5 - Production/Stable
@@ -21,6 +21,7 @@ classifiers =
 	Programming Language :: Python :: 3.10
 	Programming Language :: Python :: 3.11
 	Programming Language :: Python :: 3.12
+	Programming Language :: Python :: 3.13
 	Operating System :: MacOS
 	Operating System :: Microsoft :: Windows
 	Operating System :: Unix
@@ -36,7 +37,7 @@ classifiers =
 zip_safe = False
 include_package_data = True
 packages = find:
-python_requires = >=3.9, <3.13
+python_requires = >=3.9, <3.14
 install_requires = 
 	requests>=2.22.0,<3.0
 	urllib3>=1.26.18,<2
@@ -50,15 +51,16 @@ install_requires =
 	opentelemetry-instrumentation-urllib>=0.48b0
 	nest-asyncio~=1.6.0
 	asyncio-atexit~=1.0.1
-	httpx~=0.27.0
+	httpx>=0.27.0
+	httpcore>=1.0.9
 	tqdm>=4.66.2,<5.0
 	async-lru~=2.0.4
 	psutil~=5.9.8
 tests_require = 
-	pytest>=7.0.0,<8.0
+	pytest~=8.2.0
 	pytest-mock>=3.0,<4.0
 	pytest-socket~=0.6.0
-	pytest-asyncio>=0.23.6,<1.0
+	pytest-asyncio>=0.25.0,<1.0
 	flake8>=3.7.0,<4.0
 	pytest-xdist[psutil]>=2.2,<3.0.0
 	pytest-rerunfailures~=12.0
@@ -68,10 +70,10 @@ tests_require =
 
 [options.extras_require]
 dev = 
-	pytest>=7.0.0,<8.0
+	pytest~=8.2.0
 	pytest-mock>=3.0,<4.0
 	pytest-socket~=0.6.0
-	pytest-asyncio>=0.23.6,<1.0
+	pytest-asyncio>=0.25.0,<1.0
 	flake8>=3.7.0,<4.0
 	pytest-xdist[psutil]>=2.2,<3.0.0
 	pytest-rerunfailures~=12.0
@@ -81,10 +83,10 @@ dev =
 	pre-commit
 	pandas>=1.5,<3.0
 tests = 
-	pytest>=7.0.0,<8.0
+	pytest~=8.2.0
 	pytest-mock>=3.0,<4.0
 	pytest-socket~=0.6.0
-	pytest-asyncio>=0.23.6,<1.0
+	pytest-asyncio>=0.25.0,<1.0
 	flake8>=3.7.0,<4.0
 	pytest-xdist[psutil]>=2.2,<3.0.0
 	pytest-rerunfailures~=12.0

{synapseclient-4.7.0 → synapseclient-4.9.0}/synapseclient/.synapseConfig

@@ -4,10 +4,18 @@
 
 ## Used for logging in to Synapse. See https://python-docs.synapse.org/tutorials/authentication/
 ## for information on retrieving an auth token.
-#[authentication]
-#username = <username>
-#authtoken = <authtoken>
 
+#[default]
+#username = default_user
+#authtoken = default_auth_token
+
+#[profile user1]
+#username = user1
+#authtoken = user1_auth_token
+
+#[profile user2]
+#username = user2
+#authtoken = user2_auth_token
 
 ## If you have projects with file stored on SFTP servers, you can specify your credentials here
 ## You can specify multiple sftp credentials