ezmsg 3.6.2__tar.gz → 3.7.2__tar.gz

{ezmsg-3.6.2 → ezmsg-3.7.2}/.git-blame-ignore-revs

@@ -2,3 +2,5 @@
 5b4c220154d33cac15a75d3d7d978a75e67f2b8a
 # Ran `black` formatter on entire codebase and fixed non-standard line-endings with `dos2unix`.
 4e4f20be40a73f2162a565732bae76ea0c812739
+# chore: ruff formatting
+5ca5711e7714042f23d1286abf946217d75318c2

{ezmsg-3.6.2 → ezmsg-3.7.2}/.github/workflows/ci.yml

@@ -2,16 +2,20 @@ name: Test package
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
+      - dev
   pull_request:
-    branches: [main]
+    branches:
+      - main
+      - dev
   workflow_dispatch:
 
 jobs:
-  build:
+  pytest:
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10.15", "3.11"]  # Omit until shutdown fixed: , "3.12", "3.13"]
         os:
           - "ubuntu-latest"
           - "windows-latest"
@@ -22,16 +26,13 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v2
+        uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Set up Python ${{ matrix.python-version }}
-        run: uv python install ${{ matrix.python-version }}
+          python-version: ${{ matrix.python-version }}
 
       - name: Install the project
-        run: uv sync --all-extras --dev
+        run: uv sync
 
       - name: Run tests
-        run: uv run pytest tests
+        run: uv run pytest tests --benchmark-disable

ezmsg-3.7.2/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - dev
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install the project
+        run: uv sync --only-group docs
+
+      - name: Build documentation
+        run: |
+          cd docs
+          uv run make html
+
+      - name: Add .nojekyll file
+        run: touch docs/build/html/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/build/html'
+
+  deploy:
+    # Only deploy on push to main or release tags
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{ezmsg-3.6.2 → ezmsg-3.7.2}/.github/workflows/publish.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v6
 
       - name: Build Package
         run: uv build

{ezmsg-3.6.2 → ezmsg-3.7.2}/.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/build/
 docs/source/_build
 docs/source/generated
 
@@ -114,6 +115,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+uv.lock
 
 # Spyder project settings
 .spyderproject
@@ -141,3 +143,5 @@ cython_debug/
 
 # JetBrains
 .idea/
+
+*.local.json

{ezmsg-3.6.2 → ezmsg-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ezmsg
-Version: 3.6.2
+Version: 3.7.2
 Summary: A simple DAG-based computation model
 Author-email: Griffin Milsap <griffin.milsap@gmail.com>, Preston Peranich <pperanich@gmail.com>, Chadwick Boulay <chadwick.boulay@gmail.com>
 License: MIT License
@@ -15,21 +15,11 @@ License: MIT License
 License-File: LICENSE
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.8
-Requires-Dist: typing-extensions>=4.9.0
+Requires-Python: >=3.10
+Requires-Dist: array-api-compat>=1.12.0
+Requires-Dist: typing-extensions>=4.14.1
 Provides-Extra: axisarray
-Requires-Dist: numpy>=1.24.4; extra == 'axisarray'
-Provides-Extra: docs
-Requires-Dist: ezmsg-sigproc>=1.2.3; extra == 'docs'
-Requires-Dist: sphinx-rtd-theme==2.0.0; extra == 'docs'
-Requires-Dist: sphinx<=7.2; extra == 'docs'
-Provides-Extra: test
-Requires-Dist: flake8>=5.0.4; extra == 'test'
-Requires-Dist: numpy>=1.24.4; extra == 'test'
-Requires-Dist: pytest-asyncio>=0.23.8; extra == 'test'
-Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
-Requires-Dist: pytest>=7.0.0; extra == 'test'
-Requires-Dist: xarray>=2023.1.0; (python_version < '3.13') and extra == 'test'
+Requires-Dist: numpy>=2.2.6; extra == 'axisarray'
 Description-Content-Type: text/markdown
 
 # <img src="https://raw.githubusercontent.com/iscoe/ezmsg/main/docs/source/logo.png" width="50"/> ezmsg
@@ -71,6 +61,19 @@ Note that it is generally recommended to install poetry into its own standalone
 
 ## Documentation
 
+To build the documentation in this branch, install sphinx
+
+```bash
+pip install sphinx
+```
+
+Then change directory to the `docs/` folder and run the `make.bat` file with an html specification.
+
+```bash
+cd docs
+uv run make.bat html
+```
+
 https://ezmsg.readthedocs.io/en/latest/
 
 `ezmsg` is very similar to [`labgraph`](https://www.github.com/facebookresearch/labgraph), so you might get a primer with their documentation and examples. Additionally, there are many examples provided in the examples/tests directories strewn throughout this repository.

{ezmsg-3.6.2 → ezmsg-3.7.2}/README.md

@@ -37,6 +37,19 @@ Note that it is generally recommended to install poetry into its own standalone
 
 ## Documentation
 
+To build the documentation in this branch, install sphinx
+
+```bash
+pip install sphinx
+```
+
+Then change directory to the `docs/` folder and run the `make.bat` file with an html specification.
+
+```bash
+cd docs
+uv run make.bat html
+```
+
 https://ezmsg.readthedocs.io/en/latest/
 
 `ezmsg` is very similar to [`labgraph`](https://www.github.com/facebookresearch/labgraph), so you might get a primer with their documentation and examples. Additionally, there are many examples provided in the examples/tests directories strewn throughout this repository.

ezmsg-3.7.2/docs/source/_static/custom.css

@@ -0,0 +1,77 @@
+/* -- theme ------------------------------------------------------------------------------ */
+/* -- some theme elements are taken from the Jupyter theme, see -------------------------- */
+/* -- https://github.com/jupyter/jupyter/blob/master/docs/source/_static/custom.css ------ */
+
+:root {
+    /* colors from from https://github.com/jupyter/jupyter.github.io/blob/master/_sass/settings/_colors.scss */
+    --color-dark-orange: 197, 84, 11;
+    --color-dark-grey: 77, 77, 77;
+    --pst-color-link: var(--color-dark-orange);
+
+    --pst-color-h1: var(--color-dark-grey);
+    --pst-color-h2: var(--color-dark-grey);
+    --pst-color-h3: var(--color-dark-grey);
+    --pst-color-h4: var(--color-dark-grey);
+    --pst-color-h5: var(--color-dark-grey);
+    --pst-color-h6: var(--color-dark-grey);
+
+    --pst-color-active-navigation: var(--color-dark-orange);
+}
+
+/* -- navbar ------------------------------------------------------------- */
+
+.navbar-brand {
+    padding: 0.4em;
+}
+
+/* -- topics ------------------------------------------------------------- */
+
+div.topic {
+    border: 0px solid #ccc;
+    padding: 7px 7px 0 7px;
+    margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+    font-size: 1.1em;
+    font-weight: bold;
+    margin-top: 10px;
+}
+
+.alert {
+    color: #222222;
+}
+
+p.first.admonition-title {
+	color: #ffffff;
+}
+
+
+/* Front page table styling */
+
+.front-page-table td > p {
+    margin-bottom: 0em;
+}
+
+.front-page-table td > p:last-child {
+    font-style: italic;
+}
+
+.front-page-table a.reference {
+    font-size: 1.3em;
+}
+
+.front-page-table.table td, .front-page-table.table th {
+    border: none;
+    padding-top: .3em;
+    padding-bottom: .3em;
+}
+
+div.sd-card ul.simple {
+    list-style: none;
+    padding-left: 1em;
+}
+
+.bd-content .sd-card .sd-card-header {
+    background-color: var(--pst-color-surface);
+}

ezmsg-3.7.2/docs/source/conf.py

@@ -0,0 +1,108 @@
+# Configuration file for the Sphinx documentation builder.
+
+import os
+
+# -- Project information --------------------------
+
+project = "ezmsg"
+copyright = "2022, JHU/APL"
+author = "JHU/APL"
+
+# Read version from pyproject.toml
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+pyproject_path = os.path.join(os.path.dirname(__file__), "../../pyproject.toml")
+with open(pyproject_path, "rb") as f:
+    pyproject_data = tomllib.load(f)
+    release = pyproject_data["project"]["version"]
+    version = release
+
+
+# -- General configuration --------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.doctest",
+    "sphinx.ext.duration",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
+]
+
+templates_path = ["_templates"]
+
+source_suffix = [".rst"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+add_module_names = True
+
+# The toctree master document
+master_doc = "index"
+
+# When set to True, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Autodoc configuration ------------------------------
+autodoc_typehints_format = "short"
+python_use_unqualified_type_names = True
+
+# -- Intersphinx configuration --------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "ezmsg.sigproc": ("https://www.ezmsg.org/ezmsg-sigproc", None),
+    "ezmsg.learn": ("https://www.ezmsg.org/ezmsg-learn", None),
+    "ezmsg.blackrock": ("https://www.ezmsg.org/ezmsg-blackrock", None),
+    "ezmsg.event": ("https://www.ezmsg.org/ezmsg-event", None),
+    "ezmsg.lsl": ("https://www.ezmsg.org/ezmsg-lsl", None),
+    "ezmsg.tools": ("https://www.ezmsg.org/ezmsg-tools", None),
+    "ezmsg.xdf": ("https://www.ezmsg.org/ezmsg-xdf", None),
+    "ezmsg.zmq": ("https://www.ezmsg.org/ezmsg-zmq", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+# -- Options for HTML output -----------------------------
+
+html_theme = "pydata_sphinx_theme"
+html_logo = "_static/_images/ezmsg_logo.png"
+html_favicon = "_static/_images/ezmsg_logo.png"
+html_title = f"ezmsg {version}"
+
+html_static_path = ["_static"]
+
+# Timestamp is inserted at every page bottom in this strftime format.
+html_last_updated_fmt = "%Y-%m-%d"
+
+# -- Options for EPUB output --------------------------
+epub_show_urls = "footnote"
+
+branch = "main"
+code_url = f"https://github.com/ezmsg-org/ezmsg/blob/{branch}/"
+
+
+def linkcode_resolve(domain, info):
+    if domain != "py":
+        return None
+    if not info["module"]:
+        return None
+    filename = info["module"].replace(".", "/")
+    if "core" in filename:
+        return f"{code_url}src/ezmsg/core/__init__.py"
+    else:
+        return f"{code_url}src/{filename}.py"
+
+
+# -- Options for graphviz -----------------------------
+graphviz_output_format = "svg"
+
+
+def setup(app):
+    app.add_css_file("custom.css")

ezmsg-3.7.2/docs/source/index.rst

@@ -0,0 +1,21 @@
+ezmsg API Reference
+####################
+
+This is the API reference documentation for the **ezmsg** core library.
+
+For tutorials, guides, examples, and general documentation, visit `<https://www.ezmsg.org>`_
+
+API Documentation
+*****************
+
+.. toctree::
+   :maxdepth: 2
+
+   reference/content-reference
+
+
+Indices and tables
+******************
+
+* :ref:`genindex`
+* :ref:`modindex`

ezmsg-3.7.2/docs/source/reference/API/axisarray-util-units.rst

@@ -0,0 +1,42 @@
+AxisArray Utility Methods and Units
+=================================================
+
+Utility classes which implement functionality related to messages. These include a method for instantiating new instances of a dataclass given an existing instance:
+
+- :class:`replace <ezmsg.util.messages.axisarray.replace>` - Function for creating a new dataclass instance by replacing attributes of an existing instance
+
+and several :class:`ezmsg Unit <ezmsg.core.Unit>` classes which operate on :class:`AxisArray <ezmsg.util.messages.axisarray.AxisArray>` messages:
+
+- :class:`ArrayChunker <ezmsg.util.messages.chunker.ArrayChunker>` - ezmsg Unit to chunk AxisArray messages along specified axes
+- :class:`SetKey <ezmsg.util.messages.key.SetKey>` - ezmsg Unit for setting the key of incoming AxisArray messages
+- :class:`FilterOnKey <ezmsg.util.messages.key.FilterOnKey>` - ezmsg Unit for filtering an AxisArray based on its key.
+- :class:`ModifyAxis <ezmsg.util.messages.modify.ModifyAxis>` - ezmsg Unit for modifying axis names and dimensions of AxisArray messages.
+
+replace
+------------
+
+.. autofunction:: ezmsg.util.messages.axisarray.replace
+
+
+Array Chunking
+---------------
+
+.. automodule:: ezmsg.util.messages.chunker
+   :show-inheritance:
+   :members:
+
+
+Modifying AxisArray "key"
+---------------------------
+
+.. automodule:: ezmsg.util.messages.key
+   :show-inheritance:
+   :members:
+
+
+Modifying AxisArray "axes"
+------------------------------
+
+.. automodule:: ezmsg.util.messages.modify
+   :show-inheritance:
+   :members:

ezmsg-3.7.2/docs/source/reference/API/axisarray.rst

@@ -0,0 +1,7 @@
+AxisArray module
+##################
+
+
+.. automodule:: ezmsg.util.messages.axisarray
+   :show-inheritance:
+   :members:

ezmsg-3.7.2/docs/source/reference/API/components.rst

@@ -0,0 +1,68 @@
+Components - Units and Collections
+===================================
+
+An ezmsg pipeline is created from a few basic components. ezmsg provides a framework for you to define your own graphs using its building blocks. The nodes of the graph that defines a pipeline all inherit from the base class :class:`Component <ezmsg.core.Component>`. The two types of Component are :class:`Unit <ezmsg.core.Unit>` and :class:`Collection <ezmsg.core.Collection>`.
+
+.. note:: It is convention to ``import ezmsg.core as ez`` and then use this shorthand in your code. e.g.,
+
+   .. code-block:: python
+
+      class MyUnit(ez.Unit):
+         ...
+
+
+Component
+----------
+
+.. autoclass:: ezmsg.core.Component
+
+Unit
+---------
+
+The basic nodes of an ezmsg pipeline graph are :class:`Units <ezmsg.core.Unit>`.
+
+.. autoclass:: ezmsg.core.Unit
+   :show-inheritance:
+   :members:
+   :inherited-members:
+
+
+Collection
+------------
+
+A :class:`Collection <ezmsg.core.Collection>` is a special type of :class:`Component <ezmsg.core.Component>` that contains other :class:`Components <ezmsg.core.Component>` (:class:`Units <ezmsg.core.Unit>` and/or other :class:`Collections <ezmsg.core.Collection>`).
+
+.. autoclass:: ezmsg.core.NetworkDefinition
+
+.. autoclass:: ezmsg.core.Collection
+   :show-inheritance:
+   :members:
+
+
+Component Interaction
+---------------------
+
+Two fundamental attributes of a :class:`Component <ezmsg.core.Component>` are its :class:`Settings <ezmsg.core.Settings>` and :class:`State <ezmsg.core.State>`, both of which are optional but initialised by the ezmsg backend during :class:`Unit <ezmsg.core.Unit>` initialisation (if present).
+
+.. autoclass:: ezmsg.core.Settings
+
+.. autoclass:: ezmsg.core.State
+
+
+Stream
+------
+
+Facilitates a flow of Messages into or out of a :class:`Component <ezmsg.core.Component>`.
+
+.. autoclass:: ezmsg.core.InputStream
+
+.. autoclass:: ezmsg.core.OutputStream
+
+Custom Exceptions
+-----------------
+
+These are custom exceptions defined in ezmsg.
+
+.. autoclass:: ezmsg.core.Complete
+
+.. autoclass:: ezmsg.core.NormalTermination

ezmsg-3.7.2/docs/source/reference/API/content-api.rst

@@ -0,0 +1,13 @@
+Commonly Used API
+###########################
+
+
+.. toctree::
+   :maxdepth: 1
+
+   components
+   functiondecorators
+   entrypoint
+   axisarray
+   axisarray-util-units
+   util-units

ezmsg-3.7.2/docs/source/reference/API/entrypoint.rst

@@ -0,0 +1,9 @@
+`ezmsg` Entry Point
+========================
+
+An ezmsg pipeline is instantiated through a call to ``ezmsg.core.run()``. 
+
+.. note:: It is convention to ``import ezmsg.core as ez`` and then use this shorthand in your code.
+
+
+.. autofunction:: ezmsg.core.run

ezmsg-3.7.2/docs/source/reference/API/functiondecorators.rst

@@ -0,0 +1,18 @@
+Unit Function Decorators
+******************************************
+
+These function decorators can be added to member functions of an ezmsg ``Unit`` or ``Collection``.
+
+.. autodecorator:: ezmsg.core.subscriber
+
+.. autodecorator:: ezmsg.core.publisher
+
+.. autodecorator:: ezmsg.core.main
+
+.. autodecorator:: ezmsg.core.thread
+
+.. autodecorator:: ezmsg.core.task
+
+.. autodecorator:: ezmsg.core.process
+
+.. autodecorator:: ezmsg.core.timeit

ezmsg-3.7.2/docs/source/reference/API/util-units.rst

@@ -0,0 +1,71 @@
+Utility Units and Classes
+===========================
+
+Utility :class:`ezmsg Units <ezmsg.core.Unit>` and associated classes for `ezmsg` pipelines. Currently includes the following Units:
+
+- :class:`DebugLog <ezmsg.util.debuglog.DebugLog>`: An ezmsg Unit for logging message debug information. Convenient way to print message contents without modifying other units.
+- :class:`TerminateOnTimeout <ezmsg.util.terminate.TerminateOnTimeout>`: An ezmsg Unit that terminates the pipeline after a specified timeout period.
+- :class:`TerminateOnTotal <ezmsg.util.terminate.TerminateOnTotal>`: An ezmsg Unit that terminates the pipeline after a specified total number of messages have been processed.
+- :class:`MessageGate <ezmsg.util.messagegate.MessageGate>`: An ezmsg Unit that blocks messages based on a condition: open, open after N messages, closed, or closed after N messages.
+- :class:`MessageLogger <ezmsg.util.messagelogger.MessageLogger>`: An ezmsg Unit that logs all messages passing through it to a file.
+- :class:`MessageQueue <ezmsg.util.messagequeue.MessageQueue>`: An ezmsg Unit that is placed between two other Units to induce backpressure.
+- :class:`MessageCollector <ezmsg.util.messagereplay.MessageCollector>`: An ezmsg Unit that collects messages into a local list.
+- :class:`MessageReplay <ezmsg.util.messagereplay.MessageReplay>`: An ezmsg Unit that streams messages from :class:`MessageLogger <ezmsg.util.messagelogger.MessageLogger>` created files.
+
+and utility classes for encoding/decoding messages:
+
+- :class:`MessageDecoder <ezmsg.util.messagecodec.MessageDecoder>`: Utility class that decodes ezmsg messages from their JSON representation.
+- :class:`MessageEncoder <ezmsg.util.messagecodec.MessageEncoder>`: Utility class that encodes ezmsg messages to their JSON representation.
+
+DebugLog
+--------
+
+.. automodule:: ezmsg.util.debuglog
+   :show-inheritance:
+   :members:
+
+
+Terminate
+---------
+
+.. automodule:: ezmsg.util.terminate
+   :show-inheritance:
+   :members:
+
+MessageReplay
+-------------
+
+.. automodule:: ezmsg.util.messagereplay
+   :show-inheritance:
+   :members:
+
+
+MessageGate
+-----------
+
+.. automodule:: ezmsg.util.messagegate
+   :show-inheritance:
+   :members:
+
+
+MessageLogger
+-------------
+
+.. automodule:: ezmsg.util.messagelogger
+   :show-inheritance:
+   :members:
+
+
+MessageQueue
+------------
+
+.. automodule:: ezmsg.util.messagequeue
+   :show-inheritance:
+   :members:
+
+MessageCodec
+------------
+
+.. automodule:: ezmsg.util.messagecodec
+   :show-inheritance:
+   :members: