ftputil

https://ftputil.sschwarzer.net/documentation/
Admin
ftputil is a high-level interface to Python's ftplib module that provides FTP file transfer...
Tokens:13,700
Snippets:122
Trust Score:7.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### ftplib FTP Connection Example

Source: https://ftputil.sschwarzer.net/documentation

Demonstrates the limitations of a single `ftplib.FTP` connection when attempting to perform operations concurrently, such as starting a file transfer and then querying the current directory.

```python
>>> import ftplib
>>> ftp = ftplib.FTP(server, user, password)
>>> ftp.pwd()
'/'
>>> # Start transfer. `CONTENTS` is a text file on the server.
>>> socket = ftp.transfercmd("RETR CONTENTS")
>>> socket
<socket._socketobject object at 0x7f801a6386e0>
>>> ftp.pwd()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib64/python2.7/ftplib.py", line 578, in pwd
    return parse257(resp)
  File "/usr/lib64/python2.7/ftplib.py", line 842, in parse257
    raise error_reply, resp
ftplib.error_reply: 226-File successfully transferred
226 0.000 seconds (measured here), 5.60 Mbytes per second
>>>

```

--------------------------------

### FTPHost Construction Example

Source: https://ftputil.sschwarzer.net/documentation

Shows the basic construction of an FTPHost instance, specifying server, user, and password. The account and session_factory arguments are typically not needed.

```python
ftp_host = ftputil.FTPHost(
    server, user, password, account, session_factory=ftplib.FTP
)
```

--------------------------------

### ftputil FTPHost Connection Example

Source: https://ftputil.sschwarzer.net/documentation

Illustrates how `ftputil.FTPHost` manages operations like opening a file and querying the current directory, showcasing its ability to handle these tasks on a single conceptual connection.

```python
>>> import ftputil
>>> ftp_host = ftputil.FTPHost(server, user, password)
>>> ftp_host.getcwd()
>>> fobj = ftp_host.open("CONTENTS")
>>> fobj
<ftputil.file.FTPFile object at 0x7f8019d3aa50>
>>> ftp_host.getcwd()
u'/'
>>> fobj.readline()
u'Contents of FTP test directory\n'
>>> fobj.close()
>>>

```

--------------------------------

### Configuring Hidden File Listing

Source: https://ftputil.sschwarzer.net/documentation

Demonstrates how to enable the listing of hidden files and directories (those starting with a dot) by setting the `use_list_a_option` attribute to `True`.

```APIDOC
## Configuring Hidden File Listing

### Description
This snippet shows how to configure `ftputil` to list hidden files and directories on an FTP server by enabling the `-a` option in the `LIST` command.

### Usage
Set the `use_list_a_option` attribute of an `FTPHost` instance to `True`.

```python
import ftputil
import ftplib

ftp_host = ftputil.FTPHost(
    server, user, password, account, session_factory=ftplib.FTP
)
ftp_host.use_list_a_option = True
```

### Caveats
- Ensure the FTP server supports the `-a` option to avoid unexpected behavior.
- Some servers may be configured to ignore the `-a` option even if supported.
```

--------------------------------

### Configured FTP_TLS Session Factory

Source: https://ftputil.sschwarzer.net/documentation

Example of creating a session factory derived from `ftplib.FTP_TLS` to connect on a specific port, encrypt the data channel, use UTF-8 encoding for paths, and enable debug output.

```python
import ftplib

import ftputil
import ftputil.session


my_session_factory = ftputil.session.session_factory(
    base_class=ftpslib.FTP_TLS,
    port=31,
    encrypt_data_channel=True,
    encoding="UTF-8",
    debug_level=2,
)

with ftputil.FTPHost(
    server, user, password, session_factory=my_session_factory
) as ftp_host:
    ...

```

--------------------------------

### Setting Cache Max Age

Source: https://ftputil.sschwarzer.net/documentation

Configure the maximum age of cache entries in seconds. Set to `None` for unlimited cache duration. This example sets the cache age to one hour.

```python
with ftputil.FTPHost(server, user, password) as ftp_host:
    ftp_host.stat_cache.max_age = 60 * 60  # = 3600 seconds
```

--------------------------------

### Get Stat Information Following Links with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Use `stat` to get status information for a path, following symbolic links until a regular file or directory is found. This method inherits the limitations of `lstat` regarding the information parsed from the server.

```python
ftp_host.stat(path)
```

--------------------------------

### FTP Host Callback Function Example

Source: https://ftputil.sschwarzer.net/documentation

Define a callback function to process chunks of data during file transfers. The callback receives each transferred chunk as a bytestring, useful for implementing progress indicators.

```python
callback(chunk)
```

--------------------------------

### Cache Inconsistency Example

Source: https://ftputil.sschwarzer.net/documentation

Illustrates a potential race condition when the cache is disabled. A file might be removed between the `exists` check and the `getmtime` call, leading to an error.

```python
with ftputil.FTPHost(server, user, password) as ftp_host:
    ftp_host.stat_cache.disable()
    if ftp_host.path.exists("some_file"):
        mtime = ftp_host.path.getmtime("some_file")
```

--------------------------------

### List Directory Contents with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Use `listdir` to get a list of files and directories within a specified path. The special entries '.' and '..' are excluded from the results.

```python
ftp_host.listdir(path)
```

--------------------------------

### Get Current Working Directory

Source: https://ftputil.sschwarzer.net/documentation

Retrieves the absolute path of the current working directory on the remote FTP server.

```APIDOC
## getcwd()

### Description
Returns the absolute current directory on the remote host, similar to `os.getcwd()`.

### Method
`getcwd()`

### Endpoint
N/A (Method call)

### Parameters
None

### Response
- **current_directory** (string) - The absolute path of the current directory on the remote server.
```

--------------------------------

### Get File/Directory Status with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Use `lstat` to retrieve status information for a given path, similar to `os.lstat`. The information is parsed from the FTP server's `LIST` command output and may have limitations regarding user/group IDs, modification times, and link information.

```python
ftp_host.lstat(path)
```

--------------------------------

### Download and Copy Files with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Demonstrates downloading files from the login directory and creating a new directory to copy a remote file into using FTPHost objects. Requires connection details for the FTP server.

```python
import ftputil

# Download some files from the login directory.
with ftputil.FTPHost("ftp.domain.com", "user", "password") as ftp_host:
    names = ftp_host.listdir(ftp_host.curdir)
    for name in names:
        if ftp_host.path.isfile(name):
            ftp_host.download(name, name)  # remote, local

# Make a new directory and copy a remote file into it.
with ftputil.FTPHost("ftp.domain.com", "user", "password") as ftp_host:
    ftp_host.mkdir("newdir")
    with ftp_host.open("index.html", "rb") as source:
        with ftp_host.open("newdir/index.html", "wb") as target:
            ftp_host.copyfileobj(source, target)  # similar to shutil.copyfileobj

```

--------------------------------

### Initialize FTPHost

Source: https://ftputil.sschwarzer.net/documentation

Instantiate an FTPHost object to connect to an FTP server. This object provides access to the stat cache.

```python
ftp_host = ftputil.FTPHost(host, user, password)
```

--------------------------------

### walk(top, topdown=True, onerror=None, followlinks=False)

Source: https://ftputil.sschwarzer.net/documentation

Iterates over a directory tree, similar to `os.walk`. This method is part of the `FTPHost` object.

```APIDOC
## walk(top, topdown=True, onerror=None, followlinks=False)

### Description
Iterates over a directory tree, similar to `os.walk`. This method uses code adapted from Python's `os.walk` with necessary modifications for FTP.

### Method
`walk(top, topdown=True, onerror=None, followlinks=False)`

### Parameters
- **top** (string) - Required - The root directory to start the walk from.
- **topdown** (boolean) - Optional - If True, it visits directories before their subdirectories. Defaults to True.
- **onerror** (callable) - Optional - A function to call if an error occurs during traversal. Defaults to None.
- **followlinks** (boolean) - Optional - If True, it will follow symbolic links. Defaults to False.

### Usage Example
```python
for dirpath, dirnames, filenames in ftp_host.walk('/remote/directory'):
    print(f'Visiting: {dirpath}')
    for filename in filenames:
        print(f'  File: {filename}')
```
```

--------------------------------

### Create Directories Recursively with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Creates directories recursively, similar to os.makedirs. The mode parameter is ignored. exist_ok controls error handling for existing directories.

```python
makedirs(path, [mode], exist_ok=False)
```

--------------------------------

### Create Directory with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Creates a directory on the remote host. Intermediate directories are not created. The mode parameter is ignored.

```python
mkdir(path, [mode])
```

--------------------------------

### Read and Process Remote File Line by Line with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Shows how to open a remote file for reading and iterate over its lines using a `for` loop within a `with` statement. Includes basic text processing for each line.

```python
with ftputil.FTPHost(server, user, password) as ftp_host:
    with ftp_host.open("some_file") as input_file:
        for line in input_file:
            # Do something with the line, e.g. 
            print(line.strip().replace("ftplib", "ftputil"))

```

--------------------------------

### FTPHost.open

Source: https://ftputil.sschwarzer.net/documentation

Opens a file on the remote host for reading or writing. It returns a file-like object that mimics the behavior of Python's built-in open function.

```APIDOC
## FTPHost.open(path, mode="r", buffering=None, encoding=None, errors=None, newline=None, rest=None)

### Description
Opens a file on the remote host. The path can be absolute or relative. The default mode is 'r' (reading text files). Valid modes are 'r', 'rb', 'w', and 'wb'.

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file on the remote host.
- **mode** (string) - Optional - The mode to open the file in ('r', 'rb', 'w', 'wb'). Defaults to 'r'.
- **buffering** (integer) - Optional - Similar semantics to Python's built-in open.
- **encoding** (string) - Optional - The encoding to use for text mode. Defaults to locale.getpreferredencoding(). Must not be specified for binary mode.
- **errors** (string) - Optional - Similar semantics to Python's built-in open.
- **newline** (string) - Optional - Similar semantics to Python's built-in open.
- **rest** (integer) - Optional - For binary mode, specifies the byte offset to start reading or writing from. Use only for error recovery.

### Request Example
```python
import ftputil

with ftputil.FTPHost('ftp.example.com', 'user', 'password') as ftp_host:
    with ftp_host.open('remote_file.txt', 'w', encoding='utf8') as fobj:
        fobj.write('This is some text.')
```

### Response
#### Success Response (200)
Returns a file-like object that refers to the path on the remote host.
```

--------------------------------

### Open and Write to a Remote File with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Demonstrates opening a remote file in write mode with a specified encoding and writing text to it. Ensures the file is automatically closed using a `with` statement.

```python
import ftputil

with ftputil.FTPHost(...) as ftp_host:
    ... 
    with ftp_host.open("new_file", "w", encoding="utf8") as fobj:
        fobj.write("This is some text.")

```

--------------------------------

### Compare OSError with FTPOSError

Source: https://ftputil.sschwarzer.net/documentation

Illustrates the similarity in exception handling between local file system operations using OSError and remote operations using ftputil's FTPOSError.

```python
try:
    os.chdir("nonexisting_directory")
except OSError:
    ...
```

```python
host = ftputil.FTPHost("host", "user", "password")
try:
    host.chdir("nonexisting_directory")
except OSError:
    ...
```

--------------------------------

### path.walk(path, func, arg)

Source: https://ftputil.sschwarzer.net/documentation

A method within `FTPHost.path` similar to `os.path.walk`. It traverses a directory tree and applies a function to each file and directory.

```APIDOC
## path.walk(path, func, arg)

### Description
Similar to `os.path.walk`, this method in `FTPHost.path` can be used to traverse a directory tree. However, `FTPHost.walk` is generally recommended for ease of use.

### Method
`path.walk(path, func, arg)`

### Parameters
- **path** (string) - Required - The starting path for the walk.
- **func** (callable) - Required - The function to call for each file and directory. It typically receives `(path, dirs, files)` as arguments.
- **arg** (any) - Optional - An arbitrary argument to pass to the `func`.

### Usage Example
```python
def process_file(path, dirs, files):
    print(f"Processing directory: {path}")
    # ... further processing ...

ftp_host.path.walk('/remote/directory', process_file, None)
```
```

--------------------------------

### copyfileobj(source, target, length=64*1024)

Source: https://ftputil.sschwarzer.net/documentation

Copies the contents from a source file-like object to a target file-like object. The buffer size can be specified.

```APIDOC
## copyfileobj(source, target, length=64*1024)

### Description
Copies the contents from the file-like object `source` to the file-like object `target`. The only difference to `shutil.copyfileobj` is the default buffer size.

### Method
`copyfileobj(source, target, length=64*1024)`

### Parameters
- **source** (file-like object) - Required - The source of the data.
- **target** (file-like object) - Required - The destination for the data.
- **length** (integer) - Optional - The buffer size for copying. Defaults to 64*1024.

### Usage Example
```python
# Assuming 'source_obj' and 'target_obj' are file-like objects
ftp_host.copyfileobj(source_obj, target_obj)

# With a custom buffer size
ftp_host.copyfileobj(source_obj, target_obj, length=1024*1024)
```

### Important Note
The interfaces of `source` and `target` must match. For example, if `source` is opened in text mode and `target` in binary mode, the transfer will fail due to type mismatches (str vs. bytes).
```

--------------------------------

### Directory and File Information

Source: https://ftputil.sschwarzer.net/documentation

Methods for retrieving information about directories, files, and links on an FTP server.

```APIDOC
## listdir(path)

### Description
Returns a list containing the names of the files and directories in the given path, similar to os.listdir. The special names `.` and `..` are not in the list.

### Method
`listdir`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the directory to list.

### Response
#### Success Response (list of strings)
- A list of strings, where each string is the name of a file or directory.

```

```APIDOC
## lstat(path)

### Description
Returns an object similar to that from os.lstat. This is a kind of tuple with additional attributes; see the documentation of the `os` module for details. The result is derived by parsing the output of a `LIST` command on the server.

### Method
`lstat`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file or directory to stat.

### Response
#### Success Response (object)
- An object similar to `os.lstat` result, containing file/directory information. Attributes not determinable from the server's LIST output will be set to `None`.

### Limitations
- User and group IDs are strings, not numbers.
- Modification times may be rough.
- Links are recognized only if the server provides this information.
- `RootDirError` is raised when stat'ing the root directory.

```

```APIDOC
## stat(path)

### Description
Returns `stat` information also for files which are pointed to by a link. This method follows multiple links until a regular file or directory is found. If an infinite link chain is encountered or the target of the last link in the chain doesn’t exist, a `PermanentError` is raised.

### Method
`stat`

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file or directory to stat.

### Response
#### Success Response (object)
- An object similar to `os.stat` result, containing file/directory information. The limitations of the `lstat` method also apply.

```

--------------------------------

### Enable Listing of Hidden Files with FTPHost

Source: https://ftputil.sschwarzer.net/documentation

Set `FTPHost.use_list_a_option` to `True` to enable the `-a` option in the FTP `LIST` command, which lists hidden files and directories. Use this only if the FTP server supports the `-a` option to avoid unexpected behavior.

```python
ftp_host = ftputil.FTPHost(
    server, user, password, account, session_factory=ftplib.FTP
)
ftp_host.use_list_a_option = True
```

--------------------------------

### Define a Custom FTP Directory Parser Class

Source: https://ftputil.sschwarzer.net/documentation

Inherit from `ftputil.stat.Parser` to create a custom parser. Implement `parse_line` to process each directory listing line and `ignores_line` to specify lines that should be skipped. Use `ftputil.error.ParserError` for unparseable lines.

```python
import ftputil.error
import ftputil.stat

class XyzParser(ftputil.stat.Parser):
    """
    Parse the default format of the FTP server of the XYZ
    corporation.
    """

    def parse_line(self, line, time_shift=0.0):
        """
        Parse a `line` from the directory listing and return a
        corresponding `StatResult` object. If the line can't
        be parsed, raise `ftputil.error.ParserError`.

        The `time_shift` argument can be used to fine-tune the
        parsing of dates and times. See the class
        `ftputil.stat.UnixParser` for an example.
        """
        # Split the `line` argument and examine it further; if
        # something goes wrong, raise an `ftputil.error.ParserError`.
        ...
        # Make a `StatResult` object from the parts above.
        stat_result = ftputil.stat.StatResult(...)
        # `_st_name`, `_st_target` and `_st_mtime_precision` are optional.
        stat_result._st_name = ...
        stat_result._st_target = ...
        stat_result._st_mtime_precision = ...
        return stat_result

    # Define `ignores_line` only if the default in the base class
    # doesn't do enough!
    def ignores_line(self, line):
        """
        Return a true value if the line should be ignored. For
        example, the implementation in the base class handles
        lines like "total 17". On the other hand, if the line
        should be used for stat'ing, return a false value.
        """
        is_total_line = super().ignores_line(line)
        my_test = ...
        return is_total_line or my_test

```

--------------------------------

### FTPFile Object Methods

Source: https://ftputil.sschwarzer.net/documentation

The FTPFile object returned by FTPHost.open provides standard file-like methods for interacting with remote files.

```APIDOC
## FTPFile Object Methods

### Description
These methods operate on the file-like object returned by `FTPHost.open` and have similar semantics to standard Python file objects.

### Methods
- **close()**: Closes the remote file.
- **read([count])**: Reads and returns data from the file. `count` specifies the maximum number of bytes or characters to read.
- **readline([count])**: Reads and returns a single line from the file.
- **readlines()**: Reads and returns all lines from the file as a list.
- **write(data)**: Writes `data` (bytes or string) to the file.
- **writelines(string_sequence)**: Writes a sequence of strings to the file.

### Attributes
- **closed** (boolean): True if the file is closed, False otherwise.

### Usage Example
```python
with ftputil.FTPHost(server, user, password) as ftp_host:
    with ftp_host.open('some_file.txt') as input_file:
        for line in input_file:
            print(line.strip().replace('ftplib', 'ftputil'))
```
```

--------------------------------

### Directory Operations

Source: https://ftputil.sschwarzer.net/documentation

Functions for creating and removing directories on the remote host.

```APIDOC
## mkdir(path, [mode])

### Description
Creates a directory on the remote host. Does not create intermediate directories.

### Parameters
- **path** (string) - The path of the directory to create.
- **mode** (int, optional) - Ignored parameter for compatibility.
```

```APIDOC
## makedirs(path, [mode], exist_ok=False)

### Description
Creates a directory and its intermediate directories on the remote host.

### Parameters
- **path** (string) - The path of the directory to create.
- **mode** (int, optional) - Ignored parameter for compatibility.
- **exist_ok** (bool, optional) - If True, existing directories are not considered an error. Defaults to False.
```

```APIDOC
## rmdir(path)

### Description
Removes a directory on the remote host. Raises PermanentError if the directory is not empty.

### Parameters
- **path** (string) - The path of the directory to remove.
```

```APIDOC
## rmtree(path, ignore_errors=False, onerror=None)

### Description
Removes a directory tree on the remote host, possibly non-empty. Interface is compatible with `shutil.rmtree`.

### Parameters
- **path** (string) - The path of the directory tree to remove.
- **ignore_errors** (bool, optional) - If True, errors are ignored. Defaults to False.
- **onerror** (callable, optional) - A function to handle errors, accepting `func`, `path`, and `exc_info`.
```

--------------------------------

### Demonstrate Obsolete Cache Entry

Source: https://ftputil.sschwarzer.net/documentation

Illustrates a scenario where one FTPHost object holds an obsolete cache entry after another FTPHost object modifies the same file. This highlights the need for cache invalidation in concurrent access situations.

```python
with (
    ftputil.FTPHost(server, user1, password1) as ftp_host1,
    ftputil.FTPHost(server, user1, password1) as ftp_host2
):
    stat_result1 = ftp_host1.stat("some_file")
    stat_result2 = ftp_host2.stat("some_file")
    ftp_host2.remove("some_file")
    # `ftp_host1` will still see the obsolete cache entry!
    print(ftp_host1.stat("some_file"))
    # Will raise an exception since an `FTPHost` object
    # knows of its own changes.
    print(ftp_host2.stat("some_file"))

```

--------------------------------

### ftputil.session.session_factory Usage

Source: https://ftputil.sschwarzer.net/documentation

Use `ftputil.session.session_factory` to create session factories with various configurations for base class, port, passive mode, data channel encryption, encoding, and debug level.

```python
session_factory(
    base_class=ftplib.FTP,
    port=21,
    use_passive_mode=None,
    encrypt_data_channel=True,
    encoding=None,
    debug_level=None,
)

```

--------------------------------

### Upload File

Source: https://ftputil.sschwarzer.net/documentation

Copies a local file to the remote FTP server.

```APIDOC
## upload(source, target, callback=None)

### Description
Copies a local source file to the remote host under the specified target name. The file content is always transferred in binary mode. An optional callback function can be provided to monitor the transfer progress.

### Method
`upload(source, target, callback=None)`

### Endpoint
N/A (Method call)

### Parameters
- **source** (string) - The path to the local source file.
- **target** (string) - The path for the target file on the remote host.
- **callback** (function, optional) - A function invoked for each transferred chunk of data. It receives the chunk as a bytestring argument.

### Request Example
```python
def progress_callback(chunk):
    print(f"Transferred {len(chunk)} bytes")

ftp_host.upload('local_file.txt', 'remote_file.txt', callback=progress_callback)
```

### Response
None
```

--------------------------------

### Download File

Source: https://ftputil.sschwarzer.net/documentation

Copies a file from the remote FTP server to a local destination.

```APIDOC
## download(source, target, callback=None)

### Description
Performs a download from a remote source file to a local target file. An optional callback function can be provided for progress monitoring.

### Method
`download(source, target, callback=None)`

### Endpoint
N/A (Method call)

### Parameters
- **source** (string) - The path to the remote source file.
- **target** (string) - The path for the local target file.
- **callback** (function, optional) - A function invoked for each transferred chunk of data. It receives the chunk as a bytestring argument.

### Request Example
```python
def progress_callback(chunk):
    print(f"Downloaded {len(chunk)} bytes")

ftp_host.download('remote_file.txt', 'local_file.txt', callback=progress_callback)
```

### Response
None
```

--------------------------------

### Using FTPHost with a 'with' statement

Source: https://ftputil.sschwarzer.net/documentation

Demonstrates how to use an FTPHost object within a 'with' statement for automatic session management and closure. The FTPHost instance and associated sessions are closed automatically upon exiting the block.

```python
import ftputil

with ftputil.FTPHost(server, user, password) as ftp_host:
    print(ftp_host.listdir(ftp_host.curdir))
```

--------------------------------

### set_parser(parser)

Source: https://ftputil.sschwarzer.net/documentation

Sets a custom parser for FTP directories. This allows for handling non-standard directory listings.

```APIDOC
## set_parser(parser)

### Description
Sets a custom parser for FTP directories. This is useful when the default parsers in `ftputil` do not correctly interpret the directory listing from the FTP server.

### Method
`set_parser(parser)`

### Parameters
- **parser** (parser instance) - Required - An instance of a custom parser class.

### Usage Example
```python
# Assuming 'my_custom_parser' is an instance of a custom parser class
ftp_host.set_parser(my_custom_parser)
```
```

--------------------------------

### Download if Newer

Source: https://ftputil.sschwarzer.net/documentation

Downloads a file from the remote server to a local destination only if the remote file is newer than the local file or if the local file does not exist.

```APIDOC
## download_if_newer(source, target, callback=None)

### Description
Corresponds to `upload_if_newer` but performs a download from the server to the local host. It downloads if the remote source file is newer than the local target file, or if the target file does not exist.

### Method
`download_if_newer(source, target, callback=None)`

### Endpoint
N/A (Method call)

### Parameters
- **source** (string) - The path to the remote source file.
- **target** (string) - The path for the local target file.
- **callback** (function, optional) - A function invoked for each transferred chunk of data.

### Response
- **downloaded** (boolean) - `True` if a download occurred, `False` otherwise.

### Notes
- Similar caveats to `upload_if_newer` regarding timestamp precision and interrupted transfers apply.
```

--------------------------------

### Custom FTP Session Factory

Source: https://ftputil.sschwarzer.net/documentation

Define a custom session factory class to override default connection behavior, such as connecting to a non-default port. Ensure you pass the class itself, not an instance, to `session_factory`.

```python
import ftplib
import ftputil

EXAMPLE_PORT = 50001

class MySession(ftplib.FTP):

    def __init__(self, host, userid, password, port):
        """Act like ftplib.FTP's constructor but connect to another port."""
        ftplib.FTP.__init__(self)
        self.connect(host, port)
        self.login(userid, password)

# Do _not_ use an _instance_ of `MySession()` as factory, -
# use the class itself.
with ftputil.FTPHost(
    host, userid, password, port=EXAMPLE_PORT, session_factory=MySession
) as ftp_host:
    # Use `ftp_host` as usual.
    ...

```

--------------------------------

### Construct a StatResult Object

Source: https://ftputil.sschwarzer.net/documentation

Create a `StatResult` object to represent file or directory information. Populate it with data corresponding to `os.stat` attributes. Optional attributes like `_st_name`, `_st_target`, and `_st_mtime_precision` can also be set.

```python
stat_result = StatResult(
    (
        st_mode,
        st_ino,
        st_dev,
        st_nlink,
        st_uid,
        st_gid,
        st_size,
        st_atime,
        st_mtime,
        st_ctime,
    )
)
stat_result._st_name = ...
stat_result._st_target = ...
stat_result._st_mtime_precision = ...

```

--------------------------------

### Set File Permissions with chmod

Source: https://ftputil.sschwarzer.net/documentation

Use `chmod` to set access modes for a path on the FTP server. Be aware that not all servers support this command, and `CommandNotImplementedError` or `PermanentError` may be raised.

```python
ftp_host.chmod("some_directory", 0o755)
```

```python
with ftputil.FTPHost(server, user, password) as ftp_host:
    try:
        ftp_host.chmod("some_file", 0o644)
    except ftputil.error.CommandNotImplementedError:
        # `chmod` not supported
        ...
    except ftputil.error.PermanentError:
        # Possibly a non-existent file
        ...
```

--------------------------------

### Compare IOError with FTPIOError

Source: https://ftputil.sschwarzer.net/documentation

Compares handling of file opening errors between local file system (IOError) and remote FTP operations (IOError, but with different error codes and messages).

```python
>>> try:
...     f = open("not_there")
... except IOError as obj:
...     print(obj.errno)
...     print(obj.strerror)
... 
2
No such file or directory
```

```python
>>> ftp_host = ftputil.FTPHost("host", "user", "password")
>>> try:
...     f = ftp_host.open("not_there")
... except IOError as obj:
...     print(obj.errno)
...     print(obj.strerror)
... 
550
550 not_there: No such file or directory.
```

--------------------------------

### Path Manipulation Methods

Source: https://ftputil.sschwarzer.net/documentation

Methods available on the `path` attribute of an `FTPHost` object, similar to `os.path`.

```APIDOC
## Path Methods (e.g., abspath, basename, exists, etc.)

### Description
These methods operate on remote paths with the same semantics as their `os.path` counterparts in Python.

### Available Methods
- `abspath(path)`
- `basename(path)`
- `commonprefix(path_list)`
- `dirname(path)`
- `exists(path)`
- `getmtime(path)`
- `getsize(path)`
- `isabs(path)`
- `isdir(path)`
- `isfile(path)`
- `islink(path)`
- `join(path1, path2, ...)`
- `normcase(path)`
- `normpath(path)`
- `split(path)`
- `splitdrive(path)`
- `splitext(path)`
- `walk(path, func, arg)`

### Parameters
- **path** (string) - Required - The path or list of paths to operate on.
- **path_list** (list of strings) - Required for `commonprefix` - A list of paths.
- **func** (callable) - Required for `walk` - A function to be called for each directory visited.
- **arg** - Required for `walk` - An argument to be passed to the `func`.

### Response
- The return type varies depending on the method used, mirroring the behavior of the `os.path` module.

### Note
`ftputil`’s `is...` methods return `False` if they can’t find the path given by their argument.
```

--------------------------------

### chmod(path, mode)

Source: https://ftputil.sschwarzer.net/documentation

Sets the access mode (permission flags) for the given path on the FTP server. Note that not all FTP servers support this command.

```APIDOC
## chmod(path, mode)

### Description
Sets the access mode (permission flags) for the given path. The mode is an integer as returned by the `stat` and `lstat` methods. Be aware that not all FTP servers support the `chmod` command.

### Method
`chmod(path, mode)`

### Parameters
- **path** (string) - Required - The path to the file or directory.
- **mode** (integer) - Required - The desired access mode (e.g., 0o755).

### Usage Example
```python
# Using octal notation for mode
ftp_host.chmod("some_directory", 0o755)

# Handling potential errors
import ftputil
try:
    ftp_host.chmod("some_file", 0o644)
except ftputil.error.CommandNotImplementedError:
    print("`chmod` not supported")
except ftputil.error.PermanentError:
    print("Possibly a non-existent file or other permanent error")
```
```

--------------------------------

### Upload if Newer

Source: https://ftputil.sschwarzer.net/documentation

Uploads a local file to the remote server only if the local file is newer than the remote file or if the remote file does not exist.

```APIDOC
## upload_if_newer(source, target, callback=None)

### Description
Uploads a local file to the remote host if the source file's last modification time is more recent than the target file's, or if the target file does not exist. It considers timestamp precision and transfers a file "if in doubt".

### Method
`upload_if_newer(source, target, callback=None)`

### Endpoint
N/A (Method call)

### Parameters
- **source** (string) - The path to the local source file.
- **target** (string) - The path for the target file on the remote host.
- **callback** (function, optional) - A function invoked for each transferred chunk of data.

### Response
- **uploaded** (boolean) - `True` if an upload occurred, `False` otherwise.

### Notes
- Only checks existence and modification time; does not compare other file properties like size.
- If a transfer is interrupted, the remote file might have a newer modification time, preventing re-upload with this method. Consider using `upload` or removing the incomplete file first.
```

--------------------------------

### Accessing Cached Stat Information

Source: https://ftputil.sschwarzer.net/documentation

This snippet demonstrates accessing cached file system stat information. It assumes `ftp_host2` is an initialized ftputil FTPHost object.

```python
print(ftp_host2.stat("some_file"))
```

--------------------------------

### Path Manipulation with ftputil

Source: https://ftputil.sschwarzer.net/documentation

ftputil provides path manipulation methods on the `FTPHost.path` attribute, mirroring the functionality of Python's `os.path` module for remote paths.

```python
ftp_host.path.abspath(path)
```

```python
ftp_host.path.basename(path)
```

```python
ftp_host.path.commonprefix(path_list)
```

```python
ftp_host.path.dirname(path)
```

```python
ftp_host.path.exists(path)
```

```python
ftp_host.path.getmtime(path)
```

```python
ftp_host.path.getsize(path)
```

```python
ftp_host.path.isabs(path)
```

```python
ftp_host.path.isdir(path)
```

```python
ftp_host.path.isfile(path)
```

```python
ftp_host.path.islink(path)
```

```python
ftp_host.path.join(path1, path2, ...)
```

```python
ftp_host.path.normcase(path)
```

```python
ftp_host.path.normpath(path)
```

```python
ftp_host.path.split(path)
```

```python
ftp_host.path.splitdrive(path)
```

```python
ftp_host.path.splitext(path)
```

```python
ftp_host.path.walk(path, func, arg)
```

--------------------------------

### File and Link Removal

Source: https://ftputil.sschwarzer.net/documentation

Functions for removing files and symbolic links on the remote host.

```APIDOC
## remove(path)

### Description
Removes a file or link on the remote host, similar to `os.remove`.

### Parameters
- **path** (string) - The path of the file or link to remove.
```

```APIDOC
## unlink(path)

### Description
An alias for the `remove` function.
```

--------------------------------

### close()

Source: https://ftputil.sschwarzer.net/documentation

Closes the connection to the remote host. After this, no more interaction with the FTP server is possible with this FTPHost object. It's generally recommended to use a `with` statement for managing FTPHost instances.

```APIDOC
## close()

### Description
Closes the connection to the remote host. No further interaction with the FTP server is possible with this `FTPHost` object after calling this method.

### Method
`close()`

### Usage Example
```python
# Typically used within a 'with' statement, but can be called explicitly:
ftp_host.close()
```
```

--------------------------------

### Change Working Directory

Source: https://ftputil.sschwarzer.net/documentation

Changes the current working directory on the remote FTP server.

```APIDOC
## chdir(directory)

### Description
Sets the current directory on the FTP server, similar to `os.chdir()`.

### Method
`chdir(directory)`

### Endpoint
N/A (Method call)

### Parameters
- **directory** (string) - The path to the directory to change to. Can be an absolute or relative path.

### Response
None
```

--------------------------------

### rename(source, target)

Source: https://ftputil.sschwarzer.net/documentation

Renames the source file or directory on the FTP server to the target name.

```APIDOC
## rename(source, target)

### Description
Renames the source file (or directory) on the FTP server.

### Method
`rename(source, target)`

### Parameters
- **source** (string) - Required - The current name of the file or directory.
- **target** (string) - Required - The new name for the file or directory.

### Usage Example
```python
ftp_host.rename("old_name.txt", "new_name.txt")
ftp_host.rename("old_directory", "new_directory")
```
```

--------------------------------

### keep_alive()

Source: https://ftputil.sschwarzer.net/documentation

Attempts to keep the connection to the remote server active to prevent timeouts. Useful during long transfers.

```APIDOC
## keep_alive()

### Description
Attempts to keep the connection to the remote server active to prevent timeouts. This method is primarily intended for use during long file uploads or downloads, either in a separate thread or from a callback function.

### Method
`keep_alive()`

### Usage Example
```python
# In a scenario where a long operation is happening:
# (This is a conceptual example, actual implementation might involve threads or callbacks)

# Assume a long download is in progress...
# For demonstration, simulate a long operation:
import time

# ... inside a context where connection needs to be kept alive ...
for i in range(10):
    time.sleep(30) # Wait for 30 seconds
    ftp_host.keep_alive() # Send a keep-alive signal
# ... continue operation ...
```

### Important Note
This method will not help if the connection has already timed out. It also does not affect hidden FTP child connections established by `FTPHost.open`.
```

--------------------------------

### Conditional Upload with upload_if_newer

Source: https://ftputil.sschwarzer.net/documentation

Use `upload_if_newer` to upload a local file to the remote host only if the local file is newer than the remote file or if the remote file does not exist. Be aware that timestamp precision can lead to unexpected re-uploads; wait at least a minute between calls for the same file.

```python
ftp_host.upload_if_newer("source_file", "target_file")
time.sleep(10)
ftp_host.upload_if_newer("source_file", "target_file")
```

--------------------------------

### Set Time Shift Using Datetime Objects

Source: https://ftputil.sschwarzer.net/documentation

Sets the time shift value for ftputil by calculating the difference between local and UTC time. This is an alternative to synchronize_times when server and client time zones are the same.

```python
set_time_shift(
    round( (datetime.datetime.now() - datetime.datetime.utcnow()).seconds, -2 )
)
```

--------------------------------

### Handle Concurrent Modifications with Cache Invalidation

Source: https://ftputil.sschwarzer.net/documentation

Demonstrates how to invalidate the cache for a specific file path when concurrent modifications are expected. This ensures that subsequent calls to stat retrieve fresh data from the server, preventing the use of obsolete cache entries.

```python
with (
    ftputil.FTPHost(server, user1, password1) as ftp_host1,
    ftputil.FTPHost(server, user1, password1) as ftp_host2
):
    stat_result1 = ftp_host1.stat("some_file")
    stat_result2 = ftp_host2.stat("some_file")
    ftp_host2.remove("some_file")
    # Invalidate using an absolute path.
    absolute_path = ftp_host1.path.abspath(
        ftp_host1.path.join(ftp_host1.getcwd(), "some_file")
    )
    ftp_host1.stat_cache.invalidate(absolute_path)
    # Will now raise an exception as it should.
    print(ftp_host1.stat("some_file"))
    # Would raise an exception since an `FTPHost` object

```

--------------------------------

### Remove File or Link with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Removes a file or symbolic link on the remote host, analogous to os.remove.

```python
remove(path)
```

--------------------------------

### Remove Directory with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Removes a directory on the remote host. Raises PermanentError if the directory is not empty.

```python
rmdir(path)
```

--------------------------------

### Calculate Time Shift for Server Time

Source: https://ftputil.sschwarzer.net/documentation

Calculates the time shift in seconds between server time and UTC. This is useful for ftputil's time-sensitive operations like upload_if_newer and download_if_newer.

```python
time_shift = server_time - utc_time
```

--------------------------------

### Disabling and Re-enabling Cache

Source: https://ftputil.sschwarzer.net/documentation

Temporarily disable the stat cache to fetch all data from the network. The cache can be re-enabled later. Note that disabling the cache can lead to inconsistencies if the file system changes during the disabled period.

```python
with ftputil.FTPHost(server, user, password) as ftp_host:
    ftp_host.stat_cache.disable()
    ...
    ftp_host.stat_cache.enable()
```

--------------------------------

### Resize Stat Cache

Source: https://ftputil.sschwarzer.net/documentation

Explicitly increase the maximum number of lstat results to store in the cache. This is useful when processing very large directories or when needing stat data for many directories simultaneously.

```python
ftp_host.stat_cache.resize(20000)
```

--------------------------------

### Remove Directory Tree with ftputil

Source: https://ftputil.sschwarzer.net/documentation

Removes a directory tree recursively. Supports ignore_errors and a custom onerror callable for handling errors during the process.

```python
rmtree(path, ignore_errors=False, onerror=None)
```

--------------------------------

### Keep FTP Connection Alive

Source: https://ftputil.sschwarzer.net/documentation

The `keep_alive` method attempts to keep the connection to the remote server active to prevent timeouts. It is primarily useful during long file transfers and does not affect hidden child connections.

```python
with ftputil.FTPHost(server, userid, password) as ftp_host:
    with ftp_host.open("some_remote_file", "rb") as fobj:
        data = fobj.read(100)
        # _Futile_ attempt to avoid file connection timeout.
        for i in range(15):
            time.sleep(60)
            ftp_host.keep_alive()
        # Will raise an `ftputil.error.TemporaryError`.
        data += fobj.read()
```

--------------------------------

### Alias for File Removal

Source: https://ftputil.sschwarzer.net/documentation

An alias for the remove method, providing an alternative name for removing files or links.

```python
unlink(path)
```

--------------------------------

### Time Zone Correction

Source: https://ftputil.sschwarzer.net/documentation

Functions to manage time zone differences between the server and client for accurate file timestamp comparisons.

```APIDOC
## set_time_shift(time_shift)

### Description
Sets the time shift value in seconds, representing the difference between the server's timestamp and UTC.

### Parameters
- **time_shift** (float) - The time difference in seconds (server_time - utc_time).

### Raises
- TimeShiftError: If the absolute value of time_shift is larger than 24 hours.
```

```APIDOC
## time_shift()

### Description
Returns the currently set time shift value in seconds.
```

```APIDOC
## synchronize_times()

### Description
Synchronizes the local times of the server and the client to ensure accurate file operations. Requires an established connection and write access to the current directory.

### Raises
- TimeShiftError: If the conditions for synchronization are not met.
```
Tokens:
Raw