3.3.7. pci.api.path module

This module contains functions to find files from various input sources. The files can be filtered by using subclasses of AbstractFilenameFilter. Examples

The following example shows how to search for files in the folder ‘/data’:

from pci.api.path import find_files
from pci.api.path import find_files_by_masks
from pci.api.path import find_files_by_exclusive_masks

# find files that contain '_RAW_' in the file name
print(find_files('_RAW_', ['/data']))

# find files that contain '_PAN' in the file name
print(find_files('_PAN', ['/data']))

# find files that start with 'dem'
print(find_files_by_masks('/data', 'dem*'))

# find files that have a 'txt' or 'tif' file name extension
print(find_files_by_masks('/data', ['*.txt', '*.tif']))

# find files that have a 'txt' or 'tif' file name extension, and do not search recursively
print(find_files_by_masks('/data', ['*.txt', '*.tif'], False))

# find files that do not have the file name extension 'pix'
print(find_files_by_exclusive_masks('/data', ['*.pix']))

The preceding is based on a folder ‘/data’ with the following structure:

  • Scene_001_RAW_MS.pix

  • Scene_001_RAW_PAN.pix

  • image1.tif

  • Scene_002_RAW_MS.pix

  • Scene_001_ORTHO_PAN.pix

  • readme.txt

  • auxiliary

    • readme.txt

    • dem.pix

Note: The ‘auxiliary’ folder contains two files.

The output will be as follows:

['/data/Scene_001_RAW_MS.pix', '/data/Scene_001_RAW_PAN.pix', '/data/Scene_002_RAW_MS.pix']
['/data/Scene_001_RAW_PAN.pix', '/data/Scene_001_ORTHO_PAN.pix']
['/data/image1.tif', '/data/readme.txt', '/data/auxiliary/readme.txt']
['/data/image1.tif', '/data/readme.txt']
['/data/image1.tif', '/data/readme.txt', '/data/auxiliary/readme.txt']

New in version 2018. Finding files

pci.api.path.file_exists_in_dir_case_insensitive(directory, basename)

Return True if file with basename exist in directory. This function uses find_file_case_insensitive() to do the search.


Return a list of valid datasets from directory that can be opened using pci.api.datasource.open_dataset().


Return a list of path to files in the directory.

pci.api.path.find_file_case_insensitive(directory, basename)

Find the filename of the specified basename in the directory. The comparison is case insensitive. This function may be expensive because it iterates over all files in the directory and does a case insensitive comparison. If a match is found on disk, then it is returned, None is returned otherwise. The returned filename will match the case in the file system

pci.api.path.find_files(search_pattern, search_dirs, ignore_case=True)

Recursively search the list of directories, search_dirs for search_pattern. If the ignore_case is true (default), patterns are matched case insensitively. A list containing all matched files is returned.

search_pattern can be any part of a file name such as ‘_raw__’, ‘.PIX’

pci.api.path.find_files_by_masks(input_source, masks, recursive=True, quiet=False)

Find files that match the list of masks (see pci.api.finder.HandlingFilteredFilenameFinder) from input_source (path or pci.api.inputsource.InputSourceCollection). If recursive is True, then input_source will search for files recursively. If quiet is set, the log messages from the filter are suppressed. A list of file paths are returned on success. An Exception is raised on invalid input_source argument.

pci.api.path.locate_file(input_file, source_dir)

Locate the file input_file in the directory source_dir or any of its subdirectories. This function returns the full path to input_file, if not found, an empty string is returned.

pci.api.path.search_directory(target, directory, ignore_case=True, search_type=SearchType.SEARCH_BOTH_FILE_AND_DIRECTORY)

Search the directory, directory for file/directory name, target. If ignore_case is True then file and directory are matched case insensitively. Depending on the value of search_type, this function can search for files, directories or both pci.api.inputsource.SearchType.SEARCH_FILE_ONLY, pci.api.inputsource.SearchType.SEARCH_DIRECTORY_ONLY, pci.api.inputsource.SearchType.SEARCH_BOTH_FILE_AND_DIRECTORY. The first match is returned, if there are no match then None is returned.

For Example

If there is a match:

>>> from pci.api import path
>>> print(path.search_directory('Test_ms.pix', '/data/'))
>>> print(path.search_directory('test_ms.pix', '/data/'))

No match:

>>> from pci.api import path
>>> print(path.search_directory('Test2.tiff', '/data/'))
None Conditional functions

pci.api.path.find_files_by_exclusive_masks(input_source, masks)

Find files that don’t match any mask in the list, masks in input_source (path to directory or any iterable object). A list of file paths are returned on success. An Exception is raised on invalid input_source argument. This function uses fnmatch.fnmatch() to do the matching.


Return True if file filename exist. This function uses file_exists_in_dir_case_insensitive() to do the test.

pci.api.path.is_potential_child(potential_parent, potential_child)

Return True if potential_child is a subdirectory of potential_parent or if potential_parent == potential_child