### Navigation

- index
- modules
- next
- previous
- Home »
- Contents »
- InaSAFE’s API documentation »
- Package::safe_qgis »

# Module: safe_qgis.keyword_io

Keyword IO implementation.

Tip

Provides functionality for reading and writing keywords from within QGIS. It is an abstration for the keywords system used by the underlying library.

class `safe_qgis.keyword_io.``KeywordIO`

  Class for doing keyword read/write operations.

  It abstracts away differences between using SAFE to get keywords from a .keywords file and this plugins implemenation of keyword caching in a local sqlite db used for supporting keywords for remote datasources.

  `appendKeywords`(theLayer, theKeywords)

    Write keywords for a datasource.

    Args:
      - theLayer - A QGIS QgsMapLayer instance.
      - theKeywords - a dict containing all the keywords to be added for the layer.
    Returns:
      None.
    Raises:
      None
  `areKeywordsFileBased`(theLayer)

    Find out if keywords should be read/written to file or our keywords db.

    Args:
      - theLayer - A QGIS QgsMapLayer instance.
    Returns:
      True if keywords are storedin a file next to the dataset, else False if the dataset is remove e.g. a database.
    Raises:
      None
  `closeConnection`()

    Given an sqlite3 connection, close it.

    Args:
      None
    Returns:
      None
    Raises:
      None
  `copyKeywords`(theSourceLayer, theDestinationFile, theExtraKeywords=None)

    Helper to copy the keywords file from a source dataset to a destination dataset.

    e.g.:

        copyKeywords('foo.shp', 'bar.shp')

    Will result in the foo.keywords file being copied to bar.keyword.

    Optional argument extraKeywords is a dictionary with additional keywords that will be added to the destination file e.g:

        copyKeywords('foo.shp', 'bar.shp', {'resolution': 0.01})

    Args:
      - theSourceLayer - A QGIS QgsMapLayer instance.
      - theDestinationFile - the output filename that should be used to store the keywords in. It can be a .shp or a .keywords for exampled since the suffix will always be replaced with .keywords.
      - theExtraKeywords - a dict containing all the extra keywords to be written for the layer. The written keywords will consist of any original keywords from the source layer’s keywords file and and the extra keywords (which will replace the source layers keywords if the key is identical).
    Returns:
      None.
    Raises:
      None
  `defaultKeywordDbPath`()

    Helper to get the default path for the keywords file (which is <plugin dir>/keywords.db)

    Args:
      None
    Returns:
      A string representing the path to where the keywords file is to be.
    Raises:
      None
  `deleteKeywordsForUri`(theUri)

    Delete keywords for a URI in the keywords database. A hash will be constructed from the supplied uri and a lookup made in a local SQLITE database for the keywords. If there is an existing record for the hash, the entire record will be erased.

    See also

    writeKeywordsForUri, readKeywordsForUri

    Args:

    > - theUri - a str representing a layer uri as parameter. .e.g. ‘dbname=’osm’ host=localhost port=5432 user=’foo’ password=’bar’ sslmode=disable key=’id’ srid=4326

    Returns:
      None
    Raises:
      None
  `getCursor`()

    Get a cursor for the active connection. The cursor can be used to execute arbitrary queries against the database. This method also checks that the keywords table exists in the schema, and if not, it creates it.

    Args:
      theConnection - a valid, open sqlite3 database connection.
    Returns:
      a valid cursor opened against the connection.
    Raises:
      An sqlite.Error will be raised if anything goes wrong
  `getHashForDatasource`(theDataSource)

    Given a datasource, return its hash.

    Args:
      None
    Returns:
      None
    Raises:
      None
  `openConnection`()

    Open an sqlite connection to the keywords database. By default the keywords database will be used in the plugin dir, unless an explicit path has been set using setKeywordDbPath, or overridden in QSettings. If the db does not exist it will be created.

    Args:
      thePath - path to the desired sqlite db to use.
    Returns:
      None
    Raises:
      An sqlite.Error is raised if anything goes wrong
  `readKeywordFromUri`(theUri, theKeyword=None)

    Get metadata from the keywords file associated with a non local layer (e.g. postgresql connection).

    A hash will be constructed from the supplied uri and a lookup made in a local SQLITE database for the keywords. If there is an existing record it will be returned, if not and error will be thrown.

    See also

    writeKeywordsForUri,deleteKeywordsForUri

    Args:

    > - theUri - a str representing a layer uri as parameter. .e.g. ‘dbname=’osm’ host=localhost port=5432 user=’foo’ password=’bar’ sslmode=disable key=’id’ srid=4326
    > - keyword - optional - the metadata keyword to retrieve e.g. ‘title’

    Returns:
      A string containing the retrieved value for the keyword if the keyword argument is specified, otherwise the complete keywords dictionary is returned.
    Raises:
      KeywordNotFoundException if the keyword is not found.
  `readKeywords`(theLayer, theKeyword=None)

    Read keywords for a datasource and return them as a dictionary. This is a wrapper method that will ‘do the right thing’ to fetch keywords for the given datasource. In particular, if the datasource is remote (e.g. a database connection) it will fetch the keywords from the keywords store.

    Args:
      - theLayer - A QGIS QgsMapLayer instance.
      - theKeyword - optional - will extract only the specified keyword from the keywords dict.
    Returns:
      A dict if theKeyword is omitted, otherwise the value for the given key if it is present.
    Raises:
      Propogates any exception from the underlying reader delegate.
  `setKeywordDbPath`(thePath)

    Set the path for the keyword database (sqlite).

    The file will be used to search for keywords for non local datasets.

    Args:
      thePath - a valid path to a sqlite database. The database does not need to exist already, but the user should be able to write to the path provided.
    Returns:
      None
    Raises:
      None
  `setupKeywordDbPath`()

    Helper to set the active path for the keywords. Called at init time, you can override this path by calling setKeywordDbPath.

    Args:
      None
    Returns:
      A string representing the path to where the keywords file is to be. If the user has never specified what this path is, the defaultKeywordDbPath is returned.
    Raises:
      None
  `writeKeywords`(theLayer, theKeywords)

    Write keywords for a datasource. This is a wrapper method that will ‘do the right thing’ to store keywords for the given datasource. In particular, if the datasource is remote (e.g. a database connection) it will write the keywords from the keywords store.

    Args:
      - theLayer - A QGIS QgsMapLayer instance.
      - theKeywords - a dict containing all the keywords to be written for the layer.
    Returns:
      None.
    Raises:
      None
  `writeKeywordsForUri`(theUri, theKeywords)

    Write keywords for a URI into the keywords database. All the keywords for the uri should be written in a single operation. A hash will be constructed from the supplied uri and a lookup made in a local SQLITE database for the keywords. If there is an existing record it will be updated, if not, a new one will be created.

    See also

    readKeywordFromUri, deleteKeywordsForUri

    Args:

    > - theUri - a str representing a layer uri as parameter. .e.g. ‘dbname=’osm’ host=localhost port=5432 user=’foo’ password=’bar’ sslmode=disable key=’id’ srid=4326
    > - keywords - mandatory - the metadata keyword to retrieve e.g. ‘title’

    Returns:
      A string containing the retrieved value for the keyword if the keyword argument is specified, otherwise the complete keywords dictionary is returned.
    Raises:
      KeywordNotFoundException if the keyword is not recognised.

This module forms part of the InaSAFE tool.

### Navigation

- index
- modules
- next
- previous
- Home »
- Contents »
- InaSAFE’s API documentation »
- Package::safe_qgis »