diff --git a/docs/source/helpers.rst b/docs/source/helpers.rst index d5dde3de..4e7383f9 100644 --- a/docs/source/helpers.rst +++ b/docs/source/helpers.rst @@ -10,6 +10,6 @@ We add helpers as method of ``CSTNode`` or ``libcst.helpers`` package based on t libcst.helpers -------------- -.. autofunction:: libcst.helpers.module.insert_header_comments -.. autofunction:: libcst.helpers.expression.get_full_name_for_node -.. autofunction:: libcst.ensure_type +.. autofunction:: libcst.helpers.insert_header_comments +.. autofunction:: libcst.helpers.get_full_name_for_node +.. autofunction:: libcst.helpers.ensure_type diff --git a/libcst/__init__.py b/libcst/__init__.py index a6df39bf..f37a8e1c 100644 --- a/libcst/__init__.py +++ b/libcst/__init__.py @@ -186,7 +186,9 @@ from libcst._parser.entrypoints import parse_expression, parse_module, parse_sta from libcst._parser.types.config import PartialParserConfig from libcst._removal_sentinel import RemovalSentinel, RemoveFromParent from libcst._visitors import CSTNodeT, CSTTransformer, CSTVisitor, CSTVisitorT -from libcst.helpers.expression import ensure_type +from libcst.helpers import ( # from libcst import ensure_type is deprecated, will be removed in 0.4.0 + ensure_type, +) from libcst.metadata.base_provider import ( BaseMetadataProvider, BatchableMetadataProvider, @@ -208,7 +210,7 @@ __all__ = [ "PartialParserConfig", "RemoveFromParent", "RemovalSentinel", - "ensure_type", + "ensure_type", # from libcst import ensure_type is deprecated, will be removed in 0.4.0 "visit_batched", "parse_module", "parse_expression", diff --git a/libcst/_nodes/tests/test_assert.py b/libcst/_nodes/tests/test_assert.py index 550b5c2c..4e05128c 100644 --- a/libcst/_nodes/tests/test_assert.py +++ b/libcst/_nodes/tests/test_assert.py @@ -10,7 +10,7 @@ from typing import Any import libcst as cst from libcst import parse_statement from libcst._nodes.tests.base import CSTNodeTest -from libcst.helpers.expression import ensure_type +from libcst.helpers import ensure_type from libcst.metadata import CodeRange from libcst.testing.utils import data_provider diff --git a/libcst/_nodes/tests/test_global.py b/libcst/_nodes/tests/test_global.py index d5c40f74..7df81739 100644 --- a/libcst/_nodes/tests/test_global.py +++ b/libcst/_nodes/tests/test_global.py @@ -9,7 +9,7 @@ from typing import Any import libcst as cst from libcst import parse_statement from libcst._nodes.tests.base import CSTNodeTest -from libcst.helpers.expression import ensure_type +from libcst.helpers import ensure_type from libcst.metadata import CodeRange from libcst.testing.utils import data_provider diff --git a/libcst/_nodes/tests/test_import.py b/libcst/_nodes/tests/test_import.py index 7dee6296..07a604a6 100644 --- a/libcst/_nodes/tests/test_import.py +++ b/libcst/_nodes/tests/test_import.py @@ -9,7 +9,7 @@ from typing import Any import libcst as cst from libcst import parse_statement from libcst._nodes.tests.base import CSTNodeTest -from libcst.helpers.expression import ensure_type +from libcst.helpers import ensure_type from libcst.metadata import CodeRange from libcst.testing.utils import data_provider diff --git a/libcst/_nodes/tests/test_nonlocal.py b/libcst/_nodes/tests/test_nonlocal.py index 19a9c594..634caccb 100644 --- a/libcst/_nodes/tests/test_nonlocal.py +++ b/libcst/_nodes/tests/test_nonlocal.py @@ -9,7 +9,7 @@ from typing import Any import libcst as cst from libcst import parse_statement from libcst._nodes.tests.base import CSTNodeTest -from libcst.helpers.expression import ensure_type +from libcst.helpers import ensure_type from libcst.metadata import CodeRange from libcst.testing.utils import data_provider diff --git a/libcst/_nodes/tests/test_raise.py b/libcst/_nodes/tests/test_raise.py index 84ddc3af..14c58755 100644 --- a/libcst/_nodes/tests/test_raise.py +++ b/libcst/_nodes/tests/test_raise.py @@ -9,7 +9,7 @@ from typing import Any import libcst as cst from libcst import parse_statement from libcst._nodes.tests.base import CSTNodeTest -from libcst.helpers.expression import ensure_type +from libcst.helpers import ensure_type from libcst.metadata import CodeRange from libcst.testing.utils import data_provider diff --git a/libcst/_nodes/tests/test_yield.py b/libcst/_nodes/tests/test_yield.py index 773b8d17..b09609aa 100644 --- a/libcst/_nodes/tests/test_yield.py +++ b/libcst/_nodes/tests/test_yield.py @@ -9,7 +9,7 @@ from typing import Callable, Optional import libcst as cst from libcst import parse_statement from libcst._nodes.tests.base import CSTNodeTest -from libcst.helpers.expression import ensure_type +from libcst.helpers import ensure_type from libcst.metadata import CodeRange from libcst.testing.utils import data_provider diff --git a/libcst/codemod/commands/add_pyre_directive.py b/libcst/codemod/commands/add_pyre_directive.py index 4a2bc210..93568899 100644 --- a/libcst/codemod/commands/add_pyre_directive.py +++ b/libcst/codemod/commands/add_pyre_directive.py @@ -10,7 +10,7 @@ from typing import Pattern import libcst from libcst.codemod import CodemodContext, VisitorBasedCodemodCommand -from libcst.helpers.module import insert_header_comments +from libcst.helpers import insert_header_comments class AddPyreDirectiveCommand(VisitorBasedCodemodCommand, ABC): diff --git a/libcst/codemod/commands/fix_pyre_directives.py b/libcst/codemod/commands/fix_pyre_directives.py index 8148e269..90e4bbc6 100644 --- a/libcst/codemod/commands/fix_pyre_directives.py +++ b/libcst/codemod/commands/fix_pyre_directives.py @@ -9,7 +9,7 @@ from typing import Dict, Sequence, Union import libcst import libcst.matchers as m from libcst.codemod import CodemodContext, VisitorBasedCodemodCommand -from libcst.helpers.module import insert_header_comments +from libcst.helpers import insert_header_comments class FixPyreDirectivesCommand(VisitorBasedCodemodCommand): diff --git a/libcst/codemod/visitors/_gather_imports.py b/libcst/codemod/visitors/_gather_imports.py index 356e336a..5e53745e 100644 --- a/libcst/codemod/visitors/_gather_imports.py +++ b/libcst/codemod/visitors/_gather_imports.py @@ -9,7 +9,7 @@ from typing import Dict, List, Optional, Sequence, Set, Tuple, Union import libcst from libcst.codemod._context import CodemodContext from libcst.codemod._visitor import ContextAwareVisitor -from libcst.helpers.expression import get_full_name_for_node +from libcst.helpers import get_full_name_for_node class GatherImportsVisitor(ContextAwareVisitor): diff --git a/libcst/helpers/__init__.py b/libcst/helpers/__init__.py index 7e2062ff..5ac35705 100644 --- a/libcst/helpers/__init__.py +++ b/libcst/helpers/__init__.py @@ -4,3 +4,10 @@ # LICENSE file in the root directory of this source tree. # # pyre-strict + +from libcst.helpers.common import ensure_type +from libcst.helpers.expression import get_full_name_for_node +from libcst.helpers.module import insert_header_comments + + +__all__ = ["get_full_name_for_node", "ensure_type", "insert_header_comments"] diff --git a/libcst/helpers/common.py b/libcst/helpers/common.py new file mode 100644 index 00000000..658789bc --- /dev/null +++ b/libcst/helpers/common.py @@ -0,0 +1,26 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +# +# pyre-strict +from typing import Type + +from libcst._types import CSTNodeT + + +def ensure_type(node: object, nodetype: Type[CSTNodeT]) -> CSTNodeT: + """ + Takes any python object, and a LibCST :class:`~libcst.CSTNode` subclass and + refines the type of the python object. This is most useful when you already + know that a particular object is a certain type but your type checker is not + convinced. Note that this does an instance check for you and raises an + exception if it is not the right type, so this should be used in situations + where you are sure of the type given previous checks. + """ + + if not isinstance(node, nodetype): + raise Exception( + f"Expected a {nodetype.__name__} bot got a {node.__class__.__name__}!" + ) + return node diff --git a/libcst/helpers/expression.py b/libcst/helpers/expression.py index 587b63ce..d10f5291 100644 --- a/libcst/helpers/expression.py +++ b/libcst/helpers/expression.py @@ -4,10 +4,9 @@ # LICENSE file in the root directory of this source tree. # # pyre-strict -from typing import Optional, Type, Union +from typing import Optional, Union import libcst as cst -from libcst._types import CSTNodeT def get_full_name_for_node(node: Union[str, cst.CSTNode]) -> Optional[str]: @@ -28,20 +27,3 @@ def get_full_name_for_node(node: Union[str, cst.CSTNode]) -> Optional[str]: elif isinstance(node, (cst.FunctionDef, cst.ClassDef)): return get_full_name_for_node(node.name) return None - - -def ensure_type(node: object, nodetype: Type[CSTNodeT]) -> CSTNodeT: - """ - Takes any python object, and a LibCST :class:`~libcst.CSTNode` subclass and - refines the type of the python object. This is most useful when you already - know that a particular object is a certain type but your type checker is not - convinced. Note that this does an instance check for you and raises an - exception if it is not the right type, so this should be used in situations - where you are sure of the type given previous checks. - """ - - if not isinstance(node, nodetype): - raise Exception( - f"Expected a {nodetype.__name__} bot got a {node.__class__.__name__}!" - ) - return node diff --git a/libcst/helpers/tests/test_expression.py b/libcst/helpers/tests/test_expression.py index cb84c9b5..915b99ea 100644 --- a/libcst/helpers/tests/test_expression.py +++ b/libcst/helpers/tests/test_expression.py @@ -7,7 +7,7 @@ from typing import Optional, Union import libcst as cst -from libcst.helpers.expression import get_full_name_for_node +from libcst.helpers import get_full_name_for_node from libcst.testing.utils import UnitTest, data_provider diff --git a/libcst/helpers/tests/test_module.py b/libcst/helpers/tests/test_module.py index 407dc8a7..fda8befe 100644 --- a/libcst/helpers/tests/test_module.py +++ b/libcst/helpers/tests/test_module.py @@ -5,7 +5,7 @@ # # pyre-strict import libcst -from libcst.helpers.module import insert_header_comments +from libcst.helpers import insert_header_comments from libcst.testing.utils import UnitTest diff --git a/libcst/metadata/scope_provider.py b/libcst/metadata/scope_provider.py index bedc4a7a..2fd6795a 100644 --- a/libcst/metadata/scope_provider.py +++ b/libcst/metadata/scope_provider.py @@ -28,7 +28,7 @@ from typing import ( import libcst as cst from libcst._add_slots import add_slots from libcst._metadata_dependent import MetadataDependent -from libcst.helpers.expression import get_full_name_for_node +from libcst.helpers import get_full_name_for_node from libcst.metadata.base_provider import BatchableMetadataProvider from libcst.metadata.expression_context_provider import ( ExpressionContext,