def __repr__(self):
        return "<NamedRequirements({}{})>".format(
            self.name,
            ", filename='{}'".format(self.filename.name) if self.filename
            else "")
def find_example_file(
        top_directory_name, shuffled=True, spc_date_string=None,
        batch_number=None, raise_error_if_missing=True):
    """Looks for file with input examples.

    If `shuffled = True`, this method looks for a file with shuffled examples
    (from many different times).  If `shuffled = False`, this method looks for a
    file with examples from one SPC date.

    :param top_directory_name: Name of top-level directory with input examples.
    :param shuffled: Boolean flag.  The role of this flag is explained in the
        general discussion above.
    :param spc_date_string: [used only if `shuffled = False`]
        SPC date (format "yyyymmdd").
    :param batch_number: [used only if `shuffled = True`]
        Batch number (integer).
    :param raise_error_if_missing: Boolean flag.  If file is missing and
        `raise_error_if_missing = True`, this method will error out.
    :return: example_file_name: Path to file with input examples.  If file is
        missing and `raise_error_if_missing = False`, this is the *expected*
        path.
    :raises: ValueError: if file is missing and `raise_error_if_missing = True`.
    """

    error_checking.assert_is_string(top_directory_name)
    error_checking.assert_is_boolean(shuffled)
    error_checking.assert_is_boolean(raise_error_if_missing)

    if shuffled:
        error_checking.assert_is_integer(batch_number)
        error_checking.assert_is_geq(batch_number, 0)

        first_batch_number = int(number_rounding.floor_to_nearest(
            batch_number, NUM_BATCHES_PER_DIRECTORY))
        last_batch_number = first_batch_number + NUM_BATCHES_PER_DIRECTORY - 1

        example_file_name = (
            '{0:s}/batches{1:07d}-{2:07d}/input_examples_batch{3:07d}.nc'
        ).format(top_directory_name, first_batch_number, last_batch_number,
                 batch_number)
    else:
        time_conversion.spc_date_string_to_unix_sec(spc_date_string)

        example_file_name = (
            '{0:s}/{1:s}/input_examples_{2:s}.nc'
        ).format(top_directory_name, spc_date_string[:4], spc_date_string)

    if raise_error_if_missing and not os.path.isfile(example_file_name):
        error_string = 'Cannot find file.  Expected at: "{0:s}"'.format(
            example_file_name)
        raise ValueError(error_string)

    return example_file_name