Changeset 1889:15c2cc4fdb14


Ignore:
Timestamp:
Jan 1, 2020, 9:57:19 PM (3 months ago)
Author:
Stefan Schwarzer <sschwarzer@…>
Branch:
default
Message:
Revise documentation for ftputil 4.0.0

I did a lot of changes and don't want to commit or even mention them
all individually. Nevertheless, here are some changes I made:

- Remove references to Python 2.x
- Remove references to M2Crypto. Most users will just use the
  `ftplib.FTP_TLS` class. See also ticket #78.
- Update minimumm Python version (now 3.6)
- (Mostly) avoid terms like "unicode strings" and "byte strings"
  because these are rarely used nowadays. Instead use "strings" and
  "bytes" or `str`/`bytes`.
- Change http links to https (I didn't notice any instances where
  the target didn't support https)
- Update links to the Python standard library where necessary
- Some wording changes

I may have forgotten some advisable changes. Maybe I'll make another
revision before the release of ftputil 4.0.0(-beta).
File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/ftputil.txt

    r1888 r1889  
    347347The keyword argument ``session_factory`` may be used to generate FTP
    348348connections with other factories than the default ``ftplib.FTP``. For
    349 example, the standard library of Python 2.7 contains a class
     349example, the standard library of Python 3 contains a class
    350350``ftplib.FTP_TLS`` which extends ``ftplib.FTP`` to use an encrypted
    351351connection.
     
    389389please `enter a ticket`_.
    390390
    391 .. _`enter a ticket`: http://ftputil.sschwarzer.net/issuetrackernotes
     391.. _`enter a ticket`: https://ftputil.sschwarzer.net/issuetrackernotes
    392392
    393393For the most common uses you don't need to create your own session
     
    418418  for secure connections. This is only supported for the base classes
    419419  ``ftplib.FTP_TLS`` and ``M2Crypto.ftpslib.FTP_TLS``, otherwise the
    420   the parameter is ignored.
     420  parameter is ignored.
    421421
    422422- ``debug_level`` sets the debug level for FTP session instances. The
     
    457457ticket`_.
    458458
    459 .. _`this ticket`: http://ftputil.sschwarzer.net/trac/ticket/78
     459.. _`this ticket`: https://ftputil.sschwarzer.net/trac/ticket/78
    460460
    461461Hidden files and directories
     
    610610````````````````````
    611611
    612 If the client where ``ftputil`` runs and the server have a different
    613 understanding of their local times, this has to be taken into account
     612If the client where ``ftputil`` runs and the server have different
     613understandings of their local times, this has to be taken into account
    614614for ``upload_if_newer`` and ``download_if_newer`` to work correctly.
    615615
     
    617617(or even on the same computer), the time shift value (see below) may
    618618be different from zero. For example, my computer is set to use local
    619 time whereas the server running on the very same host insists on using
    620 UTC time.
     619time whereas the server running on the very same host uses UTC time.
    621620
    622621.. _`set_time_shift`:
     
    748747- ``lstat(path)``
    749748
    750   returns an object similar to that from `os.lstat`_. This is a
    751   "tuple" with additional attributes; see the documentation of the
     749  returns an object similar to that from `os.lstat`_. This is a kind
     750  of tuple with additional attributes; see the documentation of the
    752751  ``os`` module for details.
    753752
     
    759758    numbers, and that only if the server supplies them. This is
    760759    usually the case with Unix servers but maybe not for other FTP
    761     server programs.
     760    servers.
    762761
    763762  - Values for the time of the last modification may be rough,
    764763    depending on the information from the server. For timestamps
    765764    older than a year, this usually means that the precision of the
    766     modification timestamp value is not better than days. For newer
     765    modification timestamp value is not better than a day. For newer
    767766    files, the information may be accurate to a minute.
    768767
     
    790789.. _`os.listdir`: https://docs.python.org/library/os.html#os.listdir
    791790.. _`os.lstat`: https://docs.python.org/library/os.html#os.lstat
    792 .. _`ftputil mailing list`: http://ftputil.sschwarzer.net/mailinglist
     791.. _`ftputil mailing list`: https://ftputil.sschwarzer.net/mailinglist
    793792.. _`writing your own parser`: `Writing directory parsers`_
    794793
     
    10771076  Python 3 as a local text file and ``target`` as a remote file object
    10781077  in binary mode, the transfer will fail since ``source.read`` gives
    1079   unicode strings whereas ``target.write`` only accepts byte strings.
     1078  unicode strings (``str``) whereas ``target.write`` only accepts byte
     1079  strings (``bytes``).
    10801080
    10811081  See `File-like objects`_ for the construction and use of remote
     
    11221122              data = fobj.read(100)
    11231123              # _Futile_ attempt to avoid file connection timeout.
    1124               for i in xrange(15):
     1124              for i in range(15):
    11251125                  time.sleep(60)
    11261126                  ftp_host.keep_alive()
     
    11431143never use the ``FTPFile`` constructor directly.
    11441144
    1145 The API of remote file-like objects are is modeled after the API of
    1146 the io_ module in Python 3, which has also been backported to Python
    1147 2.6 and 2.7.
    1148 
    1149 .. _io: http://docs.python.org/library/io.html
     1145The APIs for remote file-like objects is modeled after the APIs of
     1146the built-in ``open`` function and its return value.
    11501147
    11511148- ``FTPHost.open(path, mode="r", buffering=None, encoding=None,
     
    11661163
    11671164  If you open a file in binary mode, the read and write operations use
    1168   byte strings (``str`` in Python 2, ``bytes`` in Python 3). That is,
    1169   read operations return byte strings and write operations only accept
    1170   byte strings.
    1171 
    1172   Similarly, text files always work with unicode strings (``unicode``
    1173   in Python 2, ``str`` in Python 3). Here, read operations return
    1174   unicode strings and write operations only accept unicode strings.
    1175 
    1176   .. warning::
    1177 
    1178      Note that the semantics of "text mode" has changed fundamentally
    1179      from ftputil 2.8 and earlier. Previously, "text mode" implied
    1180      converting newline characters to ``\r\n`` when writing remote
    1181      files and converting newlines to ``\n`` when reading remote
    1182      files. This is in line with the "text mode" notion of FTP command
    1183      line clients. Now, "text mode" follows the semantics in Python's
    1184      ``io`` module.
    1185 
    1186   The arguments ``errors`` and ``newline`` have the same semantics as
    1187   in `io.open`_. The argument ``buffering`` currently is ignored.
    1188   It's only there for compatibility with the ``io.open`` interface.
     1165  ``bytes`` objects. That is, read operations return ``bytes`` and
     1166  write operations only accept ``bytes``.
     1167
     1168  Similarly, text files always work with strings (``str``). Here, read
     1169  operations return string and write operations only accept strings.
     1170
     1171  The arguments ``buffering``, ``errors`` and ``newline`` have the
     1172  same semantics as in open_.
    11891173
    11901174  If the file is opened in binary mode, you may pass 0 or a positive
     
    12041188     argument for a resumed transfer.
    12051189
    1206 .. _`io.open`: http://docs.python.org/library/io.html#io.open
     1190.. _`open`: https://docs.python.org/3/library/functions.html#open
    12071191
    12081192``FTPHost.open`` can also be used in a ``with`` statement::
     
    12501234Python Library Reference.
    12511235
    1252 .. _`file objects`: https://docs.python.org/2.7/library/stdtypes.html#file-objects
     1236.. _`file objects`: https://docs.python.org/3/glossary.html#term-file-object
    12531237
    12541238
     
    14861470See the `download page`_. Announcements will be sent to the `mailing
    14871471list`_. Announcements on major updates will also be posted to the
    1488 newsgroup `comp.lang.python.announce`_ .
    1489 
    1490 .. _`download page`: http://ftputil.sschwarzer.net/download
    1491 .. _`mailing list`: http://ftputil.sschwarzer.net/mailinglist
    1492 .. _`comp.lang.python.announce`: news:comp.lang.python.announce
     1472`Python announcements list`_.
     1473
     1474.. _`download page`: https://ftputil.sschwarzer.net/download
     1475.. _`mailing list`: https://ftputil.sschwarzer.net/mailinglist
     1476.. _`Python announcements list`: https://mail.python.org/mailman3/lists/python-announce-list.python.org/
    14931477
    14941478Is there a mailing list on ``ftputil``?
    14951479~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    14961480
    1497 Yes, please visit http://ftputil.sschwarzer.net/mailinglist to
     1481Yes, please visit https://ftputil.sschwarzer.net/mailinglist to
    14981482subscribe or read the archives.
    14991483
     
    15101494have already been fixed.
    15111495
    1512 .. _`latest version`: http://ftputil.sschwarzer.net/download
    1513 
    1514 Please see http://ftputil.sschwarzer.net/issuetrackernotes for
     1496.. _`latest version`: https://ftputil.sschwarzer.net/download
     1497
     1498Please see https://ftputil.sschwarzer.net/issuetrackernotes for
    15151499guidelines on entering a bug in ``ftputil``'s ticket system. If you
    15161500are unsure if the behaviour you found is a bug or not, you should write
    1517 to the `ftputil mailing list`_. In *either* case you *must not*
    1518 include confidential information (user id, password, file names, etc.)
    1519 in the problem report! Be careful!
    1520 
    1521 Does ``ftputil`` support SSL/TLS?
    1522 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1523 
    1524 ``ftputil`` has no *built-in* SSL/TLS support.
     1501to the `ftputil mailing list`_. *Never* include confidential information
     1502(user id, password, file names, etc.) in the problem report! Be
     1503careful!
     1504
     1505Does ``ftputil`` support TLS?
     1506~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     1507
     1508``ftputil`` has no *built-in* TLS support.
    15251509
    15261510On the other hand, there are two ways to get TLS support with
    15271511ftputil:
    15281512
    1529 - In Python 2.7 and Python 3.2 and up, the ``ftplib`` library has a
    1530   class ``FTP_TLS`` that you can use for the ``session_factory``
    1531   keyword argument in the ``FTPHost`` constructor. You can't use the
    1532   class directly though if you need additional setup code in
    1533   comparison to ``ftplib.FTP``, for example calling ``prot_p``, to
    1534   secure the data connection. On the other hand,
    1535   `ftputil.session.session_factory`_ can be used to create a custom
    1536   session factory.
    1537  
    1538   If you have other requirements that ``session_factory`` can't
     1513- The ``ftplib`` library has a class ``FTP_TLS`` that you can use for
     1514  the ``session_factory`` keyword argument in the ``FTPHost``
     1515  constructor. You can't use the class directly though *if* you need
     1516  additional setup code in comparison to ``ftplib.FTP``, for example
     1517  calling ``prot_p``, to secure the data connection. On the other
     1518  hand, `ftputil.session.session_factory`_ can be used to create a
     1519  custom session factory.
     1520
     1521- If you have other requirements that ``session_factory`` can't
    15391522  fulfill, you may create your own session factory by inheriting from
    15401523  ``ftplib.FTP_TLS``::
     
    15641547.. _`ftputil.session.session_factory`: `Session factories`_
    15651548
    1566 - If you need to work with Python 2.6, you can use the
    1567   ``ftpslib.FTP_TLS`` class from the M2Crypto_ project. Again, you
    1568   can't use the class directly but need to use
    1569   ``ftputil.session.session_factory`` or a recipe similar to that
    1570   above.
    1571 
    1572   Unfortunately, ``M2Crypto.ftpslib.FTP_TLS`` (at least in version
    1573   0.22.3) doesn't work correctly if you pass unicode strings to its
    1574   methods. Since ``ftputil`` does exactly that at some point (even if
    1575   you used byte strings in ``ftputil`` calls) you need a workaround in
    1576   the session factory class::
    1577 
    1578     import M2Crypto
    1579 
    1580     import ftputil
    1581     import ftputil.tool
    1582 
    1583 
    1584     class M2CryptoSession(M2Crypto.ftpslib.FTP_TLS):
    1585 
    1586         def __init__(self, host, user, password):
    1587             M2Crypto.ftpslib.FTP_TLS.__init__(self)
    1588             # Change the port number if needed.
    1589             self.connect(host, 21)
    1590             self.auth_tls()
    1591             self.login(user, password)
    1592             self.prot_p()
    1593             self._fix_socket()
    1594             ...
    1595 
    1596         def _fix_socket(self):
    1597             """
    1598             Change the socket object so that arguments to `sendall`
    1599             are converted to byte strings before being used.
    1600             """
    1601             original_sendall = self.sock.sendall
    1602             # Bound method, therefore no `self` argument.
    1603             def sendall(data):
    1604                 data = ftputil.tool.as_bytes(data)
    1605                 return original_sendall(data)
    1606             self.sock.sendall = sendall
    1607 
    1608     # Note the `session_factory` parameter. Pass the class, not
    1609     # an instance.
    1610     with ftputil.FTPHost(server, user, password,
    1611                          session_factory=M2CryptoSession) as ftp_host:
    1612         # Use `ftp_host` as usual.
    1613         ...
    1614 
    1615   That said, ``session_factory`` has this workaround built in, so
    1616   normally you don't need to define the session factory yourself!
    1617 
    1618 .. _M2Crypto: https://github.com/martinpaljak/M2Crypto
    16191549
    16201550How do I connect to a non-default port?
     
    16581588The FTP server you connect to may use a directory format that
    16591589``ftputil`` doesn't understand. You can either write and
    1660 `plug in an own parser`_ or ask on the `mailing list`_ for
     1590`plug in your own parser`_ or ask on the `mailing list`_ for
    16611591help.
    16621592
    1663 .. _`plug in an own parser`: `Writing directory parsers`_
     1593.. _`plug in your own parser`: `Writing directory parsers`_
    16641594
    16651595``isdir``, ``isfile`` or ``islink`` incorrectly return ``False``
     
    16841614--------------------
    16851615
    1686 - ``ftputil`` needs at least Python 2.6 to work.
     1616- ``ftputil`` needs at least Python 3.6 to work.
    16871617
    16881618- Whether ``ftputil`` "sees" "hidden" directory and file names (i. e.
     
    17171647files after installation is system-dependent.
    17181648
    1719 .. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
    1720 
    1721 The files ``test_*.py`` and ``mock_ftplib.py`` are for unit-testing.
    1722 If you only *use* ``ftputil``, i. e. *don't* modify it, you can
    1723 delete these files.
     1649.. _`reStructuredText`: https://docutils.sourceforge.net/rst.html
     1650
     1651The files ``test_*.py`` and ``scripted_session.py`` are for
     1652unit-testing. If you only *use* ``ftputil``, i. e. *don't* modify it,
     1653you can delete these files.
    17241654
    17251655
     
    17271657----------
    17281658
    1729 - Mackinnon T, Freeman S, Craig P. 2000. `Endo-Testing:
    1730   Unit Testing with Mock Objects`_.
    1731 
    17321659- Postel J, Reynolds J. 1985. `RFC 959 - File Transfer Protocol (FTP)`_.
    17331660
    1734 - Van Rossum G et al. 2013. `Python Library Reference`_.
    1735 
    1736 .. _`Endo-Testing: Unit Testing with Mock Objects`:
    1737    http://www.connextra.com/aboutUs/mockobjects.pdf
    1738 .. _`RFC 959 - File Transfer Protocol (FTP)`: http://www.ietf.org/rfc/rfc959.txt
    1739 .. _`Python Library Reference`: https://docs.python.org/library/index.html
     1661- Python Software Foundation. 2020. `The Python Standard Library`_.
     1662
     1663.. _`RFC 959 - File Transfer Protocol (FTP)`: https://www.ietf.org/rfc/rfc959.txt
     1664.. _`The Python Standard Library`: https://docs.python.org/library/index.html
    17401665
    17411666
Note: See TracChangeset for help on using the changeset viewer.