root/tags/release2_2/ftputil_ru.txt.orig

Revision 511, 27.9 kB (checked in by schwa, 3 years ago)
Included some parts for upcoming release 2.1. Thanks to Anton Stepanov!
Line 
1 ``ftputil`` - �������� � ���TP ���==================================================================
2
3 :��:                   2.0.4
4 :��                    2005-06-09
5 :���                  �����Python ��� � ���TP ���:������          FTP, �� ``ftplib``, ������ ��
6 :��                    Stefan Schwarzer <sschwarzer@sschwarzer.net>
7 :�����:            ��� ��<antymail@mail.ru>
8
9
10 .. contents:: ����
11 ���
12 --------
13
14 ���putil`` ���� ���������
15 ftplib_ ���� FTPHost ��������
16 �������������� ��� os_ �os.path`_.
17
18 .. _ftplib: http://www.python.org/doc/current/lib/module-ftplib.html
19 .. _os: http://www.python.org/doc/current/lib/module-os.html
20 .. _`os.path`: http://www.python.org/doc/current/lib/module-os.path.html
21
22 ���  ::
23
24     import ftputil
25
26     # download some files from the login directory
27     host = ftputil.FTPHost('ftp.domain.com', 'user', 'password')
28     names = host.listdir(host.curdir)
29     for name in names:
30         if host.path.isfile(name):
31             host.download(name, name, 'b')  # remote, local, binary mode
32
33     # make a new directory and copy a remote file into it
34     host.mkdir('newdir')
35     source = host.file('index.html', 'r')  # file-like object
36     target = host.file('newdir/index.html', 'w')  # file-like object
37     host.copyfileobj(source, target)  # similar to shutil.copyfileobj
38     source.close()
39     target.close()
40
41 �� �� � `FTPHost.lstat`_ �FTPHost.stat`_ ���������� ��� ����� ������������s.stat`_. �� �� ��� `FTPHost.path.walk`_ ��
42 �����.
43
44 .. _`os.stat`: http://www.python.org/doc/current/lib/os-file-dir.html#l2h-1455
45
46 ������ ��``UserTuple``, �����������������stat_ ���Python 2.0 �.1.
47
48 .. _stat: http://www.python.org/doc/current/lib/module-stat.html
49
50 �������------------------
51
52 ���� �����������`ftputil``
53 (���`ftputil.TemporaryError``). ����������
54
55   ::
56
57     FTPError
58         FTPOSError(FTPError, OSError)
59             TemporaryError(FTPOSError)
60             PermanentError(FTPOSError)
61             ParserError(FTPOSError)
62         FTPIOError(FTPError)
63         InternalError(FTPError)
64             RootDirError(InternalError)
65             InaccessibleLoginDirError(InternalError)
66         TimeShiftError(FTPError)
67
68 ���������� ����:
69
70 - ``FTPError``
71
72   ���� �� ���������
73
74
75 - ``FTPOSError``
76
77   ���`OSError``. ������� �����  os ������``FTPHost``. ���
78
79   ::
80
81     try:
82         os.chdir('nonexisting_directory')
83     except OSError:
84         ...
85
86   � ::
87
88     host = ftputil.FTPHost('host', 'user', 'password')
89     try:
90         host.chdir('nonexisting_directory')
91     except OSError:
92         ...
93
94   ������
95
96
97   ::
98
99     def func(path, file):
100         ...
101
102   ��� �� ��������� ���  ��
103   ``OSErrors``.  ����������� �
104   ::
105
106     def func(path, file, os=os):
107         ...
108
109   � ���`os`` ���``os`` �� ��� ��  �
110
111   ::
112
113     host = ftputil.FTPHost('host', 'user', 'password')
114     func(path, file, os=host)
115
116   � �� ���� ������ � ���
117   ����� ������
118   �� �����OSError`` �`FTPOSError`` ���� �
119   ���� ���FTP �� � �� ``errno`` � �� ������ �����`strerror``.
120
121 - ``TemporaryError``
122
123   ������� ���� �����
124   ��� �FTP �� ��������400 �499. �� ������������ ``ftplib.error_temp`` (�
125   ``TemporaryError`` �`ftplib.error_temp`` *����� ����
126
127 - ``PermanentError``
128
129
130   ������� ���� �����
131   ��� �FTP �� ��������500 �599
132   (��������, �*� �������
133   ``ftplib.error_perm``).
134
135 - ``ParserError``
136
137   ��, ��� ��� ��� ��������
138   ���. �������� �������� ``FTPHost`` �: ``stat``, ``lstat``, �`listdir``.
139
140 - ``FTPIOError``
141
142   ������� �� ���� ����  ���. ���, �����, �� ����� ��� ������� �� ��  ``FTPHost.file`` (``FTPHost.open`` - ���). ���:
143
144   ::
145
146     >>> try:
147     ...     f = open('notthere')
148     ... except IOError, obj:
149     ...     print obj.errno
150     ...     print obj.strerror
151     ...
152     2
153     No such file or directory
154
155   � ::
156
157     >>> host = ftputil.FTPHost('host', 'user', 'password')
158     >>> try:
159     ...     f = host.open('notthere')
160     ... except IOError, obj:
161     ...     print obj.errno
162     ...     print obj.strerror
163     ...
164     550
165     550 notthere: No such file or directory.
166
167   ���� ��, ������. (���  ��� ���������)
168
169 - ``InternalError``
170
171   ������������������  ����TP ���� ������������� ��  ``ftputil``.
172
173 - ``RootDirError``
174
175   � ����`lstat`` - �� ������
176   ``stat``- ���������/.
177   ��� �� *�� � ������, ��  �. :-)
178
179 - ``InaccessibleLoginDirError``
180
181   �������� ������ �����  *��������
182
183   - ��������� ������ ��� �    �������``chdir`` ����.
184
185   - ���� ����
186
187 - ``TimeShiftError``
188   ���� ���� ��, ��������
189   `time shift`_, �������� ����������
190   �� 1 �
191
192
193 ``FTPHost`` - ���------------------
194
195 .. _`FTPHost construction`:
196
197 ����~~~~~~~~~~~
198
199 ``FTPHost`` �������� ���� �����:
200
201   ::
202
203     host = ftputil.FTPHost(host, user, password, account,
204                            session_factory=ftplib.FTP)
205
206 �� ����� ����������
207 �� FTP ���`ftplib`` �� ���`session_factory`` may ����� �, �����TP
208 ����������, ����� ���� ���`ftplib.FTP``. ���, M2Crypto �����������P
209 ��������``ftplib.FTP``.
210
211 ����� ������������
212 ``session_factory`` ��� ��, ���� ����� (������� � ����� ��� �����
213
214 ������ ������� ����������tplib.FTP`` ���� �� ��������
215 ���� �� ``ftplib.FTP`` ����
216 ���, ����, �� �������� �� ��
217 ��� ��� ����, �``ftplib.FTP`` �������
218 ������ �� ``connect``, ��������
219 �� �� ��������":
220
221   ::
222
223     import ftplib
224     import ftputil
225
226     EXAMPLE_PORT = 50001
227
228     class MySession(ftplib.FTP):
229         def __init__(self, host, userid, password, port):
230             """Act like ftplib.FTP's constructor but connect to other port."""
231             ftplib.FTP.__init__(self)
232             self.connect(host, port)
233             self.login(userid, password)
234
235     # try not to use MySession() as factory, - use the class itself
236     host = ftputil.FTPHost(host, userid, password,
237                            port=EXAMPLE_PORT, session_factory=MySession)
238     # use `host` as usual
239
240 ��� ���, ������� (�����
241 ���� stat - ��� ������ �������� ���, ��� ���� ��`set_directory_format`_ , ������"��".
242
243 ``FTPHost`` - �� ���~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
244
245 ���````````
246
247 - ``curdir``, ``pardir``, ``sep``
248
249   ������������� �� ��� ����  �������. Sep ������ ����  `RFC 959`_ (��� ����� ������������� ���� ���. Unix �� , ���, ����
250   ����- Unix ���
251 .. _`RFC 959`: `RFC 959 - File Transfer Protocol (FTP)`_
252
253 .. _`time shift`:
254
255 �����������```````````````````````````````
256
257 .. _`set_time_shift`:
258
259 - ``set_time_shift(time_shift)``
260
261   ���� ���������������� ���
262   �� ��� ��������� �� � �� ������ �� ��, � �����
263
264   ::
265
266     time_shift = server_time - client_time
267
268   ��� ���� �� ��upload_if_newer`_ � `download_if_newer`_ �� ���� ���� �� FTP �� ���� �������� (�
269   ��� ``ftputil`` ��� ������������ ������������.
270
271   ������������� ������ ���� �� 1 �,
272   � ��� ������4 �, �������``TimeShiftError``.
273
274   �. ��synchronize_times`_ � �� ����������
275 - ``time_shift()``
276
277   ������� �����������.
278   ``set_time_shift`` (��� � ����
279
280 .. _`synchronize_times`:
281
282 - ``synchronize_times()``
283
284   ������� ���� ���, �
285   ��� `upload_if_newer`_ �download_if_newer`_ �����,
286   ����� �������������� ��
287   �, ������ �� ���� �����
288
289   - ������� ������������
290   - �������� ��� ������ ����
291     ``synchronize_times`` ���
292   - ������ ����*� �� �������(� /)
293     FTP ��.
294
295   ��� ��� ��� ��� � �� ���
296   ���������� �����`set_time_shift`_. �����
297   ``synchronize_times``, ��������������������� ``TimeShiftError`` ����.
298
299 �� ����```````````````
300
301 - ``file(path, mode='r')``
302
303   ����-���� ������������ �����. ���������, � ����
304   � ������������ ��� (��� ������  ���cwd ��). �� � ����� ��������� �� "r",
305   �. �������������- "r",
306   "rb", "w", �wb".
307
308 - ``open(path, mode='r')``
309
310   ���� ����� ``file`` (���
311
312 - ``copyfileobj(source, target, length=64*1024)``
313
314   ��������-��� ������ ��-��������������
315   ``shutil.copyfileobj`` - �������� ����.
316
317 - ``close()``
318
319   ������ �����������
320   ����� FTP ������ � ��� �� ��� ``FTPHost``.
321
322 - ``getcwd()``
323
324   ������ �������������. ��  ����������``os.getcwd``.
325
326 - ``chdir(directory)``
327
328   ���� ���� �FTP ��. ��������� ``os.chdir``, �� ���-)
329
330 - ``mkdir(path, [mode])``
331
332   �� ����������. �������  ���  "����" ��� �������� ������`mode`` ������� � �����os.mkdir``,����``FTPHost``
333   ����� �����os ��(����  ��������
334
335 - ``makedirs(path, [mode])``
336   �� ������ ``mkdir`` (���� ���� "����"
337   ���(������ ``os.makedirs``). ���`mode`` ��
338   ��� ������� ``os.makedirs`` � �� ��  ����
339 - ``rmdir(path)``
340
341   �����������.
342
343   ���� �� ``ftputil``, �����������  ��, ��������� �. ``ftputil``
344   ��2.0 ���� �����������  ���
345
346   ��� �����`ftputil`` 2.0, �� ���� ������� ��� ��������� ��� ``_remove_only_empty=False``. ������������� �  ��� �������� �����ftputil``.
347
348 - ``remove(path)``
349
350   ���� ������� (�����``os.remove``).
351
352 - ``unlink(path)``
353
354   ���� ����� ``remove``.
355
356 - ``rename(source, target)``
357
358   ����� ����(� ����FTP ��.
359
360
361 - ``listdir(path)``
362
363   ����� �����������  �����������``os.listdir``.
364
365 - ``walk(top, topdown=True, onerror=None)``
366
367   ������� ���, ������ `os.walk`_ ���Python 2.3.
368   ����``FTPHost.walk`` ������ython �� ���� ������� ����� ����  ����� ����� ftputil ���� �� �� Python,
369   ��� �� 2.0 ����``walk`` ��������
370   �� �� ���ython 2.2 ��
371 .. _`os.walk`: http://docs.python.org/lib/os-file-dir.html#l2h-1638
372
373 ��� ��� ��``````````````````````````
374
375 - ``upload(source, target, mode='')``
376
377   ������ � (��� ��, ��� ����  ���������������. ����, ����  ������ � ���� �������  (���� � �������, ����).
378   �� ������ " � "@" � ASCII, � "b" � ��� ��  �� ASCII ������.
379
380 - ``download(source, target, mode='')``
381
382   ������� ��� ��� ��� �.
383   ������������������� ����  ����� �������� ������.. _`upload_if_newer`:
384
385 - ``upload_if_newer(source, target, mode='')``
386
387   ��������� ���� ��� �  �� �����, ��� ��� ����  � ��� ������������ ��  � ��� �����. ������������ ����� �������� ������������������������  ��������� ������  ������������������  ::
388
389     # transfer in ASCII mode
390     host.upload_if_newer('source_file', 'target_file', 'a')
391     # won't transfer the file again
392     host.upload_if_newer('source_file', 'target_file', 'b')
393
394   ���� �������, � ����� �������� ����  ���� �, ������ ���
395   ����������`upload_if_newer`` ���
396   ��������) � �������, � ������ ���
397
398   - ����`upload`` ��``upload_if_newer``, �
399
400   - �� ������� ``FTPHost.remove``,
401     ������`upload`` � ``upload_if_newer``, ����� ��
402   �����, �� ���"��� ��� ������  `time shift`_.
403
404 .. _`download_if_newer`:
405
406 - ``download_if_newer(source, target, mode='')``
407
408   ����``upload_if_newer``, ������������������ ����������� ���� �� ``upload_if_newer``  � �, ��� �� ���������������� �������� �������, �� ��������� ������  `time shift`_.
409
410
411 Stat - �� � ������````````````````````````````````````
412
413 �� ``lstat`` �`stat`` (����������  ��� �����TP ��������
414 ��������`FTPHost`` ��� �� ���� ���,
415 ���� ������������� ���
416 (� ����), ����� �����"��". ��� ��������������� ��
417
418 .. _`set_directory_format`:
419
420 - ``set_directory_format(server_format)``
421
422   ``server_format`` - ���������nix", ��  "ms". ��
423    �� ����� � �� ���������FTP ��
424    ���� �������������������
425    ��� ���� ���IR``).
426
427   �������������
428   ::
429
430       drwxr-sr-x   2 45854    200           512 Jul 30 17:14 image
431       -rw-r--r--   1 45854    200          4604 Jan 19 23:11 index.html
432
433   ������nix" � ���  ������� ���
434
435   ::
436
437       12-07-01  02:05PM       <DIR>          XPLaunch
438       07-17-00  02:08PM             12266720 digidash.exe
439
440   ����"ms" � ������ ``server_format``.
441
442   ������������ ������� �������. �������� ��� ��������� (������ ���IR``).
443
444 �� � ��, ``lstat`` � ``stat`` �� �� ��������� ���  ����� ���� ��, ����� ����� ����`time shift`_).
445
446 .. _`FTPHost.lstat`:
447
448 - ``lstat(path)``
449
450   �����, ����� ``os.lstat`` (�����������;  �� ���� � ``os``
451   ��. �����������
452   ��������������
453   - ����������� �� ���IR``
454     ���. �� ������FTPHost.lstat`` �    ������������� ��   �����
455   - ���� ������� ������ ��������    � ����� ���� ��. ��   ����������Unix ��� ��������   FTP ������.
456
457   - ���  ���������� ��������    � ��� ����������. ���
458     � ���������, ������ ���   ��� ���� ����� �� ����  �� ���� �������� �������
459
460   - ��������������   ����� ���� ��� ���IR``.
461
462   - ������������ ��� ���`None``.
463
464   - �� ��� ������� stat - �� ������� �    ������� ``RootDirError``. ��� ����� �   ��� ������� ``(l)stat``, � ��� ��� ��, ���   ������
465 .. update for other servers
466
467 ..
468
469   ������ ��� ``ftputil`` ���� ��MS Robin FTP ��.
470   �� ��� �������Unix ����������. ��  � ��� ������ ������������
471   ������������ ��� ��
472 .. implement and document support for setting the directory parser
473    "manually"
474
475 .. _`FTPHost.stat`:
476
477 - ``stat(path)``
478   ���``stat`` ���� � �� ����� ���
479   ������������ ����� � � ��� �����. ��������� ���� ����  ``PermanentError``.
480
481 ``FTPHost.path``
482 ~~~~~~~~~~~~~~~~
483
484 ``FTPHost`` ������ �� �: ``path``, ���`os.path`_. ���� ���������
485 ���� ��� ����� ����������� ``os.path``:
486
487 .. _`FTPHost.path.walk`:
488
489 ::
490
491     abspath(path)
492     basename(path)
493     commonprefix(path_list)
494     dirname(path)
495     exists(path)
496     getmtime(path)
497     getsize(path)
498     isabs(path)
499     isdir(path)
500     isfile(path)
501     islink(path)
502     join(path1, path2, ...)
503     normcase(path)
504     normpath(path)
505     split(path)
506     splitdrive(path)
507     splitext(path)
508     walk(path, func, arg)
509
510 ``FTPFile`` - ���------------------
511
512 ``FTPFile`` ������ �� ����`FTPHost.file`` (�
513 ``FTPHost.open``) ������ ��, (�������� �����)
514 ���� ��������:
515
516   ::
517
518     close()
519     read([count])
520     readline([count])
521     readlines()
522     write(data)
523     writelines(string_sequence)
524     xreadlines()
525
526 ���`closed``. �� ������ ������ �� `File
527 objects`_ ���������.
528
529 .. _`file objects`:
530    http://www.python.org/doc/current/lib/bltin-file-objects.html
531
532 ���������``ftputil`` ���� ��� ��������������������
533
534 ������/ FAQ
535 ------------------------
536
537 �� ���� �� ��� ��
538 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
539
540 ��� http://www.sschwarzer.net/python/python_software.html#ftputil.
541 ��� ������� ����������(�����
542 ��� ������� �����������������`comp.lang.python`_ .
543
544 .. _`comp.lang.python`: news:comp.lang.python
545
546 ���������`ftputil``?
547 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
548
549 �, ��� �����ttp://codespeak.net/mailman/listinfo/ftputil
550 � �����http://codespeak.net/pipermail/ftputil/.
551
552 �����! ����~~~~~~~~~~~~~~~~~~~~~~~~~~~
553
554 �������, ���� � �� ��� �������
555 ``ftputil``. ��� �������
556
557 ���������� �� (���� ��������``ftputil``
558 � ������� (����� ��������������
559 �*�� ��� *���* ��� ����� ����
560 (�����, ��, ���� �.� �� ��
561 ��� ���, ���������� ����:
562
563 - ��``ftputil``
564
565 - ��Python
566
567 - ���� FTP �� (������� ����")
568
569 - �������� ��� ���
570   (���� ����� ��``uname -a`` �Unix)
571
572 - ����
573
574 - ���������� ������� ��
575
576 - �������, ������������
577
578 ���������~~~~~~~~~~~~~~~~~~~~~~~~~~~
579
580 � ���, ``FTPHost`` �� ���� ����TP ����� ������������ ��`FTPHost construction`_.
581
582 � �� ���� ������ � � ���� �����
583 ������� ����� � ����
584
585 ���������������~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
586
587 ��� ��� ���``ftplib.FTP``, � �� ���
588 `FTPHost construction`_::
589
590     import ftplib
591
592     class ActiveFTPSession(ftplib.FTP):
593         def __init__(self, host, userid, password):
594             """
595             Act like ftplib.FTP's constructor but use active mode
596             explicitly.
597             """
598             ftplib.FTP.__init__(self)
599             self.connect(host, port)
600             self.login(userid, password)
601             # see http://docs.python.org/lib/ftp-objects.html
602             self.set_pasv(False)
603
604 ��� ������``session_factory`` ����``FTPHost``.
605
606
607 ��� ����� � �����������~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
608
609 � �� ����``ftputil`` ����� ����� ��� � ���. �������, ��FTP �����
610 ��������� ``ftputil``, �����������
611 ��� ������`time shift`_.
612 �� ��������synchronize_times`_.
613
614 ������������ ����stat - ������
615 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
616
617 �. ��� ������
618 ��- ����-�� (���istdir) ���������~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
619
620 �� ���`listdir`` � ``lstat`` ������������� ��������������������� �� ��� �. `set_directory_format`_.
621
622 ���� ���� ��������~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623
624 ������������������ � ������� ����:-) ����������� �
625 ���������  ftputil@codespeak.net;
626 ������ ������ ���� ��
627 ��� ����
628 --------------------
629
630 - ``ftputil`` ������Python 2.0 � ��
631 - �����``lstat`` �� ���� ����������� ���  ``/``. ��� �� � �����, �������.
632   �������������������:
633   ``FTPHost.path.exists/isfile/isdir/islink``,
634   �...
635
636 - ���������� ����������
637   ���� ��� ���� ��`FTPHost`` ��, �
638   �����`FTPFile`` ���������� 10 �� ��
639
640 - � ��, � ��������������
641   ���� �����, ���FTPFile``
642   ���� �� ������- ``FTPFile`` �������� *����� ��*
643   ������������������� ����� ����������� �� FTP ��
644
645 - ��� �������� �� ��� �����
646   ���� ��, �� ���� �����
647
648 - ``UserTuple`` �� �� ``UserTuple.py``, ��������
649   ������ ���� �� ��� ���.
650
651 ��
652 -----
653
654 ������������ �`ftputil`` �������ftputil`` ��. ����� (�reStructured Text`_ � �� HTML ) �����������
655
656 .. _`reStructured Text`: http://docutils.sourceforge.net/rst.html
657
658 �� ``_test_*.py`` �`_mock_ftplib.py`` ��� ������
659 ���  *������� ftputil (� *�����* �,
660 � �� �� ��.
661
662 ����----------
663
664 - Mackinnon T, Freeman S, Craig P. 2000. `Endo-Testing:
665   Unit Testing with Mock Objects`_.
666
667 - Postel J, Reynolds J. 1985. `RFC 959 - File Transfer Protocol (FTP)`_.
668
669 - Van Rossum G, Drake Jr FL. 2003. `Python Library Reference`_.
670
671 .. _`Endo-Testing: Unit Testing with Mock Objects`:
672    http://www.connextra.com/aboutUs/mockobjects.pdf
673 .. _`RFC 959 - File Transfer Protocol (FTP)`: http://www.ietf.org/rfc/rfc959.txt
674 .. _`Python Library Reference`: http://www.python.org/doc/current/lib/lib.html
675
676 ��-----
677
678 ����``ftputil`` ������ ����Stefan Schwarzer)
679 <sschwarzer@sschwarzer.net>.
680
681 ������ :-)
682
Note: See TracBrowser for help on using the browser.