gpf.paths module

Module that simplifies working with file or directory paths or Esri workspaces (i.e. Geodatabases).

gpf.paths.explode(path: str) → tuple

Splits path into a tuple of (directory, name, extension). Depending on the input path, extension might be an empty string.

Parameters:path – The path that should be split.

Examples:

>>> explode(r'C:/temp/test.gdb')
('C:\temp', 'test', '.gdb')
>>> explode(r'C:/temp/folder')
('C:\temp', 'folder', '')

gpf.paths.normalize(path: str, lowercase: bool = True) → str

Normalizes a path and turns it into lowercase, unless lowercase is set to False.

Parameters:

• path – The path to normalize.
• lowercase – If True (default), the path will be turned into lowercase. If False, the case remains unchanged.

gpf.paths.concat(*args) → str

Joins (concatenates) one or more paths together to create a complete path and normalizes it.

Parameters:args – One or more paths/parts.

gpf.paths.get_abs(path: str, base: str = None) → str

Creates a normalized absolute path based on path relative to base. If base is not specified, the base will be the directory to the file path of the calling function, i.e. when a script ‘test.py’ calls make_absolute(), the directory which contains ‘test.py’ will be the base.

Parameters:

• path – The relative path to turn into an absolute one.
• base – The base path that serves as the ‘root’ of the relative path.

Raises:

ValueError – If the base path is None and no valid base directory was found using the caller path.

gpf.paths.find_parent(path: str, name: str) → str

Finds within path the parent directory that contains a file or directory with the given name. Note that path and name values are matched case-insensitively, but the found path is returned in the original case (as a normalized path).

If no matches have been found or if the match has no parent, an empty string is returned. If there are multiple matches, the parent path of the first match is returned.

Examples:

>>> find_parent('C:\Projects\parent\LEVEL0\level1\level2.txt', 'level0')
'C:\Projects\parent'
>>> find_parent('C:\Projects\parent\LEVEL\level\level.txt', 'level')
'C:\Projects\parent'
>>> find_parent('C:\Projects\some_dir', 'C:')
''
>>> find_parent('C:\Projects\parent\must_include_extension.txt', 'must_include_extension')
''

Parameters:

• path – The path to search.
• name – The name for which to search the parent directory in path. This value can be a file name (with extension!) or a directory name. Partial paths, pre- or suffixes or regular expressions are not allowed here and will return None.

class gpf.paths.Path(path, {base})

Bases: object

The Path class helps to extract the different parts of a file or directory path, or helps make_path new ones based upon a root path. This class can also be used as a context manager using the with statement.

Note that path (and base) are never explicitly checked for existence. If the user wishes to validate these paths, use the exists(), is_file() or is_dir() properties.

Params:

• path (str, unicode):

  The file or directory path on which to operate.

• base (str, unicode):

  When set to a directory path, the Path class assumes that path is relative to this base directory and will make path absolute. Otherwise, it will leave path unchanged (whether absolute or relative).

See also

For Esri Geodatabase paths, use the gpf.paths.Workspace class.

exists

Returns True if the initial path exists (regardless of whether path is a file or directory).

is_file

Returns True if the initial path is an existing file.

is_dir

Returns True if the initial path is an existing directory.

extension(keep_dot: bool = True) → str

Returns the extension part of the initial path. For directories or files without extension, an empty string is returned.

Parameters:keep_dot – When False, the extension’s trailing dot will be removed. Defaults to True.

basename(keep_ext: bool = True) → str

Returns a file name (if initial path is a file) or a directory name.

Parameters:keep_ext – For files, setting this to False will remove the file extension. Defaults to True. Note that for directories, this might not have any effect.

from_extension(extension: str, force: bool = False)

Returns the initial path with an alternative file extension. If the initial path did not have an extension (e.g. when it is a directory), this function will return the initial unmodified path instead (and have no effect), unless force is True.

Parameters:

• extension – New file extension (with or without trailing dot).
• force – When True, the extension will always be appended, even if the initial path is a directory. The default is False.

Examples:

>>> with Path(r'C:/temp/myfile.txt') as pm:
>>>     pm.from_extension('log')
C:\temp\myfile.log
>>> with Path(r'C:/temp/mydir') as pm:
>>>     pm.from_extension('log')
C:\temp\mydir
>>>     pm.from_extension('gdb', force=True)
C:\temp\mydir.gdb

from_basename(basename: str) → str

Returns the initial path with an alternative basename. This will work for both directories and files.

Parameters:basename – The new basename. If basename contains an extension and the initial path is a file path that also had an extension, both the name and extension will be changed. If the initial path is a directory path, the directory name will simply be replaced by the basename.

Examples:

>>> with Path(r'C:/temp/myfile.txt') as pm:
>>>     pm.from_basename('newfile')
C:\temp\newfile.txt
>>>     pm.from_basename('newfile.log')
C:\temp\newfile.log

make_path(*parts)

Constructs a new path based on the initial path from one or more parts (directories, file names). If the initial part seems to be a file path (i.e. when an extension is present), the constructed path will be based on the containing directory of this file.

Parameters:parts – One or more directory names and/or a file name. Return type:str, unicode

Examples:

>>> with Path(r'C:/temp') as pm:
>>>     pm.make_path('folder', 'subfolder', 'myfile.txt')
'C:\temp\folder\subfolder\myfile.txt'
>>> with Path(r'C:/temp/dummy.txt') as pm:
>>>     pm.make_path('folder', 'subfolder', 'myfile.txt')
'C:\temp\folder\subfolder\myfile.txt'

gpf.paths.is_gdbpath(path: str) → bool

Checks if the given path could be an Esri Geodatabase path by searching for 1 (and only 1!) of its known extensions. Note however that this does not truly guarantee that the path actually refers to a geodatabase!

Parameters:path – The path to verify.

gpf.paths.split_gdbpath(path: str, remove_qualifier: bool = True) → tuple

Splits the Esri Geodatabase path into a tuple of (workspace, feature_dataset, feature_class/table). If any of the output tuple parts is not present, these will be set to an empty string. Note that if the path refers to a table or feature class that is not stored in a feature dataset, the feature_dataset part in the output tuple will be an empty string and the last part will contain the table or feature class name.

Examples:

>>> split_gdbpath('C:/test.gdb/table')
('C:\test.gdb', '', 'table')
>>> split_gdbpath('C:/test.sde/qualifier.featureclass', False)
('C:\test.sde', '', 'qualifier.featureclass')
>>> split_gdbpath('C:/test.sde/qualifier.fds/qualifier.fc')
('C:\test.sde', 'fds', 'fc')

Parameters:

• path – The full path to the Geodatabase feature class or table.
• remove_qualifier – If True, the split parts are “unqualified”. If any DB qualifiers exist in the path, they will be removed. This is the default behaviour. Set this parameter to False if qualifiers must be persisted.

Raises:

ValueError – If the given path does not seem to be a Geodatabase path or there are more than 2 levels in the Geodatabase.

gpf.paths.exists(path: str) → bool

Returns True if path exists. Esri paths (e.g. feature classes) are also supported.

This function can be slightly faster than Esri’s Exists(), because it checks first if the workspace path exists using Python’s built-in os.path module. If this is not the case, it immediately returns False. Only if the workspace exists, it will use Esri’s Exists() to check the complete path.

Parameters:path – The path to verify.

gpf.paths.unqualify(element: str) → str

Removes the qualifier (and anything before that) for a data element part.

class gpf.paths.Workspace({path='in_memory', {qualifier=''}, {base=None}, {separator='.'})

Bases: gpf.paths.Path

Helper class to generate fully qualified paths for elements (tables, feature datasets etc.) in an Esri workspace. An Esri Workspace can be anything ranging from an SDE connection file to a File Geodatabase folder or a simple directory containing Shapefiles.

If ``Workspace`` is initialized without parameters, an in-memory workspace is assumed.

Please note that the specified workspace is never explicitly checked for existence. If the user wants to validate the path, use the exists(), is_file() or is_dir() properties. An exception to the rule is the find_path() function, which will validate the path before it is returned.

If you like to return the workspace as its normalized initial path (e.g. for printing purposes), simply call str() on the Workspace instance. Note that the Workspace class can also behave like a context manager using the with statement.

Params:

• path (str, unicode):

  The workspace path (e.g. File Geodatabase, SDE connection file) or name. Leave empty if you wish to use an in-memory workspace.

• qualifier (str, unicode):

  An optional database qualifier. If not set and workspace is a remote database, the qualifier will be equal to the DB user specified in the SDE connection file.

• base (str, unicode):

  When set to a directory path, the Workspace class assumes that path is relative to this base directory and will make path absolute. Otherwise, it will leave path unchanged (whether absolute or relative).

Keyword params:

• separator (str, unicode):

  Optional separator (default = '.') between the qualifier and the data element name.

Raises:ValueError – If qualifier has not been set and the workspace is an existing remote database for which the properties cannot be retrieved, initialization will fail.

classmethod get_parent(path: str, outside_gdb: bool = False) → str

Class method that extracts the parent workspace path for a given Esri table/feature class path. Depending on the path, this might return a feature dataset workspace or the root workspace path.

Parameters:

• path – Full path to an Esri table, feature class or feature dataset.
• outside_gdb – If True, this will allow the function to return the parent directory of a Geodatabase, if the workspace is a GDB path. This effectively means that the function is allowed to go ‘outside’ of the Geodatabase. By default, this value is set to False. For non-Geodatabase paths, this will have no effect: the parent directory is returned.

Examples:

>>> Workspace.get_parent(r'C:/temp/test.gdb')
'C:\temp\test.gdb'
>>> Workspace.get_parent(r'C:/temp/test.gdb/feature_dataset')
'C:\temp\test.gdb'
>>> Workspace.get_parent(r'C:/temp/test.gdb', outside_gdb=True)
'C:\temp'
>>> Workspace.get_parent(r'C:/temp/test.shp')
'C:\temp'

classmethod get_root(path: str) → str

Class method that extracts the root workspace for a given Esri table/feature class path.

A root workspace is the Esri workspace of the “highest order”. For an SDE feature class, this is the SDE connection file. For a File Geodatabase table, this is the File Geodatabase directory (.gdb) itself. For a Shapefile path, this will return the parent directory. For an in memory workspace, this will return ‘in_memory’.

Parameters:path – Full path to an Esri table, feature class or feature dataset.

Examples:

>>> Workspace.get_root(r'C:/temp/test.gdb/ele/ele_kabel')
'C:\temp\test.gdb'
>>> Workspace.get_root(r'C:/temp/mydir/test.shp')
'C:\temp\mydir
>>> Workspace.get_root(r'C:/temp/test.gdb/ele')
'C:\temp\test.gdb'

is_remote

Returns True if the workspace path seems to be a remote SDE geodatabase connection.

is_gdb

Returns True if the workspace path seems to be an Esri Geodatabase (remote or local).

root

Returns the root workspace as a new Workspace instance. If the initial path already was the root path, this will return the current instance (self).

parent

Returns the parent workspace as a new Workspace instance.

exists

Returns True if the workspace path exists and/or is a valid Esri workspace.

qualifier

Returns the qualifier for the current Esri workspace. For local workspaces, this is an empty string. The trailing separator will not be included in the output string.

separator

Returns the separator for the current Esri workspace. For local workspaces, this is an empty string.

qualify(name: str, qualifier: str = None, separator: str = None) → str

Qualifies (prefixes) a data element name for SDE workspaces. If the workspace is not an SDE workspace or the name is qualified already, the input name is returned as-is.

Parameters:

• name – Feature dataset, feature class or table name.
• qualifier – Optional qualifier if the one derived from the DB connection should be overridden.
• separator – Optional separator if the initial one should be overridden (defaults to '.').

Raises:

ValueError – If no table name was specified.

find_path(table: str, refresh: bool = False) → str

Tries to resolve the full (qualified) path for the specified table or feature class and returns it, by looking up the matching feature dataset (or workspace root when not found). In contrast to the make_path() function, the path is verified before it is returned.

Parameters:

• table – The (unqualified) table or feature class name to find.
• refresh – Updates the internal table lookup first. See note below.

Raises:

ValueError – If the table was not found or found multiple times (should not happen).

Example:

>>> wm = Workspace(r'C:/temp/db_user.sde')
>>> wm.qualifier
'user'
>>> wm.find_path('ele_cable')  # finds the feature class in feature dataset "ELE"
'C:\temp\db_user.sde\user.ele\user.ele_cable'

Note

The feature dataset lookup is created once on the first call to this function. This means that the first call is relatively slow and consecutive ones are fast. When the user creates new feature class paths using the make_path() method, the lookup is updated automatically, so that this function can find the new feature class. However, when the workspace is updated from the outside, the lookup is not updated. If the user wishes to force-update the lookup, set the refresh argument to True.

make_path(*parts, {qualifier}, {separator})

Constructs a (qualified) path for the given named parts (data elements) in the order they appear.

Parameters:

• parts – Feature dataset, feature class and/or table name(s) to concatenate. Note that if the workspace is a FileSystem directory, the last part of parts should include a file extension (e.g. ‘.shp’).
• qualifier – Optional qualifier if the one derived from the DB connection should be overridden.
• separator – Optional separator if the initial one should be overridden (defaults to ‘.’).

Raises:

IndexError – When more than 2 parts have been specified, this function will fail.

In the following example, the qualifier (“user”) is derived from the connection:

>>> wm = Workspace(r'C:/temp/db_user.sde')
>>> wm.qualifier
'user'
>>> wm.make_path('ele', 'ele_kabel')
'C:\temp\db_user.sde\user.ele\user.ele_kabel'

Using the Workspace above, we can override the qualifier with a custom one:

>>> wm.make_path('ele', 'ele_kabel', qualifier='editor')
'C:\temp\db_user.sde\editor.ele\editor.ele_kabel'

basename(keep_ext: bool = True) → str

Returns a file name (if initial path is a file) or a directory name.

Parameters:keep_ext – For files, setting this to False will remove the file extension. Defaults to True. Note that for directories, this might not have any effect.

extension(keep_dot: bool = True) → str

Returns the extension part of the initial path. For directories or files without extension, an empty string is returned.

Parameters:keep_dot – When False, the extension’s trailing dot will be removed. Defaults to True.

from_basename(basename: str) → str

Returns the initial path with an alternative basename. This will work for both directories and files.

Parameters:basename – The new basename. If basename contains an extension and the initial path is a file path that also had an extension, both the name and extension will be changed. If the initial path is a directory path, the directory name will simply be replaced by the basename.

Examples:

>>> with Path(r'C:/temp/myfile.txt') as pm:
>>>     pm.from_basename('newfile')
C:\temp\newfile.txt
>>>     pm.from_basename('newfile.log')
C:\temp\newfile.log

from_extension(extension: str, force: bool = False)

Returns the initial path with an alternative file extension. If the initial path did not have an extension (e.g. when it is a directory), this function will return the initial unmodified path instead (and have no effect), unless force is True.

Parameters:

• extension – New file extension (with or without trailing dot).
• force – When True, the extension will always be appended, even if the initial path is a directory. The default is False.

Examples:

>>> with Path(r'C:/temp/myfile.txt') as pm:
>>>     pm.from_extension('log')
C:\temp\myfile.log
>>> with Path(r'C:/temp/mydir') as pm:
>>>     pm.from_extension('log')
C:\temp\mydir
>>>     pm.from_extension('gdb', force=True)
C:\temp\mydir.gdb

is_dir

Returns True if the initial path is an existing directory.

is_file

Returns True if the initial path is an existing file.

gpf.paths.get_workspace(table_path: str, root: bool = False, **kwargs) → gpf.paths.Workspace

Extracts the workspace from table_path and returns a Workspace instance for it. By default (root=False), this will return the first workspace it can find in an upwards direction: i.e. for a feature class inside a feature dataset, the feature dataset path will be returned.

Parameters:

• table_path – The full path to a table or feature class.
• root – If True (default = False), the root workspace will be extracted.
• kwargs – Optional keyword arguments for the Workspace initialization.

Examples:

>>> get_workspace(r'C:/temp/test.gdb/feature_dataset/feature_class')
Workspace('C:\temp\test.gdb\feature_dataset')
>>> get_workspace(r'C:/temp/test.gdb/feature_dataset/feature_class', root=True)
Workspace('C:\temp\test.gdb')