pygim 0.1.0.dev1__tar.gz

pygim-0.1.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Debith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygim-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: pygim
+Version: 0.1.0.dev1
+Summary: Full Python Gimmicks project with all of its sub-projects.
+Project-URL: homepage, https://github.com/Debith/pygim
+Project-URL: documentation, https://readthedocs.org/projects/pygim/
+Project-URL: source, https://github.com/Debith/pygim
+Project-URL: download, https://pypi.org/project/pygim/#files
+Project-URL: tracker, https://github.com/Debith/pygim/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: click>=8
+Requires-Dist: pyarrow==25.0.*
+Requires-Dist: polars>=0.20
+Requires-Dist: tabulate>=0.9
+Requires-Dist: typing_extensions>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: coverage[toml]; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: pybind11; extra == "dev"
+Requires-Dist: pyodbc; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: markdown; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: coverage[toml]; extra == "test"
+Requires-Dist: pyodbc; extra == "test"
+Requires-Dist: pyyaml; extra == "test"
+Requires-Dist: tomli; python_version < "3.11" and extra == "test"
+Requires-Dist: markdown; extra == "test"
+Provides-Extra: docs
+Requires-Dist: markdown; extra == "docs"
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == "pandas"
+Dynamic: license-file
+Dynamic: requires-dist
+
+#######################
+Python Gimmicks (pygim)
+#######################
+
+| |docs| |downloads| |wheel| |pyversions|
+
+.. |docs| image:: https://readthedocs.org/projects/pygim/badge/
+    :target: https://readthedocs.org/projects/pygim
+    :alt: Documentation Status
+
+.. |downloads| image:: https://img.shields.io/pypi/dm/pygim.svg
+    :alt: PyPI Package monthly downloads
+    :target: https://pypi.org/project/pygim/
+
+.. |wheel| image:: https://img.shields.io/pypi/format/pygim.svg
+    :alt: PyPI Wheel
+    :target: https://pypi.org/project/pygim/
+
+.. |pyversions| image:: https://img.shields.io/pypi/pyversions/pygim.svg
+
+
+Python Gimmicks is a library that contains magical but useful tools
+that can be used to improve productivity of any Python project. The
+goal is to use whatever Pythonic means to provide as light-weight
+and high-performance solutions as possible.
+
+Installation
+============
+
+To install this project, simply write the following command:
+
+.. code-block:: bash
+
+    $ pip install pygim
+
+Command Line Interface
+======================
+
+Installing the package also exposes a ``pygim`` command that wraps the
+project's housekeeping helpers. Run ``pygim --help`` to see the available
+sub-commands, including quick clean-up tools and a shortcut for running the
+coverage workflow used in this repository.
+
+.. code-block:: bash
+
+    $ pygim clean-up --all --yes
+    Starting clean up in `/your/project/path`
+    Excellent! You never see them again!
+
+You can also trigger the test coverage routine in one line:
+
+.. code-block:: bash
+
+    $ pygim show-test-coverage
+
+Both commands accept the same flags described in ``pygim --help``, so you can
+mix and match automation-friendly options (like ``--quiet`` or ``--yes``) to
+fit your workflow.
+
+Sub-modules
+-----------
+
+This library is divided into multiple different smaller packages.
+
+  * pygim: This is the main project that contains the CLI and all the examples.
+
+
+The ``oo`` command is the AI-flavoured front door. Free text goes to the
+assistant; ``oo docs serve`` serves a documentation tree locally with a review
+layer on top of every HTML page:
+
+.. code-block:: bash
+
+    $ oo docs serve --dir build/html --rebuild "make html"
+
+Every served page gets a ✎ button (click anywhere, or select text, to leave a
+comment); comments append to ``__notes__/site-comments.jsonl`` under the served
+root, ready to be read back and acted on. Dropping an image on a page writes it
+under ``images/``. ``GET /pages`` lists the site's pages, and ``--rebuild``
+reports which pages the rebuild added and removed. Opening a Markdown page
+generates its HTML beside it (Mermaid fences become diagrams, ``.md`` links
+point at the generated pages) and serves that, so the commenter works on it
+and comments key on the HTML page — a design folder is served as it is
+written:
+
+.. code-block:: bash
+
+    $ oo docs serve --dir docs/design --host 127.0.0.1
+
+``/`` falls back to the first of ``site/``, ``docs/``,
+``build/html/`` or ``docs/_build/html/`` that has an ``index.html`` (override
+with ``--index``). It binds all interfaces by default so the page is reachable
+via the WSL IP; set ``PYGIM_HOST`` or pass ``--host 127.0.0.1`` for
+localhost only.
+
+Persistence (Experimental)
+--------------------------
+
+An experimental high-performance persistence layer (DDD-style DataStore) now exists as a C++ extension:
+
+* Strategies: pluggable objects with ``fetch(key)->data|None`` and ``save(key,value)``.
+* Optional transformer pipeline (pre-save / post-load) when enabled at construction.
+* Optional factory callable to turn raw data into rich entities.
+* Native MSSQL strategy (ODBC) with pybind-free core/adapter architecture.
+* Fluent ``Query`` for lightweight SQL assembly without manual string concatenation.
+* Arrow IPC utilities for zero-copy hand-off between Polars and C++ pipelines.
+
+Example (read):
+
+.. code-block:: python
+
+        from pygim import persistence
+
+        store = persistence.acquire_datastore("Driver={ODBC Driver 18 for SQL Server};Server=localhost;...")
+
+        df = store.load("users")
+        print(df)
+
+Write (upsert) example: ``docs/examples/persistence/mssql_write_example.py``.
+
+Architecture Diagram:
+
+See PlantUML: ``docs/design/persistence_class_diagram.puml`` for component relationships.
+
+.. note:: The MSSQL native strategy uses a pybind-free core/adapter split. ODBC headers must be available at build time for native SQL Server support.
+
+Query Security & Dialect Notes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Passing a built ``Query`` object directly to ``DataStore.load(query)``
+will bind parameters using ODBC. The builder renders
+queries via ``MssqlDialect``, emitting ``TOP n`` for SQL Server.
+
+Native Arrow Persist Path
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bulk DataFrame persistence is handled inside native bindings via
+``DataStore.save(...)``. The strategy prefers Arrow C Data
+Interface (``__arrow_c_stream__``) and falls back to IPC serialization only
+when needed.
+
+.. code-block:: python
+
+    from pygim import persistence
+
+    conn = "Driver={ODBC Driver 18 for SQL Server};Server=localhost;..."
+    store = persistence.acquire_datastore(conn)
+    df = generate_polars_dataset(n=100_000)
+
+    metrics = store.save(df, "stress_data")
+    print(metrics)
+
+
+
+Changelog
+=========
+
+See the detailed list of changes in ``CHANGELOG.rst``. For upcoming (unreleased) work, consult the top "Unreleased" section before the next version tag.

pygim-0.1.0.dev1/README.rst

@@ -0,0 +1,158 @@
+#######################
+Python Gimmicks (pygim)
+#######################
+
+| |docs| |downloads| |wheel| |pyversions|
+
+.. |docs| image:: https://readthedocs.org/projects/pygim/badge/
+    :target: https://readthedocs.org/projects/pygim
+    :alt: Documentation Status
+
+.. |downloads| image:: https://img.shields.io/pypi/dm/pygim.svg
+    :alt: PyPI Package monthly downloads
+    :target: https://pypi.org/project/pygim/
+
+.. |wheel| image:: https://img.shields.io/pypi/format/pygim.svg
+    :alt: PyPI Wheel
+    :target: https://pypi.org/project/pygim/
+
+.. |pyversions| image:: https://img.shields.io/pypi/pyversions/pygim.svg
+
+
+Python Gimmicks is a library that contains magical but useful tools
+that can be used to improve productivity of any Python project. The
+goal is to use whatever Pythonic means to provide as light-weight
+and high-performance solutions as possible.
+
+Installation
+============
+
+To install this project, simply write the following command:
+
+.. code-block:: bash
+
+    $ pip install pygim
+
+Command Line Interface
+======================
+
+Installing the package also exposes a ``pygim`` command that wraps the
+project's housekeeping helpers. Run ``pygim --help`` to see the available
+sub-commands, including quick clean-up tools and a shortcut for running the
+coverage workflow used in this repository.
+
+.. code-block:: bash
+
+    $ pygim clean-up --all --yes
+    Starting clean up in `/your/project/path`
+    Excellent! You never see them again!
+
+You can also trigger the test coverage routine in one line:
+
+.. code-block:: bash
+
+    $ pygim show-test-coverage
+
+Both commands accept the same flags described in ``pygim --help``, so you can
+mix and match automation-friendly options (like ``--quiet`` or ``--yes``) to
+fit your workflow.
+
+Sub-modules
+-----------
+
+This library is divided into multiple different smaller packages.
+
+  * pygim: This is the main project that contains the CLI and all the examples.
+
+
+The ``oo`` command is the AI-flavoured front door. Free text goes to the
+assistant; ``oo docs serve`` serves a documentation tree locally with a review
+layer on top of every HTML page:
+
+.. code-block:: bash
+
+    $ oo docs serve --dir build/html --rebuild "make html"
+
+Every served page gets a ✎ button (click anywhere, or select text, to leave a
+comment); comments append to ``__notes__/site-comments.jsonl`` under the served
+root, ready to be read back and acted on. Dropping an image on a page writes it
+under ``images/``. ``GET /pages`` lists the site's pages, and ``--rebuild``
+reports which pages the rebuild added and removed. Opening a Markdown page
+generates its HTML beside it (Mermaid fences become diagrams, ``.md`` links
+point at the generated pages) and serves that, so the commenter works on it
+and comments key on the HTML page — a design folder is served as it is
+written:
+
+.. code-block:: bash
+
+    $ oo docs serve --dir docs/design --host 127.0.0.1
+
+``/`` falls back to the first of ``site/``, ``docs/``,
+``build/html/`` or ``docs/_build/html/`` that has an ``index.html`` (override
+with ``--index``). It binds all interfaces by default so the page is reachable
+via the WSL IP; set ``PYGIM_HOST`` or pass ``--host 127.0.0.1`` for
+localhost only.
+
+Persistence (Experimental)
+--------------------------
+
+An experimental high-performance persistence layer (DDD-style DataStore) now exists as a C++ extension:
+
+* Strategies: pluggable objects with ``fetch(key)->data|None`` and ``save(key,value)``.
+* Optional transformer pipeline (pre-save / post-load) when enabled at construction.
+* Optional factory callable to turn raw data into rich entities.
+* Native MSSQL strategy (ODBC) with pybind-free core/adapter architecture.
+* Fluent ``Query`` for lightweight SQL assembly without manual string concatenation.
+* Arrow IPC utilities for zero-copy hand-off between Polars and C++ pipelines.
+
+Example (read):
+
+.. code-block:: python
+
+        from pygim import persistence
+
+        store = persistence.acquire_datastore("Driver={ODBC Driver 18 for SQL Server};Server=localhost;...")
+
+        df = store.load("users")
+        print(df)
+
+Write (upsert) example: ``docs/examples/persistence/mssql_write_example.py``.
+
+Architecture Diagram:
+
+See PlantUML: ``docs/design/persistence_class_diagram.puml`` for component relationships.
+
+.. note:: The MSSQL native strategy uses a pybind-free core/adapter split. ODBC headers must be available at build time for native SQL Server support.
+
+Query Security & Dialect Notes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Passing a built ``Query`` object directly to ``DataStore.load(query)``
+will bind parameters using ODBC. The builder renders
+queries via ``MssqlDialect``, emitting ``TOP n`` for SQL Server.
+
+Native Arrow Persist Path
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bulk DataFrame persistence is handled inside native bindings via
+``DataStore.save(...)``. The strategy prefers Arrow C Data
+Interface (``__arrow_c_stream__``) and falls back to IPC serialization only
+when needed.
+
+.. code-block:: python
+
+    from pygim import persistence
+
+    conn = "Driver={ODBC Driver 18 for SQL Server};Server=localhost;..."
+    store = persistence.acquire_datastore(conn)
+    df = generate_polars_dataset(n=100_000)
+
+    metrics = store.save(df, "stress_data")
+    print(metrics)
+
+
+
+Changelog
+=========
+
+See the detailed list of changes in ``CHANGELOG.rst``. For upcoming (unreleased) work, consult the top "Unreleased" section before the next version tag.

pygim-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,123 @@
+[build-system]
+requires = ["setuptools", "wheel", "tomli; python_version < '3.11'", "pybind11", "setuptools_scm[toml]>=8", "pyarrow>=15"]
+build-backend = "setuptools.build_meta"
+backend-path = []
+
+[project]
+name = "pygim"
+dynamic = ["version", "dependencies"]
+description = "Full Python Gimmicks project with all of its sub-projects."
+readme = "README.rst"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+
+[project.urls]
+homepage = "https://github.com/Debith/pygim"
+documentation = "https://readthedocs.org/projects/pygim/"
+source = "https://github.com/Debith/pygim"
+download = "https://pypi.org/project/pygim/#files"
+tracker = "https://github.com/Debith/pygim/issues"
+
+
+[project.optional-dependencies]
+dev = [
+  'pytest',
+  'pytest-xdist',
+  'mypy',
+  'coverage',
+  'coverage[toml]',
+  'pandas',
+  'pybind11',
+  'pyodbc',
+  'ruff',
+  'markdown',
+]
+
+test = [
+  'pytest',
+  'pytest-xdist',
+  'coverage',
+  'coverage[toml]',
+  'pyodbc',
+  # Differential-test oracles: the pathlike harness compares decoding against
+  # reference implementations. These MUST be present wherever the suite acts
+  # as a merge gate (test_differential_oracles_installed_in_ci enforces it).
+  'pyyaml',
+  'tomli; python_version < "3.11"',
+  # `oo docs serve` renders Markdown pages; the docs-serve tests assert the rendering.
+  'markdown',
+]
+
+# `oo docs serve`: Markdown pages rendered on the fly (Mermaid fences become diagrams).
+docs = [
+  'markdown',
+]
+
+pandas = [
+  'pandas',
+]
+
+[project.scripts]
+pygim = "pygim.__main__:cli"
+oo = "pygim.__main__:cli_oo"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+python_files = "test_*.py"
+addopts = '-ra -q --doctest-glob="**/*.py" --tb=short --doctest-modules --doctest-continue-on-failure'
+testpaths = [
+    "tests/",       # doctests
+    "src/",
+]
+
+[tool.coverage.report]
+omit = [
+    "./docs/**/*.*",
+    "**/tests/**/*.*"
+    ]
+include = ["./src/**/*.py",
+           ]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if False",
+    "if __name__ == .__main__.:",
+    "@abc.abstractmethod",
+    "@abc.abstractproperty",
+]
+
+[tool.pygim.build]
+# The runtime requirements. They are dynamic because setup.py pins pyarrow to
+# the release the extensions were built against (setup.py::_pin_arrow_abi).
+dependencies = [
+  "click>=8",
+  "pyarrow>=15",
+  "polars>=0.20",
+  "tabulate>=0.9",
+  "typing_extensions>=4.0",
+]
+
+[tool.pygim.commands]
+
+[tool.mypy]
+exclude = [
+    'tests/.*',
+    'build/.*',
+]
+
+[tool.setuptools_scm]
+version_scheme = "no-guess-dev"
+local_scheme   = "dirty-tag"

pygim-0.1.0.dev1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+