fix some setup issues

Author: chenliu0831

README.md

@@ -52,7 +52,7 @@ flowchart LR
 
 - Python 3.9+
 - Apache Spark 3.5.0+
-- Java 17+
+- Java 17 (Java 21+ has known compatibility issues with Spark 3.5)
 
 ### Step 1: Download Deequ Pre-release JAR
 
@@ -111,6 +111,9 @@ Install the beta wheel directly from the GitHub release:
 ```bash
 pip install https://github.com/awslabs/python-deequ/releases/download/v2.0.0b1/pydeequ-2.0.0b1-py3-none-any.whl
 pip install pyspark[connect]==3.5.0
+
+# Python 3.12+ users: install setuptools (provides distutils removed in 3.12)
+pip install setuptools
 ```
 
 ### Step 5: Run Your First Check
@@ -255,7 +258,7 @@ check.hasCompleteness("col", gte(0.9))
 ## PyDeequ 2.0 Troubleshooting
 
 ### Server won't start
-1. Check Java version: `java -version` (should be Java 17+)
+1. Check Java version: `java -version` (must be Java 17, not 21+)
 2. Check port availability: `lsof -i :15002`
 3. Check logs: `tail -f $SPARK_HOME/logs/spark-*-SparkConnectServer-*.out`
 
@@ -268,6 +271,18 @@ ps aux | grep SparkConnectServer
 ### ClassNotFoundException: DeequRelationPlugin
 Ensure the Deequ JAR is correctly specified in `--jars` when starting the server.
 
+### UnsupportedOperationException: sun.misc.Unsafe not available
+This error occurs when using Java 21+ with Spark 3.5. Use Java 17 instead:
+```bash
+export JAVA_HOME=/path/to/java17
+```
+
+### ModuleNotFoundError: No module named 'distutils'
+This occurs on Python 3.12+ because `distutils` was removed. Install setuptools:
+```bash
+pip install setuptools
+```
+
 ---
 
 ## PyDeequ 1.x (Legacy)

pydeequ/__init__.py

@@ -11,35 +11,89 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""Placeholder docstrings"""
+"""
+PyDeequ - Python API for Deequ data quality library.
+
+For PyDeequ 2.0 (Spark Connect), use:
+    from pydeequ.v2 import VerificationSuite, Check, CheckLevel
+    from pydeequ.v2.predicates import eq, gte
+
+For PyDeequ 1.x (Legacy Py4J), set SPARK_VERSION env var and use:
+    from pydeequ import deequ_maven_coord
+    from pydeequ.checks import Check, CheckLevel
+"""
 __version__ = "2.0.0b1"
 
-from pyspark.sql import SparkSession
+# Legacy imports are deferred to avoid requiring SPARK_VERSION for V2 users.
+# V2 users should import from pydeequ.v2 directly.
+
+_deequ_maven_coord = None
+_f2j_maven_coord = "net.sourceforge.f2j:arpack_combined_all"
+
+
+def __getattr__(name):
+    """Lazy loading for legacy module attributes."""
+    global _deequ_maven_coord
+
+    if name == "deequ_maven_coord":
+        if _deequ_maven_coord is None:
+            from pydeequ.configs import DEEQU_MAVEN_COORD
+            _deequ_maven_coord = DEEQU_MAVEN_COORD
+        return _deequ_maven_coord
+
+    if name == "f2j_maven_coord":
+        return _f2j_maven_coord
+
+    if name in ("AnalysisRunner", "Check", "CheckLevel", "ColumnProfilerRunner",
+                "PyDeequSession", "DEEQU_MAVEN_COORD"):
+        # Import legacy modules on demand
+        if name == "AnalysisRunner":
+            from pydeequ.analyzers import AnalysisRunner
+            return AnalysisRunner
+        elif name == "Check":
+            from pydeequ.checks import Check
+            return Check
+        elif name == "CheckLevel":
+            from pydeequ.checks import CheckLevel
+            return CheckLevel
+        elif name == "ColumnProfilerRunner":
+            from pydeequ.profiles import ColumnProfilerRunner
+            return ColumnProfilerRunner
+        elif name == "DEEQU_MAVEN_COORD":
+            from pydeequ.configs import DEEQU_MAVEN_COORD
+            return DEEQU_MAVEN_COORD
+
+    if name == "PyDeequSession":
+        # Return the lazily-defined class
+        return _get_pydeequ_session_class()
+
+    raise AttributeError(f"module 'pydeequ' has no attribute '{name}'")
 
-from pydeequ.analyzers import AnalysisRunner
-from pydeequ.checks import Check, CheckLevel
-from pydeequ.configs import DEEQU_MAVEN_COORD
-from pydeequ.profiles import ColumnProfilerRunner
 
-deequ_maven_coord = DEEQU_MAVEN_COORD
-f2j_maven_coord = "net.sourceforge.f2j:arpack_combined_all"
+def _get_pydeequ_session_class():
+    """Lazily create PyDeequSession class to avoid importing SparkSession at module load."""
+    from pyspark.sql import SparkSession
+    from pydeequ.analyzers import AnalysisRunner
+    from pydeequ.checks import Check, CheckLevel
+    from pydeequ.profiles import ColumnProfilerRunner
 
+    class PyDeequSession:
+        """
+        For interacting with PyDeequ Modules at the "Runner" Level
+        """
 
-class PyDeequSession:
-    """
-    For interacting with PyDeequ Modules at the "Runner" Level
-    """
+        def __init__(self, spark_session: SparkSession):
+            self._spark_session = spark_session
+            self._sc = spark_session.sparkContext
+            self._jvm = spark_session._jvm
 
-    def __init__(self, spark_session: SparkSession):
-        self._spark_session = spark_session
-        self._sc = spark_session.sparkContext
-        self._jvm = spark_session._jvm
+        def createColumnProfileRunner(self):
+            return ColumnProfilerRunner(self._spark_session)
 
-    def createColumnProfileRunner(self):
-        return ColumnProfilerRunner(self._spark_session)
+        def createAnalysisRunner(self):
+            return AnalysisRunner(self._spark_session)
 
-    def createAnalysisRunner(self):
-        return AnalysisRunner(self._spark_session)
+        def createCheck(self, level: CheckLevel, description: str, constraints=None):
+            return Check(self._spark_session, level, description, constraints)
 
-    def createCheck(self, level: CheckLevel, description: str, constraints=None):
-        return Check(self._spark_session, level, description, constraints)
+    return PyDeequSession