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"]