diff --git a/changes/302e6db2488f498de9471bf36bf1c716.yaml b/changes/302e6db2488f498de9471bf36bf1c716.yaml new file mode 100644 index 0000000000..e39c22a090 --- /dev/null +++ b/changes/302e6db2488f498de9471bf36bf1c716.yaml @@ -0,0 +1,5 @@ +--- +desc: Deprecate ``$lib.str.concat()``, ``$lib.str.format()``, and ``$lib.str.join()``. +prs: [] +type: deprecation +... diff --git a/changes/59b29a495a8dcd4f6980bcc90fa5cbe2.yaml b/changes/59b29a495a8dcd4f6980bcc90fa5cbe2.yaml new file mode 100644 index 0000000000..3df8ee61a8 --- /dev/null +++ b/changes/59b29a495a8dcd4f6980bcc90fa5cbe2.yaml @@ -0,0 +1,6 @@ +--- +desc: Deprecated the synchronous use of ``synapse.telepath.openurl()`` and the ability + to make Telepath RPC calls from synchronous Python code. +prs: [] +type: deprecation +... diff --git a/changes/69a809b0a24b0d4778c03e016be17bee.yaml b/changes/69a809b0a24b0d4778c03e016be17bee.yaml new file mode 100644 index 0000000000..63a4e82f76 --- /dev/null +++ b/changes/69a809b0a24b0d4778c03e016be17bee.yaml @@ -0,0 +1,5 @@ +--- +desc: Deprecate ``inet:web:*`` forms and the ``inet:search:query:acct`` property. +prs: [] +type: deprecation +... diff --git a/changes/a85cf6e33ca144dc7c2b5f4954b4c609.yaml b/changes/a85cf6e33ca144dc7c2b5f4954b4c609.yaml new file mode 100644 index 0000000000..b71d49efcd --- /dev/null +++ b/changes/a85cf6e33ca144dc7c2b5f4954b4c609.yaml @@ -0,0 +1,5 @@ +--- +desc: Deprecated ``synapse.glob.sync()`` and ``synapse.glob.synchelp()`` APIs. +prs: [] +type: deprecation +... diff --git a/changes/ad1f8b6ce1e797a664dfdac59e942793.yaml b/changes/ad1f8b6ce1e797a664dfdac59e942793.yaml new file mode 100644 index 0000000000..e49e57c6f6 --- /dev/null +++ b/changes/ad1f8b6ce1e797a664dfdac59e942793.yaml @@ -0,0 +1,5 @@ +--- +desc: Deprecated ``synapse.coro.genrhelp()`` and ``synapse.glob.GenrHelp()`` APIs. +prs: [] +type: deprecation +... diff --git a/docs/synapse/userguides/storm_adv_vars.rstorm b/docs/synapse/userguides/storm_adv_vars.rstorm index 6ae83b7a7e..0b2891f3a6 100644 --- a/docs/synapse/userguides/storm_adv_vars.rstorm +++ b/docs/synapse/userguides/storm_adv_vars.rstorm @@ -359,11 +359,11 @@ You can assign an explicit, unchanging value to a variable. You can assign the value of a particular node property (secondary or universal) to a variable. -- **Secondary property:** Assign the ``:user`` property from an Internet-based account (``inet:web:acct``) to +- **Secondary property:** Assign the ``:user`` property from an Service based account (``inet:service:account``) to the variable ``$user``: -.. storm-pre:: [inet:web:acct=(twitter.com,hacks4cats) :email=ron@protonmail.com] -.. storm-cli:: inet:web:acct=(twitter.com,hacks4cats) $user=:user $lib.print($user) +.. storm-pre:: $twitter={[inet:service:platform=({'name': 'twitter'})]} [inet:service:account=({'platform': $twitter.value(), 'user': 'hacks4cats', 'email': 'ron@protonmail.com'})] +.. storm-cli:: inet:service:account:user=hacks4cats $user=:user $lib.print($user) - **Universal property:** Assign the ``.seen`` universal property from a DNS A node to the variable ``$time``: diff --git a/docs/synapse/userguides/storm_ref_type_specific.rstorm b/docs/synapse/userguides/storm_ref_type_specific.rstorm index 8081bc02e6..639b5b7b9b 100644 --- a/docs/synapse/userguides/storm_ref_type_specific.rstorm +++ b/docs/synapse/userguides/storm_ref_type_specific.rstorm @@ -1468,11 +1468,11 @@ Lift all organizations whose name starts with the word "Acme ": .. storm-cli:: ou:org:name^='acme ' -Filter a set of Internet accounts to those with usernames starting with 'matrix': - -.. storm-pre:: [ inet:web:acct=(twitter.com,matrixmaster) inet:web:acct=(twitter.com,matrixneo) ] -.. storm-cli:: inet:web:acct:site=twitter.com +:user^=matrix +Filter a set of Service accounts to those with usernames starting with 'matrix': +.. storm-pre:: $twitter={[inet:service:platform=({'name': 'twitter'})]} [ inet:service:account=({'platform': $twitter.value(), 'user': 'matrixmaster'}) inet:service:account=({'platform': $twitter.value(), 'user': 'matrixneo'}) ] +e:account=({'platform': $twitter.value(), 'user': 'matrixneo'}) ] +.. storm-cli:: inet:service:account:platform=({'name': 'twitter'}) +:user^=matrix Strings and string-derived types can also be lifted or filtered using the regular expression extended comparator ( ``~=``) (see :ref:`lift-regex` and :ref:`filter-regex`). diff --git a/synapse/glob.py b/synapse/glob.py index faab5cafe0..278a8aa402 100644 --- a/synapse/glob.py +++ b/synapse/glob.py @@ -2,6 +2,7 @@ import signal import asyncio import logging +import warnings import threading import faulthandler @@ -10,6 +11,11 @@ _glob_loop = None _glob_thrd = None +# TODO Remove me in 3xx - this is just to avoid a circular import on synapse.common +def _deprecated(name, curv='2.x', eolv='3.0.0'): + mesg = f'"{name}" is deprecated in {curv} and will be removed in {eolv}' + warnings.warn(mesg, DeprecationWarning) + return mesg def _asynciostacks(*args, **kwargs): # pragma: no cover ''' @@ -83,6 +89,7 @@ def sync(coro, timeout=None): Notes: This API is thread safe and should only be called by non-loop threads. ''' + _deprecated('synapse.glob.sync - synchronous wrapping of coroutines is not supported: {f.__name__}') loop = initloop() return asyncio.run_coroutine_threadsafe(coro, loop).result(timeout) @@ -115,6 +122,7 @@ def wrap(*args, **kwargs): coro = f(*args, **kwargs) if not iAmLoop(): + _deprecated('synapse.glob.synchelp - synchronous wrapping of coroutines is not supported: {f.__name__}') return sync(coro) return coro diff --git a/synapse/lib/coro.py b/synapse/lib/coro.py index 50bada66cb..c58b81ce57 100644 --- a/synapse/lib/coro.py +++ b/synapse/lib/coro.py @@ -112,7 +112,7 @@ async def timewait(self, timeout=None): async def event_wait(event: asyncio.Event, timeout=None): ''' - Wait on an an asyncio event with an optional timeout + Wait on an asyncio event with an optional timeout Returns: true if the event got set, False if timed out @@ -189,6 +189,7 @@ async def await_bg_tasks(timeout=None): class GenrHelp: def __init__(self, genr): + s_common.deprecated('synapse.coro.GenrHelp()') assert genr is not None self.genr = genr @@ -220,6 +221,7 @@ async def list(self): return [x async for x in self.genr] def genrhelp(f): + s_common.deprecated('synapse.coro.genrhelp()') @functools.wraps(f) def func(*args, **kwargs): return GenrHelp(f(*args, **kwargs)) diff --git a/synapse/lib/stormtypes.py b/synapse/lib/stormtypes.py index 75175de176..4886b89307 100644 --- a/synapse/lib/stormtypes.py +++ b/synapse/lib/stormtypes.py @@ -1988,7 +1988,7 @@ class LibStr(Lib): ''' _storm_locals = ( {'name': 'join', 'desc': 'Join items into a string using a separator.', - # 'deprecated': {'eolvers': 'v3.0.0', 'mesg': 'Use ``('').join($foo, $bar, $baz, ....)`` instead.'}, + 'deprecated': {'eolvers': 'v3.0.0', 'mesg': 'Use ``('').join($foo, $bar, $baz, ....)`` instead.'}, 'type': {'type': 'function', '_funcname': 'join', 'args': ( {'name': 'sepr', 'type': 'str', 'desc': 'The separator used to join strings with.', }, @@ -1996,14 +1996,14 @@ class LibStr(Lib): ), 'returns': {'type': 'str', 'desc': 'The joined string.', }}}, {'name': 'concat', 'desc': 'Concatenate a set of strings together.', - # 'deprecated': {'eolvers': 'v3.0.0', 'mesg': "Use ``('').join($foo, $bar, $baz, ....)`` instead."}, + 'deprecated': {'eolvers': 'v3.0.0', 'mesg': "Use ``('').join($foo, $bar, $baz, ....)`` instead."}, 'type': {'type': 'function', '_funcname': 'concat', 'args': ( {'name': '*args', 'type': 'any', 'desc': 'Items to join together.', }, ), 'returns': {'type': 'str', 'desc': 'The joined string.', }}}, {'name': 'format', 'desc': 'Format a text string.', - # 'deprecated': {'eolvers': 'v3.0.0', 'mesg': 'Use ``$mystr.format(foo=$bar)`` instead.'}, + 'deprecated': {'eolvers': 'v3.0.0', 'mesg': 'Use ``$mystr.format(foo=$bar)`` instead.'}, 'type': {'type': 'function', '_funcname': 'format', 'args': ( {'name': 'text', 'type': 'str', 'desc': 'The base text string.', }, @@ -2014,9 +2014,9 @@ class LibStr(Lib): ) _storm_lib_path = ('str',) - # _lib_str_join_depr_mesg = '$lib.str.join(), use "$sepr.join($items)" instead.' - # _lib_str_concat_depr_mesg = "$lib.str.concat(), use ('').join($foo, $bar, $baz, ....) instead." - # _lib_str_format_depr_mesg = '$lib.str.format(), use "$mystr.format(foo=$bar)" instead.' + _lib_str_join_depr_mesg = '$lib.str.join(), use "$sepr.join($items)" instead.' + _lib_str_concat_depr_mesg = "$lib.str.concat(), use ('').join($foo, $bar, $baz, ....) instead." + _lib_str_format_depr_mesg = '$lib.str.format(), use "$mystr.format(foo=$bar)" instead.' def getObjLocals(self): return { @@ -2027,29 +2027,29 @@ def getObjLocals(self): @stormfunc(readonly=True) async def concat(self, *args): - # s_common.deprecated(self._lib_str_concat_depr_mesg) - # runt = s_scope.get('runt') - # if runt: - # await runt.snap.warnonce(self._lib_str_concat_depr_mesg) + s_common.deprecated(self._lib_str_concat_depr_mesg) + runt = s_scope.get('runt') + if runt: + await runt.snap.warnonce(self._lib_str_concat_depr_mesg) strs = [await tostr(a) for a in args] return ''.join(strs) @stormfunc(readonly=True) async def format(self, text, **kwargs): - # s_common.deprecated(self._lib_str_format_depr_mesg) - # runt = s_scope.get('runt') - # if runt: - # await runt.snap.warnonce(self._lib_str_format_depr_mesg) + s_common.deprecated(self._lib_str_format_depr_mesg) + runt = s_scope.get('runt') + if runt: + await runt.snap.warnonce(self._lib_str_format_depr_mesg) text = await kwarg_format(text, **kwargs) return text @stormfunc(readonly=True) async def join(self, sepr, items): - # s_common.deprecated(self._lib_str_join_depr_mesg) - # runt = s_scope.get('runt') - # if runt: - # await runt.snap.warnonce(self._lib_str_join_depr_mesg) + s_common.deprecated(self._lib_str_join_depr_mesg) + runt = s_scope.get('runt') + if runt: + await runt.snap.warnonce(self._lib_str_join_depr_mesg) strs = [await tostr(item) async for item in toiter(items)] return sepr.join(strs) diff --git a/synapse/models/inet.py b/synapse/models/inet.py index b8a1abd8cd..4a95bf63af 100644 --- a/synapse/models/inet.py +++ b/synapse/models/inet.py @@ -1419,64 +1419,74 @@ def getModelDefs(self): }), ('inet:web:acct', ('comp', {'fields': (('site', 'inet:fqdn'), ('user', 'inet:user')), 'sepr': '/'}), { - 'doc': 'An account with a given Internet-based site or service.', - 'ex': 'twitter.com/invisig0th' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:account.', }), ('inet:web:action', ('guid', {}), { - 'doc': 'An instance of an account performing an action at an Internet-based site or service.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:access.', }), ('inet:web:chprofile', ('guid', {}), { - 'doc': 'A change to a web account. Used to capture historical properties associated with ' - ' an account, as opposed to current data in the inet:web:acct node.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:access.', }), ('inet:web:file', ('comp', {'fields': (('acct', 'inet:web:acct'), ('file', 'file:bytes'))}), { - 'doc': 'A file posted by a web account.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:message and inet:service:message:attachment.' }), ('inet:web:attachment', ('guid', {}), { - 'doc': 'An instance of a file being sent to a web service by an account.'}), + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:message and inet:service:message:attachment.'}), ('inet:web:follows', ('comp', {'fields': (('follower', 'inet:web:acct'), ('followee', 'inet:web:acct'))}), { - 'doc': 'A web account follows or is connected to another web account.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:relationship.' }), ('inet:web:group', ('comp', {'fields': (('site', 'inet:fqdn'), ('id', 'inet:group')), 'sepr': '/'}), { - 'doc': 'A group hosted within or registered with a given Internet-based site or service.', - 'ex': 'somesite.com/mycoolgroup' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:group.', }), ('inet:web:logon', ('guid', {}), { - 'doc': 'An instance of an account authenticating to an Internet-based site or service.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:login.' }), ('inet:web:memb', ('comp', {'fields': (('acct', 'inet:web:acct'), ('group', 'inet:web:group'))}), { 'deprecated': True, - 'doc': 'Deprecated. Please use inet:web:member.' + 'doc': 'Deprecated. Please use inet:service:group:member', }), ('inet:web:member', ('guid', {}), { - 'doc': 'Represents a web account membership in a channel or group.', + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:channel:member or inet:service:group:member', }), ('inet:web:mesg', ('comp', {'fields': (('from', 'inet:web:acct'), ('to', 'inet:web:acct'), ('time', 'time'))}), { - 'doc': 'A message sent from one web account to another web account or channel.', - 'ex': '((twitter.com, invisig0th), (twitter.com, gobbles), 20041012130220)' + 'deprecated': True, + 'doc': 'Deprecated. Pleas use inet:service:message.', }), ('inet:web:post', ('guid', {}), { - 'doc': 'A post made by a web account.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:message.' }), ('inet:web:post:link', ('guid', {}), { - 'doc': 'A link contained within post text.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:message:link.' }), ('inet:web:instance', ('guid', {}), { - 'doc': 'An instance of a web service such as slack or discord.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:instance.' }), ('inet:web:channel', ('guid', {}), { - 'doc': 'A channel within a web service or instance such as slack or discord.' + 'deprecated': True, + 'doc': 'Deprecated. Please use inet:service:channel.' }), ('inet:web:hashtag', ('str', {'lower': True, 'strip': True, 'regex': r'^#[^\p{Z}#]+$'}), { @@ -2744,6 +2754,7 @@ def getModelDefs(self): 'doc': 'The time the web search was issued.', }), ('acct', ('inet:web:acct', {}), { + 'deprecated': True, 'doc': 'The account that the query was issued as.', }), ('host', ('it:host', {}), { diff --git a/synapse/telepath.py b/synapse/telepath.py index c7b01867ea..8137e46e14 100644 --- a/synapse/telepath.py +++ b/synapse/telepath.py @@ -395,7 +395,7 @@ def __enter__(self): ''' if s_threads.iden() == self.tid: raise s_exc.SynErr(mesg='Use of synchronous context manager in async code') - + s_common.deprecated('synapse.telepath.Share - synchronous context manager usage.') self._ctxobj = self.schedCoroSafePend(self.__aenter__()) return self @@ -432,7 +432,7 @@ async def __aiter__(self): await self.fini() def __iter__(self): - + s_common.deprecated('synaspe.telepath.Proxy - synchronous generator use.') try: while not self.isfini: @@ -492,6 +492,7 @@ async def __aiter__(self): await asyncio.sleep(0) def __iter__(self): + s_common.deprecated('synaspe.telepath.Proxy - synchronous generator use.') genr = s_glob.sync(self.proxy.task(self.todo, name=self.share)) for item in genr: yield item @@ -824,6 +825,7 @@ def __enter__(self): ''' if s_threads.iden() == self.tid: raise s_exc.SynErr(mesg='Use of synchronous context manager in async code') + s_common.deprecated('synapse.telepath.Proxy - synchronous context manager usage.') self._ctxobj = self.schedCoroSafePend(self.__aenter__()) return self diff --git a/synapse/tests/utils.py b/synapse/tests/utils.py index dce35e2fc3..de858ad36d 100644 --- a/synapse/tests/utils.py +++ b/synapse/tests/utils.py @@ -1066,12 +1066,13 @@ class SynTest(unittest.TestCase): ''' def __init__(self, *args, **kwargs): unittest.TestCase.__init__(self, *args, **kwargs) - for s in dir(self): attr = getattr(self, s, None) # If s is an instance method and starts with 'test_', synchelp wrap it if inspect.iscoroutinefunction(attr) and s.startswith('test_') and inspect.ismethod(attr): setattr(self, s, s_glob.synchelp(attr)) + s_common.deprecated('synchelp decorated test methods are deprecated. SynTest in Synapse 3.x.x ' + 'uses unittest.IsolatedAsyncioTestCase to run async test methods.') def checkNode(self, node, expected): ex_ndef, ex_props = expected