From 79a71c19f5b7b9fa88e500a41f676382c2d4cca8 Mon Sep 17 00:00:00 2001
From: Dmitry Jemerov <yole@jetbrains.com>
Date: Wed, 15 Aug 2012 13:03:28 +0200
Subject: [PATCH] pass foothold to PyCanonicalPathProvider; javadoc

---
 .../python/psi/resolve/PyCanonicalPathProvider.java  | 12 +++++++++++-
 .../stdlib/PyStdlibCanonicalPathProvider.java        |  3 ++-
 .../python/psi/resolve/QualifiedNameFinder.java      |  2 +-
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/python/psi-api/src/com/jetbrains/python/psi/resolve/PyCanonicalPathProvider.java b/python/psi-api/src/com/jetbrains/python/psi/resolve/PyCanonicalPathProvider.java
index e8a367182ccf..5b6e4f78655d 100644
--- a/python/psi-api/src/com/jetbrains/python/psi/resolve/PyCanonicalPathProvider.java
+++ b/python/psi-api/src/com/jetbrains/python/psi/resolve/PyCanonicalPathProvider.java
@@ -1,15 +1,25 @@
 package com.jetbrains.python.psi.resolve;
 
 import com.intellij.openapi.extensions.ExtensionPointName;
+import com.intellij.psi.PsiElement;
 import com.jetbrains.python.psi.impl.PyQualifiedName;
 import org.jetbrains.annotations.Nullable;
 
 /**
+ * Allows to provide a custom qualified name when a specific symbol is going to be imported into a specific file.
+ *
  * @author yole
  */
 public interface PyCanonicalPathProvider {
   ExtensionPointName<PyCanonicalPathProvider> EP_NAME = ExtensionPointName.create("Pythonid.canonicalPathProvider");
 
+  /**
+   * Allows to provide a custom qualified name when a specific symbol is going to be imported into a specific file.
+   *
+   * @param qName    the real qualified name of the symbol being imported.
+   * @param foothold the location where the symbol is being imported.
+   * @return the qualified name to use in the import statement, or null if no replacement is necessary.
+   */
   @Nullable
-  PyQualifiedName getCanonicalPath(PyQualifiedName qName);
+  PyQualifiedName getCanonicalPath(PyQualifiedName qName, PsiElement foothold);
 }
diff --git a/python/src/com/jetbrains/python/codeInsight/stdlib/PyStdlibCanonicalPathProvider.java b/python/src/com/jetbrains/python/codeInsight/stdlib/PyStdlibCanonicalPathProvider.java
index 80bb33481f70..b6c9791067cf 100644
--- a/python/src/com/jetbrains/python/codeInsight/stdlib/PyStdlibCanonicalPathProvider.java
+++ b/python/src/com/jetbrains/python/codeInsight/stdlib/PyStdlibCanonicalPathProvider.java
@@ -1,5 +1,6 @@
 package com.jetbrains.python.codeInsight.stdlib;
 
+import com.intellij.psi.PsiElement;
 import com.jetbrains.python.psi.impl.PyQualifiedName;
 import com.jetbrains.python.psi.resolve.PyCanonicalPathProvider;
 import org.jetbrains.annotations.Nullable;
@@ -13,7 +14,7 @@ import java.util.List;
 public class PyStdlibCanonicalPathProvider implements PyCanonicalPathProvider {
   @Nullable
   @Override
-  public PyQualifiedName getCanonicalPath(PyQualifiedName qName) {
+  public PyQualifiedName getCanonicalPath(PyQualifiedName qName, PsiElement foothold) {
     return restoreStdlibCanonicalPath(qName);
   }
 
diff --git a/python/src/com/jetbrains/python/psi/resolve/QualifiedNameFinder.java b/python/src/com/jetbrains/python/psi/resolve/QualifiedNameFinder.java
index 2f51bbea3018..6784a4f5b509 100644
--- a/python/src/com/jetbrains/python/psi/resolve/QualifiedNameFinder.java
+++ b/python/src/com/jetbrains/python/psi/resolve/QualifiedNameFinder.java
@@ -114,7 +114,7 @@ public class QualifiedNameFinder {
     final PyQualifiedName qname = findShortestImportableQName(foothold != null ? foothold : symbol, virtualFile);
     if (qname != null) {
       for (PyCanonicalPathProvider provider : Extensions.getExtensions(PyCanonicalPathProvider.EP_NAME)) {
-        final PyQualifiedName restored = provider.getCanonicalPath(qname);
+        final PyQualifiedName restored = provider.getCanonicalPath(qname, foothold);
         if (restored != null) {
           return restored;
         }