feat: add get_path_url() function support for migration compatibility (#61)

* feat: add get_path_url() function support for migration compatibility

Add support for get_path_url() function to maintain compatibility with old
replicate-python client. This function extracts remote URLs from file output
objects, enabling users to reuse URLs in model inputs.

Key changes:
- Export get_path_url from main module (__init__.py)
- Add module-level function proxy in _module_client.py
- Enhance FileOutput classes with __url__ attribute for compatibility
- Add comprehensive test coverage for all supported object types
- Maintain backward compatibility with same API as old client

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: simplify get_path_url import chain by removing intermediary

Remove unnecessary lib/_get_path_url.py intermediary layer and import
get_path_url directly from lib/_predictions_use.py in _module_client.py.

This eliminates 32 lines of proxy code while maintaining identical
functionality and API compatibility.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: add bearer tokens to get_path_url tests to prevent auth errors

The FileOutput and AsyncFileOutput classes require authenticated clients.
Added TEST_TOKEN constant and provided bearer_token parameter to all
client instantiations in tests to fix CI authentication failures.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: use cleaner import pattern for get_path_url re-export

Replace lint suppression comments with explicit `import get_path_url as get_path_url`
pattern to make the re-export intent clearer and avoid lint suppressions.

Addresses PR feedback from RobertCraigle.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: import get_path_url directly in __init__.py instead of via module_client

Move get_path_url import to follow the same pattern as other lib/ exports
(FileOutput, Model, etc.) which are imported directly in __init__.py.

The _module_client.py is specifically for resource proxies and module-level
access patterns like replicate.models.list(), not for all top-level exports.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: remove get_path_url from module_client skip list

Since get_path_url is now imported directly in __init__.py (not from
_module_client), it should not be in the skip list for symbols that
are imported later from _module_client.

This ensures get_path_url gets proper __module__ attribution like
other direct imports.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: zeke

src/replicate/__init__.py

@@ -43,6 +43,7 @@
 from .lib._models import Model as Model, Version as Version, ModelVersionIdentifier as ModelVersionIdentifier
 from ._base_client import DefaultHttpxClient, DefaultAioHttpClient, DefaultAsyncHttpxClient
 from ._utils._logs import setup_logging as _setup_logging
+from .lib._predictions_use import get_path_url as get_path_url
 
 __all__ = [
     "types",
@@ -89,6 +90,7 @@
     "Model",
     "Version",
     "ModelVersionIdentifier",
+    "get_path_url",
 ]
 
 if not _t.TYPE_CHECKING:
@@ -104,6 +106,9 @@
 for __name in __all__:
     if not __name.startswith("__"):
         try:
+            # Skip symbols that are imported later from _module_client
+            if __name in ("run", "use"):
+                continue
             __locals[__name].__module__ = "replicate"
         except (TypeError, AttributeError):
             # Some of our exported symbols are builtins which we can't set attributes for.

src/replicate/lib/_files.py

@@ -139,6 +139,8 @@ class FileOutput(httpx.SyncByteStream):
     def __init__(self, url: str, client: Replicate) -> None:
         self.url = url
         self._client = client
+        # Add __url__ attribute for compatibility with get_path_url()
+        self.__url__ = url
 
     def read(self) -> bytes:
         if self.url.startswith("data:"):
@@ -184,6 +186,8 @@ class AsyncFileOutput(httpx.AsyncByteStream):
     def __init__(self, url: str, client: AsyncReplicate) -> None:
         self.url = url
         self._client = client
+        # Add __url__ attribute for compatibility with get_path_url()
+        self.__url__ = url
 
     async def read(self) -> bytes:
         if self.url.startswith("data:"):

tests/lib/test_get_path_url.py

@@ -0,0 +1,106 @@
+from pathlib import Path
+
+import replicate
+from replicate.lib._files import FileOutput, AsyncFileOutput
+from replicate.lib._predictions_use import URLPath, get_path_url
+
+# Test token for client instantiation
+TEST_TOKEN = "test-bearer-token"
+
+
+def test_get_path_url_with_urlpath():
+    """Test get_path_url returns the URL for URLPath instances."""
+    url = "https://example.com/test.jpg"
+    path_proxy = URLPath(url)
+
+    result = get_path_url(path_proxy)
+    assert result == url
+
+
+def test_get_path_url_with_fileoutput():
+    """Test get_path_url returns the URL for FileOutput instances."""
+    url = "https://example.com/test.jpg"
+    file_output = FileOutput(url, replicate.Replicate(bearer_token=TEST_TOKEN))
+
+    result = get_path_url(file_output)
+    assert result == url
+
+
+def test_get_path_url_with_async_fileoutput():
+    """Test get_path_url returns the URL for AsyncFileOutput instances."""
+    url = "https://example.com/test.jpg"
+    async_file_output = AsyncFileOutput(url, replicate.AsyncReplicate(bearer_token=TEST_TOKEN))
+
+    result = get_path_url(async_file_output)
+    assert result == url
+
+
+def test_get_path_url_with_regular_path():
+    """Test get_path_url returns None for regular Path instances."""
+    regular_path = Path("test.txt")
+
+    result = get_path_url(regular_path)
+    assert result is None
+
+
+def test_get_path_url_with_object_without_target():
+    """Test get_path_url returns None for objects without __url__."""
+
+    # Test with a string
+    result = get_path_url("not a path")
+    assert result is None
+
+    # Test with a dict
+    result = get_path_url({"key": "value"})
+    assert result is None
+
+    # Test with None
+    result = get_path_url(None)
+    assert result is None
+
+
+def test_get_path_url_module_level_import():
+    """Test that get_path_url can be imported at module level."""
+    from replicate import get_path_url as module_get_path_url
+
+    url = "https://example.com/test.jpg"
+    file_output = FileOutput(url, replicate.Replicate(bearer_token=TEST_TOKEN))
+
+    result = module_get_path_url(file_output)
+    assert result == url
+
+
+def test_get_path_url_direct_module_access():
+    """Test that get_path_url can be accessed directly from replicate module."""
+    url = "https://example.com/test.jpg"
+    file_output = FileOutput(url, replicate.Replicate(bearer_token=TEST_TOKEN))
+
+    result = replicate.get_path_url(file_output)
+    assert result == url
+
+
+def test_fileoutput_has_url_attribute():
+    """Test that FileOutput instances have __url__ attribute."""
+    url = "https://example.com/test.jpg"
+    file_output = FileOutput(url, replicate.Replicate(bearer_token=TEST_TOKEN))
+
+    assert hasattr(file_output, "__url__")
+    assert file_output.__url__ == url
+
+
+def test_async_fileoutput_has_url_attribute():
+    """Test that AsyncFileOutput instances have __url__ attribute."""
+    url = "https://example.com/test.jpg"
+    async_file_output = AsyncFileOutput(url, replicate.AsyncReplicate(bearer_token=TEST_TOKEN))
+
+    assert hasattr(async_file_output, "__url__")
+    assert async_file_output.__url__ == url
+
+
+def test_urlpath_has_url_attribute():
+    """Test that URLPath instances have __url__ attribute."""
+    url = "https://example.com/test.jpg"
+    url_path = URLPath(url)
+
+    assert hasattr(url_path, "__url__")
+    assert url_path.__url__ == url