tgclients package

Subpackages

Submodules

tgclients.aggregator module

API for the TextGrid aggregator service

class tgclients.aggregator.Aggregator(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>)

Bases: object

Provide access to the Textgrid Aggregator Service. API docs: https://textgridlab.org/doc/services/submodules/aggregator/docs/api.html

render(textgrid_uris: str, sid: str | None = None, stylesheet_uri: str | None = None, mediatype: str | None = None, link_pattern: str | None = None, sandbox: bool | None = None) → Response
render(textgrid_uris: List[str], sid: str | None = None, stylesheet_uri: str | None = None, mediatype: str | None = None, link_pattern: str | None = None, sandbox: bool | None = None) → Response

Apply an XSLT stylesheet to one or more TextGrid URIs. Will render (X)HTML by default with XSLT stylesheets from tei-c.org see https://textgridlab.org/doc/services/submodules/aggregator/docs/html.html

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

  • stylesheet_uri (Optional[str], optional) – alternative XSLT stylesheet to use. Must be a TextGrid URI.

  • mediatype (Optional[str], optional) – The requested content type. E.g., text/html or text/xml. Default is text/html

  • link_pattern (Optional[str], optional) – URL pattern for links. @URI@ will be replaced with the textgrid: URI.

  • sandbox (Optional[bool], optional) – access sandboxed data. Defaults to false

Returns:

the respone with the TEI corpus in the body

Return type:

Response

teicorpus(textgrid_uris: str, sid: str | None = None) → Response
teicorpus(textgrid_uris: List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as TEI corpus.

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Returns:

the respone with the TEI corpus in the body

Return type:

Response

text(textgrid_uris: str, sid: str | None = None) → Response
text(textgrid_uris: List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as plain text file.

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Returns:

the respone with the text in the body

Return type:

Response

zip(textgrid_uris: str, sid: str | None = None) → Response
zip(textgrid_uris: List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as ZIP file. https://textgridlab.org/doc/services/submodules/aggregator/docs/zip.html

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Returns:

the response with zip file in body.content

Return type:

Response

tgclients.auth module

Provide access to the TextGrid Authorization Service.

class tgclients.auth.TextgridAuth(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>)

Bases: object

Provide access to the TextGrid Authorization Service.

add_admin_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the admin role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

add_editor_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the editor role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

add_manager_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the manager role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

add_observer_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the observer role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

create_project(sid: str, name: str, description: str, default_owner_roles: bool | None = True) → str

Create a new project

Parameters:

  • sid (str) – TextGrid Session ID

  • name (str) – name of the project

  • description (str) – description for the project

  • default_owner_roles (bool, optional) – whether to assign the default roles to the owner (editor, authority to delete). Defaults to True.

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

the project ID of the created project

Return type:

str

delete_project(sid: str, project_id: str) → bool

Delete a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

get_eppn_for_sid(sid: str) → str

Get the EPPN belonging to a sessionID

Parameters:

sid (str) – TextGrid Session ID

Raises:

TextgridAuthException – in case of transport exceptions

Returns:

the EPPN

Return type:

str

get_project_description(project_id: str)

Returns name and description of project identified by ID. See also getAllProjects().

Parameters:

project_id (str) – the project ID

Returns:

project info with id, name and description

Return type:

zeep.objects.projectInfo

list_all_projects() → List[str]

Returns all projects stored in this RBAC instance with ID, name, and description. See also getProjectDescription(). SID is not needed as this information can be reviewed publicly.

Returns:

list of each project with ID, name and description

Return type:

list

list_assigned_projects(sid: str) → List[str]

Get assigned projects.

Parameters:

sid (str) – Session ID

Raises:

TextgridAuthException – in case of transport exceptions

Returns:

A list of project id strings

Return type:

List

exception tgclients.auth.TextgridAuthException

Bases: Exception

Exception communicating with tgauth

tgclients.config module

Variable config options with defaults to be used with the TextGrid clients library.

class tgclients.config.TextgridConfig(host: str | None = 'https://textgridlab.org')

Bases: object

Provide standard configuration / URLs for TextGrid services. Default is to connect to the TextGrid production server (https://textgridlab.org). Pass the constants tgclients.config.DEV_SERVER or tgclients.config.TEST_SERVER to the constructor to change to develop or test server or provide an URL for your own instance.

property aggregator: str

the aggregator service location

Returns:

the aggregator service location

Return type:

str

property auth_address: str

the tgauth service location

Returns:

the tgauth service location

Return type:

str

property auth_wsdl: str

the tgauth wsdl location

Returns:

the tgauth wsdl location

Return type:

str

property crud: str

the nonpublic tgcrud REST service location

Returns:

the nonpublic tgcrud REST service location

Return type:

str

property crud_public: str

the public tgcrud REST service location

Returns:

the public tgcrud REST service location

Return type:

str

property extra_crud_address: str

the tgextra service location

Returns:

the tgextra service location

Return type:

str

property extra_crud_wsdl: str

the tgextra wsdl location

Returns:

the tgextra wsdl location

Return type:

str

property host: str

the host URL

Returns:

the configured host URL

Return type:

str

property http_timeout: float

HTTP timeout to be used when accessing TextGrid services

Returns:

http timeout in seconds

Return type:

float

property search: str

the nonpublic tgsearch service location

Returns:

the nonpublic tgsearch service location

Return type:

str

property search_public: str

the public tgsearch service location

Returns:

the public tgsearch service location

Return type:

str

tgclients.crud module

TextGrid CRUD API.

class tgclients.crud.TextgridCrud(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, for_publication: bool = False)

Bases: TextgridCrudRequest

Provide access to the Textgrid CRUD Service using a XML data binding

create_resource(sid: str, project_id: str, data, metadata: MetadataContainerType) → MetadataContainerType

Create a TextGrid object

Parameters:
Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for newly created object

Return type:

MetadataContainerType

create_revision(sid: str, project_id: str, textgrid_uri: str, data, metadata: MetadataContainerType) → MetadataContainerType

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata (MetadataContainerType) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata from newly created object revision

Return type:

MetadataContainerType

read_metadata(textgrid_uri: str, sid: str | None = None) → MetadataContainerType

Read Metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to ‘’.

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for object

Return type:

MetadataContainerType

update_metadata(sid: str, textgrid_uri: str, metadata: MetadataContainerType) → MetadataContainerType

Update metadata for TextGrid object

Parameters:
Returns:

updated metadata

Return type:

MetadataContainerType

update_resource(sid: str, textgrid_uri: str, data, metadata: MetadataContainerType, create_revision: bool = False) → MetadataContainerType

Update a TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata (MetadataContainerType) – the metadata

  • create_revision (bool) – If True, create a new textgrid object revision. Default: False

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

updated metadata

Return type:

MetadataContainerType

exception tgclients.crud.TextgridCrudException

Bases: Exception

Exception communicating with tgcrud

class tgclients.crud.TextgridCrudRequest(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, for_publication: bool = False)

Bases: object

Provide low level access to the TextGrid CRUD Service.

create_resource(sid: str, project_id: str, data, metadata) → Response

Create a TextGrid object

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • data ([type]) – the data

  • metadata ([type]) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service with metadata from newly created object

Return type:

Response

create_revision(sid: str, project_id: str, textgrid_uri: str, data, metadata: str) → Response

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata (str) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service with metadata from newly created object revision

Return type:

Response

delete_resource(sid: str, textgrid_uri: str) → Response

Delete a TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service

Return type:

Response

read_data(textgrid_uri: str, sid: str | None = None) → Response

Read Data

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service

Return type:

Response

read_metadata(textgrid_uri: str, sid: str | None = None) → Response

Read Metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service

Return type:

Response

update_metadata(sid: str, textgrid_uri: str, metadata) → Response

Update metadata for TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • metadata ([type]) – the metadata

Returns:

HTTP response from service with updated metadata

Return type:

Response

update_resource(sid: str, textgrid_uri: str, data, metadata, create_revision: bool = False) → Response

Update a TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata ([type]) – the metadata

  • create_revision (bool) – If True, create new textgrid object revision. Default: False

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service with updated metadata

Return type:

Response

tgclients.metadata module

Helper functions to work with TextGrid metadata XML

class tgclients.metadata.TextgridMetadata

Bases: object

Helper functions to work with TextGrid metadata XML

build(title: str, mimetype: str) → MetadataContainerType

Build metadata for an TextGrid Object

Parameters:

  • title (str) – title of the object

  • mimetype (str) – format / MIME type of the object

Returns:

metadata

Return type:

MetadataContainerType

static create(title: str, mimetype: str) → str

Create XML metadata for an TextGrid Object

Parameters:

  • title (str) – title of the object

  • mimetype (str) – format / MIME type of the object

Returns:

XML metadata as string

Return type:

str

extension_for_format(mimetype: str) → str | None

Find a matching extension for a textgrid mime type. The first matching extension for a mime type is returned, so extensions defined first in mime.types will be used.

Parameters:

mimetype (str) – the mime type, as found in textgrid metadata format field (e.g. text/xml)

Returns:

a filename extension

Return type:

str

filename(title: str, tguri: str, mimetype: str) → str

Generate a filename for the triple of title, textfgrid-uri and extension

Parameters:

  • title (str) – the title

  • tguri (str) – the textgrid uri

  • mimetype (str) – the mime type (e.g. ‘text/xml’)

Returns:

the filename

Return type:

str

filename_from_metadata(metadata: ResultType) → str

Generate a filename for a textgrid search metadata result containg title, textfgrid-uri and extension

Parameters:

metadata (ResultType) – tgsearch metadata result

Returns:

the filename

Return type:

str

static id_from_filename(filename: str) → str

extract the id from a filename which is named according to link rewriters textgrid metadata to filename mapping

Parameters:

filename (str) – the filename

Returns:

the id

Return type:

str

static remove_tg_prefix(tguri: str) → str
searchresponse2object(xml: str) → Response
transliterate(title: str) → str

replace all chars which may be problematic in filenames from title string

Parameters:

title (str) – a title from textgrid metadata

Returns:

the title string with problematic chars replaced

Return type:

str

tgclients.search module

TextGrid Search API.

class tgclients.search.TextgridSearch(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, nonpublic: bool = False)

Bases: TextgridSearchRequest

Provide access to the TextGrid search service using a XML data binding

children(textgrid_uri: str, sid: str | None = None) → TextgridUris

List URIs for all children of this aggregation and its child aggregations

Parameters:

  • textgrid_uri (str) – Textgrid URI of an aggregation

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

URIs for children of this aggregation and its child aggregations

Return type:

TextgridUris

edition_work_metadata_for(textgrid_uri: str, sid: str | None = None) → Response

Find parent edition for an object and the edition and work metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

Edition and work metadata for given object

from first matching parent edition

Return type:

SearchResponse

info(textgrid_uri: str, sid: str | None = None) → Response

Retrieve metadata for a textgrid object specified by its textgrid-uri

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for uri

Return type:

SearchResponse

list_aggregation(textgrid_uri: str, sid: str | None = None) → Response

Get child resources of an aggregation.

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

A list of textgrid metadata entries

Return type:

SearchResponse

list_project_root(project_id: str, sid: str | None = None) → Response

Get objects belonging to a project, filtered by objects that are in an aggregation in the same project.

Parameters:

  • project_id (str) – the ID of the project to list

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

A list of textgrid metadata entries

Return type:

SearchResponse

search(query: str | None = '*', sid: str | None = None, target: str | None = None, order: str | None = None, start: int | None = None, limit: int | None = None, kwic_width: int | None = None, word_distance: int | None = None, path: bool | None = None, all_projects: bool | None = None, sandbox: bool | None = None, filters: List[str] | None = None, facet: List[str] | None = None, facet_limit: int | None = None) → Response

Run fulltext queries or filters on TextGrid metadata and fulltext objects.

Please note: as the defaults of this function are mostly set to None, the defaults from

the service are used, and also noted in this docstring. see: http://textgridlab.org/doc/services/submodules/tg-search/docs/api/search.html

Parameters:

  • query (str, optional) – Lucene search string. Defaults to ‘*’.

  • sid (str, optional) – TextGrid SessionID from tgauth. Defaults to None.

  • target (str, optional) – where to do fulltext-searches: one of ‘structure’, ‘metadata’ and ‘both’. Defaults to ‘both’.

  • order (str, optional) – key-value ascending (asc) or descending (desc) and metadata-field like asc:title or desc:author. Defaults to ‘relevance’.

  • start (int, optional) – result number to start with.. Defaults to 0.

  • limit (int, optional) – number of entries to return.. Defaults to 20.

  • kwic_width (int, optional) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (int, optional) – max distance beetween two words in fulltext query. ignored if set to a number < 0, then for a hit all words must be contained in one document. Defaults to -1.

  • path (boo], optional) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

  • all_projects (bool, optional) – all Projects should be searched for public data, warning: this query may be slow, if many results found. Defaults to false.

  • sandbox (bool, optional) – show sandboxed (not yet finally published) data. Defaults to false.

  • filters (List[str], optional) – add filter on query results, e.g. for faceting. Defaults to None.

  • facet (List[str], optional) – get facets for query results. Defaults to None.

  • facet_limit (int, optional) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

a list of textgrid metadata entries,

KWIC hits, paths and facets if requested

Return type:

SearchResponse

exception tgclients.search.TextgridSearchException

Bases: Exception

Exception communicating with tgsearch

class tgclients.search.TextgridSearchRequest(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, nonpublic: bool = False)

Bases: object

Provide low level access to the TextGrid search service, returning the response objects.

children(textgrid_uri: str, sid: str | None = None) → Response

List URIs for all children of this aggregation and its child aggregations

Parameters:

  • textgrid_uri (str) – Textgrid URI of an aggregation

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service - URIs for children of this

aggregation and its child aggregations

Return type:

Response

edition_work_metadata_for(textgrid_uri: str, sid: str | None = None) → Response

Find parent edition for an object and the edition and work metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service - edition and work metadata for given object

from first matching parent edition

Return type:

Response

info(textgrid_uri: str, sid: str | None = None) → Response

Retrieve metadata for a textgrid object specified by its textgrid-uri

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for uri

Return type:

Response

list_aggregation(textgrid_uri: str, sid: str | None = None) → Response

Get child resources of an aggregation.

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service, containing a list of textgrid metadata entries

Return type:

Response

list_project_root(project_id: str, sid: str | None = None) → Response

Get objects belonging to a project, filtered by objects that are in an aggregation in the same project.

Parameters:

  • project_id (str) – the ID of the project to list

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service, containing a list of textgrid metadata entries

Return type:

Response

search(query: str | None = '*', sid: str | None = None, target: str | None = None, order: str | None = None, start: int | None = None, limit: int | None = None, kwic_width: int | None = None, word_distance: int | None = None, path: bool | None = None, all_projects: bool | None = None, sandbox: bool | None = None, filters: List[str] | None = None, facet: List[str] | None = None, facet_limit: int | None = None) → Response

Run fulltext queries or filters on TextGrid metadata and fulltext objects.

Please note: as the defaults of this function are mostly set to None, the defaults from

the service are used, and also noted in this docstring. see: http://textgridlab.org/doc/services/submodules/tg-search/docs/api/search.html

Parameters:

  • query (str, optional) – Lucene search string. Defaults to ‘*’.

  • sid (str, optional) – TextGrid SessionID from tgauth. Defaults to None.

  • target (str, optional) – where to do fulltext-searches: one of ‘structure’, ‘metadata’ and ‘both’. Defaults to ‘both’.

  • order (str, optional) – key-value ascending (asc) or descending (desc) and metadata-field like asc:title or desc:author. Defaults to ‘relevance’.

  • start (int, optional) – result number to start with.. Defaults to 0.

  • limit (int, optional) – number of entries to return.. Defaults to 20.

  • kwic_width (int, optional) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (int, optional) – max distance beetween two words in fulltext query. ignored if set to a number < 0, then for a hit all words must be contained in one document. Defaults to -1.

  • path (boo], optional) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

  • all_projects (bool, optional) – all Projects should be searched for public data, warning: this query may be slow, if many results found. Defaults to false.

  • sandbox (bool, optional) – show sandboxed (not yet finally published) data. Defaults to false.

  • filters (List[str], optional) – add filter on query results, e.g. for faceting. Defaults to None.

  • facet (List[str], optional) – get facets for query results. Defaults to None.

  • facet_limit (int, optional) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service - a list of textgrid metadata entries,

KWIC hits, paths and facets if requested

Return type:

Response

tgclients.utils module

Utility functions for working with the TextGrid repository

class tgclients.utils.Utils

Bases: object

Utility functions for working with the TextGrid repository

static aggregation_to_list(xml: str) → List[str]

Extract URIs from TextGrid aggregation into a list

Parameters:

xml (str) – TextGrid aggregation XML

Returns:

TextGrid URIs from aggregation

Return type:

list[str]

static list_to_aggregation(textgrid_uri: str, members: List[str]) → str

Create XML for a TextGrid aggregation from list

Parameters:

  • textgrid_uri (str) – textgrid URI of the aggregation to create

  • members (list[str]) – list of textgrid URIs inside aggregation

Returns:

XML for TextGrid Aggregation

Return type:

str

Module contents

class tgclients.Aggregator(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>)

Bases: object

Provide access to the Textgrid Aggregator Service. API docs: https://textgridlab.org/doc/services/submodules/aggregator/docs/api.html

render(textgrid_uris: str, sid: str | None = None, stylesheet_uri: str | None = None, mediatype: str | None = None, link_pattern: str | None = None, sandbox: bool | None = None) → Response
render(textgrid_uris: List[str], sid: str | None = None, stylesheet_uri: str | None = None, mediatype: str | None = None, link_pattern: str | None = None, sandbox: bool | None = None) → Response

Apply an XSLT stylesheet to one or more TextGrid URIs. Will render (X)HTML by default with XSLT stylesheets from tei-c.org see https://textgridlab.org/doc/services/submodules/aggregator/docs/html.html

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

  • stylesheet_uri (Optional[str], optional) – alternative XSLT stylesheet to use. Must be a TextGrid URI.

  • mediatype (Optional[str], optional) – The requested content type. E.g., text/html or text/xml. Default is text/html

  • link_pattern (Optional[str], optional) – URL pattern for links. @URI@ will be replaced with the textgrid: URI.

  • sandbox (Optional[bool], optional) – access sandboxed data. Defaults to false

Returns:

the respone with the TEI corpus in the body

Return type:

Response

teicorpus(textgrid_uris: str, sid: str | None = None) → Response
teicorpus(textgrid_uris: List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as TEI corpus.

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Returns:

the respone with the TEI corpus in the body

Return type:

Response

text(textgrid_uris: str, sid: str | None = None) → Response
text(textgrid_uris: List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as plain text file.

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Returns:

the respone with the text in the body

Return type:

Response

zip(textgrid_uris: str, sid: str | None = None) → Response
zip(textgrid_uris: List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as ZIP file. https://textgridlab.org/doc/services/submodules/aggregator/docs/zip.html

Parameters:

  • textgrid_uris (List[str] or str) – a single or a list of TextGrid URIs

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Returns:

the response with zip file in body.content

Return type:

Response

class tgclients.TextgridAuth(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>)

Bases: object

Provide access to the TextGrid Authorization Service.

add_admin_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the admin role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

add_editor_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the editor role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

add_manager_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the manager role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

add_observer_to_project(sid: str, project_id: str, eppn: str) → bool

Give an user the observer role in a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

  • eppn (str) – the eppn identifying the user

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

create_project(sid: str, name: str, description: str, default_owner_roles: bool | None = True) → str

Create a new project

Parameters:

  • sid (str) – TextGrid Session ID

  • name (str) – name of the project

  • description (str) – description for the project

  • default_owner_roles (bool, optional) – whether to assign the default roles to the owner (editor, authority to delete). Defaults to True.

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

the project ID of the created project

Return type:

str

delete_project(sid: str, project_id: str) → bool

Delete a project

Parameters:

  • sid (str) – TextGrid Session ID

  • project_id (str) – the project ID

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

true in case of success

Return type:

bool

get_eppn_for_sid(sid: str) → str

Get the EPPN belonging to a sessionID

Parameters:

sid (str) – TextGrid Session ID

Raises:

TextgridAuthException – in case of transport exceptions

Returns:

the EPPN

Return type:

str

get_project_description(project_id: str)

Returns name and description of project identified by ID. See also getAllProjects().

Parameters:

project_id (str) – the project ID

Returns:

project info with id, name and description

Return type:

zeep.objects.projectInfo

list_all_projects() → List[str]

Returns all projects stored in this RBAC instance with ID, name, and description. See also getProjectDescription(). SID is not needed as this information can be reviewed publicly.

Returns:

list of each project with ID, name and description

Return type:

list

list_assigned_projects(sid: str) → List[str]

Get assigned projects.

Parameters:

sid (str) – Session ID

Raises:

TextgridAuthException – in case of transport exceptions

Returns:

A list of project id strings

Return type:

List

exception tgclients.TextgridAuthException

Bases: Exception

Exception communicating with tgauth

class tgclients.TextgridConfig(host: str | None = 'https://textgridlab.org')

Bases: object

Provide standard configuration / URLs for TextGrid services. Default is to connect to the TextGrid production server (https://textgridlab.org). Pass the constants tgclients.config.DEV_SERVER or tgclients.config.TEST_SERVER to the constructor to change to develop or test server or provide an URL for your own instance.

property aggregator: str

the aggregator service location

Returns:

the aggregator service location

Return type:

str

property auth_address: str

the tgauth service location

Returns:

the tgauth service location

Return type:

str

property auth_wsdl: str

the tgauth wsdl location

Returns:

the tgauth wsdl location

Return type:

str

property crud: str

the nonpublic tgcrud REST service location

Returns:

the nonpublic tgcrud REST service location

Return type:

str

property crud_public: str

the public tgcrud REST service location

Returns:

the public tgcrud REST service location

Return type:

str

property extra_crud_address: str

the tgextra service location

Returns:

the tgextra service location

Return type:

str

property extra_crud_wsdl: str

the tgextra wsdl location

Returns:

the tgextra wsdl location

Return type:

str

property host: str

the host URL

Returns:

the configured host URL

Return type:

str

property http_timeout: float

HTTP timeout to be used when accessing TextGrid services

Returns:

http timeout in seconds

Return type:

float

property search: str

the nonpublic tgsearch service location

Returns:

the nonpublic tgsearch service location

Return type:

str

property search_public: str

the public tgsearch service location

Returns:

the public tgsearch service location

Return type:

str

class tgclients.TextgridCrud(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, for_publication: bool = False)

Bases: TextgridCrudRequest

Provide access to the Textgrid CRUD Service using a XML data binding

create_resource(sid: str, project_id: str, data, metadata: MetadataContainerType) → MetadataContainerType

Create a TextGrid object

Parameters:
Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for newly created object

Return type:

MetadataContainerType

create_revision(sid: str, project_id: str, textgrid_uri: str, data, metadata: MetadataContainerType) → MetadataContainerType

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata (MetadataContainerType) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata from newly created object revision

Return type:

MetadataContainerType

read_metadata(textgrid_uri: str, sid: str | None = None) → MetadataContainerType

Read Metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to ‘’.

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for object

Return type:

MetadataContainerType

update_metadata(sid: str, textgrid_uri: str, metadata: MetadataContainerType) → MetadataContainerType

Update metadata for TextGrid object

Parameters:
Returns:

updated metadata

Return type:

MetadataContainerType

update_resource(sid: str, textgrid_uri: str, data, metadata: MetadataContainerType, create_revision: bool = False) → MetadataContainerType

Update a TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata (MetadataContainerType) – the metadata

  • create_revision (bool) – If True, create a new textgrid object revision. Default: False

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

updated metadata

Return type:

MetadataContainerType

exception tgclients.TextgridCrudException

Bases: Exception

Exception communicating with tgcrud

class tgclients.TextgridCrudRequest(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, for_publication: bool = False)

Bases: object

Provide low level access to the TextGrid CRUD Service.

create_resource(sid: str, project_id: str, data, metadata) → Response

Create a TextGrid object

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • data ([type]) – the data

  • metadata ([type]) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service with metadata from newly created object

Return type:

Response

create_revision(sid: str, project_id: str, textgrid_uri: str, data, metadata: str) → Response

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata (str) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service with metadata from newly created object revision

Return type:

Response

delete_resource(sid: str, textgrid_uri: str) → Response

Delete a TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service

Return type:

Response

read_data(textgrid_uri: str, sid: str | None = None) → Response

Read Data

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service

Return type:

Response

read_metadata(textgrid_uri: str, sid: str | None = None) → Response

Read Metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service

Return type:

Response

update_metadata(sid: str, textgrid_uri: str, metadata) → Response

Update metadata for TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • metadata ([type]) – the metadata

Returns:

HTTP response from service with updated metadata

Return type:

Response

update_resource(sid: str, textgrid_uri: str, data, metadata, create_revision: bool = False) → Response

Update a TextGrid object

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data ([type]) – the data

  • metadata ([type]) – the metadata

  • create_revision (bool) – If True, create new textgrid object revision. Default: False

Raises:

TextgridCrudException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service with updated metadata

Return type:

Response

class tgclients.TextgridSearch(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, nonpublic: bool = False)

Bases: TextgridSearchRequest

Provide access to the TextGrid search service using a XML data binding

children(textgrid_uri: str, sid: str | None = None) → TextgridUris

List URIs for all children of this aggregation and its child aggregations

Parameters:

  • textgrid_uri (str) – Textgrid URI of an aggregation

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

URIs for children of this aggregation and its child aggregations

Return type:

TextgridUris

edition_work_metadata_for(textgrid_uri: str, sid: str | None = None) → Response

Find parent edition for an object and the edition and work metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

Edition and work metadata for given object

from first matching parent edition

Return type:

SearchResponse

info(textgrid_uri: str, sid: str | None = None) → Response

Retrieve metadata for a textgrid object specified by its textgrid-uri

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for uri

Return type:

SearchResponse

list_aggregation(textgrid_uri: str, sid: str | None = None) → Response

Get child resources of an aggregation.

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

A list of textgrid metadata entries

Return type:

SearchResponse

list_project_root(project_id: str, sid: str | None = None) → Response

Get objects belonging to a project, filtered by objects that are in an aggregation in the same project.

Parameters:

  • project_id (str) – the ID of the project to list

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

A list of textgrid metadata entries

Return type:

SearchResponse

search(query: str | None = '*', sid: str | None = None, target: str | None = None, order: str | None = None, start: int | None = None, limit: int | None = None, kwic_width: int | None = None, word_distance: int | None = None, path: bool | None = None, all_projects: bool | None = None, sandbox: bool | None = None, filters: List[str] | None = None, facet: List[str] | None = None, facet_limit: int | None = None) → Response

Run fulltext queries or filters on TextGrid metadata and fulltext objects.

Please note: as the defaults of this function are mostly set to None, the defaults from

the service are used, and also noted in this docstring. see: http://textgridlab.org/doc/services/submodules/tg-search/docs/api/search.html

Parameters:

  • query (str, optional) – Lucene search string. Defaults to ‘*’.

  • sid (str, optional) – TextGrid SessionID from tgauth. Defaults to None.

  • target (str, optional) – where to do fulltext-searches: one of ‘structure’, ‘metadata’ and ‘both’. Defaults to ‘both’.

  • order (str, optional) – key-value ascending (asc) or descending (desc) and metadata-field like asc:title or desc:author. Defaults to ‘relevance’.

  • start (int, optional) – result number to start with.. Defaults to 0.

  • limit (int, optional) – number of entries to return.. Defaults to 20.

  • kwic_width (int, optional) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (int, optional) – max distance beetween two words in fulltext query. ignored if set to a number < 0, then for a hit all words must be contained in one document. Defaults to -1.

  • path (boo], optional) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

  • all_projects (bool, optional) – all Projects should be searched for public data, warning: this query may be slow, if many results found. Defaults to false.

  • sandbox (bool, optional) – show sandboxed (not yet finally published) data. Defaults to false.

  • filters (List[str], optional) – add filter on query results, e.g. for faceting. Defaults to None.

  • facet (List[str], optional) – get facets for query results. Defaults to None.

  • facet_limit (int, optional) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

a list of textgrid metadata entries,

KWIC hits, paths and facets if requested

Return type:

SearchResponse

exception tgclients.TextgridSearchException

Bases: Exception

Exception communicating with tgsearch

class tgclients.TextgridSearchRequest(config: ~tgclients.config.TextgridConfig = <tgclients.config.TextgridConfig object>, nonpublic: bool = False)

Bases: object

Provide low level access to the TextGrid search service, returning the response objects.

children(textgrid_uri: str, sid: str | None = None) → Response

List URIs for all children of this aggregation and its child aggregations

Parameters:

  • textgrid_uri (str) – Textgrid URI of an aggregation

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service - URIs for children of this

aggregation and its child aggregations

Return type:

Response

edition_work_metadata_for(textgrid_uri: str, sid: str | None = None) → Response

Find parent edition for an object and the edition and work metadata

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service - edition and work metadata for given object

from first matching parent edition

Return type:

Response

info(textgrid_uri: str, sid: str | None = None) → Response

Retrieve metadata for a textgrid object specified by its textgrid-uri

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str]) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

metadata for uri

Return type:

Response

list_aggregation(textgrid_uri: str, sid: str | None = None) → Response

Get child resources of an aggregation.

Parameters:

  • textgrid_uri (str) – Textgrid URI

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service, containing a list of textgrid metadata entries

Return type:

Response

list_project_root(project_id: str, sid: str | None = None) → Response

Get objects belonging to a project, filtered by objects that are in an aggregation in the same project.

Parameters:

  • project_id (str) – the ID of the project to list

  • sid (Optional[str], optional) – Session ID. Defaults to None.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service, containing a list of textgrid metadata entries

Return type:

Response

search(query: str | None = '*', sid: str | None = None, target: str | None = None, order: str | None = None, start: int | None = None, limit: int | None = None, kwic_width: int | None = None, word_distance: int | None = None, path: bool | None = None, all_projects: bool | None = None, sandbox: bool | None = None, filters: List[str] | None = None, facet: List[str] | None = None, facet_limit: int | None = None) → Response

Run fulltext queries or filters on TextGrid metadata and fulltext objects.

Please note: as the defaults of this function are mostly set to None, the defaults from

the service are used, and also noted in this docstring. see: http://textgridlab.org/doc/services/submodules/tg-search/docs/api/search.html

Parameters:

  • query (str, optional) – Lucene search string. Defaults to ‘*’.

  • sid (str, optional) – TextGrid SessionID from tgauth. Defaults to None.

  • target (str, optional) – where to do fulltext-searches: one of ‘structure’, ‘metadata’ and ‘both’. Defaults to ‘both’.

  • order (str, optional) – key-value ascending (asc) or descending (desc) and metadata-field like asc:title or desc:author. Defaults to ‘relevance’.

  • start (int, optional) – result number to start with.. Defaults to 0.

  • limit (int, optional) – number of entries to return.. Defaults to 20.

  • kwic_width (int, optional) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (int, optional) – max distance beetween two words in fulltext query. ignored if set to a number < 0, then for a hit all words must be contained in one document. Defaults to -1.

  • path (boo], optional) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

  • all_projects (bool, optional) – all Projects should be searched for public data, warning: this query may be slow, if many results found. Defaults to false.

  • sandbox (bool, optional) – show sandboxed (not yet finally published) data. Defaults to false.

  • filters (List[str], optional) – add filter on query results, e.g. for faceting. Defaults to None.

  • facet (List[str], optional) – get facets for query results. Defaults to None.

  • facet_limit (int, optional) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400 (# noqa: DAR402)

Returns:

HTTP response from service - a list of textgrid metadata entries,

KWIC hits, paths and facets if requested

Return type:

Response

class tgclients.Utils

Bases: object

Utility functions for working with the TextGrid repository

static aggregation_to_list(xml: str) → List[str]

Extract URIs from TextGrid aggregation into a list

Parameters:

xml (str) – TextGrid aggregation XML

Returns:

TextGrid URIs from aggregation

Return type:

list[str]

static list_to_aggregation(textgrid_uri: str, members: List[str]) → str

Create XML for a TextGrid aggregation from list

Parameters:

  • textgrid_uri (str) – textgrid URI of the aggregation to create

  • members (list[str]) – list of textgrid URIs inside aggregation

Returns:

XML for TextGrid Aggregation

Return type:

str