gntools.datasources module¶

The datasource module simplifies working with GEONIS Datasource XML files.

class gntools.datasources.Datasource(datasource)¶

Bases: gpf.paths.Workspace

Helper class to read a GEONIS Datasource XML, so that the user is able to generate fully qualified paths for elements (tables, feature datasets etc.) in an Esri workspace. To GEONIS, an Esri Workspace means an SDE connection file or a local File/Personal Geodatabase.

Params:

xml_path (str, unicode):

The full GEONIS Datasource XML file path.

Raises:	ValueError – If the GEONIS Datasource XML does not exist or failed to parse.

Note

All class methods are inherited from gpf.paths.Workspace. The initialization process of the Datasource class is different, because it will read the workspace path from the GEONIS Datasource XML. Another difference is that the Datasource class also stores the GEONIS medium it applies to. Furthermore, it features 2 helper functions, which try to guess the paths of the media directory (get_media_dir()) and the project directory (get_project_dir()) for that same medium.

basename(keep_ext=True)¶

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

Parameters:	keep_ext (bool) – For files, setting this to `False` will remove the file extension. Defaults to `True`. Note that for directories, this might not have any effect.
Return type:	str, unicode

exists¶

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

Return type:	bool

extension(keep_dot=True)¶

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

Parameters:	keep_dot (bool) – When `False`, the extension’s trailing dot will be removed. Defaults to `True`.
Return type:	str, unicode

find_path(table, refresh=False)¶

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 (str) – The (unqualified) table or feature class name to find. refresh (bool) – Updates the internal table lookup first. See note below.
Return type:	str
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.

from_basename(basename)¶

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

Parameters:	basename (str, unicode) – 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.
Return type:	str, unicode

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, force=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 (str, unicode) – New file extension (with or without trailing dot). force (bool) – When `True`, the extension will always be appended, even if the initial path is a directory. The default is `False`.
Return type:	str, unicode

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

get_media_dir()¶

Gets the derived full path to the corresponding GEONIS media directory.

Raises:	OSError – When the derived directory path does not exist.

classmethod get_parent(path, outside_gdb=False)¶

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 (str, unicode) – Full path to an Esri table, feature class or feature dataset.
outside_gdb (bool) – 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.

Return type:

str, unicode

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'

get_project_dir()¶

Gets the derived full path to the corresponding GEONIS project directory.

Raises:	OSError – When the derived directory path does not exist.

classmethod get_root(path)¶

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 (str, unicode) – Full path to an Esri table, feature class or feature dataset.
Return type:	str, unicode

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_dir¶

Returns True if the initial path is an existing directory.

Return type:	bool

is_file¶

Returns True if the initial path is an existing file.

Return type:	bool

is_gdb¶

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

Return type:	bool

is_remote¶

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

Return type:	bool

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 ‘.’).
Return type:	str, unicode
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'

medium¶: Returns the name of the GEONIS medium to which the data source applies.

parent¶

Returns the parent workspace as a new Workspace instance.

Return type:	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.

Return type:	str, unicode

qualify(name, qualifier=None, separator=None)¶

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 (str, unicode) – Feature dataset, feature class or table name. qualifier (str, unicode) – Optional qualifier if the one derived from the DB connection should be overridden. separator (str, unicode) – Optional separator if the initial one should be overridden (defaults to `'.'`).
Return type:	str, unicode
Raises:	ValueError – If no table name was specified.

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).

Return type:	Workspace

separator¶

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

Return type:	str, unicode