wkps package

Subpackages

• wkps.wio package
  • Submodules
  • wkps.wio.basewkpio module
  • wkps.wio.wannotationpro module
  • wkps.wio.wjson module
  • wkps.wio.wkpreadwrite module
  • Module contents

Submodules

wkps.filebase module

filename

sppas.src.wkps.filebase.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

Base class for a data structure of the workspace manager.

Define a base class to represent any kind of data with an id and a state and define the class to represent this latter.

class wkps.filebase.FileBase(identifier)

Bases: object

Represent any type of data with an identifier and a state.

__init__(identifier)

Constructor of a FileBase.

Data structure to store an identifier (str) and a state (States).

Parameters

identifier – (str) Any un-modifiable string.

Raises

ValueError if the identifier is not valid.

get_id()

Return the identifier (str).

get_state()

Return the state (States).

property id

Return the identifier (str).

match(functions, logic_bool='and')

Return True if this instance matches all or any of the functions.

Functions are defined in a comparator. They return a boolean. The type of the value depends on the function. The logical not is used to reverse the result of the function.

Parameters

• functions – list of (function, value, logical_not)

• logic_bool – (str) Apply a logical “and” or a logical “or” between the functions.

Returns

(bool)

set_state(value)

Set a state (to be overridden).

Parameters

value – (States) The state value to assign

Returns

(bool or list)

property state

Return the state (States).

static validate_id(identifier)

Return the given identifier if it matches the requirements.

An identifier should contain at least 2 characters.

Parameters

identifier – (str) Key to be validated

Raises

ValueError

Returns

(unicode)

class wkps.filebase.States

Bases: object

All states of any FileBase.

Example

>>>with States() as s: >>> print(s.UNUSED)

This class is a solution to mimic an ‘Enum’ but is compatible with both Python 2.7 and Python 3+.

__init__()

Create the dictionary.

wkps.filedatacompare module

filename

sppas.src.wkps.filedatacompare.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

Comparison classes to filter data structures of the workspace.

This file includes:

• sppasPathCompare() to search for a value in a path id (FilePath.id, FilePath.state, FilePath.expand)

• sppasRootCompare() to search for a value in a root id (FileRoot.id, FileRoot.state, FileRoot.expand)

• sppasNameCompare() to search for a value in a file name (FileName.name)

• sppasExtensionCompare() to search for a value in the extension of a file name (FileName.ext)

• sppassppasCatReferenceCompare()

• sppasRefAttributeCompare()

class wkps.filedatacompare.sppasFileBaseCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for any FileBase.

Example

Three different ways to compare a file data content to a given string

>>> tc = sppasFileBaseCompare()
>>> tc.exact(FilePath("c:\Users"), u("c:\Users"))
>>> tc.methods['exact'](FilePath("c:\Users"), u("c:\Users"))
>>> tc.get('exact')(FilePath("c:\Users"), u("c:\Users"))

__init__()

Create a sppasFileBaseCompare instance.

static check(fb, value)

Compare state member to the given value.

Parameters

• fb – (FileBase) Instance to compare.

• value – (bool) Boolean to be compared with.

Returns

(bool)

Raises

sppasTypeError

static contains(fb, value)

Test if fb contains the value.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static endswith(fb, value)

Test if fb ends with the characters of the value.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static exact(fb, value)

Test if fb strictly matches value.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static icontains(fb, value)

Case-insensitive contains.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iendswith(fb, value)

Case-insensitive endswith.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iexact(fb, value)

Test if fb matches value without case sensitive.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static istartswith(fb, value)

Case-insensitive startswith.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static lock(fb, value)

Compare state member to the given value.

Parameters

• fb – (FileBase) Instance to compare.

• value – (bool) Boolean to be compared with.

Returns

(bool)

Raises

sppasTypeError

static regexp(fb, pattern)

Test if text matches pattern.

Parameters

• fb – (FileBase) Instance to compare.

• pattern – (unicode) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static startswith(fb, value)

Test if fb starts with the characters of the value.

Parameters

• fb – (FileBase) Instance to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static state(fb, state)

class wkps.filedatacompare.sppasFileExtCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for FileName extension.

Example

Three different ways to compare a file data content to a given string

>>> tc = sppasFileExtCompare()
>>> tc.exact(FileName("oriana1"), u("oriana1"))
>>> tc.methods['exact'](FileName("oriana1"), u("oriana1"))
>>> tc.get('exact')(FileName("oriana1"), u("oriana1"))

__init__()

Create a sppasFileNameExtensionComparator instance.

static contains(fn, value)

Test if the name contains the value.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static endswith(fn, value)

Test if extension ends with the characters of the value.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static exact(fn, value)

Test if name strictly matches value.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static icontains(fn, value)

Case-insensitive contains.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iendswith(fn, value)

Case-insensitive endswith.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iexact(fn, value)

Test if extension matches value without case sensitive.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static istartswith(fn, value)

Case-insensitive startswith.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static regexp(fn, pattern)

Test if text matches pattern.

Parameters

• fn – (FileName)

• pattern – (unicode) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static startswith(fn, value)

Test if extension starts with the characters of the value.

Parameters

• fn – (FileName)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

class wkps.filedatacompare.sppasFileNameCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for FileName id.

Example

Three different ways to compare a file data content to a given string

>>> tc = sppasFileNameCompare()
>>> tc.exact(FileName("oriana1"), u("oriana1"))
>>> tc.methods['exact'](FileName("oriana1"), u("oriana1"))
>>> tc.get('exact')(FileName("oriana1"), u("oriana1"))

__init__()

Create a sppasRootCompare instance.

static contains(fn, value)

Test if the name contains the value.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static endswith(fn, value)

Test if name ends with the characters of the value.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static exact(fn, value)

Test if name strictly matches value.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static icontains(fn, value)

Case-insensitive contains.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iendswith(fn, value)

Case-insensitive endswith.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iexact(fn, value)

Test if name matches value without case sensitive.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static istartswith(fn, value)

Case-insensitive startswith.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static regexp(fn, pattern)

Test if text matches pattern.

Parameters

• fn – (FileName) Name to compare.

• pattern – (unicode) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static startswith(fn, value)

Test if name starts with the characters of the value.

Parameters

• fn – (FileName) Name to compare.

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

class wkps.filedatacompare.sppasFileRefCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for sppasCatReference id.

Example

Three different ways to compare a file data content to a given string

>>> tc = sppasFileRefCompare()
>>> tc.exact(sppasCatReference("mic"), u("mic"))
>>> tc.methods['exact'](sppasCatReference("mic"), u("mic"))
>>> tc.get('exact')(sppasCatReference("mic"), u("mic"))

__init__()

Create a sppasFileRefCompare instance.

static contains(cat, value)

Test if the id contains the value.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static endswith(cat, value)

Test if the id ends with the characters of the value.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static exact(cat, value)

Test if the id strictly matches value.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static icontains(cat, value)

Case-insensitive contains.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iendswith(cat, value)

Case-insensitive endswith.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iexact(cat, value)

Test if the id matches value without case sensitive.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static istartswith(cat, value)

Case-insensitive startswith.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static regexp(cat, pattern)

Test if id matches pattern.

Parameters

• cat – (sppasCatReference)

• pattern – (unicode) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static startswith(cat, value)

Test if the id starts with the characters of the value.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

class wkps.filedatacompare.sppasFileStateCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for state of a FileBase.

Author

Barthélémy Drabczuk

Organization

Laboratoire Parole et Langage, Aix-en-Provence, France

Contact

develop@sppas.org

License

GPL, v3

Copyright

Copyright (C) 2011-2020 Brigitte Bigi

Example

Three different ways to compare a file data content to a given string

>>> tc = sppasFileStateCompare()
>>> tc.state(FileName("oriana1"), States().UNUSED)
>>> tc.methods['state'](FileName("oriana1"), States().UNUSED)
>>> tc.get('state')(FileName("oriana1"), States().UNUSED)

__init__()

Create a sppasFileNameExtensionComparator instance.

static state(fb, state)

class wkps.filedatacompare.sppasRefAttributeCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for sppasRefAttribute.

__init__()

Create a sppassppasRefAttributeCompare instance.

static contains(att, value)

Test if the att contains the value.

Parameters

• att – (sppasRefAttribute)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static endswith(att, value)

Test if the att ends with the characters of the value.

Parameters

• att – (sppasRefAttribute)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static equals(att, value)

Test if att equals the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static exact(att, value)

Test if the attribute value strictly matches value.

Parameters

• att – (sppasRefAttribute)

• value – (str) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static fequals(att, value, precision=0.0)

Test if att equals the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

• precision – (number) Vagueness around the value

Returns

(bool)

Raises

sppasTypeError

static ge(att, value)

Test if att is greater than or equal to the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static gt(att, value)

Test if att is strictly greater than the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static icontains(att, value)

Case-insensitive contains.

Parameters

• att – (sppasRefAttribute)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iendswith(att, value)

Case-insensitive endswith.

Parameters

• cat – (sppasCatReference)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static iequals(att, value)

Test if att equals the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static iexact(att, value)

Test if the att matches value without case sensitive.

Parameters

• att – (sppasRefAttribute)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static istartswith(att, value)

Case-insensitive startswith.

Parameters

• att – (sppasRefAttribute)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

static le(att, value)

Test if att is less than or equal to the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static lt(att, value)

Test if att is less than the given value.

Parameters

• att – (sppasRefAttribute)

• value – (number) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static regexp(att, pattern)

Test if att matches pattern.

Parameters

• att – (sppasRefAttribute)

• pattern – (unicode) Pattern to search.

Returns

(bool)

Raises

sppasTypeError

static startswith(att, value)

Test if the att starts with the characters of the value.

Parameters

• att – (sppasRefAttribute)

• value – (unicode) Unicode string to be compared with.

Returns

(bool)

Raises

sppasTypeError

wkps.filedatafilters module

filename

sppas.src.wkps.filedatafilter.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

Filter system of the workspace.

A comparator must be implemented to define comparison functions. Then the method ‘match’ of the FileBase class can be invoked. The FileDataFilter() class is based on the use of this solution. It allows to combine results and is a simplified way to write a request. The use of the FileBase().match() is described in the next examples.

Example

Search if a FilePath() is exactly matching “my_path”:

>>> cmp = sppasFileBaseCompare()
>>> fp.match([(cmp.exact, "my_path", False)])

Example

Search if a FilePath() is starting with “my_path” and is checked:

>>> fp.match(
>>>     [(cmp.startswith, "my_path", False),
>>>      (cmp.state, True, False)],
>>>     logic_bool="and")

Example

Search if a FileRoot() is exactly matching “my_path/toto”:

>>> cmp = sppasFileBaseCompare()
>>> fr.match([(cmp.exact, "my_path", False)])

Example

Search if a FileRoot() is starting with “my_path/toto”

and is checked:

>>> fr.match(
>>>     [(cmp.startswith, "my_path/toto", False),
>>>      (cmp.state, True, False)],
>>>     logic_bool="and")

Example

Search if a FileName() is starting with “toto” and is not

a TextGrid and is checked:

>>> cmpn = sppasNameCompare()
>>> cmpe = sppasExtensionCompare()
>>> cmpp = sppasFileBaseCompare()
>>> fn.match(
>>>    [(cmpn.startswith, "toto", False),
>>>     (cmpe.iexact, "textgrid", True),
>>>     (cmpp.state, True, False)],
>>>    logic_bool="and")

class wkps.filedatafilters.sppasFileDataFilters(obj)

Bases: sppas.src.structs.basefilters.sppasBaseFilters

The ‘SPPAS file data filter system’.

Search in file data.

Example

>>> # Search for all checked TextGrid files in a path containing 'corpus'
>>> f = sppasFileDataFilters(data)
>>> f.path(contains='corpus') & f.file(state=True) & f.extension(iexact='textgrid')

__init__(obj)

Create a sppasFileDataFilters instance.

Parameters

obj – (sppasWorkspace) The object to be filtered.

att(**kwargs)

Apply functions on attributes of references of files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

The given value is a tuple with (identifier, value) of the attribute.

Example

>>> f.att(equals=("age", "14"))

Parameters

kwargs – logic_bool/any sppasAttCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

extension(**kwargs)

Apply functions on all extensions of the files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.extension(startswith=".TEXT", not_endswith='a', logic_bool="and")
>>> f.extension(startswith=".TEXT") & f.extension(not_endswith='a')
>>> f.extension(startswith=".TEXT") | f.extension(startswith="ta")

Parameters

kwargs – logic_bool/any sppasFileExtCompare() method.

Returns

(sppasDataSet)

file(**kwargs)

Apply functions on all files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Examples

>>> f.file(state=State().UNUSED)
>>> f.file(contains="dlg")

Parameters

kwargs – logic_bool/any sppasFileStateCompare() method.

Returns

(sppasDataSet)

name(**kwargs)

Apply functions on all names of the files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.name(iexact="myfile-phon", not_startswith='a', logic_bool="and")
>>> f.name(iexact="myfile-phon") & f.name(not_startswith='a')
>>> f.name(iexact="myfile-phon") | f.name(startswith="ta")

Parameters

kwargs – logic_bool/any sppasFileNameCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

path(**kwargs)

Apply functions on all paths of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.path(startswith="c:\users\myname", not_endswith='a', logic_bool="and")
>>> f.path(startswith="c:\users\myname") & f.path(not_endswith='a')
>>> f.path(startswith="c:\users\myname") | f.path(startswith="ta")

Parameters

kwargs – logic_bool/any sppasPathCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

ref(**kwargs)

Apply functions on all file properties of the object.

Return any fileroot for which at least one of its references is matching the filter.

Example

>>> f.ref(startswith="toto", endswith="tutu", logic_bool="and")
>>> f.ref(startswith="toto") & f.ref(endswith="tutu")
>>> f.ref(startswith="toto") | f.ref(contains="tutu")

Parameters

kwargs – logic_bool/any sppasFileStateCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

root(**kwargs)

Apply functions on all roots of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.root(startswith="myfile", not_endswith='a', logic_bool="and")
>>> f.root(startswith="myfile") & f.root(not_endswith='a')
>>> f.root(startswith="myfile") | f.root(startswith="ta")

Parameters

kwargs – logic_bool/any sppasRootCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

wkps.fileref module

filename

sppas.src.wkps.fileref.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

Data structures for the catalog of references of a workspace.

class wkps.fileref.sppasCatReference(identifier)

Bases: wkps.filebase.FileBase

Represent a reference in the catalogue of a workspace.

Reference is a dictionary with a name. Its keys are only alphanumerics characters spaced with underscores and its values are all sppasRefAttribute objects.

__init__(identifier)

Constructor of the sppasCatReference class.

Parameters

identifier – (str) identifier for the object, the name of the reference

add(identifier, value=None, att_type=None, descr=None)

Append an attribute into the reference.

Parameters

• identifier – (str) Id of a sppasRefAttribute

• value – (any type)

• att_type – (str) One of ‘str’, ‘bool’, ‘int’, ‘float’. Default is ‘str’.

• descr – (str) A text to describe the attribute

Raise

AttributeIdValueError

append(att)

Append an attribute into a reference.

Parameters

att – (sppasRefAttribute)

att(identifier)

Return the attribute matching the given identifier or None.

Parameters

identifier – (str) Id of a sppasRefAttribute

Returns

sppasRefAttribute or None if the identifier does not match

any attribute of this reference.

get_type()

Returns the type of the Reference.

pop(identifier)

Delete an attribute of this reference.

Parameters

identifier – (str, sppasRefAttribute) the attribute or its id to delete

set_state(state)

Set the current state to a new one.

Parameters

state – (State)

:raises (sppasTypeError)

set_type(ann_type)

Set the type of the Reference within the authorized ones.

Parameters

ann_type – (int) One of the annots.types

Raise

sppasIndexError, sppasTypeError

class wkps.fileref.sppasRefAttribute(identifier, value=None, att_type=None, descr=None)

Bases: object

Represent any attribute with an id, a value, and a description.

VALUE_TYPES = ('str', 'int', 'float', 'bool')

__init__(identifier, value=None, att_type=None, descr=None)

Constructor of sppasRefAttribute.

Parameters

• identifier – (str) The identifier of the attribute

• value – (str) String representing the value of the attribute

• att_type – (str) One of the VALUE_TYPES

• descr – (str) A string to describe what the attribute is

Raises

AttributeIdValueError

get_description()

Return current description of the attribute.

Returns

(str)

get_id()

Return the identifier of the attribute.

get_typed_value()

Return the current typed value.

Returns

(any type) the current typed value.

get_value()

Return the current non-typed value.

Returns

(str)

get_value_type()

Return the current type of the value.

Returns

(str) Either: “str”, “int”, “float”, “bool”.

property id

Return the identifier of the attribute.

set_description(description)

Set a new description of the attribute.

Parameters

description – (str)

set_value(value)

Set a new value.

Parameters

value – (str)

set_value_type(type_name)

Set a new type for the current value.

Parameters

type_name – (str) the new type name

Raises

sppasTypeError

static validate(identifier)

Return True if the given identifier matches the requirements.

An id should contain between 3 and 12 ASCII-characters only, i.e. letters a-z, letters A-Z and numbers 0-9.

Parameters

identifier – (str) Key to be validated

Returns

(bool)

wkps.filestructure module

filename

sppas.src.wkps.filestructure.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

Data structures for paths, roots and files.

class wkps.filestructure.FileName(identifier)

Bases: wkps.filebase.FileBase

Represent the data structure of a file.

FILENAME_STATES = (0, 1, 2, -1)

__init__(identifier)

Constructor of a FileName.

From the identifier, the following properties are extracted:

1. name (str) The base name of the file, without path nor ext

2. extension (str) The extension of the file, or the mime type

3. date (str) Time of the last modification

4. size (str) Size of the file

5. state (int) State of the file

Parameters

identifier – (str) Full name of a file

property date

Return a string representing the date of the last modification.

property extension

Return the extension of the file in upper-cases (str).

folder()

Return the name of the directory of this file (str).

get_date()

Return a string representing the date of the last modification.

get_extension()

Return the extension of the file in upper-cases (str).

get_mime()

Return the mime type of the file (str).

get_name()

Return the short name of the file (str).

The name is the filename without path nor extension.

get_size()

Return a string representing the size of the file.

property name

Return the short name of the file (str).

The name is the filename without path nor extension.

set_state(value)

Override. Set a state value to this filename.

A LOCKED file can only be unlocked by assigning the CHECKED state. No other state than MISSING can be assigned if the file does not exists.

Parameters

value – (States)

Returns

(bool) this filename state has changed or not

property size

Return a string representing the size of the file.

update_properties()

Update properties of the file (modified date and file size).

Returns

(bool) true if properties were changed

class wkps.filestructure.FilePath(filepath)

Bases: wkps.filebase.FileBase

Represent the data linked to a folder name.

Use instances of this class to hold data related to the path of a filename. Items in the tree will get associated back to the corresponding FileName and this FilePath object.

__init__(filepath)

Constructor of a FilePath.

Parameters

filepath – (str) Absolute or relative name of a folder

Raises

PathTypeError

append(entry, all_root=False, ctime=0.0)

Append a filename in the list of files.

Given filename can be either an absolute or relative name of a file or an instance of FileName. It can also be an instance of FileRoot.

Only an existing file can be added if the given entry is the name of the file. But any FileName() instance can be added, even if the file does not exists (of course, its path must match with this fp).

Parameters

• entry – (str, FileName, FileRoot) Absolute or relative name of a file

• all_root – (bool) Add also all files sharing the same root as the given one, or all files of the given root

• ctime – (float) Add files only if created/modified after time in seconds since the epoch

Returns

(FileName, FileRoot) the list of appended objects or None

Raises

FileOSError if entry is a non-existing filename. Exception if given entry does not math the path.

get_object(filename)

Return the instance matching the given entry.

Parameters

filename – Name of a file or a root (absolute of relative)

Notice that it returns ‘self’ if filename is a directory matching self.id.

get_root(name)

Return the FileRoot matching the given id (root or file).

Parameters

name – (str) Identifier name of a root or a file.

Returns

FileRoot or None

identifier(filename)

Return the identifier, i.e. the full name of an existing file.

Parameters

filename – (str) Absolute or relative name of a file

Returns

(str) Identifier for this filename

Raise

FileOSError if filename does not match a regular file

remove(entry)

Remove a root entry of the list of roots.

Given entry can be either the identifier of a root or an instance of FileRoot.

TODO: REMOVE IF ENTRY is FILENAME

Parameters

entry –

Returns

(identifier) Identifier of the removed entry or None

set_object_state(value, entry)

Set a state value to a filename of this filepath.

It is not allowed to manually assign one of the “AT_LEAST” states. They are automatically fixed here depending on the roots states.

Parameters

• value – (int) A state.

• entry – (FileName, FileRoot) The instance to change state

Raises

sppasTypeError, sppasOSError, sppasValueError

set_state(value)

Set a value to represent the state of the path.

It is not allowed to manually assign one of the “AT_LEAST” states (they are automatically fixed by setting the state of a FileName with set_object_state method).

The state of LOCKED files is not changed.

Parameters

value – (State) A state of FileName.

unlock()

Unlock all.

Returns

number of unlocked filenames

update_state()

Modify state depending on the checked root names.

The state is missing if the path is not existing on disk. Else, the state of a path is assigned as it:

• locked if all roots are locked,

• at_least_one_locked if at least one of its roots is locked,

• checked if all roots are checked,

• at_least_one_checked if at least one of its roots is checked and none of the others are locked,

• unused if none of its roots are neither locked, checked nor missing.

Returns

(bool) State was changed or not.

class wkps.filestructure.FileRoot(name)

Bases: wkps.filebase.FileBase

Represent the data linked to the basename of a file.

Use instances of this class to hold data related to the root of a file. The root of a file is its name without the pattern nor the extension.

__init__(name)

Constructor of a FileRoot.

Parameters

name – (str) Filename or root name

add_ref(ref)

Associate a new reference to the root.

Parameters

ref – (sppasReference)

Returns

(bool)

append(filename, all_root=False, ctime=0.0)

Append a filename in the list of files.

‘filename’ must be the absolute name of a file or an instance of FileName.

Parameters

• filename – (str, FileName) Absolute name of a file

• all_root – (bool) Add all files sharing the same root

• ctime – (float) Add files only if created/modified after time in seconds since the epoch

Returns

(list of FileName) the appended FileName() instances or None

get_object(filename)

Return the instance matching the given filename.

Return self if filename is matching the id.

Parameters

filename – Full name of a file

Returns

(FileName of None)

get_references()

Return the list of references of the catalog.

Returns

(list)

has_ref(ref)

Return True if the root contains the given reference.

Parameters

ref – (sppasReference)

Returns

(bool)

static pattern(filename)

Return the pattern of the given filename.

A pattern is the end of the filename, after the ‘-‘. It can’t contain ‘_’ and must be between 1 and 12 characters (not including the ‘-‘).

Notice that the ‘_’ can’t be supported (too many side effects).

Parameters

filename – (str) Name of a file (absolute or relative)

Returns

(str) Root pattern or an empty string if no pattern is detected

property references

Return the list of references of the catalog.

Returns

(list)

remove(filename)

Remove a filename of the list of files.

Given filename must be the absolute name of a file or an instance of FileName.

Parameters

filename – (str, FileName) Absolute name of a file

Returns

(identifier) Identifier of the removed FileName or None if nothing removed.

remove_ref(ref)

Remove a reference to unlink it to this root.

Parameters

ref – (sppasReference)

Returns

(bool)

static root(filename)

Return the root of the given filename.

Parameters

filename – (str) Name of a file (absolute or relative)

Returns

(str) Root

set_object_state(value, filename)

Set a state value to a filename of this fileroot.

Parameters

• value – (int) A state of FileName.

• filename – (FileName) The instance to change state

Returns

(list) Modified instances

Raises

sppasTypeError

set_references(list_of_references)

Fix the list of references.

The current list is overridden.

Parameters

list_of_references – (list)

Raises

sppasTypeError

set_state(value)

Set a value to represent the state of this root.

It is not allowed to manually assign one of the “AT_LEAST” states (they are automatically fixed by setting the state of a FileName with set_object_state method).

The state of LOCKED files can’t be changed with this method. Use set_object_state() instead.

Parameters

value – (State) A state of FileName.

Returns

(list) Modified instances

update_state()

Update the state depending on the checked and locked filenames.

The state of a root is assigned as it:

• locked if all files are locked,

• at_least_one_locked if at least one of its filenames is locked,

• checked if all filenames are checked,

• at_least_one_checked if at least one of its filenames is checked and none of the others are locked,

• missing if at least one of its filenames is missing and none of the others are locked nor checked,

• missing if all its filenames are missing,

• unused if none of its filenames are neither locked nor checked.

Returns

(bool) State is changed or not

wkps.sppasWkps module

filename

sppas.src.wkps.sppaswkps.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Management of the workspace files of the application.

class wkps.sppasWkps.sppasWkps

Bases: object

Manage the set of workspaces.

A workspace is made of:

• a file in which data are saved and loaded when needed;

• a name, matching the filename without path nor extension.

__init__()

Create a sppasWkps instance.

Load the list of existing wjson file names of the workspaces folder of the software.

check_filename(index)

Get the filename of the workspace at the given index.

Parameters

index – (int) Index of the workspace

Returns

(str) name of the file

Raises

IndexError, OSError

delete(index)

Delete the workspace with the given index.

Parameters

index – (int) Index of the workspace

Raises

IndexError

export_to_file(index, filename)

Save an existing workspace into an external file.

Override filename if the file already exists.

Parameters

• index – (int) Index of the workspace to save data in

• filename – (str)

Raises

IOError

import_from_file(filename)

Import and append an external workspace.

Parameters

filename – (str)

Returns

The real name used to save the workspace

index(name)

Return the index of the workspace with the given name.

Parameters

name – (str)

Returns

(int)

Raises

ValueError

load_data(index)

Return the data of the workspace at the given index.

Parameters

index – (int) Index of the workspace

Returns

(str) sppasWorkspace()

Raises

IndexError

new(name)

Create and append a new empty workspace.

Parameters

name – (str) Name of the workspace to create.

Returns

The real name used to save the workspace

Raises

IOError, ValueError

rename(index, new_name)

Set a new name to the workspace at the given index.

Parameters

• index – (int) Index of the workspace

• new_name – (str) New name of the workspace

Returns

(str)

Raises

IndexError, OSError

save_data(data, index=- 1)

Save data into a workspace.

The data can already match an existing workspace or a new workspace is created. Raises indexerror if is attempted to save the ‘Blank’ workspace.

Parameters

• data – (sppasWorkspace) Data of a workspace to save

• index – (int) Index of the workspace to save data in

Returns

The real name used to save the workspace

Raises

IOError, IndexError

set_workspaces()

Fix the list of existing workspaces in the software.

Reset the current list of workspaces.

wkps.wkpexc module

filename

sppas.src.wkps.wkpexc.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

Exceptions for the workspace manager.

exception wkps.wkpexc.AttributeIdValueError(ident)

Bases: ValueError

:ERROR 9062:.

Identifier ‘{ident}’ is not valid. It should be between 2 and 12 ASCII-characters.

__init__(ident)

exception wkps.wkpexc.AttributeTypeValueError(value, vtype)

Bases: ValueError

:ERROR 9064:.

Attribute value ‘{value}’ can’t be converted into type ‘{type}’.

__init__(value, vtype)

exception wkps.wkpexc.FileAddValueError(name)

Bases: ValueError

:ERROR 9034:.

‘{:s}’ cant be added because it already exists in the list.

__init__(name)

exception wkps.wkpexc.FileAttributeError(classname, method)

Bases: AttributeError

:ERROR 9020:.

{:s} has no attribute ‘{:s}’

__init__(classname, method)

exception wkps.wkpexc.FileIdValueError

Bases: ValueError

:ERROR 9060:.

An identifier must contain at least 2 characters.

__init__()

exception wkps.wkpexc.FileLockedError(filename)

Bases: OSError

:ERROR 9040:.

‘{!s:s}’ is locked.’

__init__(filename)

exception wkps.wkpexc.FileOSError(name)

Bases: OSError

:ERROR 9010:.

Name {!s:s} does not match a file or a directory.

__init__(name)

exception wkps.wkpexc.FileRemoveValueError(name)

Bases: ValueError

:ERROR 9036:.

‘{:s}’ cant be removed because it is not existing in the list.

__init__(name)

exception wkps.wkpexc.FileRootValueError(filename, rootname)

Bases: ValueError

:ERROR 9030:.

‘{:s}’ does not match root ‘{:s}’

__init__(filename, rootname)

exception wkps.wkpexc.FileTypeError(name)

Bases: TypeError

:ERROR 9012:.

Name {!s:s} does not match a valid file.

__init__(name)

exception wkps.wkpexc.FilesMatchingValueError(name1, name2)

Bases: ValueError

:ERROR 9032:.

‘{:s}’ does not match with ‘{:s}’

__init__(name1, name2)

exception wkps.wkpexc.PathTypeError(name)

Bases: TypeError

:ERROR 9014:.

Name {!s:s} does not match a valid directory.

__init__(name)

exception wkps.wkpexc.WkpDeleteBlankError

Bases: IndexError

:ERROR 9182:.

It is not allowed to delete the Blank workspace.

__init__()

exception wkps.wkpexc.WkpExportBlankError

Bases: IndexError

:ERROR 9180:.

It is not allowed to export the Blank workspace.

__init__()

exception wkps.wkpexc.WkpExportValueError(name)

Bases: ValueError

:ERROR 9162:.

It is not allowed to export a workspace with the same name ‘{:s}’.

__init__(name)

exception wkps.wkpexc.WkpExtensionError(ext)

Bases: OSError

:ERROR 9110:.

Unknown extension for a workspace ‘{:s}’.

__init__(ext)

exception wkps.wkpexc.WkpFileError(ext)

Bases: OSError

:ERROR 9120:.

No workspace file is matching the workspace name ‘{:s}’.

__init__(ext)

exception wkps.wkpexc.WkpIdValueError(name)

Bases: ValueError

:ERROR 9160:.

A workspace with name {:s} is already existing.

__init__(name)

exception wkps.wkpexc.WkpNameError(name)

Bases: ValueError

:ERROR 9164:.

Workspace with name ‘{:s}’ was not found.

__init__(name)

exception wkps.wkpexc.WkpRenameBlankError

Bases: IndexError

:ERROR 9184:.

It is not allowed to rename the Blank workspace.

__init__()

exception wkps.wkpexc.WkpSaveBlankError

Bases: IndexError

:ERROR 9186:.

It is not allowed to save the Blank workspace.

__init__()

wkps.workspace module

filename

sppas.src.wkps.workspace.py

author

Barthélémy Drabczuk, Brigitte Bigi

contact

develop@sppas.org

summary

The application workspace manager.

Description:

Use instances of these classes to hold data related to filenames and references.

Files are structured in a fixed tree-like structure:

• a sppasWorkspace contains a list of FilePath,

• a FilePath contains a list of FileRoot,

• a FileRoot contains a list of FileName,

• a FileName is limited to regular file names (no links, etc).

References are structured as:

• a sppasWorkspace contains a list of sppasCatReference,

• a sppasCatReference contains a list of sppasRefAttribute.

Example:

The file ‘C:UsersMyNameDesktopmyfile.pdf’ and the file ‘C:UsersMyNameDesktopmyfile.txt’ will be in the following tree:

• sppasWorkspace:

  • FilePath: id=’C:UsersMyNameDesktop’

    • FileRoot: id=’C:UsersMyNameDesktopmyfile’

      • FileName:

        • id=’C:UsersMyNameDesktopmyfile.pdf’

        • name=’myfile’

        • extension=’.PDF’

      • FileName:

        • id=’C:UsersMyNameDesktopmyfile.txt’

        • name=’myfile’

        • extension=’.TXT’

Raised exceptions:

• FileOSError (error 9010)

• FileTypeError (error 9012)

• PathTypeError (error 9014)

• FileRootValueError (error 9030)

class wkps.workspace.sppasWorkspace(identifier='c80f7746-a3cf-4925-90b8-4381c477008b')

Bases: object

Represent the data linked to a list of files and a list of references.

sppasWorkspace is the container for a list of files and a catalog. It organizes files hierarchically as a collection of FilePath instances, each of which is a collection of FileRoot instances, each of which is a collection of FileName. The catalog is a list of sppasCatReference instances each of which is a list of key/att-value.

__init__(identifier='c80f7746-a3cf-4925-90b8-4381c477008b')

Constructor of a sppasWorkspace.

Parameters

identifier – (str)

add(file_object)

Add an object into the data.

IMPLEMENTED ONLY FOR paths and references.

Parameters

file_object – (FileBase)

Raises

sppasTypeError, FileAddValueError, NotImplementedError

add_file(filename, brothers=False, ctime=0.0)

Add file(s) in the list from a file name.

Parameters

• filename – (str) Absolute or relative name of a file

• brothers – (bool) Add also all files sharing the same root as the given file

• ctime – (float) Add files only if created/modified after time in seconds since the epoch

Returns

(list of FileBase or None) List of added objects

Raises

OSError

add_ref(ref)

Add a reference in the list from its file name.

Parameters

ref – (sppasCatReference) Reference to add

Raises

sppasTypeError, FileAddValueError

associate()

dissociate()

get_filename_from_state(state)

Return every FileName in the given state.

get_filepath_from_state(state)

Return every FilePath of the given state.

get_fileroot_from_state(state)

Return every FileRoot in the given state.

get_fileroot_with_ref(ref)

Return every FileRoot with the given reference.

get_id()

Return the identifier of the workspace (str).

get_object(identifier)

Return the file object matching the given identifier.

Parameters

identifier – (str)

Returns

(sppasWorkspace, FilePath, FileRoot, FileName, sppasCatReference)

get_parent(filebase)

Return the parent of an object.

Parameters

filebase – (FileName or FileRoot).

Returns

(FileRoot or FilePath)

Raises

sppasTypeError

get_paths()

Return all the stored paths.

Returns

(list of FilePath)

get_reference_from_state(state)

Return every Reference in the given state.

get_refs()

Return the list of references.

has_locked_files()

property id

Return the identifier of the workspace (str).

is_empty()

Return if the instance contains information.

property paths

Return all the stored paths.

Returns

(list of FilePath)

property refs

Return the list of references.

remove_empties()

Remove paths and roots without files.

remove_file(filename)

Remove a file in the list from its file name.

Its root and path are also removed if empties, or their state is updated.

Parameters

filename – (str) Absolute or relative name of a file

Returns

(list) Identifiers of removed objects

Raises

OSError

remove_files(state=1)

Remove all files of the given state.

Do not remove empty roots or paths.

Parameters

state – (States)

Returns

(int)

remove_refs(state=1)

Remove all references of the given state.

Parameters

state – (States)

Returns

(int) Number of removed refs

set_object_state(state, file_obj=None)

Set the state of any or all FileBase within sppasWorkspace.

The default case is to set the state to all FilePath and FileRefence.

It is not allowed to manually assign one of the “AT_LEAST” states. They are automatically fixed depending on the paths states.

Parameters

• state – (States) state to set the file to

• file_obj – (FileBase) the specific file to set the state to. None to set all files

Raises

sppasTypeError, sppasValueError

Returns

list of modified objects

set_state(value)

Set the state of this sppasWorkspace instance.

Parameters

value – (States)

unlock(entries=None)

Unlock the given list of files.

Parameters

entries – (list, None) List of FileName to unlock

Returns

number of unlocked entries

update()

Update the data: missing files, properties changed.

Empty FileRoot and FilePath are removed.

Module contents

filename

sppas.src.wkps.__init__.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

The application workspace manager.

wkps: management of files into workspaces

Description:

This package includes classes to manage a bunch of files organized into workspaces. A workspace is made of data related to the file names and a list of references to make relations between file roots.

Requires the following other packages:

• config

• structs

and globals: paths, sppasIndexError.

Contributors:

• Barthélémy Drabczuk

• Laurent Vouriot

class wkps.FileBase(identifier)

Bases: object

Represent any type of data with an identifier and a state.

__init__(identifier)

Constructor of a FileBase.

Data structure to store an identifier (str) and a state (States).

Parameters

identifier – (str) Any un-modifiable string.

Raises

ValueError if the identifier is not valid.

get_id()

Return the identifier (str).

get_state()

Return the state (States).

property id

Return the identifier (str).

match(functions, logic_bool='and')

Return True if this instance matches all or any of the functions.

Functions are defined in a comparator. They return a boolean. The type of the value depends on the function. The logical not is used to reverse the result of the function.

Parameters

• functions – list of (function, value, logical_not)

• logic_bool – (str) Apply a logical “and” or a logical “or” between the functions.

Returns

(bool)

set_state(value)

Set a state (to be overridden).

Parameters

value – (States) The state value to assign

Returns

(bool or list)

property state

Return the state (States).

static validate_id(identifier)

Return the given identifier if it matches the requirements.

An identifier should contain at least 2 characters.

Parameters

identifier – (str) Key to be validated

Raises

ValueError

Returns

(unicode)

class wkps.FileName(identifier)

Bases: wkps.filebase.FileBase

Represent the data structure of a file.

FILENAME_STATES = (0, 1, 2, -1)

__init__(identifier)

Constructor of a FileName.

From the identifier, the following properties are extracted:

1. name (str) The base name of the file, without path nor ext

2. extension (str) The extension of the file, or the mime type

3. date (str) Time of the last modification

4. size (str) Size of the file

5. state (int) State of the file

Parameters

identifier – (str) Full name of a file

property date

Return a string representing the date of the last modification.

property extension

Return the extension of the file in upper-cases (str).

folder()

Return the name of the directory of this file (str).

get_date()

Return a string representing the date of the last modification.

get_extension()

Return the extension of the file in upper-cases (str).

get_mime()

Return the mime type of the file (str).

get_name()

Return the short name of the file (str).

The name is the filename without path nor extension.

get_size()

Return a string representing the size of the file.

property name

Return the short name of the file (str).

The name is the filename without path nor extension.

set_state(value)

Override. Set a state value to this filename.

A LOCKED file can only be unlocked by assigning the CHECKED state. No other state than MISSING can be assigned if the file does not exists.

Parameters

value – (States)

Returns

(bool) this filename state has changed or not

property size

Return a string representing the size of the file.

update_properties()

Update properties of the file (modified date and file size).

Returns

(bool) true if properties were changed

class wkps.FilePath(filepath)

Bases: wkps.filebase.FileBase

Represent the data linked to a folder name.

Use instances of this class to hold data related to the path of a filename. Items in the tree will get associated back to the corresponding FileName and this FilePath object.

__init__(filepath)

Constructor of a FilePath.

Parameters

filepath – (str) Absolute or relative name of a folder

Raises

PathTypeError

append(entry, all_root=False, ctime=0.0)

Append a filename in the list of files.

Given filename can be either an absolute or relative name of a file or an instance of FileName. It can also be an instance of FileRoot.

Only an existing file can be added if the given entry is the name of the file. But any FileName() instance can be added, even if the file does not exists (of course, its path must match with this fp).

Parameters

• entry – (str, FileName, FileRoot) Absolute or relative name of a file

• all_root – (bool) Add also all files sharing the same root as the given one, or all files of the given root

• ctime – (float) Add files only if created/modified after time in seconds since the epoch

Returns

(FileName, FileRoot) the list of appended objects or None

Raises

FileOSError if entry is a non-existing filename. Exception if given entry does not math the path.

get_object(filename)

Return the instance matching the given entry.

Parameters

filename – Name of a file or a root (absolute of relative)

Notice that it returns ‘self’ if filename is a directory matching self.id.

get_root(name)

Return the FileRoot matching the given id (root or file).

Parameters

name – (str) Identifier name of a root or a file.

Returns

FileRoot or None

identifier(filename)

Return the identifier, i.e. the full name of an existing file.

Parameters

filename – (str) Absolute or relative name of a file

Returns

(str) Identifier for this filename

Raise

FileOSError if filename does not match a regular file

remove(entry)

Remove a root entry of the list of roots.

Given entry can be either the identifier of a root or an instance of FileRoot.

TODO: REMOVE IF ENTRY is FILENAME

Parameters

entry –

Returns

(identifier) Identifier of the removed entry or None

set_object_state(value, entry)

Set a state value to a filename of this filepath.

It is not allowed to manually assign one of the “AT_LEAST” states. They are automatically fixed here depending on the roots states.

Parameters

• value – (int) A state.

• entry – (FileName, FileRoot) The instance to change state

Raises

sppasTypeError, sppasOSError, sppasValueError

set_state(value)

Set a value to represent the state of the path.

It is not allowed to manually assign one of the “AT_LEAST” states (they are automatically fixed by setting the state of a FileName with set_object_state method).

The state of LOCKED files is not changed.

Parameters

value – (State) A state of FileName.

unlock()

Unlock all.

Returns

number of unlocked filenames

update_state()

Modify state depending on the checked root names.

The state is missing if the path is not existing on disk. Else, the state of a path is assigned as it:

• locked if all roots are locked,

• at_least_one_locked if at least one of its roots is locked,

• checked if all roots are checked,

• at_least_one_checked if at least one of its roots is checked and none of the others are locked,

• unused if none of its roots are neither locked, checked nor missing.

Returns

(bool) State was changed or not.

class wkps.FileRoot(name)

Bases: wkps.filebase.FileBase

Represent the data linked to the basename of a file.

Use instances of this class to hold data related to the root of a file. The root of a file is its name without the pattern nor the extension.

__init__(name)

Constructor of a FileRoot.

Parameters

name – (str) Filename or root name

add_ref(ref)

Associate a new reference to the root.

Parameters

ref – (sppasReference)

Returns

(bool)

append(filename, all_root=False, ctime=0.0)

Append a filename in the list of files.

‘filename’ must be the absolute name of a file or an instance of FileName.

Parameters

• filename – (str, FileName) Absolute name of a file

• all_root – (bool) Add all files sharing the same root

• ctime – (float) Add files only if created/modified after time in seconds since the epoch

Returns

(list of FileName) the appended FileName() instances or None

get_object(filename)

Return the instance matching the given filename.

Return self if filename is matching the id.

Parameters

filename – Full name of a file

Returns

(FileName of None)

get_references()

Return the list of references of the catalog.

Returns

(list)

has_ref(ref)

Return True if the root contains the given reference.

Parameters

ref – (sppasReference)

Returns

(bool)

static pattern(filename)

Return the pattern of the given filename.

A pattern is the end of the filename, after the ‘-‘. It can’t contain ‘_’ and must be between 1 and 12 characters (not including the ‘-‘).

Notice that the ‘_’ can’t be supported (too many side effects).

Parameters

filename – (str) Name of a file (absolute or relative)

Returns

(str) Root pattern or an empty string if no pattern is detected

property references

Return the list of references of the catalog.

Returns

(list)

remove(filename)

Remove a filename of the list of files.

Given filename must be the absolute name of a file or an instance of FileName.

Parameters

filename – (str, FileName) Absolute name of a file

Returns

(identifier) Identifier of the removed FileName or None if nothing removed.

remove_ref(ref)

Remove a reference to unlink it to this root.

Parameters

ref – (sppasReference)

Returns

(bool)

static root(filename)

Return the root of the given filename.

Parameters

filename – (str) Name of a file (absolute or relative)

Returns

(str) Root

set_object_state(value, filename)

Set a state value to a filename of this fileroot.

Parameters

• value – (int) A state of FileName.

• filename – (FileName) The instance to change state

Returns

(list) Modified instances

Raises

sppasTypeError

set_references(list_of_references)

Fix the list of references.

The current list is overridden.

Parameters

list_of_references – (list)

Raises

sppasTypeError

set_state(value)

Set a value to represent the state of this root.

It is not allowed to manually assign one of the “AT_LEAST” states (they are automatically fixed by setting the state of a FileName with set_object_state method).

The state of LOCKED files can’t be changed with this method. Use set_object_state() instead.

Parameters

value – (State) A state of FileName.

Returns

(list) Modified instances

update_state()

Update the state depending on the checked and locked filenames.

The state of a root is assigned as it:

• locked if all files are locked,

• at_least_one_locked if at least one of its filenames is locked,

• checked if all filenames are checked,

• at_least_one_checked if at least one of its filenames is checked and none of the others are locked,

• missing if at least one of its filenames is missing and none of the others are locked nor checked,

• missing if all its filenames are missing,

• unused if none of its filenames are neither locked nor checked.

Returns

(bool) State is changed or not

class wkps.States

Bases: object

All states of any FileBase.

Example

>>>with States() as s: >>> print(s.UNUSED)

This class is a solution to mimic an ‘Enum’ but is compatible with both Python 2.7 and Python 3+.

__init__()

Create the dictionary.

class wkps.sppasCatReference(identifier)

Bases: wkps.filebase.FileBase

Represent a reference in the catalogue of a workspace.

Reference is a dictionary with a name. Its keys are only alphanumerics characters spaced with underscores and its values are all sppasRefAttribute objects.

__init__(identifier)

Constructor of the sppasCatReference class.

Parameters

identifier – (str) identifier for the object, the name of the reference

add(identifier, value=None, att_type=None, descr=None)

Append an attribute into the reference.

Parameters

• identifier – (str) Id of a sppasRefAttribute

• value – (any type)

• att_type – (str) One of ‘str’, ‘bool’, ‘int’, ‘float’. Default is ‘str’.

• descr – (str) A text to describe the attribute

Raise

AttributeIdValueError

append(att)

Append an attribute into a reference.

Parameters

att – (sppasRefAttribute)

att(identifier)

Return the attribute matching the given identifier or None.

Parameters

identifier – (str) Id of a sppasRefAttribute

Returns

sppasRefAttribute or None if the identifier does not match

any attribute of this reference.

get_type()

Returns the type of the Reference.

pop(identifier)

Delete an attribute of this reference.

Parameters

identifier – (str, sppasRefAttribute) the attribute or its id to delete

set_state(state)

Set the current state to a new one.

Parameters

state – (State)

:raises (sppasTypeError)

set_type(ann_type)

Set the type of the Reference within the authorized ones.

Parameters

ann_type – (int) One of the annots.types

Raise

sppasIndexError, sppasTypeError

class wkps.sppasFileDataFilters(obj)

Bases: sppas.src.structs.basefilters.sppasBaseFilters

The ‘SPPAS file data filter system’.

Search in file data.

Example

>>> # Search for all checked TextGrid files in a path containing 'corpus'
>>> f = sppasFileDataFilters(data)
>>> f.path(contains='corpus') & f.file(state=True) & f.extension(iexact='textgrid')

__init__(obj)

Create a sppasFileDataFilters instance.

Parameters

obj – (sppasWorkspace) The object to be filtered.

att(**kwargs)

Apply functions on attributes of references of files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

The given value is a tuple with (identifier, value) of the attribute.

Example

>>> f.att(equals=("age", "14"))

Parameters

kwargs – logic_bool/any sppasAttCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

extension(**kwargs)

Apply functions on all extensions of the files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.extension(startswith=".TEXT", not_endswith='a', logic_bool="and")
>>> f.extension(startswith=".TEXT") & f.extension(not_endswith='a')
>>> f.extension(startswith=".TEXT") | f.extension(startswith="ta")

Parameters

kwargs – logic_bool/any sppasFileExtCompare() method.

Returns

(sppasDataSet)

file(**kwargs)

Apply functions on all files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Examples

>>> f.file(state=State().UNUSED)
>>> f.file(contains="dlg")

Parameters

kwargs – logic_bool/any sppasFileStateCompare() method.

Returns

(sppasDataSet)

name(**kwargs)

Apply functions on all names of the files of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.name(iexact="myfile-phon", not_startswith='a', logic_bool="and")
>>> f.name(iexact="myfile-phon") & f.name(not_startswith='a')
>>> f.name(iexact="myfile-phon") | f.name(startswith="ta")

Parameters

kwargs – logic_bool/any sppasFileNameCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

path(**kwargs)

Apply functions on all paths of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.path(startswith="c:\users\myname", not_endswith='a', logic_bool="and")
>>> f.path(startswith="c:\users\myname") & f.path(not_endswith='a')
>>> f.path(startswith="c:\users\myname") | f.path(startswith="ta")

Parameters

kwargs – logic_bool/any sppasPathCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

ref(**kwargs)

Apply functions on all file properties of the object.

Return any fileroot for which at least one of its references is matching the filter.

Example

>>> f.ref(startswith="toto", endswith="tutu", logic_bool="and")
>>> f.ref(startswith="toto") & f.ref(endswith="tutu")
>>> f.ref(startswith="toto") | f.ref(contains="tutu")

Parameters

kwargs – logic_bool/any sppasFileStateCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

root(**kwargs)

Apply functions on all roots of the object.

Each argument is made of a function name and its expected value. Each function can be prefixed with ‘not_’, like in the next example.

Example

>>> f.root(startswith="myfile", not_endswith='a', logic_bool="and")
>>> f.root(startswith="myfile") & f.root(not_endswith='a')
>>> f.root(startswith="myfile") | f.root(startswith="ta")

Parameters

kwargs – logic_bool/any sppasRootCompare() method.

Returns

(sppasDataSet) Set of FileName() instances

class wkps.sppasRefAttribute(identifier, value=None, att_type=None, descr=None)

Bases: object

Represent any attribute with an id, a value, and a description.

VALUE_TYPES = ('str', 'int', 'float', 'bool')

__init__(identifier, value=None, att_type=None, descr=None)

Constructor of sppasRefAttribute.

Parameters

• identifier – (str) The identifier of the attribute

• value – (str) String representing the value of the attribute

• att_type – (str) One of the VALUE_TYPES

• descr – (str) A string to describe what the attribute is

Raises

AttributeIdValueError

get_description()

Return current description of the attribute.

Returns

(str)

get_id()

Return the identifier of the attribute.

get_typed_value()

Return the current typed value.

Returns

(any type) the current typed value.

get_value()

Return the current non-typed value.

Returns

(str)

get_value_type()

Return the current type of the value.

Returns

(str) Either: “str”, “int”, “float”, “bool”.

property id

Return the identifier of the attribute.

set_description(description)

Set a new description of the attribute.

Parameters

description – (str)

set_value(value)

Set a new value.

Parameters

value – (str)

set_value_type(type_name)

Set a new type for the current value.

Parameters

type_name – (str) the new type name

Raises

sppasTypeError

static validate(identifier)

Return True if the given identifier matches the requirements.

An id should contain between 3 and 12 ASCII-characters only, i.e. letters a-z, letters A-Z and numbers 0-9.

Parameters

identifier – (str) Key to be validated

Returns

(bool)

class wkps.sppasWkpRW(filename)

Bases: object

A reader/writer of any supported workspace file format.

WORKSPACE_TYPES = {'antw': <class 'wkps.wio.wannotationpro.sppasWANT'>, 'wjson': <class 'wkps.wio.wjson.sppasWJSON'>}

__init__(filename)

Create a workspace reader/writer.

Parameters

filename – (str)

static create_wkp_from_extension(filename)

Return a workspace according to a filename.

Parameters

filename – (str)

Returns

sppasBaseWkpIO()

static default_extension()

Return the default extension to read/write workspaces.

static extensions()

Return the list of supported extensions in lower case.

read()

Read a workspace from a file.

Returns

(sppasWkpRW)

write(wkp)

Write a workspace into a file.

Parameters

wkp – (sppasWorkspace) Data to be saved

class wkps.sppasWkps

Bases: object

Manage the set of workspaces.

A workspace is made of:

• a file in which data are saved and loaded when needed;

• a name, matching the filename without path nor extension.

__init__()

Create a sppasWkps instance.

Load the list of existing wjson file names of the workspaces folder of the software.

check_filename(index)

Get the filename of the workspace at the given index.

Parameters

index – (int) Index of the workspace

Returns

(str) name of the file

Raises

IndexError, OSError

delete(index)

Delete the workspace with the given index.

Parameters

index – (int) Index of the workspace

Raises

IndexError

export_to_file(index, filename)

Save an existing workspace into an external file.

Override filename if the file already exists.

Parameters

• index – (int) Index of the workspace to save data in

• filename – (str)

Raises

IOError

import_from_file(filename)

Import and append an external workspace.

Parameters

filename – (str)

Returns

The real name used to save the workspace

index(name)

Return the index of the workspace with the given name.

Parameters

name – (str)

Returns

(int)

Raises

ValueError

load_data(index)

Return the data of the workspace at the given index.

Parameters

index – (int) Index of the workspace

Returns

(str) sppasWorkspace()

Raises

IndexError

new(name)

Create and append a new empty workspace.

Parameters

name – (str) Name of the workspace to create.

Returns

The real name used to save the workspace

Raises

IOError, ValueError

rename(index, new_name)

Set a new name to the workspace at the given index.

Parameters

• index – (int) Index of the workspace

• new_name – (str) New name of the workspace

Returns

(str)

Raises

IndexError, OSError

save_data(data, index=- 1)

Save data into a workspace.

The data can already match an existing workspace or a new workspace is created. Raises indexerror if is attempted to save the ‘Blank’ workspace.

Parameters

• data – (sppasWorkspace) Data of a workspace to save

• index – (int) Index of the workspace to save data in

Returns

The real name used to save the workspace

Raises

IOError, IndexError

set_workspaces()

Fix the list of existing workspaces in the software.

Reset the current list of workspaces.

class wkps.sppasWorkspace(identifier='c80f7746-a3cf-4925-90b8-4381c477008b')

Bases: object

Represent the data linked to a list of files and a list of references.

sppasWorkspace is the container for a list of files and a catalog. It organizes files hierarchically as a collection of FilePath instances, each of which is a collection of FileRoot instances, each of which is a collection of FileName. The catalog is a list of sppasCatReference instances each of which is a list of key/att-value.

__init__(identifier='c80f7746-a3cf-4925-90b8-4381c477008b')

Constructor of a sppasWorkspace.

Parameters

identifier – (str)

add(file_object)

Add an object into the data.

IMPLEMENTED ONLY FOR paths and references.

Parameters

file_object – (FileBase)

Raises

sppasTypeError, FileAddValueError, NotImplementedError

add_file(filename, brothers=False, ctime=0.0)

Add file(s) in the list from a file name.

Parameters

• filename – (str) Absolute or relative name of a file

• brothers – (bool) Add also all files sharing the same root as the given file

• ctime – (float) Add files only if created/modified after time in seconds since the epoch

Returns

(list of FileBase or None) List of added objects

Raises

OSError

add_ref(ref)

Add a reference in the list from its file name.

Parameters

ref – (sppasCatReference) Reference to add

Raises

sppasTypeError, FileAddValueError

associate()

dissociate()

get_filename_from_state(state)

Return every FileName in the given state.

get_filepath_from_state(state)

Return every FilePath of the given state.

get_fileroot_from_state(state)

Return every FileRoot in the given state.

get_fileroot_with_ref(ref)

Return every FileRoot with the given reference.

get_id()

Return the identifier of the workspace (str).

get_object(identifier)

Return the file object matching the given identifier.

Parameters

identifier – (str)

Returns

(sppasWorkspace, FilePath, FileRoot, FileName, sppasCatReference)

get_parent(filebase)

Return the parent of an object.

Parameters

filebase – (FileName or FileRoot).

Returns

(FileRoot or FilePath)

Raises

sppasTypeError

get_paths()

Return all the stored paths.

Returns

(list of FilePath)

get_reference_from_state(state)

Return every Reference in the given state.

get_refs()

Return the list of references.

has_locked_files()

property id

Return the identifier of the workspace (str).

is_empty()

Return if the instance contains information.

property paths

Return all the stored paths.

Returns

(list of FilePath)

property refs

Return the list of references.

remove_empties()

Remove paths and roots without files.

remove_file(filename)

Remove a file in the list from its file name.

Its root and path are also removed if empties, or their state is updated.

Parameters

filename – (str) Absolute or relative name of a file

Returns

(list) Identifiers of removed objects

Raises

OSError

remove_files(state=1)

Remove all files of the given state.

Do not remove empty roots or paths.

Parameters

state – (States)

Returns

(int)

remove_refs(state=1)

Remove all references of the given state.

Parameters

state – (States)

Returns

(int) Number of removed refs

set_object_state(state, file_obj=None)

Set the state of any or all FileBase within sppasWorkspace.

The default case is to set the state to all FilePath and FileRefence.

It is not allowed to manually assign one of the “AT_LEAST” states. They are automatically fixed depending on the paths states.

Parameters

• state – (States) state to set the file to

• file_obj – (FileBase) the specific file to set the state to. None to set all files

Raises

sppasTypeError, sppasValueError

Returns

list of modified objects

set_state(value)

Set the state of this sppasWorkspace instance.

Parameters

value – (States)

unlock(entries=None)

Unlock the given list of files.

Parameters

entries – (list, None) List of FileName to unlock

Returns

number of unlocked entries

update()

Update the data: missing files, properties changed.

Empty FileRoot and FilePath are removed.