Release Notes

2.1.1

31 March 2021
  • changed

    DependenciesUpdate clique to 1.6.0 and remove constraints to python version.

  • fixed

    docsApi documentation is not building on read the docs platform.

2.1.0

23 November 2020
  • changed

    DocumentationUpdated workflow schema creation example with more readable statues and types. Added task template.

  • new

    eventssessionAdded new event ftrack.api.session.get-file-type-from-string to allow extension parsing customization.

  • changed

    DependenciesExplicitly link clique versions to python versions.

  • changed

    SessioncacheSchema cache is now saved per user, to avoid permissions conflicts on multi user Os. Please refer to the appdirs module documentation for the location of the local cache folder, for your operating system.

  • new

    SessionrequestsAdded new parameter timeout to Session with default value of 60 seconds to avoid infinity request on sudden disconnection.

  • changed

    DocumentationFix references to new python 3k support. Installing.

  • new

    DocumentationAdded advanced example of how to create workflow schemas Creating workflow schemas.

2.0.0

6 May 2020
  • new

    DocumentationAdded new section Set attributes on new entities to custom attributes known limitation.

  • fixed

    testsNote reply randomly fails.

  • fixed

    eventssessionEvent server wait method will sometimes raise a connection error because of a race condition.

  • changed

    websocketSelect highest available protocol version when connecting to websocket.

  • changed

    versionReplace fixed version with automatic versioning from git repository.

  • changed

    eventsNotify users on remote event server connection status while waiting.

  • fix

    Transfer component from server storage breaks due to different string/byte handling.

  • changed

    SessionPrivate method Session._entity_reference() has been deprecated.

    Note

    You should now use the public method Session.entity_reference().

  • changed

    SessionPrivate method Session._call() has been deprecated.

    Note

    You should now use the public method Session.call().

  • changed

    SessionPublic method Session.delayed_job() has been deprecated.

    Note

    You should now use Session.call().

  • fixed

    ApiLocationLocationMixins are not compatible with Python 3.

  • fixed

    TestEntity test fails due to missing parents.

  • new

    TestsAdd support for flaky tests to improve test reliability.

  • changed

    SessionDo not auto connect by default to event server hub.

  • new

    Provide support for python3.X.

1.8.2

14 January 2020
  • fixed

    Testtest_ensure_entity_with_non_string_data_types test fails due to missing parents.

  • changed

    sessionUse WeakMethod when registering atexit handler to prevent memory leak.

1.8.1

30 October 2019
  • changed

    LocationIncrease chunk size for file operations to 1 Megabyte. This value can now also be set from the environment variable:

    FTRACK_API_FILE_CHUNK_SIZE

  • new

    setupAdd check for correct python version when installing with pip.

  • new

    NotesAdd support for note labels in create_note helper method.

  • changed

    sessionEnsure errors from server are fully reported with stack trace.

1.8.0

21 February 2019
  • fixed

    documentationEvent description component-removed report component-added event signature.

  • new

    attributesessionAdd new scalar type object to factory.

  • new

    attributesessionAdd support for list of computed attributes as part of schema definition. A computed attribute is derived on the server side, and can be time dependentant and differ between users. As such a computed attribute is not suitable for long term encoding and will not be encoded with the persisted_only stragey.

  • changed

    The delayed_job method has been deprecated in favour of a direct Session.call. See Sync users with LDAP for example usage.

  • changed

    Private method Session._call() has been converted to a public method, Session.call().

    The private method will continue to work, but a pending deprecation warning will be issued when used. The private method will be removed entirely in version 2.0.

  • changed

    eventssessionEvent server connection error is too generic, the actual error is now reported to users.

1.7.1

13 November 2018
  • fixed

    eventssessionMeta events for event hub connect and disconnect does not include source.

  • fixed

    locationsessionMissing context argument to ResourceIdentifierTransformer.decode() in Location.get_resource_identifier().

1.7.0

27 July 2018
  • new

    eventssessionAdded new events ftrack.api.session.ready and ftrack.api.session.reset which can be used to perform operations after the session is ready or has been reset, respectively.

  • changed

    Private method Session._entity_reference() has been converted to a public method, Session.entity_reference().

    The private method will continue to work, but a pending deprecation warning will be issued when used. The private method will be removed entirely in version 2.0.

  • fixed

    eventssessionSession.close() raises an exception if event hub was explicitly connected after session initialization.

1.6.0

17 May 2018
  • new

    depreciationeventsIn version 2.0.0 of the ftrack-python-api the default behavior for the Session class will change for the argument auto_connect_event_hub, the default value will switch from True to False.

    A warning will now be emitted if async events are published or subscribed to without auto_connect_event_hub has not explicitly been set to True.

  • fixed

    documentationEvent payload not same as what is being emitted for ftrack.location.component-added and ftrack.location.component-removed.

  • fixed

    eventsPyparsing is causing random errors in a threaded environment.

1.5.0

19 April 2018
  • fixed

    cachesessionCached entities not updated correctly when fetched in a nested query.

1.4.0

5 February 2018

1.3.3

16 November 2017
  • new

    ldapusersAdd support for triggering a synchronization of users between ldap and ftrack. See Sync users with LDAP for example usage.

    Note

    This requires that you run ftrack 3.5.10 or later.

  • fixed

    Not possible to set metadata on creation.

1.3.2

18 September 2017
  • new

    task templateAdded example for managing task templates through the API. See Working with Task Templates for example usage.

  • fixed

    custom attributes

    Not possible to set hierarchical custom attributes on an entity that has not been committed.

  • fixed

    custom attributes

    Not possible to set custom attributes on an Asset that has not been committed.

  • fixed

    Not possible to set metadata on creation.

1.3.1

21 July 2017
  • fixed

    eventssessionCalling disconnect on the event hub is slow.

1.3.0

17 July 2017
  • new

    sessionSupport using a Session as a context manager to aid closing of session after use:

    with ftrack_api.Session() as session:
        # Perform operations with session.
    
  • new

    sessionSession.close() automatically called on Python exit if session not already closed.

  • new

    sessionAdded Session.close() to properly close a session’s connections to the server(s) as well as ensure event listeners are properly unsubscribed.

  • new

    Added ftrack_api.exception.ConnectionClosedError to represent error caused when trying to access servers over closed connection.

1.2.0

16 June 2017
  • changed

    eventsUpdated the websocket-client dependency to version >= 0.40.0 to allow for http proxies.

  • fixed

    documentationThe Publishing versions example incorrectly stated that a location would be automatically picked if the location keyword argument was omitted.

1.1.1

27 April 2017
  • fixed

    custom attributesCannot use custom attributes for Asset in ftrack versions prior to 3.5.0.

  • fixed

    documentationThe example section for managing text custom attributes is not correct.

1.1.0

8 March 2017
  • new

    server locationthumbnailAdded method get_thumbnail_url() to server location, which can be used to retrieve a thumbnail URL. See Retrieving thumbnail URL for example usage.

  • new

    documentationAdded example on how to manage entity links from the API.

  • new

    documentationAdded example on how to manage custom attribute configurations from the API.

  • new

    documentationAdded example on how to use SecurityRole and UserSecurityRole to manage security roles for users.

  • new

    documentationAdded examples to show how to list a user’s assigned tasks and all users assigned to a task.

  • changed

    pluginssessionAdded plugin_arguments to Session to allow passing of optional keyword arguments to discovered plugin register functions. Only arguments defined in a plugin register function signature are passed so existing plugin register functions do not need updating if the new functionality is not desired.

  • fixed

    documentationThe Working with projects example can be confusing since the project schema may not contain the necessary object types.

  • fixed

    documentationQuery tutorial article gives misleading information about the has operator.

  • fixed

    sessionSize is not set on sequence components when using Session.create_component().

1.0.4

13 January 2017
  • fixed

    custom attributesCustom attribute values cannot be set on entities that are not persisted.

  • fixed

    eventsusername in published event’s source data is set to the operating system user and not the API user.

1.0.3

4 January 2017
  • changed

    custom attributessessionIncreased performance of custom attributes and better support for filtering when using a version of ftrack that supports non-sparse attribute values.

  • changed

    custom attributessessionCustom attributes can no longer be set by mutating entire dictionary.

1.0.2

17 November 2016
  • changed

    sessionRemoved version restriction for higher server versions.

1.0.1

11 November 2016
  • fixed

    EventHub.publish on_reply callback only called for first received reply. It should be called for all relevant replies received.

1.0.0

28 October 2016
  • new

    sessionSession.get_upload_metadata() has been added.

  • changed

    backwards-incompatiblelocationsData transfer between locations using accessors is now chunked to avoid reading large files into memory.

  • changed

    server accessorftrack_api.accessor.server.ServerFile has been refactored to work with large files more efficiently.

  • changed

    server accessorftrack_api.accessor.server.ServerFile has been updated to use the get_upload_metadata API endpoint instead of /component/getPutMetadata.

  • changed

    locationsftrack_api.data.String is now using a temporary file instead of StringIO to avoid reading large files into memory.

  • fixed

    locationssessionftrack.centralized-storage does not properly validate location selection during user configuration.

0.16.0

18 October 2016
  • new

    encode mediasessionSession.encode_media() can now automatically associate the output with a version by specifying a version_id keyword argument. A new helper method on versions, AssetVersion.encode_media, can be used to make versions playable in a browser. A server version of 3.3.32 or higher is required for it to function properly.

    See also

    Encoding media.

  • changed

    encode mediasessionYou can now decide if Session.encode_media() should keep or delete the original component by specifying the keep_original keyword argument.

  • changed

    backwards-incompatiblecollectionCollection mutation now stores collection instance in operations rather than underlying data structure.

  • changed

    performanceImprove performance of commit operations by optimising encoding and reducing payload sent to server.

  • fixed

    documentationAsset parent variable is declared but never used in Publishing versions.

  • fixed

    documentationDocumentation of hierarchical attributes and their limitations are misleading. See Using custom attributes.

0.15.5

12 August 2016

0.15.4

12 July 2016
  • fixed

    queryingCustom offset not respected by QueryResult.first.

  • changed

    queryingUsing a custom offset with QueryResult.one helper method now raises an exception as an offset is inappropriate when expecting to select a single item.

  • fixed

    cachingLayeredCache.remove incorrectly raises KeyError if key only exists in sub-layer cache.

0.15.3

30 June 2016
  • fixed

    cachingsessionA newly created entity now has the correct ftrack_api.symbol.CREATED state when checked in caching layer. Previously the state was ftrack_api.symbol.NOT_SET. Note that this fix causes a change in logic and the stored ftrack_api.operation.CreateEntityOperation might hold data that has not been fully merged.

  • fixed

    documentationThe second example in the assignments article is not working.

  • changed

    cachingsessionA callable cache maker can now return None to indicate that it could not create a suitable cache, but Session instantiation can continue safely.

0.15.2

2 June 2016
  • new

    documentationAdded an example on how to work with assignments and allocations Working with assignments and allocations.

  • new

    documentationAdded Using entity links article with examples of how to manage asset version dependencies.

  • fixed

    performanceImprove performance of large collection management.

  • fixed

    Entities are not hashable because ftrack_api.entity.base.Entity.__hash__() raises TypeError.

0.15.1

2 May 2016
  • fixed

    attributecollectionperformanceCustom attribute configurations does not cache necessary keys, leading to performance issues.

  • fixed

    locationsstructureStandard structure does not work if version relation is not set on the Component.

0.15.0

4 April 2016
  • new

    locationssessionftrack.centralized-storage not working properly on Windows.

0.14.0

14 March 2016
  • changed

    locationssessionThe ftrack.centralized-storage configurator now validates that name, label and description for new locations are filled in.

  • new

    client reviewsessionAdded Session.send_review_session_invite() and Session.send_review_session_invites() that can be used to inform review session invitees about a review session.

    See also

    Usage guide.

  • new

    locationssessionAdded ftrack.centralized-storage configurator as a private module. It implements a wizard like interface used to configure a centralised storage scenario.

  • new

    locationssessionftrack.centralized-storage storage scenario is automatically configured based on information passed from the server with the query_server_information action.

  • new

    structureAdded ftrack_api.structure.standard.StandardStructure with hierarchy based resource identifier generation.

  • new

    documentationAdded more information to the Configuring plugins article.

  • fixed

    start_timer() arguments comment and name are ignored.

  • fixed

    stop_timer() calculates the wrong duration when the server is not running in UTC.

    For the duration to be calculated correctly ftrack server version >= 3.3.15 is required.

0.13.0

10 February 2016
  • new

    componentthumbnailAdded improved support for handling thumbnails.

  • new

    encode mediasessionAdded Session.encode_media() that can be used to encode media to make it playable in a browser.

    See also

    Encoding media.

  • fixed

    Session.commit() fails when setting a custom attribute on an asset version that has been created and committed in the same session.

  • new

    locationsAdded ftrack_api.entity.location.Location.get_url() to retrieve a URL to a component in a location if supported by the ftrack_api.accessor.base.Accessor.

  • new

    documentationUpdated Using notes and Managing jobs articles with examples of how to use note and job components.

  • changed

    loggingperformanceLogged messages now evaluated lazily using ftrack_api.logging.LazyLogMessage as optimisation.

  • changed

    eventssessionAuto connection of event hub for Session now takes place in background to improve session startup time.

  • changed

    eventssessionEvent hub connection timeout is now 60 seconds instead of 10.

  • changed

    server versionftrack server version >= 3.3.11, < 3.4 required.

  • changed

    performancequeryingftrack_api.query.QueryResult now pages internally using a specified page size in order to optimise record retrieval for large query results. Session.query() has also been updated to allow passing a custom page size at runtime if desired.

  • changed

    performancequeryingIncreased performance of first() and one() by using new limit syntax.

0.12.0

17 December 2015

0.11.0

4 December 2015
  • new

    documentationUpdated Migrating from old API with new link attribute and added a usage example.

  • new

    cachingperformanceschemasCaching of schemas for increased performance. ftrack_api.session.Session() now accepts schema_cache_path argument to specify location of schema cache. If not set it will use a temporary folder.

0.10.0

24 November 2015
  • changed

    testsUpdated session test to use mocked schemas for encoding tests.

  • fixed

    Documentation specifies Python 2.6 instead of Python 2.7 as minimum interpreter version.

  • fixed

    Documentation does not reflect current dependencies.

  • changed

    componentlocationsperformancesessionImproved performance of ftrack_api.entity.location.Location.add_components() by batching database operations.

    As a result it is no longer possible to determine progress of transfer for container components in realtime as events will be emitted in batch at end of operation.

    In addition, it is now the callers responsibility to clean up any transferred data should an error occur during either data transfer or database registration.

  • changed

    exceptionlocationsftrack_api.exception.ComponentInLocationError now accepts either a single component or multiple components and makes them available as components in its details parameter.

  • changed

    testsUpdated session test to not fail on the new private link attribute.

  • changed

    sessionInternal method _fetch_schemas() has beed renamed to Session._load_schemas() and now requires a schema_cache_path argument.

0.9.0

30 October 2015
  • new

    cachingAdded ftrack_api.cache.Cache.values() as helper for retrieving all values in cache.

  • fixed

    cachingsessionSession.merge() redundantly attempts to expand entity references that have already been expanded causing performance degradation.

  • new

    sessionSession.rollback() has been added to support cleanly reverting session state to last good state following a failed commit.

  • changed

    eventsEvent hub will no longer allow unverified SSL connections.

  • changed

    sessionSession.reset() no longer resets the connection. It also clears all local state and re-configures certain aspects that are cache dependant, such as location plugins.

  • fixed

    factoryDebug logging messages using incorrect index for formatting leading to misleading exception.

0.8.4

8 October 2015

0.8.3

28 September 2015
  • changed

    server versionftrack server version >= 3.2.1, < 3.4 required.

  • changed

    Updated ftrack.server location implementation. A server version of 3.3 or higher is required for it to function properly.

  • fixed

0.8.2

16 September 2015

0.8.1

8 September 2015

0.8.0

28 August 2015
  • changed

    server versionftrack server version >= 3.2.1, < 3.3 required.

  • new

    Added lists example.

    See also

    Using lists.

  • new

    Added convenience methods for handling timers start_timer and stop_timer.

  • changed

    The dynamic API classes Type, Status, Priority and StatusType have been renamed to Type, Status, Priority and State.

  • changed

    Session.reset() now also clears the top most level cache (by default a MemoryCache).

  • fixed

    Some invalid server url formats not detected.

  • fixed

    Reply events not encoded correctly causing them to be misinterpreted by the server.

0.7.0

24 August 2015
  • changed

    server versionftrack server version >= 3.2, < 3.3 required.

  • changed

    Removed automatic set of default statusid, priorityid and typeid on objects as that is now either not mandatory or handled on server.

  • changed

    Updated get_statuses() and get_types() to handle custom objects.

0.6.0

19 August 2015
  • changed

    server versionftrack server version >= 3.1.8, < 3.2 required.

  • changed

    documentationqueryingUpdated documentation with details on new operators has and any for querying relationships.

0.5.2

29 July 2015
  • changed

    server versionftrack server version 3.1.5 or greater required.

  • changed

    Server reported errors are now more readable and are no longer sometimes presented as an HTML page.

0.5.1

6 July 2015
  • changed

    Defaults computed by StandardFactory are now memoised per session to improve performance.

  • changed

    Memoiser now supports a return_copies parameter to control whether deep copies should be returned when a value was retrieved from the cache.

0.5.0

2 July 2015
  • changed

    Now checks for server compatibility and requires an ftrack server version of 3.1 or greater.

  • new

    Added convenience methods to QueryResult to fetch first() or exactly one() result.

  • new

    notesAdded support for handling notes.

    See also

    Using notes.

  • changed

    Collection attributes generate empty collection on first access when no remote value available. This allows interacting with a collection on a newly created entity before committing.

  • fixed

    sessionAmbiguous error raised when Session is started with an invalid user or key.

  • fixed

    cachingsessionSession.merge() fails against SerialisedCache when circular reference encountered due to entity identity not being prioritised in merge.

0.4.3

29 June 2015
  • fixed

    entity typespluginssessionEntity types not constructed following standard install.

    This is because the discovery of the default plugins is unreliable across Python installation processes (pip, wheel etc). Instead, the default plugins have been added as templates to the Event list documentation and the StandardFactory used to create any missing classes on Session startup.

0.4.2

26 June 2015
  • fixed

    Setting exact same metadata twice can cause ImmutableAttributeError to be incorrectly raised.

  • fixed

    sessionCalling Session.commit() does not clear locally set attribute values leading to immutability checks being bypassed in certain cases.

0.4.1

25 June 2015
  • fixed

    Setting metadata twice in one session causes KeyError.

0.4.0

22 June 2015
  • changed

    documentationDocumentation extensively updated.

  • new

    Client reviewAdded support for handling review sessions.

    See also

    Usage guide.

  • fixed

    Metadata property not working in line with rest of system, particularly the caching framework.

  • new

    collectionAdded ftrack_api.collection.MappedCollectionProxy class for providing a dictionary interface to a standard ftrack_api.collection.Collection.

  • new

    attributecollectionAdded ftrack_api.attribute.MappedCollectionAttribute class for describing an attribute that should use the ftrack_api.collection.MappedCollectionProxy.

  • new

    Entities that use composite primary keys are now fully supported in the session, including for Session.get() and Session.populate().

  • change

    Base ftrack_api.entity.factory.Factory refactored to separate out attribute instantiation into dedicated methods to make extending simpler.

  • change

    attributecollectionftrack_api.attribute.DictionaryAttribute and ftrack_api.attribute.DictionaryAttributeCollection removed. They have been replaced by the new ftrack_api.attribute.MappedCollectionAttribute and ftrack_api.collection.MappedCollectionProxy respectively.

  • new

    eventsSession now supports an auto_connect_event_hub argument to control whether the built in event hub should connect to the server on session initialisation. This is useful for when only local events should be supported or when the connection should be manually controlled.

0.3.0

14 June 2015
  • fixed

    Session operations may be applied server side in invalid order resulting in unexpected error.

  • fixed

    Creating and deleting an entity in single commit causes error as create operation never persisted to server.

    Now all operations for the entity are ignored on commit when this case is detected.

  • changed

    Internally moved from differential state to operation tracking for determining session changes when persisting.

  • new

    Session.recorded_operations attribute for examining current pending operations on a Session.

  • new

    Session.operation_recording() context manager for suspending recording operations temporarily. Can also manually control Session.record_operations boolean.

  • new

    Operation classes to track individual operations occurring in session.

  • new

    Public Session.merge() method for merging arbitrary values into the session manually.

  • changed

    An entity’s state is now computed from the operations performed on it and is no longer manually settable.

  • changed

    Entity.state attribute removed. Instead use the new inspection ftrack_api.inspection.state().

    Previously:

    print entity.state
    

    Now:

    import ftrack_api.inspection
    print ftrack_api.inspection.state(entity)
    

    There is also an optimised inspection, ftrack_api.inspection.states(). for determining state of many entities at once.

  • changed

    Shallow copying a ftrack_api.symbol.Symbol instance now returns same instance.

0.2.0

4 June 2015
  • changed

    Changed name of API from ftrack to ftrack_api.

    See also

    New API name.

  • new

    cachingConfigurable caching support in Session, including the ability to use an external persisted cache and new cache implementations.

    See also

    Caching.

  • new

    cachingSession.get() now tries to retrieve matching entity from configured cache first.

  • new

    cachingserialisationSession.encode() supports a new mode persisted_only that will only encode persisted attribute values.

  • changed

    Session.merge method is now private (Session._merge()) until it is qualified for general usage.

  • changed

    entity stateEntity state now managed on the entity directly rather than stored separately in the Session.

    Previously:

    session.set_state(entity, state)
    print session.get_state(entity)
    

    Now:

    entity.state = state
    print entity.state
    
  • changed

    entity stateEntity states are now ftrack_api.symbol.Symbol instances rather than strings.

    Previously:

    entity.state = 'created'
    

    Now:

    entity.state = ftrack_api.symbol.CREATED
    
  • fixed

    entity stateIt is now valid to transition from most entity states to an ftrack_api.symbol.NOT_SET state.

  • changed

    cachingEntityKeyMaker removed and replaced by StringKeyMaker. Entity identity now computed separately and passed to key maker to allow key maker to work with non entity instances.

  • fixed

    entityInternal data keys ignored when re/constructing entities reducing distracting and irrelevant warnings in logs.

  • fixed

    entityEntity equality test raises error when other is not an entity instance.

  • changed

    cachingentitymerge() now also merges state and local attributes. In addition, it ensures values being merged have also been merged into the session and outputs more log messages.

  • fixed

    inspectionftrack_api.inspection.identity() returns different result for same entity depending on whether entity type is unicode or string.

  • fixed

    ftrack_api.mixin() causes method resolution failure when same class mixed in multiple times.

  • changed

    Representations of objects now show plain id rather than converting to hex.

  • fixed

    eventsEvent hub raises TypeError when listening to ftrack.update events.

  • fixed

    eventsftrack_api.event.hub.EventHub.subscribe() fails when subscription argument contains special characters such as @ or +.

  • fixed

    collectionftrack_api.collection.Collection() incorrectly modifies entity state on initialisation.

0.1.0

25 March 2015
  • changed

    Moved standardised construct entity type logic to core package (as part of the StandardFactory) for easier reuse and extension.

0.1.0-beta.2

17 March 2015
  • new

    locationsSupport for ftrack.server location. The corresponding server build is required for it to function properly.

  • new

    locationsSupport for managing components in locations has been added. Check out the dedicated tutorial.

  • new

    A new inspection API (ftrack_api.inspection) has been added for extracting useful information from objects in the system, such as the identity of an entity.

  • changed

    Entity.primary_key and Entity.identity have been removed. Instead, use the new ftrack_api.inspection.primary_key() and ftrack_api.inspection.identity() functions. This was done to make it clearer the the extracted information is determined from the current entity state and modifying the returned object will have no effect on the entity instance itself.

  • changed

    ftrack_api.inspection.primary_key() now returns a mapping of the attribute names and values that make up the primary key, rather than the previous behaviour of returning a tuple of just the values. To emulate previous behaviour do:

    ftrack_api.inspection.primary_key(entity).values()
    
  • changed

    Session.encode() now supports different strategies for encoding entities via the entity_attribute_strategy* keyword argument. This makes it possible to use this method for general serialisation of entity instances.

  • changed

    Encoded referenced entities are now a mapping containing __entity_type__ and then each key, value pair that makes up the entity’s primary key. For example:

    {
        '__entity_type__': 'User',
        'id': '8b90a444-4e65-11e1-a500-f23c91df25eb'
    }
    
  • changed

    Session.decode() no longer automatically adds decoded entities to the Session cache making it possible to use decode independently.

  • new

    Added Session.merge() for merging entities recursively into the session cache.

  • fixed

    Replacing an entity in a ftrack_api.collection.Collection with an identical entity no longer raises ftrack_api.exception.DuplicateItemInCollectionError.