Merge pull request #62 from swistakm/feature/extra-module-for-utility…

…-functions

Extra module for utility functions

doc/source/reference/imgui.extra.rst

@@ -0,0 +1,7 @@
+imgui.extra module
+==================
+
+
+.. automodule:: imgui.extra
+    :members:
+    :undoc-members:

doc/source/reference/modules.rst

@@ -10,4 +10,5 @@ API reference
 
    imgui
    imgui.core
+   imgui.extra
    imgui.integrations

imgui/__init__.py

@@ -4,15 +4,17 @@
 
 from imgui.core import *  # noqa
 from imgui import core
+from imgui.extra import *  # noqa
+from imgui import extra
+from imgui import _compat
 
+VERTEX_BUFFER_POS_OFFSET = extra.vertex_buffer_vertex_pos_offset()
+VERTEX_BUFFER_UV_OFFSET = extra.vertex_buffer_vertex_uv_offset()
+VERTEX_BUFFER_COL_OFFSET = extra.vertex_buffer_vertex_col_offset()
 
-VERTEX_BUFFER_POS_OFFSET = core.vertex_buffer_vertex_pos_offset()
-VERTEX_BUFFER_UV_OFFSET = core.vertex_buffer_vertex_uv_offset()
-VERTEX_BUFFER_COL_OFFSET = core.vertex_buffer_vertex_col_offset()
+VERTEX_SIZE = extra.vertex_buffer_vertex_size()
 
-VERTEX_SIZE = core.vertex_buffer_vertex_size()
-
-INDEX_SIZE = core.index_buffer_index_size()
+INDEX_SIZE = extra.index_buffer_index_size()
 
 # ==== Condition constants (redefines for autodoc)
 #: Set the variable always
@@ -267,3 +269,24 @@
 INPUT_TEXT_READ_ONLY = core.INPUT_TEXT_READ_ONLY
 #: Password mode, display all characters as '*'
 INPUT_TEXT_PASSWORD = core.INPUT_TEXT_PASSWORD
+
+
+# extra aliases for backwards compatibility
+def _core_to_extra_deprecated(fn):
+    return _compat.deprecated("""
+        The imgui.core.{0}() is deprecated
+        and will be removed in 1.0.0 version of pyimgui.
+        Please use imgui.extra.{0}()
+        or imgui.{0}() instead.
+        """.format(fn.__name__)
+    )(fn)
+
+
+core.font = _core_to_extra_deprecated(extra.font)
+core.styled = _core_to_extra_deprecated(extra.styled)
+core.istyled = _core_to_extra_deprecated(extra.istyled)
+core.vertex_buffer_vertex_pos_offset = _core_to_extra_deprecated(extra.vertex_buffer_vertex_pos_offset)  # noqa
+core.vertex_buffer_vertex_uv_offset = _core_to_extra_deprecated(extra.vertex_buffer_vertex_uv_offset)  # noqa
+core.vertex_buffer_vertex_col_offset = _core_to_extra_deprecated(extra.vertex_buffer_vertex_col_offset)  # noqa
+core.vertex_buffer_vertex_size = _core_to_extra_deprecated(extra.vertex_buffer_vertex_size)  # noqa
+core.index_buffer_index_size = _core_to_extra_deprecated(extra.index_buffer_index_size)  # noqa

imgui/_compat.py

@@ -0,0 +1,16 @@
+from functools import wraps
+from warnings import warn
+
+
+class ImguiDeprecationWarning(FutureWarning):
+    pass
+
+
+def deprecated(reason):
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            warn(reason, ImguiDeprecationWarning, stacklevel=2)
+            return fn(*args, **kwargs)
+        return wrapper
+    return decorator

imgui/core.pxd

@@ -0,0 +1,13 @@
+"""
+This file provides all C/C++ definitions that need to be shared between all
+extension modules. This is mostly for the `extra` submodule that provides
+some additional utilities that do not belong to `core`.
+"""
+cimport cimgui
+
+
+cdef class _Font(object):
+    cdef cimgui.ImFont* _ptr
+
+    @staticmethod
+    cdef from_ptr(cimgui.ImFont* ptr)

imgui/core.pyx

@@ -583,8 +583,6 @@ cdef class _StaticGlyphRanges(object):
 
 
 cdef class _Font(object):
-    cdef cimgui.ImFont* _ptr
-
     @staticmethod
     cdef from_ptr(cimgui.ImFont* ptr):
         instance = _Font()
@@ -5389,16 +5387,26 @@ def end_group():
     """
     cimgui.EndGroup()
 
-# additional helpers
-# todo: move to separate extension module (extra?)
+
+# === Python/C++ cross API for error handling ===
+from cpython.exc cimport PyErr_NewException
+
+cdef public _ImGuiError "ImGuiError" = PyErr_NewException(
+    "imgui.core.ImGuiError", Exception, {}
+)
+
+ImGuiError = _ImGuiError # make visible to Python
+
+
+# === Extra utilities ====
 
 @contextmanager
-def font(_Font font):
+def _py_font(_Font font):
     """Use specified font in given context.
 
     Example:
 
-    .. code-block: python
+    .. code-block:: python
 
         ...
         font_extra = io.fonts.add_font_from_file_ttf(
@@ -5420,8 +5428,9 @@ def font(_Font font):
     yield
     pop_font()
 
+
 @contextmanager
-def styled(cimgui.ImGuiStyleVar variable, value):
+def _py_styled(cimgui.ImGuiStyleVar variable, value):
     # note: we treat bool value as integer to guess if we are required to pop
     #       anything because IMGUI may simply skip pushing
     count = push_style_var(variable, value)
@@ -5430,7 +5439,7 @@ def styled(cimgui.ImGuiStyleVar variable, value):
 
 
 @contextmanager
-def istyled(*variables_and_values):
+def _py_istyled(*variables_and_values):
     # todo: rename to nstyled?
     count = 0
     iterator = iter(variables_and_values)
@@ -5457,27 +5466,17 @@ def istyled(*variables_and_values):
         cimgui.PopStyleVar(count)
 
 
-def vertex_buffer_vertex_pos_offset():
+def _py_vertex_buffer_vertex_pos_offset():
     return <uintptr_t><size_t>&(<cimgui.ImDrawVert*>NULL).pos
 
-def vertex_buffer_vertex_uv_offset():
+def _py_vertex_buffer_vertex_uv_offset():
     return <uintptr_t><size_t>&(<cimgui.ImDrawVert*>NULL).uv
 
-def vertex_buffer_vertex_col_offset():
+def _py_vertex_buffer_vertex_col_offset():
     return <uintptr_t><size_t>&(<cimgui.ImDrawVert*>NULL).col
 
-def vertex_buffer_vertex_size():
+def _py_vertex_buffer_vertex_size():
     return sizeof(cimgui.ImDrawVert)
 
-def index_buffer_index_size():
+def _py_index_buffer_index_size():
     return sizeof(cimgui.ImDrawIdx)
-
-
-# === Python/C++ cross API for error handling ===
-from cpython.exc cimport PyErr_NewException
-
-cdef public _ImGuiError "ImGuiError" = PyErr_NewException(
-    "imgui.core.ImGuiError", Exception, {}
-)
-
-ImGuiError = _ImGuiError # make visible to Python

imgui/extra.py

@@ -0,0 +1,26 @@
+"""
+This module provides extra utilities that are not part of core ImGui C++ API
+but are useful in Python application.
+
+"""
+from . import core
+
+__all__ = (
+    "font",
+    "styled",
+    "istyled",
+    "vertex_buffer_vertex_pos_offset",
+    "vertex_buffer_vertex_uv_offset",
+    "vertex_buffer_vertex_col_offset",
+    "vertex_buffer_vertex_size",
+    "index_buffer_index_size",
+)
+
+font = core._py_font
+styled = core._py_styled
+istyled = core._py_istyled
+vertex_buffer_vertex_pos_offset = core._py_vertex_buffer_vertex_pos_offset
+vertex_buffer_vertex_uv_offset = core._py_vertex_buffer_vertex_uv_offset
+vertex_buffer_vertex_col_offset = core._py_vertex_buffer_vertex_col_offset
+vertex_buffer_vertex_size = core._py_vertex_buffer_vertex_size
+index_buffer_index_size = core._py_index_buffer_index_size

setup.py

@@ -81,7 +81,21 @@ def get_version(version_tuple):
     general_macros = []
 
 
-extension_sources = ["imgui/core" + ('.pyx' if USE_CYTHON else '.cpp')]
+def extension_sources(path):
+    sources = ["{0}{1}".format(path, '.pyx' if USE_CYTHON else '.cpp')]
+
+    if not USE_CYTHON:
+        # note: Cython will pick these files automatically but when building
+        #       a plain C++ sdist without Cython we need to explicitly mark
+        #       these files for compilation and linking.
+        sources += [
+            'imgui-cpp/imgui.cpp',
+            'imgui-cpp/imgui_draw.cpp',
+            'imgui-cpp/imgui_demo.cpp',
+            'config-cpp/py_imconfig.cpp'
+        ]
+
+    return sources
 
 
 def backend_extras(*requirements):
@@ -91,6 +105,7 @@ def backend_extras(*requirements):
     """
     return ["PyOpenGL"] + list(requirements)
 
+
 EXTRAS_REQUIRE = {
     'Cython':  ['Cython>=0.24,<=0.28.2'],
     'cocos2d': backend_extras('cocos2d'),
@@ -104,21 +119,9 @@ def backend_extras(*requirements):
 # backend integrations and additional extra features.
 EXTRAS_REQUIRE['full'] = list(set(chain(*EXTRAS_REQUIRE.values())))
 
-
-if not USE_CYTHON:
-    # note: Cython will pick these files automatically but when building
-    #       a plain C++ sdist without Cython we need to explicitly mark
-    #       these files for compilation and linking.
-    extension_sources += [
-        'imgui-cpp/imgui.cpp',
-        'imgui-cpp/imgui_draw.cpp',
-        'imgui-cpp/imgui_demo.cpp',
-        'config-cpp/py_imconfig.cpp'
-    ]
-
 EXTENSIONS = [
     Extension(
-        "imgui.core", extension_sources,
+        "imgui.core", extension_sources("imgui/core"),
         extra_compile_args=os_specific_flags,
         define_macros=[
             # note: for raising custom exceptions directly in ImGui code