API

Sid

class spil.sid.sid.BaseSid[source]

Base class for Sids.

Implements __new__ and __init__ to allow Sid instances to be created by a factory. The goal is to have an extendable Sid and factory.

static __new__(cls, *args, **kwargs)[source]

Calls a Factory function that handles the Sid object creation. Returns the instance from that factory.

(To avoid that the factory calls itself, the method uses the kwarg “from_factory”. If it is set, an object instance is returned.)

Parameters:

  • *args –

  • **kwargs –

__init__(*args, **kwargs)[source]

Empty Method. See documentation about the Sid Factory creation mechanism.

Parameters:

  • *args –

  • **kwargs –

class spil.sid.sid.StringSid[source]

StringSid is the barest form of Sids. It only has a string. It is not typed.

property string: str

Returns the string representation of a Sid. The string can be any arbitrary string if the Sid is not typed.

If the Sid is typed, the string will is a path like representation of its values.

Examples

>>> Sid('hamlet/s/sq030/sh0100/anim').string
'hamlet/s/sq030/sh0100/anim'

>>> Sid('blablabla').string
'blablabla'
Returns:

The string representation.

property uri: str

Returns the “uri” representation of a Sid. The form is “type:string” if typed, else just the sid string.

(This property is overriden in TypedSid)

Returns:

The uri representation.

copy()[source]

Returns a copy of the current Sid. Copy is generated by calling Sid(self.uri).

Example

>>> Sid('hamlet/a/char/ophelia/model').copy()
Sid('asset__task:hamlet/a/char/ophelia/model')
Returns:

A Sid copy.

Return type:

Sid

Returns True if the current Sid contains search symbols. Search symbols are defined in the Sid conf, and are typically: [‘*’, ‘,’, ‘>’, ‘<’, ‘**’]

The Sid may not be typed.

Examples

>>> Sid('hamlet/a/char/*/*').is_search()
True

>>> Sid('hamlet/a/char/ophelia').is_search()
False
Returns:

True if the Sid contains search symbols, else False.

Return type:

bool

__truediv__(other)[source]

Override the division operator, to compose a Sid from another one. Inspired by pathlib.Path.

The get_with() method is prefered, since it generally is less “volatile”.

Examples

>>> Sid('hamlet') / 's' / 'sq030'
Sid('shot__sequence:hamlet/s/sq030')

>>> sid = Sid("hamlet/s/sq030")
>>> sid.parent / sid.get(sid.keytype) == sid
True

>>> Sid("hamlet/s/sq030") / None
Sid('shot__sequence:hamlet/s/sq030')
Parameters:

other (Sid | str | None) –

Return type:

Sid

class spil.sid.sid.TypedSid[source]

The TypedSid class implements a Sid that has been resolved successfully.

It has a “type” and a “field” data dictionary.

property type: str

Returns the Sids type.

If the Sid has no type, an empty string is returned.

Examples

>>> Sid("hamlet/a/char/ophelia/rig").type
'asset__task'

>>> Sid("hamlet/a/char/*").type
'asset__asset'

>>> Sid("blabla").type
''
Returns:

The Sid type

property fields: dict

Returns the Sids data dictionary.

The fields match what is defined in the Sid template.

Examples

>>> Sid("hamlet/a/char/*").fields
{'project': 'hamlet', 'type': 'a', 'assettype': 'char', 'asset': '*'}

>>> Sid("hamlet/s/sq010/sh0010/anim").fields
{'project': 'hamlet', 'type': 's', 'sequence': 'sq010', 'shot': 'sh0010', 'task': 'anim'}
Returns:

Sids data dictionary.

property uri: str

Returns the “uri” representation of a Sid.

The form is “type:string” if typed, else just the sid string.

Examples

>>> Sid('hamlet/s/sq030/sh0100/anim').uri
'shot__task:hamlet/s/sq030/sh0100/anim'

>>> Sid('blablabla').uri
'blablabla'

Note

If the Sid ends with a “query”, this query is applied, if possible. An unapplied query stays in the string and thus, the uri.

Examples with query:

>>> Sid('hamlet/s/sq030/sh0100/anim?task=render').uri
'shot__task:hamlet/s/sq030/sh0100/render'

>>> Sid('hamlet/s/sq030/sh0100/anim?foo=bar').uri
'shot__task:hamlet/s/sq030/sh0100/anim?foo=bar'

>>> Sid('blablabla?foo=bar').uri
'blablabla?foo=bar'
Returns

the “uri” representation of a Sid.

property basetype: str | None

The basetype is the first part of the type.

Examples

>>> Sid("hamlet/s/sq030/sh0100/anim").basetype
'shot'

>>> Sid("hamlet/a/prop/dagger").basetype
'asset'

>>> Sid("bla/bla").basetype
Returns

string basetype

property keytype: str | None

Returns the last key of the fields dictionary.

Note that this is not necessarily the second part of the “type”.

Note

Sid(“hamlet/a/char/claudius/model/v001/w/blend”)

  • type: ‘asset__file’

  • keytype: ‘ext’

  • basetype: ‘asset’

Sid(“hamlet/s”)

  • type: ‘shot’

  • keytype: ‘type’

  • basetype: ‘shot’

Sid(“hamlet”)

  • type: ‘project’

  • keytype: ‘project’

  • basetype: ‘project’

Examples

>>> Sid("hamlet/a/char/claudius/model/v001/w/blend").keytype
'ext'

>>> Sid("hamlet/a/char/ophelia/model").keytype
'task'

>>> Sid("hamlet/s/sq001/sh0010").keytype
'shot'
Returns:

string keytype

property parent: Sid

Returns the parent Sid.

Returns an empty Sid, if the Sid is not “defined”, or a copy of self if the Sid is already the root (has no parent).

Note that this is a logical operation, without data access.

Examples

>>> Sid('hamlet/s/sq030/sh0100').parent
Sid('shot__sequence:hamlet/s/sq030')

>>> Sid('hamlet').parent
Sid('project:hamlet')

>>> Sid('bla/bla/bla').parent
Sid('')
Returns:

Returns an empty Sid, if the Sid is not “defined”, or self if the Sid is already the root (has no parent).

__len__()[source]

Returns the “length” of a Sid, which is the number of keys in its “fields” data dictionary.

Returns:

The amount of keys in the “fields” dictionary.

Return type:

int

get(key)[source]

Returns the value of given key. As defined in the internal “fields” data dictionary.

Example

>>> Sid("hamlet/s/sq030/sh0100/anim").get("shot")
'sh0100'
Parameters:

key (str) – retrieved key

Returns:

Value of given key, in the “fields” data dictionary.

Return type:

str | None

get_as(key)[source]

Returns a new Sid built of the fields until (and including) the given key.

If the Sid is not typed or the key is not found, an empty Sid is returned.

Examples

>>> Sid('hamlet/a/char/ophelia/model/v001/w/ma').get_as('task')
Sid('asset__task:hamlet/a/char/ophelia/model')

>>> Sid('hamlet/a/char/ophelia/model/v001/w/ma').get_as('something')
Sid('')

>>> Sid('hamlet/bla/bla').get_as('shot')
Sid('')
Parameters:

key (str) – key until which the new Sid should be built

Returns:

Sid as given key

Return type:

Sid

get_with(query=None, key=None, value=None, **kwargs)[source]

Returns a new Sid.

  • with the given query applied (see details about query application in documentation)

or

  • updated using given key and value, eg. get_with(key=’task’, value=’rendering’) and

  • updated using **kwargs where keys are sid keys, eg. get_with(task=’rendering’)

Depending on the update, the type of the returned Sid can change, or the Sid can end up untyped.

A key set to None will be removed. To empty a keys value, set it to an empty string “”.

Note

Only works on typed or empty Sids.

Examples

>>> Sid('hamlet/s/sq030/sh0010/anim').get_with(task='render')
Sid('shot__task:hamlet/s/sq030/sh0010/render')

>>> Sid("hamlet/a/prop/dagger").get_with(query='asset=skull')
Sid('asset__asset:hamlet/a/prop/skull')

>>> Sid().get_with(project="hamlet")
Sid('project:hamlet')
Parameters:

  • query (Optional[str]) – s tring query, in the format ?key=value&key2=value2

  • key (Optional[str]) – a key name, for example “shot”, “sequence”, or “task”

  • value (Optional[str]) – a new value for given key. May be None (removes the key) or “” (empty value).

  • **kwargs – a key/value dictionary

Returns:

A new Sid. Depending on the update, the type of the returned Sid can change.

Return type:

Sid

is_leaf()[source]

Returns True if the current Sid is a “leaf” node.

A leaf node has no children (and cannot have children).

Current implementation checks if the keytype is set as a “leaf type” in the config_name. For example: “ext” (file extension) is the keytype of leaf nodes. This is configured per basetype.

This implementation is still experimental. Implementation and concept needs to be clarified.

Note: A leaf should be dependent on the context and type. For example, in searching for render files, it can be useful to handle the “render pass” as leave, to avoid going too deep in the hierarchy.

This is done, for example, in the spil_ui browser, to browse render files by the pass folder, not individually by default.

Returns:

True if this Sid is a leaf, else False.

as_query()[source]

Returns the fields as a key value string, as in an Query.

Example

>>> Sid('hamlet/a/char/ophelia/model').as_query()
'project=hamlet&type=a&assettype=char&asset=ophelia&task=model'
Returns:

string query

Return type:

str

match(search_sid)[source]

Returns True if a given search_sid matches the current Sid, else False.

This method is useful to create filters matching groups of Sids, more precise than types.

Examples

>>> Sid('hamlet/a/char/ophelia/model').match('hamlet/a/*/*/model')
True

>>> Sid('hamlet/s/sq030/sh0100/anim').match('hamlet/s/*/*/*')
True

>>> Sid('hamlet/a/char/ophelia').match('hamlet/a/prop/*')
False
Returns

True if matched, else False

Parameters:

search_sid (Sid | str) –

Return type:

bool

class spil.sid.sid.PathSid[source]

The PathSid adds path resolving.

TODO: cache must be invalidated whenever (if ever) the default PathConfig changes.

path(config=None)[source]

Returns the file path for the current Sid, as a pathlib.Path. Returns None if the Sid has no path, or if it cannot be resolved.

This method is cached. A path for a Sid is configured (not the result of a data lookup), and is not supposed to change during runtime.

Example

>>> sid = Sid('hamlet/a/char/ophelia/model/v001/w/ma')
>>> path = sid.path()
>>> new_sid = Sid(path=path)
>>> sid == new_sid
True

>>> path = Sid('hamlet/a/char/ophelia/model/v001/w/ma').path()
>>> path.relative_to(conf.default_sid_conf_data_path).as_posix()  # to be location and os independent
'testing/SPIL_PROJECTS/LOCAL/PROJECTS/HAMLET/PROD/ASSETS/char/ophelia/model/v001/char_ophelia_model_WORK_v001.ma'

>>> Sid('bla/bla').path()
Parameters:

config (Optional[str]) – Name of the path config to be used, as configured.

Returns:

A path, if the Sid has a path, else None.

Return type:

Path | None

class spil.sid.sid.DataSid[source]

The DataSid implements operations that delegate calls to data sources: Finders and Getters. By default FindInAll and GetFromAll are used.

# TODO: make configurable which Finder is used for DataSid operations (FindInAll per default). # Could be handled using a default config_name, and/or be changed at runtime.

get_attr(attribute)[source]

Returns an attribute for the current sid. Uses GetFromAll, which calls the apropriate Getter defined for this Sid in spil_data_conf.

Shortcut to GetFromAll().get_attr(sid, attribute), which is called internally.

Example

>>> from spil import WriteToPaths
>>> sid = Sid('hamlet/a/char/ophelia/model/v001/w/ma')
>>> __ = WriteToPaths().set(sid, comment="Updated topology")
>>> sid.get_attr('comment')
'Updated topology'
Parameters:

attribute (str) – Name of an attribute

Returns:

The value of the attribute, or None if it was not found.

Return type:

Any | None

get_last(key=None)[source]

Returns a new Sid object, with the same fields as self, and the last existing match for given key. If key is not given, the keytype is used. If the Sid is untyped, returns an empty Sid.

Examples

>>> Sid('hamlet/a/char/ophelia/model/v001/p/ma').get_last('version')
Sid('asset__file:hamlet/a/char/ophelia/model/v002/p/ma')

>>> Sid('hamlet/a/char/ophelia/model').get_last()
Sid('asset__task:hamlet/a/char/ophelia/surface')

>>> Sid('bla/bla').get_last('whatever')
Sid('')
This method calls FindinAll internally, and is a shortcut to:

FindInAll().find_one(self.get_with(key=key, value=’>’), as_sid=True)

Note: Sid sorting is currently limited to string values, which usually works with versions. A meaningful sorting of tasks (eg. “render” after “animation”) is planned.

(implementation is experimental)

Returns:

Sid or None

Parameters:

key (Optional[str]) –

Return type:

Sid

get_next(key)[source]

Returns self with key’s value incremented, or first value if there is none. If value is ‘*’, returns “get_new” (next of last)

If the result is not a valid Sid (not typed, no fields), returns an empty Sid.

Note

Currently limited to version.

Examples

>>> Sid('hamlet/a/char/ophelia/model/v001/w/ma').get_next('version')
Sid('asset__file:hamlet/a/char/ophelia/model/v002/w/ma')

>>> Sid('hamlet/a/char/ophelia/model/*/w/ma').get_next('version')
Sid('asset__file:hamlet/a/char/ophelia/model/v003/w/ma')

>>> Sid('hamlet/a/char/ophelia/model').get_next('version')
Sid('asset__version:hamlet/a/char/ophelia/model/v001')
Parameters:

key (str) – the key for which we want to increment the value. Typically a version.

Returns:

A Sid with key’s value incremented, or an empty Sid.

Return type:

Sid

get_new(key)[source]

Returns a new Sid with the key incremented to the “next available value”. Makes sense with numerical values, especially with versions.

For example, if the given key is “version”: Returns self with next version (the one following the last), or first version if there is no version. If the result is not a valid Sid (not typed, no fields), returns an empty Sid.

Example

>>> Sid('hamlet/a/char/ophelia/model/v001/w/ma').get_new('version')
Sid('asset__file:hamlet/a/char/ophelia/model/v003/w/ma')
Parameters:

key (str) –

Returns:

Sid

Return type:

Sid

exists()[source]

Returns True if the current Sid exists. Shortcut to FindInAll().exists(self), which is called internally.

Examples

>>> Sid('hamlet/a/char/ophelia').exists()
True

>>> Sid('hamlet/a/prop/computer').exists()
False

>>> Sid('bla/bla').exists()
False
Returns:

True if Sid exists, else False

Return type:

bool

siblings_as(key)[source]

Returns existing siblings, in other words children of parent, as Sid of given keytype.

Example

>>> sorted( Sid('hamlet/a/fx/blood/surface/v002/p/ma').siblings_as('asset') )
[Sid('asset__asset:hamlet/a/fx/blood'), Sid('asset__asset:hamlet/a/fx/mist'), Sid('asset__asset:hamlet/a/fx/rain'), Sid('asset__asset:hamlet/a/fx/thunder'), Sid('asset__asset:hamlet/a/fx/water')]
Parameters:

key (str) – keytype we want siblings from

Returns:

List of sibling Sids

Return type:

List[Sid]

siblings()[source]

Returns existing siblings, in other words children of parent.

Example

>>> sorted( Sid('hamlet/a/fx/blood/surface').siblings() )
[Sid('asset__task:hamlet/a/fx/blood/art'), Sid('asset__task:hamlet/a/fx/blood/model'), Sid('asset__task:hamlet/a/fx/blood/rig'), Sid('asset__task:hamlet/a/fx/blood/surface')]
Returns:

List of sibling Sids.

Return type:

List[Sid]

children()[source]

Returns existing children. Shortcut to: FindInAll().find(self / ‘*’, as_sid=True)

Examples

>>> Sid('hamlet/a/char/ophelia/rig').children()
[Sid('asset__version:hamlet/a/char/ophelia/rig/v001'), Sid('asset__version:hamlet/a/char/ophelia/rig/v002')]

>>> Sid('hamlet/a/char/ophelia/model/v001/w/ma').children()
[]
Returns:

Children Sids

Return type:

List[Sid]

class spil.sid.sid.Sid[source]

Sid class.

Multiple ways to create a Sid: - Sid string, uri, query string (starting with “?”), Sid object, or empty string - query string - fields dictionary - path (with optional config)

Examples

>>> Sid("hamlet/s/sq010")                                   # string
Sid('shot__sequence:hamlet/s/sq010')

>>> Sid(sid="hamlet/s/sq010")                               # parameter + string
Sid('shot__sequence:hamlet/s/sq010')

>>> Sid(Sid("hamlet/s/sq010"))                              # Sid object
Sid('shot__sequence:hamlet/s/sq010')

>>> Sid("shot__sequence:hamlet/s/sq010")                    # uri
Sid('shot__sequence:hamlet/s/sq010')

>>> Sid("?project=hamlet&type=s&sequence=sq010")             # empty string with query
Sid('shot__sequence:hamlet/s/sq010')

>>> Sid(query="project=hamlet&type=s&sequence=sq010")          # query
Sid('shot__sequence:hamlet/s/sq010')

>>> Sid(fields={'project': 'hamlet', 'sequence': 'sq010', 'type': 's'})  # fields dict
Sid('shot__sequence:hamlet/s/sq010')

>>> path = Path(conf.default_sid_conf_data_path) / "testing/SPIL_PROJECTS/LOCAL/PROJECTS/HAMLET/PROD/ASSETS/char/ophelia/model/v001/char_ophelia_model_WORK_v001.ma"
>>> Sid(path=path)           # path (default config) # TODO: any config
Sid('asset__file:hamlet/a/char/ophelia/model/v001/w/ma')

>>> Sid(path=path, config='local')   # path (config "local")
Sid('asset__file:hamlet/a/char/ophelia/model/v001/w/ma')

This class inherits all functionality from the class hierarchy. It only defines the factory to be used to create the Sid.

Note that this implementation may change, but API will remain the same. The goal is to be able to Extend the Sid class to custom needs.

Finders

class spil.sid.read.finder.Finder[source]

Interface for Sid Finder.

Implements common public Sid Search methods “find”, “find_one”, and “exists”

The search process is as follows:

find(): - the search sid string is “unfolded” into a list of typed search Sids.

do_find() - runs the actual search on each typed search sid

find(search_sid: str, as_sid: typing_extensions.Literal[True]) → Iterator[Sid][source]
find(search_sid: str, as_sid: typing_extensions.Literal[False]) → Iterator[str]
find(search_sid: Sid, as_sid: typing_extensions.Literal[True]) → Iterator[Sid]
find(search_sid: Sid, as_sid: typing_extensions.Literal[False]) → Iterator[str]
find(search_sid: str) → Iterator[Sid]
find(search_sid: Sid) → Iterator[Sid]

Yields the Sids found using the given search_sid. Returns a generator over Sids, if as_sid is True (default), or over Sid strings.

Example

>>> from spil import FindInAll
>>> list(FindInAll().find('hamlet/a/*'))
[Sid('asset__assettype:hamlet/a/char'), Sid('asset__assettype:hamlet/a/location'), Sid('asset__assettype:hamlet/a/prop'), Sid('asset__assettype:hamlet/a/fx')]
Parameters:

  • search_sid – typed or untyped Sid or string

  • as_sid – if the result should be Sid objects or strings

Returns:

Generator over Sids or strings

do_find(search_sids: List[Sid], as_sid: typing_extensions.Literal[True]) → Iterator[Sid][source]
do_find(search_sids: List[Sid], as_sid: typing_extensions.Literal[False]) → Iterator[str]
do_find(search_sids: List[Sid], as_sid: Optional[bool]) → Iterator[Sid] | Iterator[str]
find_one(search_sid: str | Sid, as_sid: typing_extensions.Literal[True]) → Sid[source]
find_one(search_sid: str | Sid, as_sid: typing_extensions.Literal[False]) → str
find_one(search_sid: str | Sid, as_sid: Optional[bool]) → Sid | str

Returns the first Sid found using the given search_sid.

Returns a Sid, if as_sid is True (default), or a Sid strings.

Internally calls “first” on “find”.

Example

>>> from spil import FindInAll
>>> FindInAll().find_one('hamlet/a/char/ophelia')
Sid('asset__asset:hamlet/a/char/ophelia')
Parameters:

  • search_sid – typed or untyped Sid or string

  • as_sid – if the result should be a Sid object or string

Returns:

first found Sid or string

exists(search_sid)[source]

Returns True if the given search_sid returns a result. Else False.

Internally calls “bool” on “find_one”.

Example

>>> from spil import FindInAll
>>> FindInAll().exists('hamlet/a/char/ophelia')
True

>>> from spil import FindInAll
>>> FindInAll().exists('hamlet/a/char/jimmy')
False
Parameters:

search_sid (str | Sid) – search_sid: typed or untyped Sid or string

Returns:

True if search_sid returns a result, else False

Return type:

bool

class spil.sid.read.finders.find_glob.FindByGlob[source]

Parent class for glob type searches: FindInFiles, FindInList, FindInConstants

The search process is as follows:

find(): - the search sid string is “unfolded” into a list of typed search Sids.

do_find() - depending on the types of searches, defined by the search symbols (‘>’, …), the search is delegated to a finder function. (currently either “sorted_search” or “star_search”).

do_find(search_sids: List[Sid], as_sid: typing_extensions.Literal[True]) → Iterator[Sid][source]
do_find(search_sids: List[Sid], as_sid: typing_extensions.Literal[False]) → Iterator[str]
do_find(search_sids: List[Sid], as_sid: Optional[bool]) → Iterator[Sid] | Iterator[str]
star_search(search_sids: List[Sid], as_sid: typing_extensions.Literal[True], do_sort: bool = False) → Iterator[Sid]
star_search(search_sids: List[Sid], as_sid: Optional[bool], do_sort: bool) → Iterator[str] | Iterator[Sid]

Operates a sorted read. A sorted read contains the “>” sign, standing for “last” or the “<” sign, standing for “first”. (not yet implemented)

TODO: “meaningful sort” (eg. LAY < ANI < RND), currently only alphanumerical sort.

Parameters:

  • search_sids (List[Sid]) –

  • as_sid (bool) –

Returns:

Return type:

Iterator[Sid] | Iterator[str]

class spil.sid.read.finders.find_list.FindInList[source]

List search.

Searches for sids from a Sid string list. The search list is given during object instantiation.

The search list can optionally be extrapolated.

Implements a glob like “star_search”. This loops through the list and accumulates the matching results.

Note: searchlist can be a generator, but it will be exhausted after a single function call.

Still beta.

__init__(searchlist, do_extrapolate=False, do_pre_sort=False, do_strip=False)[source]

Sets the search list, a list of sid strings.

Note: searchlist could be a generator, but it would be exhausted after a single function call. If do_extrapolate is True, searchlist becomes a list.

Parameters:

  • searchlist (List[str]) –

  • do_extrapolate (bool) –

  • do_pre_sort (bool) –

  • do_strip (bool) – if the returned items should be strip() (typically if coming from file input)

Simple star search.

Transforms the pattern into a regex (like fnmatch.translate), but without traversing “/” (the sid separator).

Parameters:

  • search_sids (List[Sid]) –

  • as_sid (bool) –

  • do_sort (bool) –

Return type:

Iterator[Sid] | Iterator[str]

Returns:

class spil.sid.read.finders.find_constants.FindInConstants[source]

Finds Sid from a list, for a specific type.

Whereas FindInList looks inside a list of Sids, FindInConstants looks inside a list for one specific keytype.

Implements star_search for a specific key, by getting the values from a given, constant, list. If there is a search “above” the given key, the search is delegated to the given “parent_source”.

This is used to create a Data Source for constant values.

Examples

We instantiate a parent Finder

>>> from spil import FindInPaths
>>> fp = FindInPaths()

Finding a constant list of asset types

>>> finder = FindInConstants('assettype', ['char', 'location', 'prop', 'fx'], parent_source=fp)
>>> list( finder.find('hamlet/a/*') )
[Sid('asset__assettype:hamlet/a/char'), Sid('asset__assettype:hamlet/a/location'), Sid('asset__assettype:hamlet/a/prop'), Sid('asset__assettype:hamlet/a/fx')]

Search “above” in the hierarchy is delegated to the parent

>>> list( finder.find('hamlet/*/prop') )
[Sid('asset__assettype:hamlet/a/prop')]

Other examples, defining a constant list of “states” and searching for states

>>> finder_states = FindInConstants('state', ["w", "p"], parent_source=fp)
>>> list( finder_states.find('hamlet/a/location/ramparts/rig/v001/*') )
[Sid('asset__state:hamlet/a/location/ramparts/rig/v001/w'), Sid('asset__state:hamlet/a/location/ramparts/rig/v001/p')]

Finding a state with a parent search

>>> list( finder_states.find('hamlet/a/location/ramparts/rig/*/p') )
[Sid('asset__state:hamlet/a/location/ramparts/rig/v001/p'), Sid('asset__state:hamlet/a/location/ramparts/rig/v002/p')]

Finding a state with a multi-parent search

>>> sorted(list( finder_states.find('hamlet/a/location/*/rig/*/p') ))
[Sid('asset__state:hamlet/a/location/elsinore/rig/v001/p'), Sid('asset__state:hamlet/a/location/elsinore/rig/v002/p'), Sid('asset__state:hamlet/a/location/garden/rig/v001/p'), Sid('asset__state:hamlet/a/location/garden/rig/v002/p'), Sid('asset__state:hamlet/a/location/lakeside/rig/v001/p'), Sid('asset__state:hamlet/a/location/lakeside/rig/v002/p'), Sid('asset__state:hamlet/a/location/queens_chamber/rig/v001/p'), Sid('asset__state:hamlet/a/location/queens_chamber/rig/v002/p'), Sid('asset__state:hamlet/a/location/ramparts/rig/v001/p'), Sid('asset__state:hamlet/a/location/ramparts/rig/v002/p')]

Combining parent and constant search

>>> list( finder_states.find('hamlet/a/location/ramparts/rig/*/*') )
[Sid('asset__state:hamlet/a/location/ramparts/rig/v001/w'), Sid('asset__state:hamlet/a/location/ramparts/rig/v001/p'), Sid('asset__state:hamlet/a/location/ramparts/rig/v002/w'), Sid('asset__state:hamlet/a/location/ramparts/rig/v002/p')]

Finds itself if needed.

>>> list( finder_states.find('hamlet/a/location/ramparts/rig/v001/p') )
[Sid('asset__state:hamlet/a/location/ramparts/rig/v001/p')]

This is still beta code.

__init__(key, values, parent_source=None)[source]
Parameters:

  • key (str) – the keytype for which this Finder operates.

  • values (List[str]) – the list of values that this Finder always finds, for the given key.

  • parent_source (Finder | None) – delegates to this finder for searches above the keytype (parents of the keytype)

Parameters:

  • search_sids (List[Sid]) –

  • as_sid (bool) –

  • do_sort (bool) –

Return type:

Iterator[Sid] | Iterator[str]

class spil.sid.pathops.find_paths.FindInPaths[source]

Searches for sids in a File System. Mainly uses the glob search.

Still Beta.

__init__(config=None)[source]

Config is the desired config_name name, as configured in data_conf. If config_name is None, the default config_name (during class instantiation) is used.

Parameters:

config (Optional[str]) –

Star search main function.

Delegates to “star_search_simple” by default, or to “star_search_framed” to handle file sequences, if “frame=*” is in the search

Parameters:

  • search_sids (List[Sid]) – list of Sids to search

  • as_sid (bool) – return the result as sid object or string (the default)

  • do_sort (bool) – not implemented in FindInPaths (#FIXME correct design)

Return type:

Iterator[Sid] | Iterator[str]

Returns:

star_search_simple(search_sids, as_sid=False)[source]

Star search without file sequence handline.

Uses Glob.

Parameters:

  • search_sids (List[Sid]) –

  • as_sid (bool) –

Returns:

Return type:

Iterator[Sid] | Iterator[str]

star_search_framed(search_sids, as_sid=False)[source]

Star search with file sequence handling.

Uses Glob and fileseq.

Parameters:

  • search_sids (List[Sid]) –

  • as_sid (bool) –

Returns:

Return type:

Iterator[Sid] | Iterator[str]

class spil.sid.read.finders.find_all.FindInAll[source]

This Finder will call other Finders, as configured, depending on the search sids type.

The do_find() method is delegated to other finders, and not implemented.

__init__(config=None)[source]

“config” is an argument that will be passed through to the config, via get_finder_for(sid, config). “config” acts like a key, to allow multiple FindInAll configurations to co-exist.

Parameters:

config (Optional[str]) – name of a configuration

find(search_sid: str, as_sid: typing_extensions.Literal[True]) → Iterator[Sid][source]
find(search_sid: str, as_sid: typing_extensions.Literal[False]) → Iterator[str]
find(search_sid: Sid, as_sid: typing_extensions.Literal[True]) → Iterator[Sid]
find(search_sid: Sid, as_sid: typing_extensions.Literal[False]) → Iterator[str]
find(search_sid: str) → Iterator[Sid]
find(search_sid: Sid) → Iterator[Sid]

Search dispatcher.

The search is “unfolded” (one possibly untyped search sid is “unfolded” into a list of typed search sids). For each typed sid, we get the appropriate Finder.

We then group the searches by Finder, to call each Finder with a list of searches (instead of each search individually).

Parameters:

  • search_sid – Sid to search

  • as_sid – result will be returned as a Sid object if True, as a string otherwise.

Returns:

Generator over the found Sids, as Sid or string instances.

Getters

class spil.sid.read.getter.Getter[source]

Interface for Sid Getter.

Whereas the Finder only finds Sids, the Getter retrieves Sid(s) and its data.

A Getter is getting from a data source. Eg. GetFromPaths, GetFromSG.

The Getters work has two forms: Finding with data form a search sid, or Getting data from a Sid.

  1. Finding with data

The Getter receives a Search Sid, finds the result Sid(s) and returns them together with data. This can be considered like a Finder including dependencies (the “Finder” itself only finds Sids).

Implementation options

  • The Getter calls the data source directly and retrieves Sids with data in one go. Typically, it is done when the data source is a database (for example GetFromSG)

  • The Getter calls a Finder to find the Sids, and then retrieves the data for each of them. For example GetFromPaths calls FindInPaths and then reads the data from disk for the Sids.

Methods: get(), do_get(), get_one() These methods yield over dicts containing the data. One special field named “sid” contains the Sid.

  1. Getting data

The Getter receives a specific Sid, and retrieves its data.

It is possible to call

  • For a given existing Sid, retrieving data with all or some attributes

  • For a given existing Sid, retrieving one attribute

Methods: get_data(), get_attr() get_data() returns the data dict get_attr() returns the attributee

get(search_sid, attributes=None, sid_encode=<class 'str'>)[source]

For a given search, returns an Iterator over Mappings containing the retrieved data. One special field named “sid” contains the Sid. The Sid can be encoded by providing a callable to “sid_encode”. Default is str.

By default, attributes is None, retrieved data contains all configured data for the Sid type. If “attributes” is given, data contains only the key:value for the given attributes.

The Sids returned by Getter.get() should be identical to those returned by Finder.find(). Getter retrieves data related to these Sids, whereas the Finder finds only the existing Sids themselves.

Parameters:

  • search_sid (str | Sid) – the search sid (possibly untyped).

  • attributes (Optional[List[str]]) – a list of attribute names, that should be fetched.

  • sid_encode (Callable) – a callable to which the sid object will be passed, that should return the value added to the data dictionary under the “sid” key. Example: sid_encode=lambda x: x.uri If the callable returns None, the value is not added. As in sid_encode=lambda x: None

Returns:

Iterator over Mappings containing the retrieved data. One special field named “sid” contains the Sid

Return type:

Iterator[Mapping[str, Any]]

do_get(search_sids, attributes=None, sid_encode=<class 'str'>)[source]

Has the same purpose as get(), but operates on given “search_sids”, a list of typed search sids.

Is called by get() after unfolding and typing the search sid.

Parameters:

  • search_sids (List[Sid]) – List of typed search sids.

  • attributes (Optional[List[str]]) – a list of attribute names, that should be fetched.

  • sid_encode (Callable) – a callable to which the sid object will be passed, that should return the value added to the data dictionary under the “sid” key. Example: sid_encode=lambda x: x.uri If the callable returns None, the value is not added. As in sid_encode=lambda x: None

Returns:

Iterator over Mappings containing the retrieved data. One special field named “sid” contains the Sid.

Return type:

Iterator[Mapping[str, Any]]

get_one(search_sid, attributes=None, sid_encode=<class 'str'>)[source]

Calls get() with the given parameters, and returns the first result.

Parameters:

  • get() (See) –

  • search_sid (str | Sid) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Returns:

Mapping containing the retrieved data. One special field named “sid” contains the Sid

Return type:

Mapping[str, Any]

get_data(sid, attributes=None, sid_encode=<class 'str'>)[source]

Returns data associated to the given Sid, as a key:value dictionary. One special field named “sid” contains the Sid.

Returns an empty dictionary if no data was found.

Parameters:

  • sid (str | Sid) – a typed sid

  • attributes (Optional[List[str]]) – a list of attribute names, that should be fetched.

  • sid_encode (Callable) – a callable to which the sid object will be passed, that should return the value added to the data dictionary under the “sid” key. Example: sid_encode=lambda x: x.uri If the callable returns None, the value is not added. As in sid_encode=lambda x: None

Returns:

Mapping containing the retrieved data. One special field named “sid” contains the Sid

Return type:

Mapping[str, Any]

get_attr(sid, attribute)[source]

Returns an attribute, a named piece of data, for the given Sid.

Parameters:

  • sid (str | Sid) – typed Sid

  • attribute (str) – attribute name

Returns:

The value for the given Sid and attribute name.

Return type:

Any | None

class spil.sid.read.getters.getter_finder.GetByFinder[source]

Some Getters first use a Finder to retrieve the Sids, then, in a second distinct step, retrieve the data. For example, GetFromPaths which stores data in json “sidecar” files.

This “GetByFinder” is an abstract Getter, implementing shared methods for Getters that use a Finder.

These Getters can inherit GetByFinder, and: - override the constructor and define self.finder - or pass it to the constructor (inherited from GetByFinder) - and implement get_data()

__init__(finder)[source]
Parameters:

finder (Finder) –

get(search_sid, attributes=None, sid_encode=<class 'str'>)[source]

See Getter.

Parameters:

  • search_sid (str | Sid) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Return type:

Iterator[Mapping[str, Any]]

do_get(search_sids, attributes=None, sid_encode=<class 'str'>)[source]

See Getter.

Parameters:

  • search_sids (List[Sid]) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Return type:

Iterator[Mapping[str, Any]]

get_data(sid, attributes=None, sid_encode=<class 'str'>)[source]

See Getter.

Parameters:

  • sid (str | Sid) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Return type:

Mapping[str, Any]

class spil.sid.pathops.getter_paths.GetFromPaths[source]

Getter from File system.

This is still experimental.

__init__(config=None)[source]
Parameters:

config (Optional[str]) –

get_data(sid, attributes=None, sid_encode=<class 'str'>)[source]

Returns data associated to the given Sid, as a key:value dictionary. Returns an empty dictionary if no data was found.

Reads data dictionary from a json. To infer the jsons file path, the Sid path is used, with the suffix replaced, as per config.

Parameters:

  • sid (str | Sid) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Return type:

Mapping[str, Any]

Returns: A key:value dictionary, or an empty dictionary

class spil.sid.read.getters.getter_all.GetFromAll[source]

This Getter will call other Getters, as configured, depending on the search sids type.

The do_get() method is delegated to other Getters, and not implemented.

__init__(config=None)[source]

Config is an argument that will be passed to the config, via get_getter_for(sid, config). Config acts like a key, to allow multiple GetFromAll configurations to co-exist.

Parameters:

config (Optional[str]) – name of a configuration

get(search_sid, attributes=None, sid_encode=<class 'str'>)[source]

See Getter.

Parameters:

  • search_sid (str | Sid) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Return type:

Iterator[Mapping[str, Any]]

get_data(sid, attributes=None, sid_encode=<class 'str'>)[source]

See Getter

Parameters:

  • sid (str | Sid) –

  • attributes (Optional[List[str]]) –

  • sid_encode (Callable) –

Return type:

Mapping[str, Any]

get_attr(sid, attribute)[source]

Returns an attribute, a named piece of data, for the given Sid.

Parameters:

  • sid (str | Sid) – typed Sid

  • attribute (str) – attribute name

Returns:

The value for the given Sid and attribute name.

Return type:

Any | None

Writers

class spil.sid.write.writer.Writer[source]

A “Writer” implements CRUD’s Create/Update/Delete functions.

The Writer creates Sids, with or without attributes. It Updates and Sets “data” / attributes for given Sids. It also deletes Sids.

Writer is subclassed for the different data destinations, like the Filesystem or database management systems (WriteToPaths, WriteToShotgrid, etc.).

WriteToPaths (as FindInPaths) works with Sids on the Filesystem.

The goal of this CRUD formalisation is to propose a simple API around Sids. These features are still experimental.

(Finders and Getters implement read)

create(sid, data=None)[source]

Creates the given Sid, optionally with given data.

Parameters:

  • sid (Sid | str) – Sid string or instance

  • data (Optional[dict]) – optional data dictionary

Return type:

bool

Returns: True on success, False on failure

update(sid, data)[source]

Updates given data on given Sid.

Parameters:

  • sid (Sid | str) – Sid string or instance

  • data (Mapping[str, Any]) – data dictionary

Return type:

bool

Returns: True on success, False on failure

set(sid, attribute, value, **kwargs)[source]

Sets given attribute with given value, and / or given kwargs, for given Sid.

Parameters:

  • sid (Sid | str) – Sid string or instance

  • attribute (Optional[str]) – attribute name, data key

  • value (Optional[Any]) – value for data

  • **kwargs – key / value pairs.

Return type:

bool

Returns: True on success, False on failure

delete(sid)[source]

Deletes given Sid.

Parameters:

sid (Sid | str) – Sid string or instance

Return type:

bool

Returns: True on success, False on failure

class spil.sid.pathops.write_paths.WriteToPaths[source]

Writer to Paths. “Writers” implement the CRUD’s Create/Update/Delete functions.

WriteToPaths edits Sids and Sid data at the file system.

This class should be considered an example implementation. Although it can be considered useful, it is not by itself production ready. It is used to create mock/test files and folders for Sid testing purposes.

As FindInPaths and the sid.path() it is possible to instantiate this Writer with a fs config name. The config name points to the path templates config file.

Sids are created at the configured path. Sid File creation is either done by copy of a template file (if exists as configured), or by “touch”, which creates an empty file.

Data is created and updated in the form of a json file, at the same path, with a specific configured suffix.

__init__(config=None)[source]
Parameters:

config (Optional[str]) –

create(sid, data=None)[source]

Creates the given Sid, optionally with given data.

Parameters:

  • sid (Sid | str) – Sid string or instance

  • data (Optional[dict]) – optional data dictionary

Return type:

bool

Returns: True on success, False on failure

update(sid, data)[source]

Updates given data on given Sid.

Parameters:

  • sid (Sid | str) – Sid string or instance

  • data (Mapping[str, Any]) – data dictionary

Return type:

bool

Returns: True on success, False on failure

set(sid, attribute=None, value=None, **kwargs)[source]

Sets given attribute with given value, and / or given kwargs, for given Sid. Updates the data if it already exists.

Internally calls update().

Parameters:

  • sid (Sid | str) – Sid string or instance

  • attribute (Optional[str]) – attribute name, data key

  • value (Optional[Any]) – value for data

  • **kwargs – key / value pairs.

Return type:

bool

Returns: True on success, False on failure

delete(sid)[source]

Deletes given Sid.

Parameters:

sid (Sid | str) – Sid string or instance

Return type:

bool

Returns: True on success, False on failure