0
# Public Link Management
1

2
Functions for generating, managing, and removing public links to files and directories. Enables sharing of cloud storage content with expiration control where supported by the storage backend.
3

4
## Capabilities
5

6
### Public Link Operations
7

8
Generate shareable public links for files and directories, with optional expiration times and link management.
9

10
```python { .api }
11
def link(path: str, expire: Union[str, None] = None, unlink=False, args=None) -> str:
12
    """
13
    Generates, retrieves, or removes public links for files or directories.
14
    
15
    Parameters:
16
    - path (str): File or directory path to create/manage link for
17
    - expire (str, optional): Link expiration time (format depends on backend)
18
    - unlink (bool): Remove existing public link instead of creating/retrieving
19
    - args (List[str]): Additional rclone link flags
20
    
21
    Returns:
22
    str: Public link URL (empty string when unlink=True)
23
    
24
    Raises:
25
    RcloneException: If link operation fails or backend doesn't support public links
26
    """
27
```
28

29
## Usage Examples
30

31
### Basic Link Generation
32

33
```python
34
from rclone_python import rclone
35

36
# Generate public link for file
37
file_link = rclone.link('onedrive:documents/report.pdf')
38
print(f"Public link: {file_link}")
39

40
# Generate link for directory
41
folder_link = rclone.link('dropbox:shared_folder')
42
print(f"Folder link: {folder_link}")
43

44
# Generate link for single image
45
image_link = rclone.link('box:photos/vacation.jpg')
46
print(f"Image link: {image_link}")
47
```
48

49
### Links with Expiration
50

51
```python
52
from rclone_python import rclone
53

54
# Create link expiring in 1 hour (format depends on backend)
55
temp_link = rclone.link('gdrive:temporary_file.zip', expire='1h')
56
print(f"Temporary link (1h): {temp_link}")
57

58
# Create link expiring in 7 days
59
week_link = rclone.link('onedrive:project_files', expire='7d')
60
print(f"Week-long link: {week_link}")
61

62
# Create link with specific expiration date (backend-specific format)
63
dated_link = rclone.link('dropbox:presentation.pptx', expire='2024-12-31T23:59:59Z')
64
print(f"Link expires 2024-12-31: {dated_link}")
65
```
66

67
### Link Management
68

69
```python
70
from rclone_python import rclone
71

72
# Create link
73
file_path = 'box:shared/document.pdf'
74
public_link = rclone.link(file_path)
75
print(f"Created link: {public_link}")
76

77
# Later, remove the public link
78
rclone.link(file_path, unlink=True)
79
print("Public link removed")
80

81
# Verify link is removed (this may fail if no link exists)
82
try:
83
    removed_link = rclone.link(file_path)
84
    print(f"Link still exists: {removed_link}")
85
except Exception:
86
    print("Link successfully removed")
87
```
88

89
### Batch Link Generation
90

91
```python
92
from rclone_python import rclone
93

94
def create_links_for_directory(base_path, expire_time=None):
95
    """Create public links for all files in a directory"""
96
    
97
    # Get all files in directory
98
    files = rclone.ls(base_path, files_only=True)
99
    
100
    links = {}
101
    for file in files:
102
        file_path = f"{base_path}/{file['Name']}" if not base_path.endswith(':') else f"{base_path}{file['Name']}"
103
        
104
        try:
105
            link_url = rclone.link(file_path, expire=expire_time)
106
            links[file['Name']] = link_url
107
            print(f"✓ {file['Name']}: {link_url}")
108
        except Exception as e:
109
            print(f"✗ {file['Name']}: Failed - {e}")
110
    
111
    return links
112

113
# Create links for all files in a folder
114
public_links = create_links_for_directory('onedrive:presentation_materials', expire='2d')
115

116
# Save links to file
117
with open('public_links.txt', 'w') as f:
118
    for filename, link in public_links.items():
119
        f.write(f"{filename}: {link}\n")
120
```
121

122
### Secure Link Sharing
123

124
```python
125
from rclone_python import rclone
126
import secrets
127
import json
128
from datetime import datetime, timedelta
129

130
def create_secure_share(file_path, recipient_email, expire_hours=24):
131
    """Create secure file share with tracking"""
132
    
133
    # Generate unique share ID
134
    share_id = secrets.token_urlsafe(16)
135
    
136
    # Create expiring public link
137
    expire_time = f"{expire_hours}h"
138
    public_link = rclone.link(file_path, expire=expire_time)
139
    
140
    # Create share record
141
    share_record = {
142
        'share_id': share_id,
143
        'file_path': file_path,
144
        'recipient': recipient_email,
145
        'created': datetime.now().isoformat(),
146
        'expires': (datetime.now() + timedelta(hours=expire_hours)).isoformat(),
147
        'public_link': public_link,
148
        'accessed': False
149
    }
150
    
151
    # Save share record (in real app, use database)
152
    shares_file = 'active_shares.json'
153
    try:
154
        with open(shares_file, 'r') as f:
155
            shares = json.load(f)
156
    except FileNotFoundError:
157
        shares = {}
158
    
159
    shares[share_id] = share_record
160
    
161
    with open(shares_file, 'w') as f:
162
        json.dump(shares, f, indent=2)
163
    
164
    print(f"Secure share created:")
165
    print(f"  Share ID: {share_id}")
166
    print(f"  Recipient: {recipient_email}")
167
    print(f"  Expires: {share_record['expires']}")
168
    print(f"  Link: {public_link}")
169
    
170
    return share_id, public_link
171

172
def revoke_share(share_id):
173
    """Revoke a secure share"""
174
    
175
    shares_file = 'active_shares.json'
176
    try:
177
        with open(shares_file, 'r') as f:
178
            shares = json.load(f)
179
    except FileNotFoundError:
180
        print("No active shares found")
181
        return
182
    
183
    if share_id not in shares:
184
        print(f"Share {share_id} not found")
185
        return
186
    
187
    share = shares[share_id]
188
    
189
    # Remove public link
190
    try:
191
        rclone.link(share['file_path'], unlink=True)
192
        print(f"✓ Public link removed for {share['file_path']}")
193
    except Exception as e:
194
        print(f"⚠ Failed to remove link: {e}")
195
    
196
    # Remove from active shares
197
    del shares[share_id]
198
    
199
    with open(shares_file, 'w') as f:
200
        json.dump(shares, f, indent=2)
201
    
202
    print(f"Share {share_id} revoked")
203

204
# Create secure share
205
share_id, link = create_secure_share(
206
    'confidential:report.pdf',
207
    'colleague@company.com',
208
    expire_hours=48
209
)
210

211
# Later, revoke the share
212
# revoke_share(share_id)
213
```
214

215
### Link Validation and Testing
216

217
```python
218
from rclone_python import rclone
219
import requests
220
from urllib.parse import urlparse
221

222
def test_public_link(file_path):
223
    """Test if public link is accessible"""
224
    
225
    try:
226
        # Generate link
227
        link_url = rclone.link(file_path)
228
        print(f"Generated link: {link_url}")
229
        
230
        # Parse URL to validate format
231
        parsed = urlparse(link_url)
232
        if not parsed.scheme or not parsed.netloc:
233
            print("⚠ Invalid link format")
234
            return False
235
        
236
        # Test accessibility (HEAD request to avoid downloading)
237
        try:
238
            response = requests.head(link_url, timeout=10)
239
            if response.status_code == 200:
240
                print("✓ Link is accessible")
241
                
242
                # Check content type if available
243
                content_type = response.headers.get('content-type', 'unknown')
244
                print(f"  Content-Type: {content_type}")
245
                
246
                # Check content length if available
247
                content_length = response.headers.get('content-length')
248
                if content_length:
249
                    size_mb = int(content_length) / (1024 * 1024)
250
                    print(f"  Size: {size_mb:.2f} MB")
251
                
252
                return True
253
            else:
254
                print(f"✗ Link returned status code: {response.status_code}")
255
                return False
256
                
257
        except requests.RequestException as e:
258
            print(f"✗ Link test failed: {e}")
259
            return False
260
            
261
    except Exception as e:
262
        print(f"✗ Failed to generate link: {e}")
263
        return False
264

265
# Test public link accessibility
266
test_public_link('onedrive:public/document.pdf')
267
```
268

269
### Backend-Specific Link Features
270

271
```python
272
from rclone_python import rclone
273

274
def create_backend_optimized_link(file_path, backend_type='onedrive'):
275
    """Create links optimized for specific backends"""
276
    
277
    backend_configs = {
278
        'onedrive': {
279
            'expire_format': '2024-12-31T23:59:59Z',  # ISO format
280
            'args': ['--onedrive-link-type', 'view']   # View-only link
281
        },
282
        'dropbox': {
283
            'expire_format': '2024-12-31',  # Date only
284
            'args': ['--dropbox-shared-links']
285
        },
286
        'googledrive': {
287
            'expire_format': None,  # Doesn't support expiration
288
            'args': ['--drive-shared-with-me']
289
        }
290
    }
291
    
292
    config = backend_configs.get(backend_type, {})
293
    
294
    # Create link with backend-specific options
295
    try:
296
        link_url = rclone.link(
297
            file_path,
298
            expire=config.get('expire_format'),
299
            args=config.get('args', [])
300
        )
301
        
302
        print(f"Created {backend_type} link: {link_url}")
303
        return link_url
304
        
305
    except Exception as e:
306
        print(f"Failed to create {backend_type} link: {e}")
307
        return None
308

309
# Create backend-specific links
310
onedrive_link = create_backend_optimized_link('onedrive:file.pdf', 'onedrive')
311
dropbox_link = create_backend_optimized_link('dropbox:file.pdf', 'dropbox')
312
```
313

314
## Backend Support and Limitations
315

316
Public link support varies by storage backend:
317

318
### Full Support
319
- **OneDrive**: Supports expiration, view/edit permissions
320
- **Dropbox**: Supports expiration, password protection (via args)
321
- **Box**: Supports expiration, download/preview options
322
- **Google Drive**: Basic link generation (no expiration)
323

324
### Limited Support
325
- **Amazon S3**: Pre-signed URLs with expiration
326
- **Azure Blob**: SAS tokens with expiration
327
- **SFTP/FTP**: No public link support
328
- **Local**: No public link support
329

330
### Backend-Specific Features
331

332
```python
333
from rclone_python import rclone
334

335
# OneDrive with specific link type
336
onedrive_view_link = rclone.link(
337
    'onedrive:document.pdf',
338
    args=['--onedrive-link-type', 'view', '--onedrive-link-scope', 'anonymous']
339
)
340

341
# Dropbox with password (if supported)
342
dropbox_protected_link = rclone.link(
343
    'dropbox:sensitive.zip',
344
    expire='7d',
345
    args=['--dropbox-shared-links']
346
)
347

348
# S3 pre-signed URL
349
s3_presigned_link = rclone.link(
350
    's3:bucket/file.pdf',
351
    expire='3600',  # Seconds for S3
352
    args=['--s3-shared-credentials-file', '/path/to/credentials']
353
)
354
```
355

356
## Error Handling
357

358
```python
359
from rclone_python import rclone
360
from rclone_python.utils import RcloneException
361

362
def safe_link_creation(file_path, expire=None):
363
    """Safely create public link with error handling"""
364
    
365
    try:
366
        link_url = rclone.link(file_path, expire=expire)
367
        print(f"✓ Link created: {link_url}")
368
        return link_url
369
        
370
    except RcloneException as e:
371
        if "not supported" in str(e).lower():
372
            print(f"✗ Public links not supported for this backend")
373
        elif "not found" in str(e).lower():
374
            print(f"✗ File not found: {file_path}")
375
        elif "permission" in str(e).lower():
376
            print(f"✗ Permission denied for: {file_path}")
377
        else:
378
            print(f"✗ Link creation failed: {e}")
379
        return None
380
        
381
    except Exception as e:
382
        print(f"✗ Unexpected error: {e}")
383
        return None
384

385
# Safe link creation
386
link = safe_link_creation('onedrive:may_not_exist.pdf', expire='1d')
387
```