pyflyby 1.10.4__cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

pyflyby-1.10.4.data/scripts/saveframe

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""
+Utility to save information for debugging / reproducing an issue.
+
+Usage:
+If you have a script or command that is currently failing due to 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 (e.g.,
+error frames specific to the upstream codebase). 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 the user's script or command. Following is the
+sample structure of the info saved in the file:
+
+{
+    # 5th frame from the bottom
+    5: {
+            'frame_index': 5,
+            'filename': '/path/to/file.py',
+            'lineno': 3423,
+            'function_name': 'func1',
+            'function_qualname': 'FooClass.func1',
+            'function_object': <pickled object>,
+            'module_name': '<frame_module>'
+            'frame_identifier': '/path/to/file.py,3423,func1',
+            'code': '... python code line ...'
+            'variables': {'local_variable1': <pickled value>, 'local_variable2': <pickled value>, ...}
+        },
+    # 17th frame from the bottom
+    17: {
+            'frame_index': 17,
+            ...
+        },
+    ...
+    'exception_full_string': f'{exc.__class.__name__}: {exc}'
+    'exception_object': exc,
+    'exception_string': str(exc),
+    'exception_class_name': exc.__class__.__name__,
+    'exception_class_qualname': exc.__class__.__qualname__,
+    'traceback': '(multiline traceback)
+}
+
+NOTE:
+    - The above data gets saved in the file in pickled form.
+    - In the above data, the key of each frame's entry is the index of that frame
+      from the bottom of the error stack trace. So the first frame from the bottom
+      (the error frame) has index 1, and so on.
+    - 'variables' key in each frame's entry stores the local variables of that frame.
+    - The 'exception_object' key stores the actual exception object but without
+      the __traceback__ info (for security reasons).
+
+Example Usage:
+
+    Let's say your script / command is raising an error with the following traceback:
+
+    File "dir/__init__.py", line 6, in init_func1
+        func1()
+    File "dir/mod1.py", line 14, in func1
+        func2()
+    File "dir/mod1.py", line 9, in func2
+        obj.func2()
+    File "dir/pkg1/mod2.py", line 10, in func2
+        func3()
+    File "dir/pkg1/pkg2/mod3.py", line 6, in func3
+        raise ValueError("Error is raised")
+    ValueError: Error is raised
+
+    => To save the last frame (the error frame) in file '/path/to/file', use:
+    $ saveframe --filename=/path/to/file <script_or_command_to_run>
+
+    => To save a specific frame like `File "dir/mod1.py", line 9, in func2`, use:
+    $ saveframe --filename=/path/to/file --frames=mod1.py:9:func2 <script_or_command_to_run>
+
+    => To save the first 3 frames from the bottom, use:
+    $ saveframe --frames=3 <script_or_command_to_run>
+
+    => To save all the frames from 'mod1.py' and 'mod2.py' files, use:
+    $ saveframe --filename=/path/to/file --frames=mod1.py::,mod2.py:: <script_or_command_to_run>
+
+    => To save a range of frames from 'mod1.py' to 'mod3.py', use:
+    $ saveframe --frames=mod1.py::..mod3.py:: <script_or_command_to_run>
+
+    => To save a range of frames from '__init__.py' till the last frame, use:
+    $ saveframe --frames=__init__.py::.. <script_or_command_to_run>
+
+    => To only save local variables 'var1' and 'var2' from the frames, use:
+    $ saveframe --frames=frames_to_save --variables=var1,var2 <script_or_command_to_run>
+
+    => To exclude local variables 'var1' and 'var2' from the frames, use:
+    $ saveframe --frames=frames_to_save --exclude_variables=var1,var2 <script_or_command_to_run>
+
+For interactive use cases, checkout pyflyby.saveframe function.
+"""
+from __future__ import annotations
+
+# Save an unspoiled copy of globals for running the user program.
+globals_cpy = globals().copy()
+
+import argparse
+import os
+import sys
+
+from   pyflyby._saveframe       import (_SAVEFRAME_LOGGER,
+                                        _save_frames_and_exception_info_to_file,
+                                        _validate_saveframe_arguments)
+
+
+def getargs():
+    """
+    Parse the command-line arguments.
+    """
+    parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
+                                     description=__doc__,
+                                     prog=os.path.basename(sys.argv[0]))
+    parser.add_argument(
+        "--filename", default=None,
+        help="File path in which to save the frame information. If this file "
+             "already exists, it will be overwritten; otherwise, a new file will "
+             "be created with permission mode '0o644'\nDefault behavior: "
+             "If --filename is not passed, the info gets saved in the "
+             "'saveframe.pkl' file in the current working directory."
+    )
+    parser.add_argument(
+        "--frames", default=None,
+        help="Error stack frames to save.\n"
+             "Default behavior: If --frames is not passed, the first frame from "
+             "the bottom (the error frame) is saved.\n\n"
+             "A single frame follows the format "
+             "'filename:line_no:function_name', where:\n"
+             "    - filename: The file path or a regex pattern matching the file "
+             "path (displayed in the stack trace) of that error frame.\n"
+             "    - line_no (Optional): The code line number (displayed in the "
+             "stack trace) of that error frame.\n"
+             "    - function_name (Optional): The function name (displayed in "
+             "the stack trace) of that error frame.\n\n"
+             "Partial frames are also supported where line_no and/or function_name "
+             "can be omitted:\n"
+             "    - 'filename::' -> Includes all the frames that matches the filename\n"
+             "    - 'filename:line_no:' -> Include all the frames that matches "
+             "specific line in any function in the filename\n"
+             "    - 'filename::function_name' -> Include all the frames that matches "
+             "any line in the specific function in the filename\n\n"
+             "Following formats are supported to pass the frames:\n\n"
+             "1. Single frame:\n"
+             "   --frames=frame\n"
+             "   Example: --frames=/path/to/file.py:24:some_func\n"
+             "   Includes only the specified frame.\n\n"
+             "2. Multiple frames:\n"
+             "   --frames=frame1,frame2,...\n"
+             "   Example: --frames=/dir/foo.py:45:,.*/dir2/bar.py:89:caller\n"
+             "   Includes all specified frames.\n\n"
+             "3. Range of frames:\n"
+             "   --frames=first_frame..last_frame\n"
+             "   Example: --frames=/dir/foo.py:45:get_foo../dir3/blah.py:23:myfunc\n"
+             "   Includes all the frames from first_frame to last_frame (both inclusive).\n\n"
+             "4. Range from first_frame to bottom:\n"
+             "   --frames=first_frame..\n"
+             "   Example: --frames=/dir/foo.py:45:get_foo..\n"
+             "   Includes all the frames from first_frame to the bottom of the stack trace.\n\n"
+             "5. Number of Frames from Bottom:\n"
+             "   --frames=num\n"
+             "   Example: --frames=5\n"
+             "   Includes the first 'num' frames from the bottom of the stack trace."
+    )
+    parser.add_argument(
+        "--variables", default=None,
+        help="Local variables to include in each frame. Allowed format:\n"
+             "--variables=var1,var2,var3...\nExample: --variables=foo,bar\n\n"
+             "Default behavior: If --variables is not passed, save all the local "
+             "variables of the included frames."
+    )
+    parser.add_argument(
+        "--exclude_variables", default=None,
+        help="Local variables to exclude from each frame. Allowed format:\n"
+             "--exclude_variables=var1,var2,var3...\nExample: "
+             "--exclude_variables=foo,bar\n\n"
+             "Default behavior: If --exclude_variables is not passed, save all "
+             "the local variables of the included frames as per --variables."
+    )
+    parser.add_argument(
+        "command", default=argparse.SUPPRESS, nargs=argparse.REMAINDER,
+        help="User's script / command to execute.")
+    args = parser.parse_args()
+    return args
+
+
+def which(program):
+    """
+    Find the complete path of the ``program``.
+
+    :param program:
+      Program for which to find the complete path.
+    :return:
+      Complete path of the program.
+    """
+    if os.access(program, os.R_OK):
+        return program
+
+    fpath, fname = os.path.split(program)
+    if fpath:
+        if os.access(fpath, os.R_OK):
+            return program
+    else:
+        for path in os.environ["PATH"].split(os.pathsep):
+            exe_file = os.path.join(path, program)
+            if os.access(exe_file, os.X_OK):
+                return exe_file
+
+    return None
+
+
+def execfile(filepath):
+    """
+    Execute the script stored in ``filepath``.
+
+    :param filepath:
+      Path of the script to execute.
+    """
+    globals_cpy.update({
+        "__file__": filepath,
+        "__name__": "__main__",
+    })
+    with open(filepath, 'rb') as file:
+        exec(compile(file.read(), filepath, 'exec'), globals_cpy)
+
+
+def run_program(command):
+    """
+    Run a program.
+
+    :param command:
+      List containing the command to run.
+    """
+    if len(command) == 0:
+        raise SystemExit("Error: Please pass a valid script / command to run!")
+    if command[0] == '-c':
+        if len(command) == 1:
+            raise SystemExit("Error: Please pass a valid script / command to run!")
+        # Set sys.argv.  Mimic regular python -c by dropping the code but
+        # keeping the rest.
+        sys.argv = ['-c'] + command[2:]
+        globals_cpy['__file__'] = None
+        # Evaluate the command line code.
+        code = compile(command[1], "<stdin>", "exec")
+        eval(code)
+    else:
+        prog = which(command[0])
+        if not prog:
+            raise SystemExit(f"Error: Can't find the script / command: {command[0]!r}")
+
+        # Set sys.argv to mimic the command execution.
+        sys.argv = command
+        sys.path.insert(0, os.path.dirname(os.path.realpath(prog)))
+        execfile(prog)
+
+
+def main():
+    """
+    Main body of the script.
+    """
+    args = getargs()
+    # Validate the arguments.
+    filename, frames, variables, exclude_variables = _validate_saveframe_arguments(
+        filename=args.filename, frames=args.frames, variables=args.variables,
+        exclude_variables=args.exclude_variables, utility='script')
+    command = args.command
+    command_string = ' '.join(command)
+
+    if len(command) == 0:
+        raise SystemExit("Error: Please pass a valid script / command to run!")
+    if (command[0] in ['python', 'python3'] or command[0].endswith('/python')
+            or command[0].endswith('/python3')):
+        del command[0]
+
+    # Run the user script / command. Explicitly catch Exception and
+    # KeyboardInterrupt rather than BaseException, since we don't want to
+    # catch SystemExit.
+    try:
+        _SAVEFRAME_LOGGER.info("Executing the program: %a", command_string)
+        run_program(command)
+    except (Exception, KeyboardInterrupt) as err:
+        _SAVEFRAME_LOGGER.info(
+            "Saving frames and metadata info for the exception: %a", err)
+        # Save the frames and metadata info to the file.
+        _save_frames_and_exception_info_to_file(
+            filename=filename, frames=frames, variables=variables,
+            exclude_variables=exclude_variables,
+            exception_obj=err)
+    else:
+        raise SystemExit(
+            f"Error: No exception is raised by the program: {command_string!a}")
+
+
+if __name__ == '__main__':
+    main()

pyflyby-1.10.4.data/scripts/tidy-imports

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+tidy-imports *.py
+tidy-imports < foo.py
+
+Automatically improves python import statements.
+
+  - Adds missing imports and mandatory imports.
+  - Removes unused imports.
+  - Nicely formats imports (sorts, aligns, wraps).
+
+If filenames are given on the command line, rewrites them.  Otherwise, if
+stdin is not a tty, read from stdin and write to stdout.
+
+Only top-level import statements are touched.
+
+"""
+
+# pyflyby/tidy-imports
+# Copyright (C) 2011, 2012, 2014 Karl Chen.
+# License: MIT http://opensource.org/licenses/MIT
+
+
+from   pyflyby._cmdline         import (_get_pyproj_toml_config, hfmt,
+                                        parse_args, process_actions)
+from   pyflyby._import_sorting  import sort_imports
+from   pyflyby._imports2s       import (canonicalize_imports,
+                                        fix_unused_and_missing_imports,
+                                        replace_star_imports,
+                                        transform_imports)
+from   pyflyby._parse           import PythonBlock
+
+
+def _addopts(parser):
+    """
+    Callbacks to the parser to fill in extra options.
+    """
+    parser.add_option('--add-missing',
+                        default=True, action='store_true',
+                        help=hfmt('''
+                            (Default) Add missing imports.'''))
+    parser.add_option('--no-add-missing', dest='add_missing',
+                        default=True, action='store_false',
+                        help=hfmt('''
+                            Don't add missing imports.'''))
+    parser.add_option('--remove-unused',
+                        default="AUTOMATIC", action='store_true',
+                        help=hfmt('''
+                            Remove unused imports
+                            (default unless filename == __init__.py).'''))
+    parser.add_option('--no-remove-unused', dest='remove_unused',
+                        action='store_false',
+                        help=hfmt('''
+                            Don't remove unused imports
+                            (default if filename == __init__.py).'''))
+    parser.add_option('--add-mandatory',
+                        default=True, action='store_true',
+                        help=hfmt('''
+                            (Default) Add mandatory imports.'''))
+    parser.add_option('--no-add-mandatory', dest='add_mandatory',
+                        default=True, action='store_false',
+                        help=hfmt('''
+                            Don't add mandatory imports.'''))
+    parser.add_option('--replace-star-imports',
+                        default=False, action='store_true',
+                        help=hfmt('''
+                            Replace 'from foo.bar import *' with full list
+                            of imports before removing unused imports.'''))
+    parser.add_option('--no-replace-star-imports',
+                        dest='replace_star_imports',
+                        action='store_false',
+                        help=hfmt('''
+                            (Default) Don't replace 'from foo.bar import
+                            *'.'''))
+    parser.add_option('--canonicalize',
+                        default=True, action='store_true',
+                        help=hfmt('''
+                            (Default) Replace imports with canonical
+                            equivalent imports, according to database.'''))
+    parser.add_option('--experimental-sort-imports',
+                        default=False, action='store_true',
+                        help=hfmt('''
+                            experimental import sorting'''))
+    parser.add_option('--no-canonicalize', dest='canonicalize',
+                        default=True, action='store_false',
+                        help=hfmt('''
+                            Don't canonicalize imports.'''))
+    parser.add_option('--exclude', type='string', dest='exclude',
+                        action='append', help=hfmt('Files to exclude from formatting.'))
+
+
+    def transform_callback(option, opt_str, value, group):
+        k, v = value.split("=", 1)
+        group.values.transformations[k] = v
+    parser.add_option("--transform", action='callback',
+                        type="string", callback=transform_callback,
+                        metavar="OLD=NEW",
+                        dest="transformations", default={},
+                        help=hfmt('''
+                            Replace OLD with NEW in imports.
+                            May be specified multiple times.'''))
+    def no_add_callback(option, opt_str, value, group):
+        group.values.add_missing = False
+        group.values.add_mandatory = False
+    parser.add_option('--no-add', action='callback',
+                        callback=no_add_callback,
+                        help=hfmt('''
+                            Equivalent to --no-add-missing
+                            --no-add-mandatory.'''))
+def main() -> None:
+
+    config = _get_pyproj_toml_config()
+    if config:
+        default_config = config.get('tool', {}).get('pyflyby',{})
+    else:
+        default_config = {}
+
+    def _add_opts_and_defaults(parser):
+        _addopts(parser)
+        parser.set_defaults(**default_config)
+
+    options, args = parse_args(
+        _add_opts_and_defaults,
+        import_format_params=True,
+        modify_action_params=True,
+    )
+
+    def modify(block:PythonBlock) -> PythonBlock:
+        if options.transformations:
+            block = transform_imports(block, options.transformations,
+                                  params=options.params)
+        if options.replace_star_imports:
+            block = replace_star_imports(block, params=options.params)
+        block = fix_unused_and_missing_imports(
+            block, params=options.params,
+            add_missing=options.add_missing,
+            remove_unused=options.remove_unused,
+            add_mandatory=options.add_mandatory,
+            )
+        # TODO: disable sorting until we figure out #287
+        # https://github.com/deshaw/pyflyby/issues/287
+
+        # here we get a (single?) PythonBlock, we can access each statement with
+        # >>> block.statements
+        # and each statement can have a:
+        # is_import
+        # or
+        # is_comment or blank
+
+        # TODO: we do Python(str(...)) in order to unparse-reparse and get proper ast node numbers.
+        if options.experimental_sort_imports:
+            sorted_imports = PythonBlock(str(sort_imports(block)))
+        else:
+            sorted_imports = block
+        if options.canonicalize:
+            cannonical_imports = canonicalize_imports(sorted_imports, params=options.params)
+        else:
+            cannonical_imports = sorted_imports
+        return cannonical_imports
+
+    cmdline_exclude = getattr(options, "exclude")
+    process_actions(
+        args,
+        options.actions, modify,
+        exclude=default_config.get('tidy-imports', {}).get('exclude', []) + (cmdline_exclude if cmdline_exclude else [])
+    )
+
+
+if __name__ == '__main__':
+    main()

pyflyby-1.10.4.data/scripts/transform-imports

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+transform-imports --transform aa.bb=xx.yy *.py
+transform-imports --transform aa.bb=xx.yy < foo.py
+
+Transforms::
+  from aa.bb.cc import dd, ee
+  from aa import bb
+to::
+  from xx.yy.cc import dd, ee
+  from xx import yy as bb
+
+If filenames are given on the command line, rewrites them.  Otherwise, if
+stdin is not a tty, read from stdin and write to stdout.
+
+"""
+
+# pyflyby/transform-imports
+# Copyright (C) 2014 Karl Chen.
+# License: MIT http://opensource.org/licenses/MIT
+
+
+from   pyflyby._cmdline         import hfmt, parse_args, process_actions
+from   pyflyby._imports2s       import transform_imports
+
+
+def main():
+    transformations = {}
+    def addopts(parser):
+        def callback(option, opt_str, value, group):
+            k, v = value.split("=", 1)
+            transformations[k] = v
+        parser.add_option("--transform", action='callback',
+                          type="string", callback=callback,
+                          metavar="OLD=NEW",
+                          help=hfmt('''
+                                Replace OLD with NEW in imports.
+                                May be specified multiple times.'''))
+    options, args = parse_args(
+        addopts, import_format_params=True, modify_action_params=True)
+    def modify(x):
+        return transform_imports(x, transformations, params=options.params)
+    process_actions(args, options.actions, modify)
+
+
+if __name__ == '__main__':
+    main()