Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/libcst/_removal_sentinel.py: 83%

1# Copyright (c) Meta Platforms, Inc. and affiliates. 

2# 

3# This source code is licensed under the MIT license found in the 

4# LICENSE file in the root directory of this source tree. 

5 

6""" 

7Used by visitors. This is hoisted into a separate module to avoid some circular 

8dependencies in the definition of CSTNode. 

9""" 

10 

11from enum import auto, Enum 

12 

13 

14class RemovalSentinel(Enum): 

15 """ 

16 A :attr:`RemovalSentinel.REMOVE` value should be returned by a 

17 :meth:`CSTTransformer.on_leave` method when we want to remove that child from its 

18 parent. As a convenience, this can be constructed by calling 

19 :func:`libcst.RemoveFromParent`. 

20 

21 The parent node should make a best-effort to remove the child, but may raise an 

22 exception when removing the child doesn't make sense, or could change the semantics 

23 in an unexpected way. For example, a function definition with no name doesn't make 

24 sense, but removing one of the arguments is valid. 

25 

26 In we can't automatically remove the child, the developer should instead remove the 

27 child by constructing a new parent in the parent's :meth:`~CSTTransformer.on_leave` 

28 call. 

29 

30 We use this instead of ``None`` to force developers to be explicit about deletions. 

31 Because ``None`` is the default return value for a function with no return 

32 statement, it would be too easy to accidentally delete nodes from the tree by 

33 forgetting to return a value. 

34 """ 

35 

36 REMOVE = auto() 

37 

38 

39def RemoveFromParent() -> RemovalSentinel: 

40 """ 

41 A convenience method for requesting that this node be removed by its parent. 

42 Use this in place of returning :class:`RemovalSentinel` directly. 

43 For example, to remove all arguments unconditionally:: 

44 

45 def leave_Arg( 

46 self, original_node: cst.Arg, updated_node: cst.Arg 

47 ) -> Union[cst.Arg, cst.RemovalSentinel]: 

48 return RemoveFromParent() 

49 """ 

50 return RemovalSentinel.REMOVE