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 (Union[str, List[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 (Union[str, List[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 (Union[str, List[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 (Union[str, List[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 (Optional[bool]) – 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_ids(sid: str, name: str, mail: str, organisation: str)

Returns user records for a name or mail address.

Parameters:

  • sid (str) – SessionID of user that wants to query for names

  • name (str) – Name

  • mail (str) – E-Mail Address

  • organisation (str) – Organisation

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

contains 0…n userDetails, which themselves have elements ePPN, name, mail,

organisation, agreesearch, usersupplieddata

Return type:

zeep.object.getIDsResponse

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

get_user_role(sid: str, project_id: str)

Returns ePPNs plus Array of Roles of all members in the project.

Caller must be member herself.

Parameters:

  • sid (str) – String, SessionID of user that wants to query for roles

  • project_id (str) – the project ID

Returns:

ePPNs plus Array of Roles of all members in project

Return type:

zeep.objects.getUserRoleResponse

list_all_projects() → List[str]

List all projects.

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[str]

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[str]

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

Remove an users 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

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

Remove an users editor role from 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

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

Remove an users manager role from 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

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

Remove an users observer role from 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

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 publish: str

The publish service location.

Returns:

the publish service location

Return type:

str

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: str | IO[Any], metadata: MetadataContainerType, uri: str | None = None) → MetadataContainerType

Create a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • data (Union[str, IO[Any]]) – the data

  • metadata (MetadataContainerType) – the metadata

  • uri (Optional[str]) – optionally set a TextGrid URI to use for new object (see get_uri method)

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

metadata for newly created object

Return type:

MetadataContainerType

create_revision(sid: str, project_id: str, textgrid_uri: str, data: str | IO[Any], metadata: MetadataContainerType) → MetadataContainerType

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – the data

  • metadata (MetadataContainerType) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

metadata from newly created object revision

Return type:

MetadataContainerType

get_uri(sid: str, how_many: int) → list

Get TextGrid URIs.

Get an specified amount of TextGrid URIs for assigning to new TextGrid objects. Useful e.g. for bulk imports.

Parameters:

  • sid (str) – Session ID

  • how_many (int) – number of URIs to generate

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

List with TextGrid URIs

Return type:

list

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

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: str | IO[Any], metadata: MetadataContainerType, create_revision: bool = False) → MetadataContainerType

Update a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – 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

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: str | IO[Any], metadata: str | IO[Any], uri: str | None = None) → Response

Create a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • data (Union[str, IO[Any]]) – the data

  • metadata (Union[str, IO[Any]]) – the metadata

  • uri (Optional[str]) – optionally set a TextGrid URI to use for new object (see get_uri method)

Raises:

TextgridCrudException – if HTTP status code >= 400

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: str | IO[Any], metadata: str | IO[Any]) → Response

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – the data

  • metadata (Union[str, IO[Any]]) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400

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

Returns:

HTTP response from service

Return type:

Response

get_uri(sid: str, how_many: int) → Response

Get TextGrid URIs.

Get an specified amount of TextGrid URIs for assigning to new TextGrid objects. Useful e.g. for bulk imports.

Parameters:

  • sid (str) – Session ID

  • how_many (int) – number of URIs to generate

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

HTTP response from service with TextGrid URIs in body

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

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

Returns:

HTTP response from service

Return type:

Response

update_metadata(sid: str, textgrid_uri: str, metadata: str | IO[Any]) → Response

Update metadata for TextGrid object.

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • metadata (Union[str, IO[Any]]) – the metadata

Returns:

HTTP response from service with updated metadata

Return type:

Response

update_resource(sid: str, textgrid_uri: str, data: str | IO[Any], metadata: str | IO[Any], create_revision: bool = False) → Response

Update a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – the data

  • metadata (Union[str, IO[Any]]) – the metadata

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

Raises:

TextgridCrudException – if HTTP status code >= 400

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:

Optional[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.

This is made of title, textgrid-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.

This 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

Remove the ‘textgrid:’ prefix from an textgrid URI.

Parameters:

tguri (str) – the textgrid URI

Returns:

uri without the prefix

Return type:

str

searchresponse2object(xml: str) → Response

Build databinding for XML string returned from tgsearch.

Parameters:

xml (str) – xml string as returned from tgsearch

Returns:

tgsearch Response

Return type:

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.publish module

API for the TextGrid publish service.

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

Bases: TextgridPublishRequest

Provide access to the Textgrid Publish Service using XML data binding.

API docs: https://textgridlab.org/doc/services/submodules/kolibri/kolibri-tgpublish-service/docs/index.html

copy(sid: str, textgrid_uris: List[str], project_id: str) → str

Copies the objects belonging to the given URIs to the given project ID.

Also copies all aggregated objects (from aggregations/editions/collections).

Parameters:

  • sid (str) – Session ID

  • textgrid_uris (List[str]) – Textgrid URIs of objects to copy

  • project_id (str) – Project ID of the project to copy the objects to.

Raises:

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

Returns:

UUID of copy job queued

Return type:

str

copy_to_new_revision(sid: str, textgrid_uris: List[str]) → str

Copies the objects belonging to the given URIs to new revisions of themselves.

Also copies all aggregated objects (from aggregations/editions/collections).

Parameters:

  • sid (str) – Session ID

  • textgrid_uris (List[str]) – Textgrid URIs of objects to copy

Raises:

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

Returns:

UUID of copy job queued

Return type:

str

get_status(job_id: str) → PublishResponse

Get status for job specified by job_id.

Parameters:

job_id (str) – ID of job to get the status for

Raises:

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

Returns:

publish response object

Return type:

PublishResponse

publish(sid: str, textgrid_uri: str, ignore_warnings: bool = False, dry_run: bool = True) → str

Publish the edition or collection belonging to the given URIs.

Also publish all aggregated objects (from aggregations/editions/collections)

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI of object to publish

  • ignore_warnings (bool) – try publishing even if warnings occured

  • dry_run (bool) – do not really publish, just check

Raises:

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

Returns:

just an OK if the job started

Return type:

str

publish_worldreadable(sid: str, textgrid_uri: str, ignore_warnings: bool = False, dry_run: bool = True) → str

Publish the technical object with given URI.

Worldreadable objects are some technical objects which may be published independently of editions or collections. Get a list of allowed mime types here: https://textgridlab.org/1.0/tgpublish/listWorldReadables

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI of object to publish

  • ignore_warnings (bool) – try publishing even if warnings occured

  • dry_run (bool) – do not really publish, just check

Raises:

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

Returns:

just an OK if the job started

Return type:

str

exception tgclients.publish.TextgridPublishException

Bases: Exception

Exception communicating with tgpublish!

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

Bases: object

Provide low level access to the Textgrid Publish Service returning HTTP response objects.

API docs: https://textgridlab.org/doc/services/submodules/kolibri/kolibri-tgpublish-service/docs/index.html

copy(sid: str, textgrid_uris: List[str], project_id: str) → Response

Copies the objects belonging to the given URIs to the given project ID.

Also copies all aggregated objects (from aggregations/editions/collections).

Parameters:

  • sid (str) – Session ID

  • textgrid_uris (List[str]) – Textgrid URIs of objects to copy

  • project_id (str) – Project ID of the project to copy the objects to.

Raises:

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

Returns:

HTTP response from service - UUID of copy job queued

Return type:

Response

copy_to_new_revision(sid: str, textgrid_uris: List[str]) → Response

Copies the objects belonging to the given URIs to new revisions of themselves.

Also copies all aggregated objects (from aggregations/editions/collections).

Parameters:

  • sid (str) – Session ID

  • textgrid_uris (List[str]) – Textgrid URIs of objects to copy

Raises:

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

Returns:

HTTP response from service - UUID of copy job queued

Return type:

Response

get_status(job_id: str) → Response

Get status for job specified by job_id.

Parameters:

job_id (str) – ID of job to get the status for

Raises:

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

Returns:

HTTP response from service - with XML containing the publish status

Return type:

Response

publish(sid: str, textgrid_uri: str, ignore_warnings: bool = False, dry_run: bool = True)

Publish the edition or collection belonging to the given URIs.

Also publish all aggregated objects (from aggregations/editions/collections)

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI of object to publish

  • ignore_warnings (bool) – try publishing even if warnings occured

  • dry_run (bool) – do not really publish, just check

Raises:

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

Returns:

HTTP response from service

Return type:

Response

publish_worldreadable(sid: str, textgrid_uri: str, ignore_warnings: bool = False, dry_run: bool = True)

Publish the technical object with given URI.

Worldreadable objects are some technical objects which may be published independently of editions or collections. Get a list of allowed mime types here: https://textgridlab.org/1.0/tgpublish/listWorldReadables

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI of object to publish

  • ignore_warnings (bool) – try publishing even if warnings occured

  • dry_run (bool) – do not really publish, just check

Raises:

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

Returns:

HTTP response from service

Return type:

Response

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

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

Returns:

Edition and work metadata for given object

from first matching parent edition

Return type:

SearchResponse

get_project_info(project_id: str, sid: str | None = None) → Dict

Get project information for a single project.

This includes portalconfig, readme.md, title, etc.

Parameters:

  • project_id (str) – the project ID

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

Returns:

JSON response from service - readme.md, portalconfig etc

Return type:

Dict

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

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

Returns:

A list of textgrid metadata entries

Return type:

SearchResponse

list_project_infos(sid: str | None = None) → Dict

Get project information for all projects.

This includes portalconfig, readme.md, title, etc.

Parameters:

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

Returns:

JSON response from service - readme.md, portalconfig etc

Return type:

Dict

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

Get objects belonging to a project.

These are 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

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: str | 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 (Optional[str]) – Lucene search string. Defaults to ‘*’.

  • sid (Optional[str]) – TextGrid SessionID from tgauth. Defaults to None.

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

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

  • start (Optional[str]) – result to start with. a number or the result from the last search results next attribute. number only works up to 10.000 hits.

  • limit (Optional[int]) – number of entries to return.. Defaults to 20.

  • kwic_width (Optional[int]) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (Optional[int]) – 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 (Optional[bool]) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

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

  • sandbox (Optional[bool]) – show sandboxed (not yet finally published) data. Defaults to false.

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

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

  • facet_limit (Optional[int]) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400

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

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

Returns:

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

from first matching parent edition

Return type:

Response

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

Get project information for a single project.

This includes portalconfig, readme.md, title, etc.

Parameters:

  • project_id (str) – the project ID

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

Returns:

HTTP response from service - readme.md, portalconfig etc

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

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

Returns:

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

Return type:

Response

list_project_infos(sid: str | None = None) → Response

Get project information for all projects.

This includes portalconfig, readme.md, title, etc.

Parameters:

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

Returns:

HTTP response from service - readme.md, portalconfig etc

Return type:

Response

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

Get objects belonging to a project.

These are 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

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: str | 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 (Optional[str]) – Lucene search string. Defaults to ‘*’.

  • sid (Optional[str]) – TextGrid SessionID from tgauth. Defaults to None.

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

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

  • start (Optional[str]) – result to start with. a number or the result from the last search results next attribute. number only works up to 10.000 hits.

  • limit (Optional[int]) – number of entries to return.. Defaults to 20.

  • kwic_width (Optional[int]) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (Optional[int]) – 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 (Optional[bool]) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

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

  • sandbox (Optional[bool]) – show sandboxed (not yet finally published) data. Defaults to false.

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

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

  • facet_limit (Optional[int]) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400

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

tgclients provide access to TextGrid services.

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 | 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 (Union[str, List[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 | List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as TEI corpus.

Parameters:

  • textgrid_uris (Union[str, List[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 | List[str], sid: str | None = None) → Response

Download aggregated TextGrid objects as plain text file.

Parameters:

  • textgrid_uris (Union[str, List[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 | 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 (Union[str, List[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 (Optional[bool]) – 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_ids(sid: str, name: str, mail: str, organisation: str)

Returns user records for a name or mail address.

Parameters:

  • sid (str) – SessionID of user that wants to query for names

  • name (str) – Name

  • mail (str) – E-Mail Address

  • organisation (str) – Organisation

Raises:

TextgridAuthException – in case of tgauth faults

Returns:

contains 0…n userDetails, which themselves have elements ePPN, name, mail,

organisation, agreesearch, usersupplieddata

Return type:

zeep.object.getIDsResponse

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

get_user_role(sid: str, project_id: str)

Returns ePPNs plus Array of Roles of all members in the project.

Caller must be member herself.

Parameters:

  • sid (str) – String, SessionID of user that wants to query for roles

  • project_id (str) – the project ID

Returns:

ePPNs plus Array of Roles of all members in project

Return type:

zeep.objects.getUserRoleResponse

list_all_projects() → List[str]

List all projects.

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[str]

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[str]

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

Remove an users 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

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

Remove an users editor role from 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

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

Remove an users manager role from 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

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

Remove an users observer role from 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

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 publish: str

The publish service location.

Returns:

the publish service location

Return type:

str

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: str | IO[Any], metadata: MetadataContainerType, uri: str | None = None) → MetadataContainerType

Create a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • data (Union[str, IO[Any]]) – the data

  • metadata (MetadataContainerType) – the metadata

  • uri (Optional[str]) – optionally set a TextGrid URI to use for new object (see get_uri method)

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

metadata for newly created object

Return type:

MetadataContainerType

create_revision(sid: str, project_id: str, textgrid_uri: str, data: str | IO[Any], metadata: MetadataContainerType) → MetadataContainerType

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – the data

  • metadata (MetadataContainerType) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

metadata from newly created object revision

Return type:

MetadataContainerType

get_uri(sid: str, how_many: int) → list

Get TextGrid URIs.

Get an specified amount of TextGrid URIs for assigning to new TextGrid objects. Useful e.g. for bulk imports.

Parameters:

  • sid (str) – Session ID

  • how_many (int) – number of URIs to generate

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

List with TextGrid URIs

Return type:

list

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

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: str | IO[Any], metadata: MetadataContainerType, create_revision: bool = False) → MetadataContainerType

Update a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – 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

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: str | IO[Any], metadata: str | IO[Any], uri: str | None = None) → Response

Create a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • data (Union[str, IO[Any]]) – the data

  • metadata (Union[str, IO[Any]]) – the metadata

  • uri (Optional[str]) – optionally set a TextGrid URI to use for new object (see get_uri method)

Raises:

TextgridCrudException – if HTTP status code >= 400

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: str | IO[Any], metadata: str | IO[Any]) → Response

Create a TextGrid object revision.

Parameters:

  • sid (str) – Session ID

  • project_id (str) – Project ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – the data

  • metadata (Union[str, IO[Any]]) – the metadata

Raises:

TextgridCrudException – if HTTP status code >= 400

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

Returns:

HTTP response from service

Return type:

Response

get_uri(sid: str, how_many: int) → Response

Get TextGrid URIs.

Get an specified amount of TextGrid URIs for assigning to new TextGrid objects. Useful e.g. for bulk imports.

Parameters:

  • sid (str) – Session ID

  • how_many (int) – number of URIs to generate

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

HTTP response from service with TextGrid URIs in body

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

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

Returns:

HTTP response from service

Return type:

Response

update_metadata(sid: str, textgrid_uri: str, metadata: str | IO[Any]) → Response

Update metadata for TextGrid object.

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • metadata (Union[str, IO[Any]]) – the metadata

Returns:

HTTP response from service with updated metadata

Return type:

Response

update_resource(sid: str, textgrid_uri: str, data: str | IO[Any], metadata: str | IO[Any], create_revision: bool = False) → Response

Update a TextGrid object.

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI

  • data (Union[str, IO[Any]]) – the data

  • metadata (Union[str, IO[Any]]) – the metadata

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

Raises:

TextgridCrudException – if HTTP status code >= 400

Returns:

HTTP response from service with updated metadata

Return type:

Response

class tgclients.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:

Optional[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.

This is made of title, textgrid-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.

This 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

Remove the ‘textgrid:’ prefix from an textgrid URI.

Parameters:

tguri (str) – the textgrid URI

Returns:

uri without the prefix

Return type:

str

searchresponse2object(xml: str) → Response

Build databinding for XML string returned from tgsearch.

Parameters:

xml (str) – xml string as returned from tgsearch

Returns:

tgsearch Response

Return type:

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

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

Bases: TextgridPublishRequest

Provide access to the Textgrid Publish Service using XML data binding.

API docs: https://textgridlab.org/doc/services/submodules/kolibri/kolibri-tgpublish-service/docs/index.html

copy(sid: str, textgrid_uris: List[str], project_id: str) → str

Copies the objects belonging to the given URIs to the given project ID.

Also copies all aggregated objects (from aggregations/editions/collections).

Parameters:

  • sid (str) – Session ID

  • textgrid_uris (List[str]) – Textgrid URIs of objects to copy

  • project_id (str) – Project ID of the project to copy the objects to.

Raises:

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

Returns:

UUID of copy job queued

Return type:

str

copy_to_new_revision(sid: str, textgrid_uris: List[str]) → str

Copies the objects belonging to the given URIs to new revisions of themselves.

Also copies all aggregated objects (from aggregations/editions/collections).

Parameters:

  • sid (str) – Session ID

  • textgrid_uris (List[str]) – Textgrid URIs of objects to copy

Raises:

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

Returns:

UUID of copy job queued

Return type:

str

get_status(job_id: str) → PublishResponse

Get status for job specified by job_id.

Parameters:

job_id (str) – ID of job to get the status for

Raises:

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

Returns:

publish response object

Return type:

PublishResponse

publish(sid: str, textgrid_uri: str, ignore_warnings: bool = False, dry_run: bool = True) → str

Publish the edition or collection belonging to the given URIs.

Also publish all aggregated objects (from aggregations/editions/collections)

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI of object to publish

  • ignore_warnings (bool) – try publishing even if warnings occured

  • dry_run (bool) – do not really publish, just check

Raises:

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

Returns:

just an OK if the job started

Return type:

str

publish_worldreadable(sid: str, textgrid_uri: str, ignore_warnings: bool = False, dry_run: bool = True) → str

Publish the technical object with given URI.

Worldreadable objects are some technical objects which may be published independently of editions or collections. Get a list of allowed mime types here: https://textgridlab.org/1.0/tgpublish/listWorldReadables

Parameters:

  • sid (str) – Session ID

  • textgrid_uri (str) – Textgrid URI of object to publish

  • ignore_warnings (bool) – try publishing even if warnings occured

  • dry_run (bool) – do not really publish, just check

Raises:

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

Returns:

just an OK if the job started

Return type:

str

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

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

Returns:

Edition and work metadata for given object

from first matching parent edition

Return type:

SearchResponse

get_project_info(project_id: str, sid: str | None = None) → Dict

Get project information for a single project.

This includes portalconfig, readme.md, title, etc.

Parameters:

  • project_id (str) – the project ID

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

Returns:

JSON response from service - readme.md, portalconfig etc

Return type:

Dict

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

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

Returns:

A list of textgrid metadata entries

Return type:

SearchResponse

list_project_infos(sid: str | None = None) → Dict

Get project information for all projects.

This includes portalconfig, readme.md, title, etc.

Parameters:

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

Returns:

JSON response from service - readme.md, portalconfig etc

Return type:

Dict

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

Get objects belonging to a project.

These are 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

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: str | 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 (Optional[str]) – Lucene search string. Defaults to ‘*’.

  • sid (Optional[str]) – TextGrid SessionID from tgauth. Defaults to None.

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

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

  • start (Optional[str]) – result to start with. a number or the result from the last search results next attribute. number only works up to 10.000 hits.

  • limit (Optional[int]) – number of entries to return.. Defaults to 20.

  • kwic_width (Optional[int]) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (Optional[int]) – 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 (Optional[bool]) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

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

  • sandbox (Optional[bool]) – show sandboxed (not yet finally published) data. Defaults to false.

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

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

  • facet_limit (Optional[int]) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400

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

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

Returns:

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

from first matching parent edition

Return type:

Response

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

Get project information for a single project.

This includes portalconfig, readme.md, title, etc.

Parameters:

  • project_id (str) – the project ID

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

Returns:

HTTP response from service - readme.md, portalconfig etc

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

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

Returns:

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

Return type:

Response

list_project_infos(sid: str | None = None) → Response

Get project information for all projects.

This includes portalconfig, readme.md, title, etc.

Parameters:

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

Returns:

HTTP response from service - readme.md, portalconfig etc

Return type:

Response

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

Get objects belonging to a project.

These are 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

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: str | 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 (Optional[str]) – Lucene search string. Defaults to ‘*’.

  • sid (Optional[str]) – TextGrid SessionID from tgauth. Defaults to None.

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

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

  • start (Optional[str]) – result to start with. a number or the result from the last search results next attribute. number only works up to 10.000 hits.

  • limit (Optional[int]) – number of entries to return.. Defaults to 20.

  • kwic_width (Optional[int]) – number of chars before and after a kwic match. Defaults to 40.

  • word_distance (Optional[int]) – 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 (Optional[bool]) – path of found result(work->edition->aggregations) should be applied to hit. Defaults to false.

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

  • sandbox (Optional[bool]) – show sandboxed (not yet finally published) data. Defaults to false.

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

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

  • facet_limit (Optional[int]) – number of results to return for each facet. Defaults to 10.

Raises:

TextgridSearchException – if HTTP status code >= 400

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