dartsim · jslee02 · Nov 25, 2025 · Nov 24, 2025 · Nov 24, 2025 · Nov 24, 2025
diff --git a/CHANGELOG.md b/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`.

diff --git a/docs/onboarding/README.md b/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
 ```
 
 ---

diff --git a/docs/onboarding/python-bindings.md b/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

diff --git a/docs/python_api/modules/collision.rst b/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:
diff --git a/docs/python_api/modules/common.rst b/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:
diff --git a/docs/python_api/modules/constraint.rst b/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:
diff --git a/docs/python_api/modules/dynamics.rst b/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:
diff --git a/docs/python_api/modules/gui.rst b/docs/python_api/modules/gui.rst
@@ -3,5 +3,3 @@ dartpy.gui
 
 .. automodule:: dartpy.gui
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/python_api/modules/math.rst b/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:
diff --git a/docs/python_api/modules/optimizer.rst b/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:
diff --git a/docs/python_api/modules/simulation.rst b/docs/python_api/modules/simulation.rst
@@ -1,7 +1,7 @@
-dartpy.simulation
-=================
+dartpy
+======
 
-.. automodule:: dartpy.simulation
+.. note:: Legacy submodules will be removed in DART 8.0; use top-level `dartpy`.
+
+.. automodule:: dartpy
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/python_api/modules/utils.rst b/docs/python_api/modules/utils.rst
@@ -1,7 +1,7 @@
-dartpy.utils
-============
+dartpy.io
+=========
 
-.. automodule:: dartpy.utils
+.. note:: Legacy `dartpy.utils` will be removed in DART 8.0; use `dartpy.io`.
+
+.. automodule:: dartpy.io
    :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/readthedocs/README.md b/docs/readthedocs/README.md
@@ -141,10 +141,10 @@ When adding new Python API documentation:
 Example module file:
 
 ```rst
-dartpy.simulation Module
+dartpy Module
 ========================
 
-.. automodule:: dartpy.simulation
+.. automodule:: dartpy
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/readthedocs/dartpy/python_api_reference.rst b/docs/readthedocs/dartpy/python_api_reference.rst
@@ -22,14 +22,16 @@ To explore the bindings locally:
    pip install dartpy
    python - <<'PY'
    import dartpy as dart
-   world = dart.simulation.World()
-   print(world.getGravity())
+   world = dart.World()
+   print(world.get_gravity())
    PY
 
 Module Reference
 ----------------
 
-The sections below mirror the module layout from ``docs/python_api/``.
+.. note::
+   The dartpy API is flattened to the top-level ``dartpy`` package and
+   ``dartpy.io`` for parsers. Legacy submodules will be removed in DART 8.0.
 
 .. toctree::
    :maxdepth: 1

diff --git a/python/dartpy/CMakeLists.txt b/python/dartpy/CMakeLists.txt
@@ -344,19 +344,21 @@ target_compile_options(dartpy PRIVATE "-UNB_COMPACT_ASSERTIONS")
 
 set_target_properties(dartpy PROPERTIES OUTPUT_NAME "_dartpy")
 
-# Copy the Python package shim into the build tree so tests can import it
-configure_file(
-  ${CMAKE_CURRENT_SOURCE_DIR}/__init__.py
-  ${CMAKE_CURRENT_BINARY_DIR}/__init__.py
-  COPYONLY
-)
-add_custom_command(
-  TARGET dartpy POST_BUILD
-  COMMAND ${CMAKE_COMMAND} -E copy_if_different
-          ${CMAKE_CURRENT_SOURCE_DIR}/__init__.py
-          ${CMAKE_CURRENT_BINARY_DIR}/__init__.py
-  COMMENT "Updating dartpy __init__.py"
-)
+# Copy pure-Python helpers into the build tree so tests can import them
+foreach(_py_file __init__.py _naming.py _layout.py)
+  configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/${_py_file}
+    ${CMAKE_CURRENT_BINARY_DIR}/${_py_file}
+    COPYONLY
+  )
+  add_custom_command(
+    TARGET dartpy POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+            ${CMAKE_CURRENT_SOURCE_DIR}/${_py_file}
+            ${CMAKE_CURRENT_BINARY_DIR}/${_py_file}
+    COMMENT "Updating dartpy ${_py_file}"
+  )
+endforeach()
 
 if(DEFINED DART_DARTPY_RUNTIME_DIR)
   set(_dartpy_output_dir "${DART_DARTPY_RUNTIME_DIR}")
@@ -387,13 +389,17 @@ if(DEFINED SKBUILD_PLATLIB_DIR)
     LIBRARY DESTINATION "${SKBUILD_PLATLIB_DIR}/dartpy"
   )
   install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/__init__.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/_naming.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/_layout.py
     DESTINATION "${SKBUILD_PLATLIB_DIR}/dartpy"
   )
 elseif(DEFINED PYTHON_SITE_PACKAGES)
   install(TARGETS dartpy
     LIBRARY DESTINATION "${PYTHON_SITE_PACKAGES}/dartpy"
   )
   install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/__init__.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/_naming.py
+                ${CMAKE_CURRENT_SOURCE_DIR}/_layout.py
     DESTINATION "${PYTHON_SITE_PACKAGES}/dartpy"
   )
 endif()

diff --git a/python/dartpy/__init__.py b/python/dartpy/__init__.py
@@ -32,6 +32,7 @@ def _candidate_package_dirs() -> List[str]:
 
 from . import _dartpy as _ext  # type: ignore[attr-defined]
 __version__ = getattr(_ext, "__version__", None)
+from . import _layout, _naming
 
 
 def _alias_extension_submodules() -> None:
@@ -58,6 +59,8 @@ def _alias_extension_submodules() -> None:
 from ._dartpy import *  # noqa: F401,F403
 
 _alias_extension_submodules()
+_naming.install_aliases(_ext)
+_layout.install_layout(sys.modules[__name__])
 
 
 def __getattr__(name: str):
@@ -68,4 +71,5 @@ def __getattr__(name: str):
   except ModuleNotFoundError as exc:  # pragma: no cover - passthrough
     raise AttributeError(name) from exc
   globals()[name] = module
+  _naming.install_aliases(module)
   return module