# API Reference — Opening Files

See Downloading and Using Data Files for an explanation of how Skyfield programs use an instance of the `Loader` class described below to download and open the data files they need in order to operate.

## The loader class

class skyfield.iokit.Loader(directory, verbose=True, expire=False)

  A tool for downloading and opening astronomical data files.

  A default `Loader` that saves data files to the current working directory can be imported directly from the Skyfield API:

      from skyfield.api import load

  But users can also create a `Loader` of their own, if there is another directory they want data files saved to, or if they want to specify different options. The directory is created automatically if it does not yet exist:

      from skyfield.api import Loader
      load = Loader('~/skyfield-data')

  The options are:

  `verbose`

    If set to `False`, then the loader will not print a progress bar to the screen each time it downloads a file. (If the standard output is not a TTY, then no progress bar is printed anyway.)

  `expire`

    (This option is no longer supported.)

  Once a `Loader` is created, it can be called like a function to open, or else to download and open, a file whose name it recognizes:

      planets = load('de405.bsp')

  Each loader also supports an attribute and a few methods.

  directory

    The directory where this loader looks when trying to open a file, and where it downloads files that have not been downloaded yet.

  path_to(filename)

    Return the path to `filename` in this loader’s directory.

  days_old(filename)

    Return how recently `filename` was modified, measured in days.

  build_url(filename)

    Return the URL Skyfield will try downloading for a given filename.

    Raises `ValueError` if Skyfield doesn’t know where to get the file based on its name.

  tle_file(url, reload=False, filename=None, ts=None, skip_names=False)

    Load and parse a TLE file, returning a list of Earth satellites.

    Given a URL or local path to an ASCII text file, this loads a series of TLE “Two-Line Element” sets and returns a list of `EarthSatellite` objects for them. See Earth Satellites.

    See the `open()` method for the meaning of the `reload` and `filename` parameters.

    See the `parse_tle_file()` function for the meaning of the `ts` and `skip_names` parameters.

  download(url, filename=None, backup=False)

    Download a file, even if it’s already on disk; return its path.

    You can specify the local `filename` to which the file will be saved; the default is to use the final component of `url`. Set `backup` to `True` if you want an already-existing file moved out of the way instead of overwritten.

    Your operating system may raise any of several errors during a download: hostname lookup failure (this is the usual symptom if you are disconnected from the Internet); the server refusing the connection; and the connection closing mid-download. Skyfield makes no attempt to intercept or interpret these errors — which vary by operating system — so your application itself should catch network errors if it needs to avoid printing raw Python exceptions, or if you want to retry failed downloads.

  open(url, mode='rb', reload=False, filename=None, backup=False)

    Open a file, downloading it first if it does not yet exist.

    Unlike when you call a loader directly like `my_loader()`, this `my_loader.open()` method does not attempt to parse or interpret the file; it simply returns an open file object.

    The `url` can be either an external URL, or else the path to a file on the current filesystem. A relative path will be assumed to be relative to the base directory of this loader object.

    If a URL was provided and the `reload` parameter is true, then any existing file will be removed before the download starts.

    The `filename` parameter lets you specify an alternative local filename instead of having the filename extracted from the final component of the URL.

  timescale(delta_t=None, builtin=True)

    Return a `Timescale` built using official Earth rotation data.

    `delta_t` — Lets you override the standard ∆T tables by providing your own ∆T offset in seconds. For details, see Setting a Custom Value For ∆T.

    `builtin` — By default, Skyfield uses ∆T and leap second tables that it carries internally; to instead load this data from files, set this option to `False`. For compatibility with Skyfield ≤ 1.30, if you have on disk the three files `deltat.data`, `deltat.preds`, and `Leap_Second.dat`, then Skyfield will load them. Otherwise, Skyfield will download and use `finals2000A.all` from the International Earth Rotation Service. For details, see UT1 and downloading IERS data.

## Standalone functions

skyfield.iokit.load_file(path)

  Open a file on your local drive, using its extension to guess its type.

  This routine only works on `.bsp` ephemeris files right now, but will gain support for additional file types in the future.

      from skyfield.api import load_file
      planets = load_file('~/Downloads/de421.bsp')

skyfield.iokit.parse_tle_file(lines, ts=None, skip_names=False)

  Parse lines of TLE satellite data, yielding a sequence of satellites.

  Given a sequence `lines` of byte strings (which can be an open binary file, which acts like a sequence of lines in Python), this routine yields an `EarthSatellite` for each pair of adjacent lines that start with `"1 "` and `"2 "` and have 69 or more characters each. If the line preceding a TLE is not part of another TLE, it is used as the satellite’s `.name`.

  If you pass a `ts` timescale, Skyfield will use it to build the `.epoch` date attribute on each satellite; otherwise a timescale derived from Skyfield’s built-in leap second files will be used.

  If for a particular file you see random lines of text being interpreted as satellite names, set `skip_names` to `True` and Skyfield will not try to store satellite names.

  See Earth Satellites for details. An exception is raised if the attempt to parse a pair of candidate lines as TLE lines fails.