Flatten dartpy namespace and add snake_case shims (#2259)

Author: jslee02

CHANGELOG.md

@@ -9,6 +9,7 @@
     - See [Compatibility Policy](docs/onboarding/compatibility-policy.md) for details
   - Renamed `RootJointType` enum values to PascalCase (`Floating`, `Fixed`) across `dart::utils::SdfParser`, `dart::utils::DartLoader`, and their dartpy bindings to align with the code-style guidelines.
   - Removed all optional optimizer plugins (`dart-optimizer-ipopt`, `dart-optimizer-nlopt`, `dart-optimizer-pagmo`, and `dart-optimizer-snopt`) along with the pagmo-based multi-objective optimization APIs since they were only exercised by tests.
+  - Flattened the dartpy namespace to `dartpy`, `dartpy.io` (alias for `utils`), and `dartpy.gui`, promoting core symbols to the package root and deprecating deep module paths (`dartpy.dynamics`, `dartpy.collision`, etc.) plus camelCase names. Legacy modules and camelCase remain available with `DeprecationWarning` for DART 7.x and are slated for removal in DART 8.0 (see `DARTPY_ENABLE_LEGACY_MODULES`, `DARTPY_WARN_ON_LEGACY_MODULES`, `DARTPY_ENABLE_SNAKE_CASE`, `DARTPY_WARN_ON_CAMELCASE`).
   - Moved the generic optimization primitives (`Function`, `Problem`, `Solver`, `GradientDescentSolver`) under `dart/math/optimization`; the legacy `<dart/optimizer/...>` headers and `dart::optimizer::*` namespace now forward (with deprecation notices) to the new `dart::math::*` definitions.
   - Dropped the deprecated `docker/dev/v6.15` images; use the maintained v6.16 images instead.
   - Renamed the OpenSceneGraph GUI component/target to `gui`/`dart-gui` (previously `gui-osg`/`dart-gui-osg`) and replaced the `DART_BUILD_GUI_OSG` toggle with `DART_BUILD_GUI`.

docs/onboarding/README.md

@@ -558,13 +558,10 @@ graph TB
 
 **Key Modules**:
 
-- `dartpy.math` - Mathematical utilities and Eigen↔NumPy conversion
-- `dartpy.dynamics` - Skeletons, BodyNodes, Joints, IK
-- `dartpy.collision` - Collision detection backends
-- `dartpy.constraint` - Constraint solving
-- `dartpy.simulation` - World simulation
+- `dartpy` (top-level) - Core classes/functions (math, dynamics, collision, simulation, constraint, optimizer) exposed in snake_case
+- `dartpy.io` - File parsers (URDF, SDF, SKEL, MJCF) [alias for legacy `utils`]
 - `dartpy.gui` - 3D visualization with OSG and ImGui
-- `dartpy.utils` - File parsers (URDF, SDF, SKEL, MJCF)
+- Legacy `dartpy`/`math`/`dynamics`/`collision`/`simulation`/`constraint`/`optimizer`/`utils` remain importable in DART 7.x but emit `DeprecationWarning` and will be removed in DART 8.0.
 
 **Key Files**:
 
@@ -818,20 +815,20 @@ sequenceDiagram
     participant NumPy as NumPy
 
     Python->>dartpy: import dartpy
-    Python->>dartpy: world = dartpy.simulation.World()
+    Python->>dartpy: world = dartpy.World()
     dartpy->>DART: World::create()
 
-    Python->>dartpy: skel = dartpy.dynamics.Skeleton.create()
+    Python->>dartpy: skel = dartpy.Skeleton.create()
     dartpy->>DART: Skeleton::create()
 
-    Python->>dartpy: world.addSkeleton(skel)
+    Python->>dartpy: world.add_skeleton(skel)
     dartpy->>DART: World::addSkeleton()
 
     loop Simulation
         Python->>dartpy: world.step()
         dartpy->>DART: World::step()
-        Python->>dartpy: q = skel.getPositions()
-        dartpy->>DART: Skeleton::getPositions()
+        Python->>dartpy: q = skel.get_positions()
+        dartpy->>DART: Skeleton::get_positions()
         DART->>NumPy: convert Eigen to ndarray
         NumPy-->>Python: positions array
     end
@@ -1207,7 +1204,7 @@ dart_gui/
 ```python
 import dartpy as dart
 from dartpy.gui import Viewer, RealTimeWorldNode
-from dartpy.utils import DartLoader
+from dartpy.io import DartLoader
 ```
 
 ---

docs/onboarding/python-bindings.md

@@ -45,19 +45,21 @@
 
 ### Module Structure
 
-dartpy organizes DART's C++ API into Python modules:
+dartpy now flattens most symbols onto the top-level package to avoid deep
+namespaces:
 
 ```
 dartpy/
-├── math          # Eigen integration, geometry utilities
-├── dynamics      # Skeletons, BodyNodes, Joints
-├── collision     # Collision detection backends
-├── constraint    # Constraint solving
-├── simulation    # World simulation
-├── utils         # File parsers (URDF, SDF, SKEL, MJCF)
+├── io            # File parsers (URDF, SDF, SKEL, MJCF)
 └── gui           # 3D visualization (OpenSceneGraph + ImGui)
 ```
 
+- Core classes/functions (dynamics, collision, math, simulation, constraint,
+  optimizer) are promoted onto `dartpy` directly.
+- Legacy submodules remain importable in DART 7.x but will be removed in DART
+  8.0. Toggle deprecation handling with `DARTPY_WARN_ON_LEGACY_MODULES` or
+  `DARTPY_ENABLE_LEGACY_MODULES`.
+
 **Source**: See `python/dartpy/` directory for module implementations
 
 ### Eigen ↔ NumPy Integration
@@ -80,10 +82,10 @@ import dartpy as dart
 import numpy as np
 
 # NumPy arrays automatically convert to Eigen types
-skel.setPositions(np.array([0.1, 0.2, 0.3]))
+skel.set_positions(np.array([0.1, 0.2, 0.3]))
 
 # Eigen types automatically convert to NumPy arrays
-positions = skel.getPositions()  # Returns ndarray
+positions = skel.get_positions()  # Returns ndarray
 ```
 
 ### OSG Bindings Design
@@ -111,6 +113,13 @@ positions = skel.getPositions()  # Returns ndarray
 
 **Result**: OSG now works on all platforms where OpenSceneGraph is available (Linux, macOS, Windows via conda-forge)
 
+## Pythonic Naming Transition
+
+- All camelCase bindings now receive snake_case aliases at import time (runtime shim lives in `python/dartpy/_naming.py`)
+- camelCase still works but emits a one-time `DeprecationWarning` per symbol by default; set `DARTPY_WARN_ON_CAMELCASE=0` to silence
+- Turn the shim off entirely with `DARTPY_ENABLE_SNAKE_CASE=0` (useful for bisecting)
+- Prefer snake_case in new code; ship a codemod/release note alongside the next major to help users update usages
+
 ## Installation Methods
 
 ### For End Users

docs/python_api/modules/collision.rst

@@ -1,7 +1,7 @@
-dartpy.collision
-================
+dartpy
+======
 
-.. automodule:: dartpy.collision
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance:

docs/python_api/modules/common.rst

@@ -1,7 +1,7 @@
-dartpy.common
-=============
+dartpy
+======
 
-.. automodule:: dartpy.common
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance:

docs/python_api/modules/constraint.rst

@@ -1,7 +1,7 @@
-dartpy.constraint
-=================
+dartpy
+======
 
-.. automodule:: dartpy.constraint
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance:

docs/python_api/modules/dynamics.rst

@@ -1,7 +1,7 @@
-dartpy.dynamics
-===============
+dartpy
+======
 
-.. automodule:: dartpy.dynamics
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance:

docs/python_api/modules/gui.rst

@@ -3,5 +3,3 @@ dartpy.gui
 
 .. automodule:: dartpy.gui
    :members:
-   :undoc-members:
-   :show-inheritance:

docs/python_api/modules/math.rst

@@ -1,7 +1,7 @@
-dartpy.math
-============
+dartpy
+======
 
-.. automodule:: dartpy.math
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance:

docs/python_api/modules/optimizer.rst

@@ -1,7 +1,7 @@
-dartpy.optimizer
-================
+dartpy
+======
 
-.. automodule:: dartpy.optimizer
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance: