pyflyby 1.9.6__tar.gz → 1.9.8__tar.gz

{pyflyby-1.9.6/lib/python/pyflyby.egg-info → pyflyby-1.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pyflyby
-Version: 1.9.6
+Version: 1.9.8
 Summary: pyflyby - Python development productivity tools, in particular automatic import management
 Home-page: https://pypi.org/project/pyflyby/
 Author: Karl Chen
@@ -16,7 +16,7 @@ Classifier: Topic :: Software Development :: Interpreters
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
-Requires-Python: >3.8, <4
+Requires-Python: >3.9, <4
 License-File: LICENSE.txt
 
 #########
@@ -113,7 +113,7 @@ configuration file:
 
 .. code:: python
 
-   
+
     from pyflyby import add_import
 
     add_import("foo", "foo = 1")
@@ -481,6 +481,38 @@ Emacs support
 - Pyflyby.el doesn't yet work with XEmacs; patches welcome.
 
 
+saveframe: A utility for debugging / reproducing an issue
+=========================================================
+
+PyFlyBy provides a utility named **saveframe** which can be used to save
+information for debugging / reproducing an issue.
+
+**Usage**: If you have a piece of code or a script that is failing due an issue
+originating from upstream code, and you cannot share your private code as a reproducer,
+use this utility to save relevant information to a file. Share the generated file with
+the upstream team, enabling them to reproduce and diagnose the issue independently.
+
+**Information saved in the file**: This utility captures and saves *error stack frames*
+to a file. It includes the values of local variables from each stack frame, as well
+as metadata about each frame and the exception raised by your code.
+
+This utility comes with 2 interfaces:
+
+1. **A function**: For interactive usages such as IPython, Jupyter Notebook, or a
+   debugger (pdb/ipdb), use **pyflyby.saveframe** function. To know how to use this
+   function, checkout it's documentation:
+
+.. code::
+
+   In [1]: saveframe?
+
+2. **A script**: For cli usages (like a failing script), use **pyflyby/bin/saveframe**
+   script. To know how to use this script, checkout its documentation:
+
+.. code::
+
+   $ saveframe --help
+
 Authorship
 ==========
 

{pyflyby-1.9.6 → pyflyby-1.9.8}/README.rst

@@ -92,7 +92,7 @@ configuration file:
 
 .. code:: python
 
-   
+
     from pyflyby import add_import
 
     add_import("foo", "foo = 1")
@@ -460,6 +460,38 @@ Emacs support
 - Pyflyby.el doesn't yet work with XEmacs; patches welcome.
 
 
+saveframe: A utility for debugging / reproducing an issue
+=========================================================
+
+PyFlyBy provides a utility named **saveframe** which can be used to save
+information for debugging / reproducing an issue.
+
+**Usage**: If you have a piece of code or a script that is failing due an issue
+originating from upstream code, and you cannot share your private code as a reproducer,
+use this utility to save relevant information to a file. Share the generated file with
+the upstream team, enabling them to reproduce and diagnose the issue independently.
+
+**Information saved in the file**: This utility captures and saves *error stack frames*
+to a file. It includes the values of local variables from each stack frame, as well
+as metadata about each frame and the exception raised by your code.
+
+This utility comes with 2 interfaces:
+
+1. **A function**: For interactive usages such as IPython, Jupyter Notebook, or a
+   debugger (pdb/ipdb), use **pyflyby.saveframe** function. To know how to use this
+   function, checkout it's documentation:
+
+.. code::
+
+   In [1]: saveframe?
+
+2. **A script**: For cli usages (like a failing script), use **pyflyby/bin/saveframe**
+   script. To know how to use this script, checkout its documentation:
+
+.. code::
+
+   $ saveframe --help
+
 Authorship
 ==========
 

{pyflyby-1.9.6 → pyflyby-1.9.8}/bin/pyflyby/__init__.py

@@ -32,6 +32,7 @@ from   pyflyby._interactive     import (disable_auto_importer,
 from   pyflyby._livepatch       import livepatch, xreload
 from   pyflyby._log             import logger
 from   pyflyby._parse           import PythonBlock, PythonStatement
+from   pyflyby._saveframe       import saveframe
 from   pyflyby._version         import __version__
 
 # Deprecated:

{pyflyby-1.9.6 → pyflyby-1.9.8}/bin/pyflyby/_autoimp.py

@@ -1,5 +1,5 @@
 # pyflyby/_autoimp.py.
-# Copyright (C) 2011, 2012, 2013, 2014, 2015, 2018, 2019 Karl Chen.
+# Copyright (C) 2011, 2012, 2013, 2014, 2015, 2018, 2019, 2024 Karl Chen.
 # License: MIT http://opensource.org/licenses/MIT
 
 
@@ -24,7 +24,7 @@ from   pyflyby._parse           import (PythonBlock, _is_ast_str,
 from   six                      import reraise
 import sys
 import types
-from   typing                   import Any, Set
+from   typing                   import Any, Set, Optional, List, Tuple
 
 if sys.version_info >= (3, 12):
     ATTRIBUTE_NAME = "value"
@@ -341,19 +341,26 @@ def symbol_needs_import(fullname, namespaces):
     return True
 
 
-class _UseChecker(object):
+class _UseChecker:
     """
     An object that can check whether it was used.
     """
-    used = False
 
-    def __init__(self, name, source, lineno):
+    used: bool = False
+    name: str
+    source: str
+    lineno: int
+
+    def __init__(self, name: str, source: str, lineno: int):
         self.name = name
         self.source = source # generally an Import
         self.lineno = lineno
 
+    def __repr__(self):
+        return f"<{type(self).__name__}: name:{self.name} source:{self.source!r} lineno:{self.lineno} used:{self.used}>"
+
 
-class _MissingImportFinder(object):
+class _MissingImportFinder:
     """
     A helper class to be used only by `_find_missing_imports_in_ast`.
 
@@ -371,8 +378,14 @@ class _MissingImportFinder(object):
 
     """
 
-    def __init__(self, scopestack, find_unused_imports=False,
-                 parse_docstrings=False):
+    scopestack: ScopeStack
+    _lineno: Optional[int]
+    missing_imports: List[Tuple[Optional[int], DottedIdentifier]]
+    parse_docstrings: bool
+    unused_imports: Optional[List[Tuple[int, str]]]
+    _deferred_load_checks: list[tuple[str, ScopeStack, Optional[int]]]
+
+    def __init__(self, scopestack, *, find_unused_imports:bool, parse_docstrings:bool):
         """
         Construct the AST visitor.
 
@@ -385,19 +398,26 @@ class _MissingImportFinder(object):
         # includes the globals dictionary.  ScopeStack() will make sure this
         # includes builtins.
         scopestack = ScopeStack(scopestack)
+
         # Add an empty namespace to the stack.  This facilitates adding stuff
         # to scopestack[-1] without ever modifying user globals.
         scopestack = scopestack.with_new_scope()
+
         self.scopestack = scopestack
+
         # Create data structure to hold the result.
         # missing_imports is a list of (lineno, DottedIdentifier) tuples.
         self.missing_imports = []
+
         # unused_imports is a list of (lineno, Import) tuples, if enabled.
         self.unused_imports = [] if find_unused_imports else None
+
         self.parse_docstrings = parse_docstrings
+
         # Function bodies that we need to check after defining names in this
         # function scope.
         self._deferred_load_checks = []
+
         # Whether we're currently in a FunctionDef.
         self._in_FunctionDef = False
         # Current lineno.
@@ -419,7 +439,8 @@ class _MissingImportFinder(object):
         finally:
             self.scopestack = oldscopestack
 
-    def scan_for_import_issues(self, codeblock):
+    def scan_for_import_issues(self, codeblock: PythonBlock):
+        assert isinstance(codeblock, PythonBlock)
         # See global `scan_for_import_issues`
         if not isinstance(codeblock, PythonBlock):
             codeblock = PythonBlock(codeblock)
@@ -588,7 +609,7 @@ class _MissingImportFinder(object):
             return
         if (len(node.targets) == 1 and isinstance(node.targets[0], ast.Name)
             and node.targets[0].id == '__all__'):
-            if not isinstance(node.value, ast.List):
+            if not isinstance(node.value, (ast.List, ast.Tuple)):
                 logger.warning("Don't know how to handle __all__ as (%s)" % node.value)
                 return
             if not all(_is_ast_str(e) for e in node.value.elts):
@@ -909,9 +930,8 @@ class _MissingImportFinder(object):
 
     def _visit_StoreImport(self, node, modulename):
         name = node.asname or node.name
-        logger.debug("_visit_StoreImport(asname=%r,name=%r)",
-                     node.asname, node.name)
-        is_star = node.name == '*'
+        logger.debug("_visit_StoreImport(asname=%r, name=%r)", node.asname, node.name)
+        is_star = node.name == "*"
         if is_star:
             logger.debug("Got star import: line %s: 'from %s import *'",
                          self._lineno, modulename)
@@ -998,10 +1018,11 @@ class _MissingImportFinder(object):
         # Don't call generic_visit(node) here.  Reason: We already visit the
         # parts above, if relevant.
 
-    def _visit_Load_defered_global(self, fullname):
+    def _visit_Load_defered_global(self, fullname:str):
         """
         Some things will be resolved in global scope later.
         """
+        assert isinstance(fullname, str), fullname
         logger.debug("_visit_Load_defered_global(%r)", fullname)
         if symbol_needs_import(fullname, self.scopestack):
             data = (fullname, self.scopestack, self._lineno)
@@ -1090,7 +1111,11 @@ class _MissingImportFinder(object):
         unused_imports.sort()
 
 
-def scan_for_import_issues(codeblock, find_unused_imports=True, parse_docstrings=False):
+def scan_for_import_issues(
+    codeblock: PythonBlock,
+    find_unused_imports: bool = True,
+    parse_docstrings: bool = False,
+):
     """
     Find missing and unused imports, by lineno.
 
@@ -1117,7 +1142,7 @@ def scan_for_import_issues(codeblock, find_unused_imports=True, parse_docstrings
         ([], [(1, Import('import baz'))])
 
     """
-    logger.debug("scan_for_import_issues()")
+    logger.debug("global scan_for_import_issues()")
     if not isinstance(codeblock, PythonBlock):
         codeblock = PythonBlock(codeblock)
     namespaces = ScopeStack([{}])
@@ -1148,7 +1173,10 @@ def _find_missing_imports_in_ast(node, namespaces):
     # Traverse the abstract syntax tree.
     if logger.debug_enabled:
         logger.debug("ast=%s", ast.dump(node))
-    return _MissingImportFinder(namespaces).find_missing_imports(node)
+    return _MissingImportFinder(
+                 namespaces,
+                 find_unused_imports=False,
+                 parse_docstrings=False).find_missing_imports(node)
 
 # TODO: maybe we should replace _find_missing_imports_in_ast with
 # _find_missing_imports_in_code(compile(node)).  The method of parsing opcodes

{pyflyby-1.9.6/lib/python → pyflyby-1.9.8/bin}/pyflyby/_importdb.py

@@ -284,7 +284,7 @@ class ImportDB:
         target_path = Path(target_filename).resolve()
 
         parents: List[Path]
-        if not target_path.is_dir():
+        if target_path.is_dir():
             parents = [target_path]
         else:
             parents = []
@@ -560,9 +560,11 @@ class ImportDB:
             filenames = [filenames]
         for f in filenames:
             assert isinstance(f, Filename)
-        logger.debug("ImportDB: loading [%s], mandatory=[%s]",
-                     ', '.join(map(str, filenames)),
-                     ', '.join(map(str, _mandatory_filenames_deprecated)))
+        logger.debug(
+            "ImportDB: loading %r, mandatory=%r",
+            [str(f) for f in filenames],
+            [str(f) for f in _mandatory_filenames_deprecated],
+        )
         if SUPPORT_DEPRECATED_BEHAVIOR:
             # Before 2014-10, pyflyby read the following:
             #   * known_imports from $PYFLYBY_PATH/known_imports/**/*.py or

{pyflyby-1.9.6 → pyflyby-1.9.8}/bin/pyflyby/_importstmt.py

@@ -96,7 +96,7 @@ If <module_name> is ``None``, then there is no "from" clause; instead just::
 """
 
 @total_ordering
-class Import(object):
+class Import:
     """
     Representation of the desire to import a single name into the current
     namespace.

{pyflyby-1.9.6 → pyflyby-1.9.8}/bin/pyflyby/_interactive.py

@@ -15,7 +15,7 @@ import re
 import subprocess
 import sys
 
-from typing import List, Any, Dict
+from typing import List, Any, Dict, Union, Literal
 
 
 from   pyflyby._autoimp         import (LoadSymbolError, ScopeStack, auto_eval,
@@ -2269,7 +2269,9 @@ class AutoImporter:
 
     def _safe_call(self, function, *args, **kwargs):
         on_error = kwargs.pop("on_error", None)
-        raise_on_error = kwargs.pop("raise_on_error", "if_debug")
+        raise_on_error: Union[bool, Literal["if_debug"]] = kwargs.pop(
+            "raise_on_error", "if_debug"
+        )
         if self._errored:
             # If we previously errored, then we should already have
             # unregistered the hook that led to here.  However, in some corner
@@ -2295,7 +2297,7 @@ class AutoImporter:
                     logger.error("Error trying to disable: %s: %s",
                                  type(e2).__name__, e2)
                 # Raise or print traceback in debug mode.
-                if raise_on_error == True:
+                if raise_on_error is True:
                     raise
                 elif raise_on_error == 'if_debug':
                     if logger.debug_enabled:
@@ -2305,7 +2307,7 @@ class AutoImporter:
                             import traceback
                             traceback.print_exc()
                         raise
-                elif raise_on_error == False:
+                elif raise_on_error is False:
                     if logger.debug_enabled:
                         import traceback
                         traceback.print_exc()
@@ -2328,8 +2330,13 @@ class AutoImporter:
                          sorted([k for k,v in autoimported.items() if not v]))
         self._autoimported_this_cell = {}
 
-    def auto_import(self, arg, namespaces=None,
-                    raise_on_error='if_debug', on_error=None):
+    def auto_import(
+        self,
+        arg,
+        namespaces=None,
+        raise_on_error: Union[bool, Literal["if_debug"]] = "if_debug",
+        on_error=None,
+    ):
         if namespaces is None:
             namespaces = get_global_namespaces(self._ip)
 

{pyflyby-1.9.6/lib/python → pyflyby-1.9.8/bin}/pyflyby/_parse.py

@@ -20,7 +20,7 @@ import re
 import sys
 from   textwrap                 import dedent
 import types
-from   typing                   import Any, List, Optional, Tuple, Union, cast
+from   typing                   import Any, List, Optional, Tuple, Union, cast, Literal
 import warnings
 
 
@@ -353,7 +353,7 @@ def _annotate_ast_nodes(ast_node: ast.AST) -> AnnotatedAst:
 
 
 def _annotate_ast_startpos(
-    ast_node: ast.AST, parent_ast_node, minpos, text, flags
+    ast_node: ast.AST, parent_ast_node, minpos: FilePos, text: FileText, flags
 ) -> bool:
     r"""
     Annotate ``ast_node``.  Set ``ast_node.startpos`` to the starting position
@@ -410,8 +410,8 @@ def _annotate_ast_startpos(
     # Walk all nodes/fields of the AST.  We implement this as a custom
     # depth-first search instead of using ast.walk() or ast.NodeVisitor
     # so that we can easily keep track of the preceding node's lineno.
-    child_minpos = minpos
-    is_first_child = True
+    child_minpos: FilePos = minpos
+    is_first_child: bool = True
     leftstr_node = None
     for child_node in _iter_child_nodes_in_order(aast_node):
         leftstr = _annotate_ast_startpos(
@@ -469,7 +469,16 @@ def _annotate_ast_startpos(
         # Not a multiline string literal.  (I.e., it could be a non-string or
         # a single-line string.)
         # Easy.
-        startpos = text.startpos + delta
+        if sys.version_info < (3, 12):
+            """There is an issue for f-strings at the begining of a file in 3.11 and
+            before
+
+            https://github.com/deshaw/pyflyby/issues/361,
+            here we ensure a child node min pos, can't be before it's parent.
+            """
+            startpos = max(text.startpos + delta, minpos)
+        else:
+            startpos = text.startpos + delta
 
         # Special case for 'with' statements.  Consider the code:
         #    with X: pass
@@ -668,7 +677,7 @@ def _ast_node_is_in_docstring_position(ast_node):
     return False
 
 
-def infer_compile_mode(arg):
+def infer_compile_mode(arg:ast.AST) -> Literal['exec','eval','single']:
     """
     Infer the mode needed to compile ``arg``.
 
@@ -679,19 +688,18 @@ def infer_compile_mode(arg):
     """
     # Infer mode from ast object.
     if isinstance(arg, ast.Module):
-        mode = "exec"
+        return "exec"
     elif isinstance(arg, ast.Expression):
-        mode = "eval"
+        return "eval"
     elif isinstance(arg, ast.Interactive):
-        mode = "single"
+        return "single"
     else:
         raise TypeError(
             "Expected Module/Expression/Interactive ast node; got %s"
             % (type(arg).__name__))
-    return mode
 
 
-class _DummyAst_Node(object):
+class _DummyAst_Node:
     pass
 
 
@@ -945,8 +953,9 @@ class PythonBlock:
         return cls.from_text(Filename(filename))
 
     @classmethod
-    def from_text(cls, text, filename=None, startpos=None, flags=None,
-                  auto_flags=False):
+    def from_text(
+        cls, text, filename=None, startpos=None, flags=None, auto_flags: bool = False
+    ):
         """
         :type text:
           `FileText` or convertible
@@ -1144,7 +1153,7 @@ class PythonBlock:
         else:
             return None
 
-    def parse(self, mode=None) -> Union[ast.Expression, ast.Module]:
+    def parse(self, mode: Optional[str] = None) -> Union[ast.Expression, ast.Module]:
         """
         Parse the source text into an AST.
 
@@ -1165,7 +1174,7 @@ class PythonBlock:
                 return self.expression_ast_node
             else:
                 raise SyntaxError
-        elif mode == None:
+        elif mode is None:
             if self.expression_ast_node:
                 return self.expression_ast_node
             else:
@@ -1176,7 +1185,7 @@ class PythonBlock:
         else:
             raise ValueError("parse(): invalid mode=%r" % (mode,))
 
-    def compile(self, mode=None):
+    def compile(self, mode: Optional[str] = None):
         """
         Parse into AST and compile AST into code.
 
@@ -1184,9 +1193,9 @@ class PythonBlock:
           ``CodeType``
         """
         ast_node = self.parse(mode=mode)
-        mode = infer_compile_mode(ast_node)
+        c_mode = infer_compile_mode(ast_node)
         filename = str(self.filename or "<unknown>")
-        return compile(ast_node, filename, mode)
+        return compile(ast_node, filename, c_mode)
 
     @cached_property
     def statements(self) -> Tuple[PythonStatement, ...]:

{pyflyby-1.9.6/lib/python → pyflyby-1.9.8/bin}/pyflyby/_py.py

@@ -286,19 +286,6 @@ from   typing                   import Any
 from   pyflyby._util            import cmp
 from   shlex                    import quote as shquote
 
-usage = """
-py --- command-line python multitool with automatic importing
-
-$ py [--file]   filename.py arg1 arg2      Execute file
-$ py [--apply]  function arg1 arg2         Call function
-$ py [--eval]  'function(arg1, arg2)'      Evaluate code
-$ py [--module] modname arg1 arg2          Run a module
-
-$ py --debug    file/code... args...       Debug code
-$ py --debug    PID                        Attach debugger to PID
-
-$ py                                       IPython shell
-""".strip()
 
 # TODO: add --tidy-imports, etc
 
@@ -377,6 +364,19 @@ from   pyflyby._modules         import ModuleHandle
 from   pyflyby._parse           import PythonBlock
 from   pyflyby._util            import indent, prefixes
 
+usage = """
+py --- command-line python multitool with automatic importing
+
+$ py [--file]   filename.py arg1 arg2      Execute file
+$ py [--apply]  function arg1 arg2         Call function
+$ py [--eval]  'function(arg1, arg2)'      Evaluate code
+$ py [--module] modname arg1 arg2          Run a module
+
+$ py --debug    file/code... args...       Debug code
+$ py --debug    PID                        Attach debugger to PID
+
+$ py                                       IPython shell
+""".strip()
 
 # Default compiler flags (feature flags) used for all user code.  We include
 # "print_function" here, but we also use auto_flags=True, which means
@@ -409,7 +409,7 @@ def _get_argspec(arg:Any) -> inspect.FullArgSpec:
         "_get_argspec: unexpected %s" % (type(arg).__name__,))
 
 
-def _requires_parens_as_function(function_name:str):
+def _requires_parens_as_function(function_name:str) -> bool:
     """
     Returns whether the given string of a callable would require parentheses
     around it to call it.
@@ -552,7 +552,7 @@ class _ParseInterruptedWantSource(Exception):
     pass
 
 
-class UserExpr(object):
+class UserExpr:
     """
     An expression from user input, and its evaluated value.
 
@@ -647,7 +647,7 @@ class UserExpr(object):
         else:
             raise ValueError("UserExpr(): bad arg_mode=%r" % (arg_mode,))
 
-    def _infer_and_evaluate(self):
+    def _infer_and_evaluate(self) -> None:
         if self._original_arg_mode == "raw_value":
             pass
         elif self._original_arg_mode == "eval":
@@ -891,7 +891,7 @@ class NotAFunctionError(Exception):
     pass
 
 
-def _get_help(expr, verbosity=1):
+def _get_help(expr:UserExpr, verbosity:int=1) -> str:
     """
     Construct a help string.
 
@@ -1053,7 +1053,7 @@ def auto_apply(function, commandline_args, namespace, arg_mode=None,
 
 
 @total_ordering
-class LoggedList(object):
+class LoggedList:
     """
     List that logs which members have not yet been accessed (nor removed).
     """