Changeset 2048:0de064144674


Ignore:
Timestamp:
Feb 1, 2021, 6:58:37 PM (10 months ago)
Author:
Stefan Schwarzer <sschwarzer@…>
Branch:
default
Message:
Update README/announcements for version 5.0.0-alpha

The `-alpha` suffix is only there in case I want to change any APIs.
The software quality should already be production-level, as usual.
Location:
doc
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/README.txt

    r1968 r2048  
    2020
    2121This ftputil version isn't fully backward-compatible with the previous
    22 version. The backward-incompatible changes are:
     22version due to changes in the `ftplib` module in the standard
     23library of Python 3.9 [1].
    2324
    24 - Python 2 is no longer supported.
     25That said, if you only deal with directory and file paths which solely
     26consist of ASCII characters, this change doesn't affect you.
    2527
    26 - The minimum supported Python 3 version is 3.6.
     28Here are some details, you can find more in the ftputil documentation
     29[2] and in ticket #143 [3].
    2730
    28 - By default, time stamps in directory listings coming from the server
    29   are now assumed to be in UTC. Previously, listings were assumed to
    30   use the local time of the client. [1]
     31Internally, ftputil uses `ftplib.FTP` or compatible classes to perform
     32most low-level FTP operations. In Python 3.8 and before, the default
     33encoding for FTP paths was latin-1, but there was no official
     34documentation on using a different encoding. In Python 3.9, the
     35default encoding changed to UTF-8 and the encoding is configurable
     36with an `ftplib.FTP` constructor argument.
    3137
    32   Correspondingly, the definition of "time shift" has changed. The
    33   time shift is now defined as the time zone used in server listings
    34   (say, UTC+02:00) and UTC, in other words, the time shift now is the
    35   time zone offset applied in the server listings. In earlier ftputil
    36   versions, the time shift was defined as "time used in server
    37   listings" minus "local client time."
     38The documentation of ftputil 4.0.0 and earlier stated:
     39- ftputil uses latin-1 encoding for paths
     40- ftputil uses `ftplib.FTP` as the default session factory
    3841
    39 - The flag `use_list_a_option` of `FTPHost` instances is now set to
    40   `False` by default. This option was intended to make life easier for
    41   users, but turned out to be problematic [2].
    42 
    43 - As in `os.makedirs`, `FTPHost.makedirs` now supports the `exist_ok`
    44   flag and uses the default of `False`. You can get the behavior of
    45   ftputil 3.x by passing `exist_ok=True`. [3]
    46 
    47 If you need to use Python versions before 3.6, please use the previous
    48 stable ftputil version 3.4.
     42With the change of the default encoding in Python 3.9 these two
     43statements are contradictory. To resolve the conflict, the new
     44behavior of ftputil is:
     45- ftputil uses `ftplib.FTP` as default session factory, but explicitly
     46  sets the path encoding to latin-1 (regardless of the Python
     47  version). This is the same behavior as in ftputil 4.0.0 or earlier
     48  if running under Python 3.8 or earlier.
     49- If client code uses a custom session factory (i. e. the
     50  `session_factory` argument of the `FTPHost` constructor), ftputil
     51  will take the path encoding to use for `bytes` paths from the
     52  `encoding` attribute of an FTP session from this factory. If there's
     53  no such attribute, an exception is raised.
    4954
    5055Other changes
    5156~~~~~~~~~~~~~
    5257
    53 - Functions and methods which used to accept only `str` or `bytes`
    54   paths now _also_ accept `PathLike` objects [4, 5].
    55 
    56 - Clear the stat cache when setting a new time shift value. [6]
    57 
    58 - ftputil now officially follows semantic versioning (SemVer) [7].
    59   Actually ftputil has been following semantic versioning since a long
    60   time (probably since version 2.0 in 2004), but it was never
    61   explicitly guaranteed and new major versions were named x.0 instead
    62   of x.0.0 and new minor versions x.y instead of x.y.0.
    63 
    64 - Internal changes: The tests were moved to pytest. The old mocking
    65   approach was replaced by a "scripted session" approach.
     58`ftputil.session.session_factory` got a new keyword argument
     59`encoding` to set the path encoding of the sessions created by the
     60factory. If the argument isn't specified, the path encoding will be
     61taken from the `base_class` argument. (This means that the encoding
     62will be different for `ftplib.FTP` in Python 3.8 or earlier vs.
     63Python 3.9 or later.)
    6664
    6765Documentation
     
    114112
    115113
    116 [1] https://ftputil.sschwarzer.net/trac/ticket/134
    117 [2] https://ftputil.sschwarzer.net/trac/ticket/110
    118 [3] https://ftputil.sschwarzer.net/trac/ticket/117
    119 [4] https://docs.python.org/3/library/os.html#os.PathLike
    120 [5] https://ftputil.sschwarzer.net/trac/ticket/119
    121 [6] https://ftputil.sschwarzer.net/trac/ticket/136
    122 [7] https://semver.org/
     114[1] https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-python-api
     115    "The encoding parameter has been added to the classes ftplib.FTP
     116    and ftplib.FTP_TLS as a keyword-only parameter, and the default
     117    encoding is changed from Latin-1 to UTF-8 to follow RFC 2640."
     118[2] https://ftputil.sschwarzer.net/trac/wiki/Documentation
     119[3] https://ftputil.sschwarzer.net/trac/ticket/143
     120
  • doc/announcements.txt

    r1969 r2048  
     1ftputil 5.0.0-alpha is now available from
     2https://ftputil.sschwarzer.net/download .
     3
     4
     5Changes since the last stable release 4.0
     6-----------------------------------------
     7
     8Backward-incompatible changes
     9~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     10
     11This ftputil version isn't fully backward-compatible with the previous
     12version due to changes in the `ftplib` module in the standard
     13library of Python 3.9 [1].
     14
     15That said, if you only deal with directory and file paths which solely
     16consist of ASCII characters, this change doesn't affect you.
     17
     18Here are some details. You can find more in the ftputil documentation
     19[2] and in ticket #143 [3].
     20
     21Internally, ftputil uses `ftplib.FTP` or compatible classes to perform
     22most low-level FTP operations. In Python 3.8 and before, the default
     23encoding for FTP paths was latin-1, but there was no official
     24documentation on using a different encoding. In Python 3.9, the
     25default encoding changed to UTF-8 and the encoding is configurable
     26with an `ftplib.FTP` constructor argument.
     27
     28The documentation of ftputil 4.0.0 and earlier stated:
     29- ftputil uses latin-1 encoding for paths
     30- ftputil uses `ftplib.FTP` as the default session factory
     31
     32With the change of the default encoding in Python 3.9 these two
     33statements are contradictory. To resolve the conflict, the new
     34behavior of ftputil is:
     35- ftputil uses `ftplib.FTP` as default session factory, but explicitly
     36  sets the path encoding to latin-1 (regardless of the Python
     37  version). This is the same behavior as in ftputil 4.0.0 or earlier
     38  if running under Python 3.8 or earlier.
     39- If client code uses a custom session factory (i. e. the
     40  `session_factory` argument of the `FTPHost` constructor), ftputil
     41  will take the path encoding to use for `bytes` paths from the
     42  `encoding` attribute of an FTP session from this factory. If there's
     43  no such attribute, an exception is raised.
     44
     45Other changes
     46~~~~~~~~~~~~~
     47
     48`ftputil.session.session_factory` got a new keyword argument
     49`encoding` to set the path encoding of the sessions created by the
     50factory. If the argument isn't specified, the path encoding will be
     51taken from the `base_class` argument. (This means that the encoding
     52will be different for `ftplib.FTP` in Python 3.8 or earlier vs.
     53Python 3.9 or later.)
     54
     55
     56What is ftputil?
     57----------------
     58
     59ftputil is a high-level FTP client library for the Python programming
     60language. ftputil implements a virtual file system for accessing FTP
     61servers, that is, it can generate file-like objects for remote files.
     62The library supports many functions similar to those in the `os`,
     63`os.path` and `shutil` modules. ftputil has convenience functions for
     64conditional uploads and downloads, and handles FTP clients and servers
     65in different timezones.
     66
     67See the documentation for details:
     68https://ftputil.sschwarzer.net/trac/wiki/Documentation
     69
     70
     71License
     72-------
     73
     74ftputil is open source software, released under the 3-clause BSD
     75license (see https://opensource.org/licenses/BSD-3-Clause ).
     76
     77
     78[1] https://docs.python.org/3/whatsnew/3.9.html#changes-in-the-python-api
     79    "The encoding parameter has been added to the classes ftplib.FTP
     80    and ftplib.FTP_TLS as a keyword-only parameter, and the default
     81    encoding is changed from Latin-1 to UTF-8 to follow RFC 2640."
     82[2] https://ftputil.sschwarzer.net/trac/wiki/Documentation
     83[3] https://ftputil.sschwarzer.net/trac/ticket/143
     84
     85
     86Best regards,
     87Stefan
     88
     89----------------------------------------------------------------------
    190ftputil 4.0.0 is now available from
    291https://ftputil.sschwarzer.net/download .
Note: See TracChangeset for help on using the changeset viewer.