Set up Python packaging and release process

.bumpversion.cfg

@@ -0,0 +1,12 @@
+[bumpversion]
+current_version = 0.1.0
+commit = True
+tag = True
+
+[bumpversion:file:tools/__init__.py]
+search = __version__ = "{current_version}"
+replace = __version__ = "{new_version}"
+
+[bumpversion:file:CHANGELOG.md]
+search = ## [{current_version}]
+replace = ## [{new_version}]

.gitignore

@@ -34,6 +34,11 @@ sql_cache/*
 # Compiled python file
 *.pyc
 
+# Python packaging artifacts
+build/
+dist/
+*.egg-info/
+
 # Workload directory
 bench/workflows/*
 bench/conf/custom/

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format roughly follows `Keep a Changelog <https://keepachangelog.com/>`_.
+
+## [0.1.0] - 2025-10-24
+### Added
+- Initial packaging configuration for the Python analysis utilities.
+- Version management via ``bump2version``.
+- Release checklist documenting the release process.

README.md

@@ -7,6 +7,18 @@ MacroBase is a data analytics tool that prioritizes attention in large datasets
 
 For tutorial, documentation, papers and additional information, please refer to our project website: http://macrobase.stanford.edu/.
 
+### Python analysis utilities
+
+This repository now exposes a distributable Python package named
+``macrobasev`` that contains the analysis utilities previously found under the
+``tools`` directory. The package can be built locally with::
+
+    python -m build
+
+which will generate both a source distribution and a wheel under ``dist/``.
+After building you can inspect the artifacts with ``twine check dist/*`` and,
+once satisfied, publish them to PyPI as described in
+``docs/release-checklist.md``.
 ### MacroBase Python Toolkit
 
 This repository now includes an experimental Python package, `macrobase-py`,

docs/release-checklist.md

@@ -0,0 +1,32 @@
+# MacroBase Python Utilities Release Checklist
+
+This checklist covers the steps required to publish a new version of the
+``macrobasev`` Python distribution to PyPI.
+
+1. **Preparation**
+   - Make sure all pending work is merged and the codebase is clean.
+   - Update ``CHANGELOG.md`` with the highlights for the release.
+   - Confirm the version number you plan to release.
+
+2. **Run tests and quality checks**
+   - Execute the project's automated tests (if applicable).
+   - Run ``python -m build`` to ensure sdist and wheel artifacts can be
+     created successfully.
+   - Run ``twine check dist/*`` to validate the distribution metadata.
+
+3. **Bump the version**
+   - Use ``bump2version`` to increment the version appropriately, for example:
+     ``bump2version patch``.
+   - Push the resulting commit and tag to the upstream repository.
+
+4. **Publish to PyPI**
+   - Ensure you have valid credentials configured for ``twine``.
+   - Upload the artifacts with ``twine upload dist/*``.
+   - Verify that the release appears on https://pypi.org/project/macrobasev/.
+
+5. **Post-release**
+   - Announce the release as appropriate (mailing list, Slack, etc.).
+   - Create an issue or milestone for the next development cycle.
+
+Following these steps ensures that each release is consistent, well-documented,
+and reproducible.

pyproject.toml

@@ -1,4 +1,57 @@
 [build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "macrobasev"
+dynamic = ["version"]
+description = "Python analysis utilities that accompany the MacroBase project"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+authors = [{name = "MacroBase Contributors"}]
+keywords = ["macrobase", "anomaly detection", "analytics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "psycopg2",
+    "matplotlib",
+    "pandas",
+    "pyyaml",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "twine",
+    "bump2version",
+]
+
+[project.urls]
+Homepage = "https://github.com/stanford-futuredata/macrobase"
+Source = "https://github.com/stanford-futuredata/macrobase"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = {attr = "tools.__version__"}
+
+[tool.setuptools.packages.find]
+include = ["tools", "tools.*"]
+
+[tool.setuptools.package-data]
+"tools.bench" = ["*.conf", "*.txt", "matplotlibrc"]
 requires = ["hatchling>=1.18"]
 build-backend = "hatchling.build"
 

tools/__init__.py

@@ -0,0 +1,11 @@
+"""Python utilities and analysis scripts for MacroBase.
+
+This module now exposes a :data:`__version__` attribute so packaging tools
+can derive the canonical version number for the distribution.
+"""
+
+__all__ = []
+
+# NOTE: Keep the version in sync with the value referenced by the packaging
+# configuration in ``pyproject.toml`` and the bumpversion configuration.
+__version__ = "0.1.0"