# encoding: utf-8

#

# Copyright (c) 2014 Dean Jackson <deanishe@deanishe.net>

#

# MIT Licence. See http://opensource.org/licenses/MIT

#

# Created on 2014-02-15

#

"""

The :class:`Workflow` object is the main interface to this library.

See :ref:`setup` in the :ref:`user-manual` for an example of how to set

up your Python script to best utilise the :class:`Workflow` object.

"""

from __future__ import print_function, unicode_literals

import binascii

from contextlib import contextmanager

import cPickle

from copy import deepcopy

import errno

import json

import logging

import logging.handlers

import os

import pickle

import plistlib

import re

import shutil

import signal

import string

import subprocess

import sys

import time

import unicodedata

try:

import xml.etree.cElementTree as ET

except ImportError: # pragma: no cover

import xml.etree.ElementTree as ET

#: Sentinel for properties that haven't been set yet (that might

#: correctly have the value ``None``)

UNSET = object()

####################################################################

# Standard system icons

####################################################################

# These icons are default OS X icons. They are super-high quality, and

# will be familiar to users.

# This library uses `ICON_ERROR` when a workflow dies in flames, so

# in my own workflows, I use `ICON_WARNING` for less fatal errors

# (e.g. bad user input, no results etc.)

# The system icons are all in this directory. There are many more than

# are listed here

ICON_ROOT = '/System/Library/CoreServices/CoreTypes.bundle/Contents/Resources'

ICON_ACCOUNT = os.path.join(ICON_ROOT, 'Accounts.icns')

ICON_BURN = os.path.join(ICON_ROOT, 'BurningIcon.icns')

ICON_CLOCK = os.path.join(ICON_ROOT, 'Clock.icns')

ICON_COLOR = os.path.join(ICON_ROOT, 'ProfileBackgroundColor.icns')

ICON_COLOUR = ICON_COLOR # Queen's English, if you please

ICON_EJECT = os.path.join(ICON_ROOT, 'EjectMediaIcon.icns')

# Shown when a workflow throws an error

ICON_ERROR = os.path.join(ICON_ROOT, 'AlertStopIcon.icns')

ICON_FAVORITE = os.path.join(ICON_ROOT, 'ToolbarFavoritesIcon.icns')

ICON_FAVOURITE = ICON_FAVORITE

ICON_GROUP = os.path.join(ICON_ROOT, 'GroupIcon.icns')

ICON_HELP = os.path.join(ICON_ROOT, 'HelpIcon.icns')

ICON_HOME = os.path.join(ICON_ROOT, 'HomeFolderIcon.icns')

ICON_INFO = os.path.join(ICON_ROOT, 'ToolbarInfo.icns')

ICON_NETWORK = os.path.join(ICON_ROOT, 'GenericNetworkIcon.icns')

ICON_NOTE = os.path.join(ICON_ROOT, 'AlertNoteIcon.icns')

ICON_SETTINGS = os.path.join(ICON_ROOT, 'ToolbarAdvanced.icns')

ICON_SWIRL = os.path.join(ICON_ROOT, 'ErasingIcon.icns')

ICON_SWITCH = os.path.join(ICON_ROOT, 'General.icns')

ICON_SYNC = os.path.join(ICON_ROOT, 'Sync.icns')

ICON_TRASH = os.path.join(ICON_ROOT, 'TrashIcon.icns')

ICON_USER = os.path.join(ICON_ROOT, 'UserIcon.icns')

ICON_WARNING = os.path.join(ICON_ROOT, 'AlertCautionIcon.icns')

ICON_WEB = os.path.join(ICON_ROOT, 'BookmarkIcon.icns')

####################################################################

# non-ASCII to ASCII diacritic folding.

# Used by `fold_to_ascii` method

####################################################################

ASCII_REPLACEMENTS = {

'À': 'A',

'Á': 'A',

'Â': 'A',

'Ã': 'A',

'Ä': 'A',

'Å': 'A',

'Æ': 'AE',

'Ç': 'C',

'È': 'E',

'É': 'E',

'Ê': 'E',

'Ë': 'E',

'Ì': 'I',

'Í': 'I',

'Î': 'I',

'Ï': 'I',

'Ð': 'D',

'Ñ': 'N',

'Ò': 'O',

'Ó': 'O',

'Ô': 'O',

'Õ': 'O',

'Ö': 'O',

'Ø': 'O',

'Ù': 'U',

'Ú': 'U',

'Û': 'U',

'Ü': 'U',

'Ý': 'Y',

'Þ': 'Th',

'ß': 'ss',

'à': 'a',

'á': 'a',

'â': 'a',

'ã': 'a',

'ä': 'a',

'å': 'a',

'æ': 'ae',

'ç': 'c',

'è': 'e',

'é': 'e',

'ê': 'e',

'ë': 'e',

'ì': 'i',

'í': 'i',

'î': 'i',

'ï': 'i',

'ð': 'd',

'ñ': 'n',

'ò': 'o',

'ó': 'o',

'ô': 'o',

'õ': 'o',

'ö': 'o',

'ø': 'o',

'ù': 'u',

'ú': 'u',

'û': 'u',

'ü': 'u',

'ý': 'y',

'þ': 'th',

'ÿ': 'y',

'Ł': 'L',

'ł': 'l',

'Ń': 'N',

'ń': 'n',

'Ņ': 'N',

'ņ': 'n',

'Ň': 'N',

'ň': 'n',

'Ŋ': 'ng',

'ŋ': 'NG',

'Ō': 'O',

'ō': 'o',

'Ŏ': 'O',

'ŏ': 'o',

'Ő': 'O',

'ő': 'o',

'Œ': 'OE',

'œ': 'oe',

'Ŕ': 'R',

'ŕ': 'r',

'Ŗ': 'R',

'ŗ': 'r',

'Ř': 'R',

'ř': 'r',

'Ś': 'S',

'ś': 's',

'Ŝ': 'S',

'ŝ': 's',

'Ş': 'S',

'ş': 's',

'Š': 'S',

'š': 's',

'Ţ': 'T',

'ţ': 't',

'Ť': 'T',

'ť': 't',

'Ŧ': 'T',

'ŧ': 't',

'Ũ': 'U',

'ũ': 'u',

'Ū': 'U',

'ū': 'u',

'Ŭ': 'U',

'ŭ': 'u',

'Ů': 'U',

'ů': 'u',

'Ű': 'U',

'ű': 'u',

'Ŵ': 'W',

'ŵ': 'w',

'Ŷ': 'Y',

'ŷ': 'y',

'Ÿ': 'Y',

'Ź': 'Z',

'ź': 'z',

'Ż': 'Z',

'ż': 'z',

'Ž': 'Z',

'ž': 'z',

'ſ': 's',

'Α': 'A',

'Β': 'B',

'Γ': 'G',

'Δ': 'D',

'Ε': 'E',

'Ζ': 'Z',

'Η': 'E',

'Θ': 'Th',

'Ι': 'I',

'Κ': 'K',

'Λ': 'L',

'Μ': 'M',

'Ν': 'N',

'Ξ': 'Ks',

'Ο': 'O',

'Π': 'P',

'Ρ': 'R',

'Σ': 'S',

'Τ': 'T',

'Υ': 'U',

'Φ': 'Ph',

'Χ': 'Kh',

'Ψ': 'Ps',

'Ω': 'O',

'α': 'a',

'β': 'b',

'γ': 'g',

'δ': 'd',

'ε': 'e',

'ζ': 'z',

'η': 'e',

'θ': 'th',

'ι': 'i',

'κ': 'k',

'λ': 'l',

'μ': 'm',

'ν': 'n',

'ξ': 'x',

'ο': 'o',

'π': 'p',

'ρ': 'r',

'ς': 's',

'σ': 's',

'τ': 't',

'υ': 'u',

'φ': 'ph',

'χ': 'kh',

'ψ': 'ps',

'ω': 'o',

'А': 'A',

'Б': 'B',

'В': 'V',

'Г': 'G',

'Д': 'D',

'Е': 'E',

'Ж': 'Zh',

'З': 'Z',

'И': 'I',

'Й': 'I',

'К': 'K',

'Л': 'L',

'М': 'M',

'Н': 'N',

'О': 'O',

'П': 'P',

'Р': 'R',

'С': 'S',

'Т': 'T',

'У': 'U',

'Ф': 'F',

'Х': 'Kh',

'Ц': 'Ts',

'Ч': 'Ch',

'Ш': 'Sh',

'Щ': 'Shch',

'Ъ': "'",

'Ы': 'Y',

'Ь': "'",

'Э': 'E',

'Ю': 'Iu',

'Я': 'Ia',

'а': 'a',

'б': 'b',

'в': 'v',

'г': 'g',

'д': 'd',

'е': 'e',

'ж': 'zh',

'з': 'z',

'и': 'i',

'й': 'i',

'к': 'k',

'л': 'l',

'м': 'm',

'н': 'n',

'о': 'o',

'п': 'p',

'р': 'r',

'с': 's',

'т': 't',

'у': 'u',

'ф': 'f',

'х': 'kh',

'ц': 'ts',

'ч': 'ch',

'ш': 'sh',

'щ': 'shch',

'ъ': "'",

'ы': 'y',

'ь': "'",

'э': 'e',

'ю': 'iu',

'я': 'ia',

# 'ᴀ': '',

# 'ᴁ': '',

# 'ᴂ': '',

# 'ᴃ': '',

# 'ᴄ': '',

# 'ᴅ': '',

# 'ᴆ': '',

# 'ᴇ': '',

# 'ᴈ': '',

# 'ᴉ': '',

# 'ᴊ': '',

# 'ᴋ': '',

# 'ᴌ': '',

# 'ᴍ': '',

# 'ᴎ': '',

# 'ᴏ': '',

# 'ᴐ': '',

# 'ᴑ': '',

# 'ᴒ': '',

# 'ᴓ': '',

# 'ᴔ': '',

# 'ᴕ': '',

# 'ᴖ': '',

# 'ᴗ': '',

# 'ᴘ': '',

# 'ᴙ': '',

# 'ᴚ': '',

# 'ᴛ': '',

# 'ᴜ': '',

# 'ᴝ': '',

# 'ᴞ': '',

# 'ᴟ': '',

# 'ᴠ': '',

# 'ᴡ': '',

# 'ᴢ': '',

# 'ᴣ': '',

# 'ᴤ': '',

# 'ᴥ': '',

'ᴦ': 'G',

'ᴧ': 'L',

'ᴨ': 'P',

'ᴩ': 'R',

'ᴪ': 'PS',

'ẞ': 'Ss',

'Ỳ': 'Y',

'ỳ': 'y',

'Ỵ': 'Y',

'ỵ': 'y',

'Ỹ': 'Y',

'ỹ': 'y',

}

####################################################################

# Smart-to-dumb punctuation mapping

####################################################################

DUMB_PUNCTUATION = {

'‘': "'",

'’': "'",

'‚': "'",

'“': '"',

'”': '"',

'„': '"',

'–': '-',

'—': '-'

}

####################################################################

# Used by `Workflow.filter`

####################################################################

# Anchor characters in a name

#: Characters that indicate the beginning of a "word" in CamelCase

INITIALS = string.ascii_uppercase + string.digits

#: Split on non-letters, numbers

split_on_delimiters = re.compile('[^a-zA-Z0-9]').split

# Match filter flags

#: Match items that start with ``query``

MATCH_STARTSWITH = 1

#: Match items whose capital letters start with ``query``

MATCH_CAPITALS = 2

#: Match items with a component "word" that matches ``query``

MATCH_ATOM = 4

#: Match items whose initials (based on atoms) start with ``query``

MATCH_INITIALS_STARTSWITH = 8

#: Match items whose initials (based on atoms) contain ``query``

MATCH_INITIALS_CONTAIN = 16

#: Combination of :const:`MATCH_INITIALS_STARTSWITH` and

#: :const:`MATCH_INITIALS_CONTAIN`

MATCH_INITIALS = 24

#: Match items if ``query`` is a substring

MATCH_SUBSTRING = 32

#: Match items if all characters in ``query`` appear in the item in order

MATCH_ALLCHARS = 64

#: Combination of all other ``MATCH_*`` constants

MATCH_ALL = 127

####################################################################

# Used by `Workflow.check_update`

####################################################################

# Number of days to wait between checking for updates to the workflow

DEFAULT_UPDATE_FREQUENCY = 1

####################################################################

# Lockfile and Keychain access errors

####################################################################

class AcquisitionError(Exception):

"""Raised if a lock cannot be acquired."""

class KeychainError(Exception):

"""Raised for unknown Keychain errors.

Raised by methods :meth:`Workflow.save_password`,

:meth:`Workflow.get_password` and :meth:`Workflow.delete_password`

when ``security`` CLI app returns an unknown error code.

"""

class PasswordNotFound(KeychainError):

"""Raised by method :meth:`Workflow.get_password` when ``account``

is unknown to the Keychain.

"""

class PasswordExists(KeychainError):

"""Raised when trying to overwrite an existing account password.

You should never receive this error: it is used internally

by the :meth:`Workflow.save_password` method to know if it needs

to delete the old password first (a Keychain implementation detail).

"""

####################################################################

# Helper functions

####################################################################

def isascii(text):

"""Test if ``text`` contains only ASCII characters.

:param text: text to test for ASCII-ness

:type text: ``unicode``

:returns: ``True`` if ``text`` contains only ASCII characters

:rtype: ``Boolean``

"""

try:

text.encode('ascii')

except UnicodeEncodeError:

return False

return True

####################################################################

# Implementation classes

####################################################################

class SerializerManager(object):

"""Contains registered serializers.

.. versionadded:: 1.8

A configured instance of this class is available at

``workflow.manager``.

Use :meth:`register()` to register new (or replace

existing) serializers, which you can specify by name when calling

:class:`Workflow` data storage methods.

See :ref:`manual-serialization` and :ref:`manual-persistent-data`

for further information.

"""

def __init__(self):

"""Create new SerializerManager object."""

self._serializers = {}

def register(self, name, serializer):

"""Register ``serializer`` object under ``name``.

Raises :class:`AttributeError` if ``serializer`` in invalid.

.. note::

``name`` will be used as the file extension of the saved files.

:param name: Name to register ``serializer`` under

:type name: ``unicode`` or ``str``

:param serializer: object with ``load()`` and ``dump()``

methods

"""

# Basic validation

getattr(serializer, 'load')

getattr(serializer, 'dump')

self._serializers[name] = serializer

def serializer(self, name):

"""Return serializer object for ``name``.

:param name: Name of serializer to return

:type name: ``unicode`` or ``str``

:returns: serializer object or ``None`` if no such serializer

is registered.

"""

return self._serializers.get(name)

def unregister(self, name):

"""Remove registered serializer with ``name``.

Raises a :class:`ValueError` if there is no such registered

serializer.

:param name: Name of serializer to remove

:type name: ``unicode`` or ``str``

:returns: serializer object

"""

if name not in self._serializers:

raise ValueError('No such serializer registered : {0}'.format(

name))

serializer = self._serializers[name]

del self._serializers[name]

return serializer

@property

def serializers(self):

"""Return names of registered serializers."""

return sorted(self._serializers.keys())

class JSONSerializer(object):

"""Wrapper around :mod:`json`. Sets ``indent`` and ``encoding``.

.. versionadded:: 1.8

Use this serializer if you need readable data files. JSON doesn't

support Python objects as well as ``cPickle``/``pickle``, so be

careful which data you try to serialize as JSON.

"""

@classmethod

def load(cls, file_obj):

"""Load serialized object from open JSON file.

.. versionadded:: 1.8

:param file_obj: file handle

:type file_obj: ``file`` object

:returns: object loaded from JSON file

:rtype: object

"""

return json.load(file_obj)

@classmethod

def dump(cls, obj, file_obj):

"""Serialize object ``obj`` to open JSON file.

.. versionadded:: 1.8

:param obj: Python object to serialize

:type obj: JSON-serializable data structure

:param file_obj: file handle

:type file_obj: ``file`` object

"""

return json.dump(obj, file_obj, indent=2, encoding='utf-8')

class CPickleSerializer(object):

"""Wrapper around :mod:`cPickle`. Sets ``protocol``.

.. versionadded:: 1.8

This is the default serializer and the best combination of speed and

flexibility.

"""

@classmethod

def load(cls, file_obj):

"""Load serialized object from open pickle file.

.. versionadded:: 1.8

:param file_obj: file handle

:type file_obj: ``file`` object

:returns: object loaded from pickle file

:rtype: object

"""

return cPickle.load(file_obj)

@classmethod

def dump(cls, obj, file_obj):

"""Serialize object ``obj`` to open pickle file.

.. versionadded:: 1.8

:param obj: Python object to serialize

:type obj: Python object

:param file_obj: file handle

:type file_obj: ``file`` object

"""

return cPickle.dump(obj, file_obj, protocol=-1)

class PickleSerializer(object):

"""Wrapper around :mod:`pickle`. Sets ``protocol``.

.. versionadded:: 1.8

Use this serializer if you need to add custom pickling.

"""

@classmethod

def load(cls, file_obj):

"""Load serialized object from open pickle file.

.. versionadded:: 1.8

:param file_obj: file handle

:type file_obj: ``file`` object

:returns: object loaded from pickle file

:rtype: object

"""

return pickle.load(file_obj)

@classmethod

def dump(cls, obj, file_obj):

"""Serialize object ``obj`` to open pickle file.

.. versionadded:: 1.8

:param obj: Python object to serialize

:type obj: Python object

:param file_obj: file handle

:type file_obj: ``file`` object

"""

return pickle.dump(obj, file_obj, protocol=-1)

# Set up default manager and register built-in serializers

manager = SerializerManager()

manager.register('cpickle', CPickleSerializer)

manager.register('pickle', PickleSerializer)

manager.register('json', JSONSerializer)

class Item(object):

"""Represents a feedback item for Alfred.

Generates Alfred-compliant XML for a single item.

You probably shouldn't use this class directly, but via

:meth:`Workflow.add_item`. See :meth:`~Workflow.add_item`

for details of arguments.

"""

def __init__(self, title, subtitle='', modifier_subtitles=None,

arg=None, autocomplete=None, valid=False, uid=None,

icon=None, icontype=None, type=None, largetext=None,

copytext=None):

"""Arguments the same as for :meth:`Workflow.add_item`.

"""

self.title = title

self.subtitle = subtitle

self.modifier_subtitles = modifier_subtitles or {}

self.arg = arg

self.autocomplete = autocomplete

self.valid = valid

self.uid = uid

self.icon = icon

self.icontype = icontype

self.type = type

self.largetext = largetext

self.copytext = copytext

@property

def elem(self):

"""Create and return feedback item for Alfred.

:returns: :class:`ElementTree.Element <xml.etree.ElementTree.Element>`

instance for this :class:`Item` instance.

"""

# Attributes on <item> element

attr = {}

if self.valid:

attr['valid'] = 'yes'

else:

attr['valid'] = 'no'

# Allow empty string for autocomplete. This is a useful value,

# as TABing the result will revert the query back to just the

# keyword

if self.autocomplete is not None:

attr['autocomplete'] = self.autocomplete

# Optional attributes

for name in ('uid', 'type'):

value = getattr(self, name, None)

if value:

attr[name] = value

root = ET.Element('item', attr)

ET.SubElement(root, 'title').text = self.title

ET.SubElement(root, 'subtitle').text = self.subtitle

# Add modifier subtitles

for mod in ('cmd', 'ctrl', 'alt', 'shift', 'fn'):

if mod in self.modifier_subtitles:

ET.SubElement(root, 'subtitle',

{'mod': mod}).text = self.modifier_subtitles[mod]

# Add arg as element instead of attribute on <item>, as it's more

# flexible (newlines aren't allowed in attributes)

if self.arg:

ET.SubElement(root, 'arg').text = self.arg

# Add icon if there is one

if self.icon:

if self.icontype:

attr = dict(type=self.icontype)

else:

attr = {}

ET.SubElement(root, 'icon', attr).text = self.icon

if self.largetext:

ET.SubElement(root, 'text',

{'type': 'largetype'}).text = self.largetext

if self.copytext:

ET.SubElement(root, 'text',

{'type': 'copy'}).text = self.copytext

return root

class LockFile(object):

"""Context manager to create lock files."""

def __init__(self, protected_path, timeout=0, delay=0.05):

"""Create new :class:`LockFile` object."""

self.lockfile = protected_path + '.lock'

self.timeout = timeout

self.delay = delay

self._locked = False

@property

def locked(self):

"""`True` if file is locked by this instance."""

return self._locked

def acquire(self, blocking=True):

"""Acquire the lock if possible.

If the lock is in use and ``blocking`` is ``False``, return

``False``.

Otherwise, check every `self.delay` seconds until it acquires

lock or exceeds `self.timeout` and raises an exception.

"""

start = time.time()

while True:

try:

fd = os.open(self.lockfile, os.O_CREAT | os.O_EXCL | os.O_RDWR)

with os.fdopen(fd, 'w') as fd:

fd.write('{0}'.format(os.getpid()))

break

except OSError as err:

if err.errno != errno.EEXIST: # pragma: no cover

raise

if self.timeout and (time.time() - start) >= self.timeout:

raise AcquisitionError('Lock acquisition timed out.')

if not blocking:

return False

time.sleep(self.delay)

self._locked = True

return True

def release(self):

"""Release the lock by deleting `self.lockfile`."""

self._locked = False

os.unlink(self.lockfile)

def __enter__(self):

"""Acquire lock."""

self.acquire()

return self

def __exit__(self, typ, value, traceback):

"""Release lock."""

self.release()

def __del__(self):

"""Clear up `self.lockfile`."""

if self._locked: # pragma: no cover

self.release()

@contextmanager

def atomic_writer(file_path, mode):

"""Atomic file writer.

:param file_path: path of file to write to.

:type file_path: ``unicode``

:param mode: sames as for `func:open`

:type mode: string

.. versionadded:: 1.12

Context manager that ensures the file is only written if the write

succeeds. The data is first written to a temporary file.

"""

temp_suffix = '.aw.temp'

temp_file_path = file_path + temp_suffix

with open(temp_file_path, mode) as file_obj:

try:

yield file_obj

os.rename(temp_file_path, file_path)

finally:

try:

os.remove(temp_file_path)

except (OSError, IOError):

pass

class uninterruptible(object):

"""Decorator that postpones SIGTERM until wrapped function is complete.

.. versionadded:: 1.12

Since version 2.7, Alfred allows Script Filters to be killed. If

your workflow is killed in the middle of critical code (e.g.

writing data to disk), this may corrupt your workflow's data.

Use this decorator to wrap critical functions that *must* complete.

If the script is killed while a wrapped function is executing,

the SIGTERM will be caught and handled after your function has

finished executing.

Alfred-Workflow uses this internally to ensure its settings, data

and cache writes complete.

.. important::

This decorator is NOT thread-safe.

"""

def __init__(self, func, class_name=''):

self.func = func

self._caught_signal = None

def signal_handler(self, signum, frame):

"""Called when process receives SIGTERM."""

self._caught_signal = (signum, frame)

def __call__(self, *args, **kwargs):

self._caught_signal = None

# Register handler for SIGTERM, then call `self.func`

self.old_signal_handler = signal.getsignal(signal.SIGTERM)

signal.signal(signal.SIGTERM, self.signal_handler)

self.func(*args, **kwargs)

# Restore old signal handler

signal.signal(signal.SIGTERM, self.old_signal_handler)

# Handle any signal caught during execution

if self._caught_signal is not None:

signum, frame = self._caught_signal

if callable(self.old_signal_handler):

self.old_signal_handler(signum, frame)

elif self.old_signal_handler == signal.SIG_DFL:

sys.exit(0)

def __get__(self, obj=None, klass=None):

return self.__class__(self.func.__get__(obj, klass),

klass.__name__)

class Settings(dict):

"""A dictionary that saves itself when changed.

Dictionary keys & values will be saved as a JSON file

at ``filepath``. If the file does not exist, the dictionary

(and settings file) will be initialised with ``defaults``.

:param filepath: where to save the settings

:type filepath: :class:`unicode`

:param defaults: dict of default settings

:type defaults: :class:`dict`

An appropriate instance is provided by :class:`Workflow` instances at

:attr:`Workflow.settings`.

"""

def __init__(self, filepath, defaults=None):

super(Settings, self).__init__()

self._filepath = filepath

self._nosave = False

self._original = {}

if os.path.exists(self._filepath):

self._load()

elif defaults:

for key, val in defaults.items():

self[key] = val

self.save() # save default settings

def _load(self):

"""Load cached settings from JSON file `self._filepath`"""

self._nosave = True

d = {}

with open(self._filepath, 'rb') as file_obj:

for key, value in json.load(file_obj, encoding='utf-8').items():

d[key] = value

self.update(d)

self._original = deepcopy(d)

self._nosave = False

@uninterruptible

def save(self):

"""Save settings to JSON file specified in ``self._filepath``

If you're using this class via :attr:`Workflow.settings`, which

you probably are, ``self._filepath`` will be ``settings.json``

in your workflow's data directory (see :attr:`~Workflow.datadir`).

"""

if self._nosave:

return