rotifer.db.ncbi.ftp.connection

class rotifer.db.ncbi.ftp.connection(url='ftp.ncbi.nlm.nih.gov', tries=3, timeout=50, cache='/tmp')

Bases: object

A live connection to the NCBI FTP server.

Parameters:

urlstr, optional

NCBI FTP server address. Defaults to the ftpserver configuration entry.

triesint, default 3

Maximum number of attempts to download a file.

timeoutint, default 50

Maximum time, in seconds, to wait for a server connection.

cachestr, optional

Directory for temporary files. Defaults to the rotifer cache directory.

Examples

>>> from rotifer.db.ncbi import ftp as ncbiftp
>>> conn = ncbiftp.connection(tries=3)
>>> localpath = conn.ftp_get('genomes/README.txt')

connect()

Connect or reconnect to the server.

An existing connection is probed with a NOOP command and replaced when stale. Connection attempts are repeated up to tries times, sleeping one second after each timeout.

ftp_get(target, avoid_collision=False, outdir=None)

Download a file from the NCBI FTP site.

Parameters:

targetstr

URL or path of the file, relative to the server root.

avoid_collisionbool, default False

Avoid name collisions by adding a random suffix to the local file name.

outdirstr, optional

Output directory. Defaults to the connection’s cache directory, which is created when missing.

Returns:

str

Path to the downloaded file.

Raises:

IOError

If the output directory cannot be created or the download fails.

Examples

>>> from rotifer.db.ncbi import ftp as ncbiftp
>>> conn = ncbiftp.connection(tries=3)
>>> localpath = conn.ftp_get('genomes/README.txt')

ftp_ls(targets)

List the contents of one or more FTP directories.

Parameters:

targetsstr or list of str

Path of one or more directories.

Returns:

pandas.DataFrame

One row per directory entry, with the server’s file facts plus target (the listed directory) and name (the entry name).

Raises:

FileNotFoundError

If a directory listing cannot be retrieved.

Examples

>>> from rotifer.db.ncbi import ftp as ncbiftp
>>> conn = ncbiftp.connection()
>>> contents = conn.ftp_ls('genomes')

ftp_open(target, mode='rt', avoid_collision=True, delete=True)

Open a file stored at the NCBI FTP site.

The file is first downloaded to the cache directory and then opened. Compressed files are uncompressed on the fly.

Parameters:

targetstr

Path of the file, relative to the server root.

modestr, default ‘rt’

Read mode used to open the file, such as r, rt or rb.

avoid_collisionbool, default True

Avoid name collisions by adding a random suffix to the local file name.

deletebool, default True

Whether the local copy is removed when the returned stream is closed. When False, the file remains in the cache directory.

Returns:

file-like

The open data stream.

Examples

Open a genome GBFF file:

>>> from rotifer.db.ncbi import ftp as ncbiftp
>>> conn = ncbiftp.connection()
>>> path = "genomes/all/GCA/900/547/725/GCA_900547725.1_UMGS1014/"
>>> path += "GCA_900547725.1_UMGS1014_genomic.gbff.gz"
>>> fh = conn.ftp_open(path, mode="rt")