Source code for inkex.deprecated

# coding=utf-8
#
# Copyright (C) 2018 - Martin Owens <doctormo@mgail.com>
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#
"""
Provide some documentation to existing extensions about why they're failing.
"""
#
# We ignore a lot of pylint warnings here:
#
# pylint: disable=invalid-name,unused-argument,missing-docstring,too-many-public-methods
#

import os
import sys
import traceback
import warnings
import argparse
from argparse import ArgumentParser

import inkex
import inkex.utils
import inkex.units
from inkex.localization import _
from inkex.elements import Guide
from inkex.svg import SvgDocumentElement
from inkex.base import SvgThroughMixin, InkscapeExtension

warnings.simplefilter("default")
# To load each of the deprecated sub-modules (the ones without a namespace)
# we will add the directory to our pythonpath so older scripts can find them

INKEX_DIR = os.path.abspath(os.path.dirname(__file__))
SIMPLE_DIR = os.path.join(INKEX_DIR, 'deprecated-simple')

if os.path.isdir(SIMPLE_DIR):
    sys.path.append(SIMPLE_DIR)

try:
    DEPRECATION_LEVEL = int(os.environ.get('INKEX_DEPRECATION_LEVEL', 1))
except ValueError:
    DEPRECATION_LEVEL = 1

def _deprecated(msg, stack=2, level=DEPRECATION_LEVEL):
    """Internal method for raising a deprecation warning"""
    if level > 1:
        msg += ' ; '.join(traceback.format_stack())
    if level:
        warnings.warn(msg, category=DeprecationWarning, stacklevel=stack + 1)

[docs]class DeprecatedEffect(object): """An Inkscape effect, takes SVG in and outputs SVG, providing a deprecated layer""" def __init__(self): super(DeprecatedEffect, self).__init__() self._doc_ids = None # These are things we reference in the deprecated code, they are provided # by the new effects code, but we want to keep this as a Mixin so these # items will keep pylint happy and let use check our code as we write. if not hasattr(self, 'svg'): self.svg = SvgDocumentElement() if not hasattr(self, 'arg_parser'): self.arg_parser = ArgumentParser() if not hasattr(self, 'run'): self.run = self.affect @classmethod def _deprecated(cls, name, msg=_('{} is deprecated and should be removed'), stack=3): """Give the user a warning about their extension using a deprecated API""" _deprecated( msg.format('Effect.' + name, cls=cls.__module__ + '.' + cls.__name__), stack=stack) @property def OptionParser(self): self._deprecated( 'OptionParser', _('{} or `optparse` has been deprecated and replaced with `argparser`.' 'You must change `self.OptionParser.add_option` to ' '`self.arg_parser.add_argument`; the arguments are similar.')) return self
[docs] def add_option(self, *args, **kw): # Convert type string into type method as needed if 'type' in kw: kw['type'] = { 'string': str, 'int': int, 'float': float, 'inkbool': inkex.utils.inkbool, }.get(kw['type']) if kw.get('action', None) == 'store': # Default store action not required, removed. kw.pop('action') args = [arg for arg in args if arg != ""] self.arg_parser.add_argument(*args, **kw)
[docs] def effect(self): self._deprecated('effect', _('{} method is now a required method. It should ' 'be created on {cls}, even if it does nothing.'))
@property def current_layer(self): self._deprecated('current_layer',\ _('{} is now a method in the svg. Use `self.svg.get_current_layer()` instead.')) return self.svg.get_current_layer() @property def view_center(self): self._deprecated('view_center',\ _('{} is now a method in the svg. Use `self.svg.get_center_position()` instead.')) return self.svg.get_center_position() @property def selected(self): self._deprecated('selected', _('{} is now a dict in the svg. Use `self.svg.selected`.')) return self.svg.selected @property def doc_ids(self): self._deprecated('doc_ids', _('{} is now a method in the svg ' 'document. Use `self.svg.get_ids()` instead.')) if self._doc_ids is None: self._doc_ids = dict.fromkeys(self.svg.get_ids()) return self._doc_ids
[docs] def getdocids(self): self._deprecated('getdocids', _('Use `self.svg.get_ids()` instead of {} and `doc_ids`.')) self._doc_ids = None self.svg.ids.clear()
[docs] def getselected(self): self._deprecated('getselected', _('{} has been removed'))
[docs] def getElementById(self, eid): self._deprecated('getElementById',\ _('{} is now a method in the svg. Use `self.svg.getElementById(eid)` instead.')) return self.svg.getElementById(eid)
[docs] def xpathSingle(self, xpath): self._deprecated('xpathSingle', _('{} is now a new method in the svg ' 'document. Use `self.svg.getElement(path)` instead.`')) return self.svg.getElement(xpath)
[docs] def getParentNode(self, node): self._deprecated('getParentNode',\ _('{} is no longer in use. Use the lxml .getparent() method instead.')) return node.getparent()
[docs] def getNamedView(self): self._deprecated('getNamedView',\ _('{} is now a property of the svg. Use `self.svg.namedview` to access this element')) return self.svg.namedview
[docs] def createGuide(self, posX, posY, angle): self._deprecated('createGuide',\ _('{} is now a method of the namedview element object. ' 'Use `self.svg.namedview.add(Guide().move_to(x, y, a))` instead')) return self.svg.namedview.add(Guide().move_to(posX, posY, angle))
[docs] def affect(self, args=sys.argv[1:], output=True): # pylint: disable=dangerous-default-value # We need a list as the default value to preserve backwards compatibility self._deprecated('affect', _('{} is now `Effect.run()`. The `output` argument has changed.')) self._args = args[-1:] return self.run(args=args)
@property def args(self): self._deprecated('args', _('self.args[-1] is now self.options.input_file')) return self._args @property def svg_file(self): self._deprecated('svg_file', _('self.svg_file is now self.options.input_file')) return self.options.input_file
[docs] def save_raw(self, ret): # Derived class may implement "output()" # Attention: 'cubify.py' implements __getattr__ -> hasattr(self, 'output') returns True if hasattr(self.__class__, 'output'): self._deprecated('output', 'Use `save()` or `save_raw()` instead.', stack=5) return getattr(self, 'output')() return inkex.base.InkscapeExtension.save_raw(self, ret)
[docs] def uniqueId(self, old_id, make_new_id=True): self._deprecated('uniqueId', _('{} is now a method in the svg document. ' ' Use `self.svg.get_unique_id(old_id)` instead.')) return self.svg.get_unique_id(old_id)
[docs] def getDocumentWidth(self): self._deprecated('getDocumentWidth', _('{} is now a property of the svg ' 'document. Use `self.svg.width` instead.')) return self.svg.get('width')
[docs] def getDocumentHeight(self): self._deprecated('getDocumentHeight', _('{} is now a property of the svg ' 'document. Use `self.svg.height` instead.')) return self.svg.get('height')
[docs] def getDocumentUnit(self): self._deprecated('getDocumentUnit', _('{} is now a property of the svg ' 'document. Use `self.svg.unit` instead.')) return self.svg.unit
[docs] def unittouu(self, string): self._deprecated('unittouu', _('{} is now a method in the svg ' 'document. Use `self.svg.unittouu(str)` instead.')) return self.svg.unittouu(string)
[docs] def uutounit(self, val, unit): self._deprecated('uutounit', _('{} is now a method in the svg ' 'document. Use `self.svg.uutounit(value, unit)` instead.')) return self.svg.uutounit(val, unit)
[docs] def addDocumentUnit(self, value): self._deprecated('addDocumentUnit', _('{} is now a method in the svg ' 'document. Use `self.svg.add_unit(value)` instead.')) return self.svg.add_unit(value)
[docs]class Effect(SvgThroughMixin, DeprecatedEffect, InkscapeExtension): """An Inkscape effect, takes SVG in and outputs SVG""" pass
[docs]def deprecate(func): """Function decorator for deprecation functions which have a one-liner equivalent in the new API. The one-liner has to passed as a string to the decorator. >>> @deprecate >>> def someOldFunction(*args): >>> '''Example replacement code someNewFunction('foo', ...)''' >>> someNewFunction('foo', *args) Or if the args API is the same: >>> someOldFunction = deprecate(someNewFunction) """ def _inner(*args, **kwargs): _deprecated('{0.__module__}.{0.__name__} -> {0.__doc__}'.format(func), stack=2) return func(*args, **kwargs) _inner.__name__ = func.__name__ if func.__doc__: _inner.__doc__ = "Deprecated -> " + func.__doc__ return _inner
[docs]class DeprecatedDict(dict): @deprecate def __getitem__(self, key): return super(DeprecatedDict, self).__getitem__(key) @deprecate def __iter__(self): return super(DeprecatedDict, self).__iter__()
# legacy inkex members
[docs]class lazyproxy(object): """Proxy, use as decorator on a function with provides the wrapped object. The decorated function is called when a member is accessed on the proxy. """ def __init__(self, getwrapped): ''' :param getwrapped: Callable which returns the wrapped object ''' self._getwrapped = getwrapped def __getattr__(self, name): return getattr(self._getwrapped(), name) def __call__(self, *args, **kwargs): return self._getwrapped()(*args, **kwargs)
@lazyproxy def optparse(): _deprecated('inkex.optparse was removed, use "import optparse"', stack=3) import optparse as wrapped return wrapped @lazyproxy def etree(): _deprecated('inkex.etree was removed, use "from lxml import etree"', stack=3) from lxml import etree as wrapped return wrapped @lazyproxy def InkOption(): import optparse class wrapped(optparse.Option): TYPES = optparse.Option.TYPES + ("inkbool", ) TYPE_CHECKER = dict(optparse.Option.TYPE_CHECKER) TYPE_CHECKER["inkbool"] = lambda _1, _2, v: str(v).capitalize() == 'True' return wrapped
[docs]@lazyproxy def localize(): _deprecated('inkex.localize was moved to inkex.localization.localize', stack=3) from .localization import localize as wrapped return wrapped
[docs]def are_near_relative(a, b, eps): _deprecated('inkex.are_near_relative was moved to ' 'inkex.units.are_near_relative', stack=2) return inkex.units.are_near_relative(a, b, eps)
[docs]def debug(what): _deprecated('inkex.debug was moved to inkex.utils.debug', stack=2) return inkex.utils.debug(what)
# legacy inkex members <= 0.48.x
[docs]def unittouu(string): _deprecated('inkex.unittouu is now a method in the svg ' 'document. Use `self.svg.unittouu(str)` instead.', stack=2) return inkex.units.convert_unit(string, 'px')
# optparse.Values.ensure_value
[docs]def ensure_value(self, attr, value): _deprecated('Effect().options.ensure_value was removed', stack=2) if getattr(self, attr, None) is None: setattr(self, attr, value) return getattr(self, attr)
argparse.Namespace.ensure_value = ensure_value