README.rst
1Pure python scp module
2======================
3
4The scp.py module uses a paramiko transport to send and recieve files via the
5scp1 protocol. This is the protocol as referenced from the openssh scp program,
6and has only been tested with this implementation.
7
8
9Example
10-------
11
12.. code-block:: python
13
14 from paramiko import SSHClient
15 from scp import SCPClient
16
17 ssh = SSHClient()
18 ssh.load_system_host_keys()
19 ssh.connect('example.com')
20
21 # SCPCLient takes a paramiko transport as an argument
22 scp = SCPClient(ssh.get_transport())
23
24 scp.put('test.txt', 'test2.txt')
25 scp.get('test2.txt')
26
27 # Uploading the 'test' directory with its content in the
28 # '/home/user/dump' remote directory
29 scp.put('test', recursive=True, remote_path='/home/user/dump')
30
31 scp.close()
32
33
34.. code-block::
35
36 $ md5sum test.txt test2.txt
37 fc264c65fb17b7db5237cf7ce1780769 test.txt
38 fc264c65fb17b7db5237cf7ce1780769 test2.txt
39
40Using 'with' keyword
41--------------------
42
43.. code-block:: python
44
45 from paramiko import SSHClient
46 from scp import SCPClient
47
48 ssh = SSHClient()
49 ssh.load_system_host_keys()
50 ssh.connect('example.com')
51
52 with SCPClient(ssh.get_transport()) as scp:
53 scp.put('test.txt', 'test2.txt')
54 scp.get('test2.txt')
55
56
57.. code-block::
58
59 $ md5sum test.txt test2.txt
60 fc264c65fb17b7db5237cf7ce1780769 test.txt
61 fc264c65fb17b7db5237cf7ce1780769 test2.txt
62
63
64Uploading file-like objects
65---------------------------
66
67The ``putfo`` method can be used to upload file-like objects:
68
69.. code-block:: python
70
71 import io
72 from paramiko import SSHClient
73 from scp import SCPClient
74
75 ssh = SSHClient()
76 ssh.load_system_host_keys()
77 ssh.connect('example.com')
78
79 # SCPCLient takes a paramiko transport as an argument
80 scp = SCPClient(ssh.get_transport())
81
82 # generate in-memory file-like object
83 fl = io.BytesIO()
84 fl.write(b'test')
85 fl.seek(0)
86 # upload it directly from memory
87 scp.putfo(fl, '/tmp/test.txt')
88 # close connection
89 scp.close()
90 # close file handler
91 fl.close()
92
93
94Tracking progress of your file uploads/downloads
95------------------------------------------------
96
97A ``progress`` function can be given as a callback to the SCPClient to handle
98how the current SCP operation handles the progress of the transfers. In the
99example below we print the percentage complete of the file transfer.
100
101.. code-block:: python
102
103 from paramiko import SSHClient
104 from scp import SCPClient
105 import sys
106
107 ssh = SSHClient()
108 ssh.load_system_host_keys()
109 ssh.connect('example.com')
110
111 # Define progress callback that prints the current percentage completed for the file
112 def progress(filename, size, sent):
113 sys.stdout.write("%s's progress: %.2f%% \r" % (filename, float(sent)/float(size)*100) )
114
115 # SCPCLient takes a paramiko transport and progress callback as its arguments.
116 scp = SCPClient(ssh.get_transport(), progress=progress)
117
118 # you can also use progress4, which adds a 4th parameter to track IP and port
119 # useful with multiple threads to track source
120 def progress4(filename, size, sent, peername):
121 sys.stdout.write("(%s:%s) %s's progress: %.2f%% \r" % (peername[0], peername[1], filename, float(sent)/float(size)*100) )
122 scp = SCPClient(ssh.get_transport(), progress4=progress4)
123
124 scp.put('test.txt', '~/test.txt')
125 # Should now be printing the current progress of your put function.
126
127 scp.close()
128