diff --git a/.bumpversion.cfg b/.bumpversion.cfg new file mode 100644 index 000000000..3ebf2f5d8 --- /dev/null +++ b/.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}] diff --git a/.gitignore b/.gitignore index 8db521319..a12822fbd 100644 --- a/.gitignore +++ b/.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/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..612f5eebe --- /dev/null +++ b/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 `_. + +## [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. diff --git a/README.md b/README.md index 058dcda4a..a0f333bea 100644 --- a/README.md +++ b/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`, diff --git a/docs/release-checklist.md b/docs/release-checklist.md new file mode 100644 index 000000000..334bce126 --- /dev/null +++ b/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. diff --git a/pyproject.toml b/pyproject.toml index b19fee375..d44c30a83 100644 --- a/pyproject.toml +++ b/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" diff --git a/tools/__init__.py b/tools/__init__.py index e69de29bb..03a07e1ac 100644 --- a/tools/__init__.py +++ b/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"