Ticket #1: ftputil_ru.txt.orig

File ftputil_ru.txt.orig, 26.5 kB (added by schwa, 3 years ago)

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