py-imports 1.3.0

  # Absolute imports
  #  --- from py_imports.manager import PyImports ---
  # If we introspect the object, we will get the following
 
  example_abs_import = absolute_imports[0]
  example_abs_import.children -> ['PyImports']
  example_abs_import.parent -> 'py_imports.manager'
  example_abs_import.statement -> 'from py_imports.manager import PyImports'
  example_abs_import.level -> 0
  example_abs_import.line -> 2

  # relative imports
  #  --- from .parse_local_dir import file_imports_from_dir_one ---
  # If we introspect the object, we will get the following
 
  example_relative_import = relative_imports[0]
  example_abs_import.children -> ['file_imports_from_dir_one']
  example_abs_import.children_unused -> ['file_imports_from_dir_one']
  example_abs_import.parent -> 'parse_local_dir'
  example_abs_import.statement -> 'from .parse_local_dir import file_imports_from_dir_one'
  example_abs_import.level -> 1
  example_abs_import.line -> 3

     # standard imports
     #  --- import logging ---
     # If we introspect the object, we will get the following
     
     example_standard_import = standard_imports[0]
     example_standard_import.children -> ['logging']
     example_standard_import.children_unused -> ['logging']
     example_standard_import.statement -> 'import logging'
     example_standard_import.line -> 1

• Python Abstract Grammar

  The util allow identifying and group the imports according to the abstract grammar defined with python

   ...
   | Import(alias* names)
   | ImportFrom(identifier? module, alias* names, int? level)
  

• Import types

  • Relative Imports

    Relative imports use leading dots. A single leading dot indicates a relative import, starting with the current package. Two or more leading dots indicate a relative import to the parent(s) of the current package, one level per dot after the first.

    • Schema syntax

      Relative imports must always use from <> import;import <> is always absolute.
      • pydocs: https://docs.python.org/3/reference/import.html#package-relative-imports
      • Metadata will be abstracted in RelativeImportStatement objects.

    • Ex.

      from .moduleY import spam
      from .moduleY import spam as ham
      from . import moduleY
      from ..subpackage1 import moduleY
      from ..subpackage2.moduleZ import eggs
      from ..moduleA import foo
      from ...package import bar
      from ...sys import path
      

  • Absolute Imports

    Absolute import involves full path i.e., from the project’s root folder to the desired module. An absolute import state that the resource
    to be imported using its full path from the project’s root folder.

    • Schema syntax

      Absolute imports may use either the import <> or from <> import <> syntax, but relative imports may only use the second form.
      • PEP328: https://www.python.org/dev/peps/pep-0328/
      • Metadata will be abstracted in AbsoluteImportStatement objects.

    • Ex.

      from moduleY import spam
      from moduleY import spam as ham
      
      # OR
      
      import XXX.YYY.ZZZ
      

  • Standard Imports

    Standard imports will be introspected and the data about it will be saved in an object named ImportStatement.

    • Schema syntax

      standard imports use the import <> syntax.
      • PEP328: https://www.python.org/dev/peps/pep-0328/
      • Metadata will be abstracted in ImportStatement objects.

    • Ex.

      import moduleY
      import moduleX
      

• Unused imports

  If some child it's not used in an import, this will be added in children_unused attribute in every concrete implementation that represent an imports.

  from ..subpackage1 import moduleY, moduleZ
  
  def foo() -> moduleZ:
      pass
  

  In this case the relative import from ..subpackage1 import moduleY, moduleZ has a child that is not used in the file.

  ...  # After introspect the file
  
  relative_imports = imports_file.relative_imports
  relative_imports[0].children_unused -> ["moduleY"]
  
  # But the total of children present in this file 
  relative_imports[0].children -> ["moduleY", "moduleZ"]
  

  it's used pyflakes to determine the unused imports, because follow the same philosophy to get the information just using a static analysis.

• Imports in inner scopes

  If some imports are located inside an inner scope, the import object will contain a boolean field named in_inner_scope indicating that is located outside his default position (the top of the file or in the global scope), also will be included an attribute named outer_parent_node that will contain the AST node, to allow the user get more information about the data structure node parent that is around the import.

  def foo():
     from pkg import moduleY, moduleZ
  ...
  

  In this case the absolute import is located inside a function named foo.

  ...  # After introspect the file
  
  absolute_imports = imports_file.absolute_imports
  absolute_imports[0].in_inner_scope -> True
  
  # it's possible to get the ast node parent with
  absolute_imports[0].outer_parent_node -> ast.AST object