FunctionalityWrapper

class FunctionalityWrapper(use_TLS=False)[source]

Baseclass which holds the functionality of ftpserver. The derived classes are ThreadFTPServer and ProcessFTPServer, which (depending on the OS) are the classes of the ftpserver instance.

Parameters:use_TLS (bool) – Whether or not to use TLS/SSL encryption.

Notes

For custom configuration the following environment variables can be used:

General:

FTP_USER: str
Name of the registered user.
FTP_PASS: str
Password of the registered user.
FTP_HOME: str
Local path to FTP home for the registered user.
FTP_PORT: int
Desired port for the unencrypted server to listen to.
FTP_FIXTURE_SCOPE: {‘function’, ‘module’, ‘session’}: default ‘module’
Scope the fixture will be in.

TLS only:

FTP_HOME_TLS = str
Local path to FTP home for the registered user of the encrypted server.
FTP_PORT_TLS: int
Desired port for the encrypted server to listen to.
FTP_CERTFILE: str
Path to the certificate used by the encrypted server.

Attributes Summary

anon_root Local path to FTP home for the anonymous user.
cert_path Path to the used certificate File.
password Password of the registered user.
server_home Local path to FTP home for the registered user.
server_port Port the server is running on.
username Name of the registered user.
uses_TLS Weather or not the server uses TLS/SSL encryption.

Methods Summary

format_file_path Formats the relative path to as relative path or url.
get_cert Returns the path to the used certificate or its content as string or bytes.
get_file_contents Yields dicts containing the path and content of files on the FTP server.
get_file_paths Yields the paths of all files server_home/anon_root, in the given style.
get_local_base_path Returns the basepath on the local file system.
get_login_data Returns the login data as dict or url.
put_files Copies the files defined in files_on_local to the sever.
reset_tmp_dirs Clears all temp files generated on the FTP server.
stop Stops the server, closes all the open ports and deletes all temp files.

Methods Documentation

format_file_path(rel_file_path, style='rel_path', anon=False)[source]

Formats the relative path to as relative path or url. Relative paths are relative to the server_home/anon_root, which can be used by a FTP client. Urls can be used by a browser/downloader. This method works, weather the file exists or not.

Notes

Even so taking a relative path and returning a relative path may seam pointless, this is needed to prevent errors with Windows path formatting (\ instead of /).

Parameters:
  • rel_file_path (str) – Relative filepath to server_home/anon_root depending on the value of anon.
  • style ({'rel_path', 'url'}, default 'rel_path') –
    ‘rel_path’:
    path relative to server_home/anon_root is returned.
    ’url’:
    url to the file is returned.
  • anon (bool) –
    True:
    return the filepaths/url of file in anon_root
    False:
    return the filepaths/url of file in server_home
Returns:

file_path – Relative path or url depending on the value of style
Return type:

str
Raises:
  • TypeError – If style is not a str
  • TypeError – If anon is not a bool
  • ValueError – If the value of style is not ‘rel_path’ or ‘url’

Examples

>>> ftpserver.format_file_path("test_folder\test_file", style="rel_path", anon=False))
test_folder/test_file

>>> ftpserver.format_file_path("test_folder/test_file", style="rel_path", anon=False))
test_folder/test_file

>>> ftpserver.format_file_path("test_folder/test_file", style="url", anon=False))
ftp://fakeusername:qweqwe@localhost:8888/test_folder/test_file

>>> ftpserver.format_file_path("test_folder/test_file", style="url", anon=True))
ftp://localhost:8888/test_folder/test_file

See also

get_local_base_path(), get_file_paths()

get_cert(style='path', read_mode='r')[source]

Returns the path to the used certificate or its content as string or bytes.

Parameters:
  • style ({'path', 'content'}, default 'path') – List of filepaths/content dicts in server_home/anon_root
  • read_mode ({'r', 'rb'}, default 'r') – This only applies if style is ‘content’. Mode in which files should be read (see open("filepath", read_mode) )
Returns:

cert – Path to or content of the used certificate
Return type:

str
Raises:
  • TypeError – If style is not a str
  • TypeError – If read_mode is not a str
  • ValueError – If the value of style is not ‘path’ or ‘content’
  • ValueError – If the value of read_mode is not ‘r’ or ‘rb’
  • WrongFixtureError – If used on ftpserver fixture, instead of ftpserver_TLS fixture.

Examples

>>> ftpserver_TLS.get_cert()
"/home/certs/TLS_cert.pem"

>>> ftpserver_TLS.get_cert(style="content")
"-----BEGIN RSA PRIVATE KEY-----\nMIICXw..."

>>> ftpserver_TLS.get_cert(style="content", read_mode="rb")
b"-----BEGIN RSA PRIVATE KEY-----\nMIICXw..."
get_file_contents(rel_file_paths=None, style='rel_path', anon=False, read_mode='r')[source]

Yields dicts containing the path and content of files on the FTP server.

Parameters:
  • rel_file_paths (str, list of str, None, default None) –
    None:
    The content of all files on the server will be retrieved.
    str or list of str:
    Only the content of those files will be retrieved.
  • style ({'rel_path', 'url'}, default 'rel_path') –
    ‘rel_path’:
    Path relative to server_home/anon_root is returned.
    ’url’:
    A url to the file is returned.
  • anon (bool) –
    True:
    return the filepaths/url of files in anon_root
    False:
    return the filepaths/url of files in in server_home
  • read_mode ({'r', 'rb'}, default 'r') – Mode in which files should be read (see open("filepath", read_mode) )
Yields:

content_dict (dict) – Dict containing the file path as relpath or url (see style) and the content of the file as string or bytes (see read_mode)
Raises:
  • TypeError – If rel_file_paths is not None, a str or an iterable
  • TypeError – If style is not a str
  • TypeError – If anon is not a bool
  • TypeError – If read_mode is not a str
  • ValueError – If the value of rel_file_paths or its items are not valid filepaths
  • ValueError – If the value of style is not ‘rel_path’ or ‘url’
  • ValueError – If the value of read_mode is not ‘r’ or ‘rb’

Examples

Assuming a file structure as follows.

filesystem
+---server_home
    +---test_file1.txt
    +---test_folder
        +---test_file2.zip

>>> list(ftpserver.get_file_contents())
[{"path": "test_file1.txt", "content": "test text"},
 {"path": "test_folder/test_file2.txt", "content": "test text2"}]

>>> list(ftpserver.get_file_contents("test_file1.txt"))
[{"path": "test_file1.txt", "content": "test text"}]

>>> list(ftpserver.get_file_contents("test_file1.txt", style="url"))
[{"path": "ftp://fakeusername:qweqwe@localhost:8888/test_file1.txt",
  "content": "test text"}]

>>> list(ftpserver.get_file_contents(["test_file1.txt", "test_folder/test_file2.zip"],
...                                  read_mode="rb"))
[{"path": "test_file1.txt", "content": b"test text"},
 {"path": "test_folder/test_file2.zip", "content": b'PK\x03\x04\x14\x00\x00...'}]

See also

get_file_paths(), put_files()

get_file_paths(style='rel_path', anon=False)[source]

Yields the paths of all files server_home/anon_root, in the given style.

Parameters:
  • style ({'rel_path', 'url'}, default 'rel_path') –
    ‘rel_path’:
    path relative to server_home/anon_root is returned.
    ’url’:
    url to the file is returned.
  • anon (bool) –
    True:
    filepaths/urls of all files in anon_root is returned.
    False:
    filepaths/urls of all files in server_home is returned.
Yields:

file_path (str) – Generator of all filepaths in the server_home/anon_root
Raises:
  • TypeError – If style is not a str
  • TypeError – If anon is not a bool
  • ValueError – If the value of style is not ‘rel_path’ or ‘url’

Examples

Assuming a file structure as follows.

filesystem
+---server_home
|   +---test_file1
|   +---test_folder
|       +---test_file2
|
+---anon_root
    +---test_file3
    +---test_folder
        +---test_file4

>>> list(ftpserver.get_file_paths(style="rel_path", anon=False))
["test_file1", "test_folder/test_file2"]

>>> list(ftpserver.get_file_paths(style="rel_path", anon=True))
["test_file3", "test_folder/test_file4"]

>>> list(ftpserver.get_file_paths(style="url", anon=False))
["ftp://fakeusername:qweqwe@localhost:8888/test_file1",
"ftp://fakeusername:qweqwe@localhost:8888/test_folder/test_file2"]

>>> list(ftpserver.get_file_paths(style="url", anon=True))
["ftp://localhost:8888/test_file3", "ftp://localhost:8888/test_folder/test_file4"]
get_local_base_path(anon=False)[source]

Returns the basepath on the local file system. Depending on anon the basepath is for the registered or anonymous user.

Parameters:
  • anon (bool) –
  • anon –
    True:
    returns the local path to anon_root
    False:
    returns the local path to server_home
Returns:

base_path – Basepath on the local file system.
Return type:

str
Raises:

TypeError – If anon is not a bool

Examples

>>> ftpserver.get_local_base_path(anon=False))
/tmp/ftp_home_1rg7_i

>>> ftpserver.get_local_base_path(anon=True))
/tmp/anon_root_m6fknmyx
get_login_data(style='dict', anon=False)[source]

Returns the login data as dict or url. What the returned value looks like is depending on style and the anonymous user or registered user depending anon.

Parameters:
  • style ({'dict', 'url'}, default 'dict') –
    ‘dict’:
    returns a dict with keys host, port, user and passwd or only host and port
    ’url’:
    returns a url containing the the login data
  • anon (bool) –
    True:
    returns the login data for the anonymous user
    False:
    returns the login data for the registered user
Returns:

login_data – Login data as dict or url, depending on the value of style.
Return type:

dict, str
Raises:
  • TypeError – If style is not a str
  • TypeError – If anon is not a bool
  • ValueError – If the value of style is not ‘dict’ or ‘url’

Examples

>>> ftpserver.get_login_data()
{"host": "localhost", "port": 8888, "user": "fakeusername",
"passwd": "qweqwe"}

>>> ftpserver.get_login_data(anon=True)
{"host": "localhost", "port": 8888}

>>> ftpserver.get_login_data(style="url")
ftp://fakeusername:qweqwe@localhost:8888

>>> ftpserver.get_login_data(style="url", anon=True)
ftp://localhost:8888
put_files(files_on_local, style='rel_path', anon=False, overwrite=False, return_paths='input', return_content=False, read_mode='r')[source]

Copies the files defined in files_on_local to the sever. After ‘uploading’ the files it returns a list of paths or content_dicts depending on return_content

Parameters:
  • files_on_local (str, dict, list of str/dict, iterable of str/dict) –

    Path/-s to the local file/-s which should be copied to the server.

    str/list of str:
    all files will be copied to the chosen root.
    dict/list of dict:
    files_on_local[“src”]:
    gives the local file path and
    files_on_local[“dest”]:
    gives the relative path the file on the server.
  • style ({'rel_path', 'url'}, default 'rel_path') –
    ‘rel_path’:
    path relative to server_home/anon_root is returned.
    ’url’:
    url to the file is returned.
  • anon (bool) –
    True:
    Use anon_root as basepath
    False:
    Use server_home as basepath
  • overwrite (bool, default False) –
    True:
    overwrites file without warning
    False:
    warns the user if a file exists and doesn’t overwrite it
  • return_paths ({'all', 'input', 'new'}, default 'input') –
    ‘all’:
    Return all files in the server_home/anon_root.
    ’input’:
    Return files in the server_home/anon_root, which were added by put_files.
    ’new’:
    Return only changed files in the server_home/anon_root, which were added by put_files.
  • return_content (bool, default False) –
    False:
    Elements of the iterable to be returned will consist of only the paths (str).
    True:
    Elements of the iterable to be returned will consist of content_dicts.
  • read_mode ({'r', 'rb'}, default 'r') – This only applies if return_content is True. Mode in which files should be read (see open("filepath", read_mode) )
Returns:

file_list – List of filepaths/content dicts in server_home/anon_root
Return type:

list
Raises:
  • TypeError – If files_on_local is not a str, dict or iterable of str/dict
  • TypeError – If style is not a str
  • TypeError – If anon is not a bool
  • TypeError – If overwrite is not a bool
  • TypeError – If return_paths is not a str
  • TypeError – If return_content is not a bool
  • TypeError – If read_mode is not a str
  • ValueError – If files_on_local is/contains an invalid filepath.
  • ValueError – If the value of style is not ‘rel_path’ or ‘url’
  • ValueError – If the value of return_paths is not ‘all’, ‘input’ or ‘new’
  • ValueError – If the value of read_mode is not ‘r’ or ‘rb’
  • KeyError – If dict or list of dicts is used for files_on_local and the dict is missing the keys ‘src’ and ‘dest’.

Examples

>>> ftpserver.put_files("test_folder/test_file", style="rel_path", anon=False)
["test_file"]

>>> ftpserver.put_files("test_folder/test_file", style="url", anon=False)
["ftp://fakeusername:qweqwe@localhost:8888/test_file"]

>>> ftpserver.put_files("test_folder/test_file", style="url", anon=True)
["ftp://localhost:8888/test_file"]

>>> ftpserver.put_files({"src": "test_folder/test_file",
...                      "dest": "remote_folder/uploaded_file"},
...                     style="url", anon=True)
["ftp://localhost:8888/remote_folder/uploaded_file"]

>>> ftpserver.put_files("test_folder/test_file", return_content=True)
[{"path": "test_file", "content": "some text in test_file"}]

>>> ftpserver.put_files("test_file.zip", return_content=True, read_mode="rb")
[{"path": "test_file.zip", "content": b'PK\x03\x04\x14\x00\x00...'}]

>>> ftpserver.put_files("test_file", return_paths="new")
UserWarning: test_file does already exist and won't be overwritten.
    Set `overwrite` to True to overwrite it anyway.
[]

>>> ftpserver.put_files("test_file", return_paths="new", overwrite=True)
["test_file"]

>>> ftpserver.put_files("test_file3", return_paths="all")
["test_file", "remote_folder/uploaded_file", "test_file.zip"]

See also

get_file_contents(), get_file_paths()

reset_tmp_dirs()[source]

Clears all temp files generated on the FTP server. This method is implemented to have more control over the module scoped ftp server.

Examples

filesystem before:

filesystem
+---server_home
|   +---test_file1
|   +---test_folder
|       +---test_file2
|
+---anon_root
    +---test_file3
    +---test_folder
        +---test_file4

>>> ftpserver.reset_tmp_dirs()

filesystem after:

filesystem
+---server_home
|
+---anon_root
stop()[source]

Stops the server, closes all the open ports and deletes all temp files. This is especially useful if you want to test if your code behaves gracefully, when the ftpserver isn’t reachable.

Warning

If pytest-localftpserver is run in ‘module’ (default) or ‘session’ scope, this should be the last test run using this fixture (in the given test module or suite), Since the server can’t be restarted.

Examples

>>> ftpserver.stop()
>>> your_code_connecting_to_the_ftp()
RuntimeError: Server is offline/ not reachable.