mgplot 0.1.3__tar.gz → 0.1.5__tar.gz

mgplot-0.1.5/.gitignore

@@ -0,0 +1,27 @@
+# python stuff to be ignored
+__pycache__/
+*.py[cod]
+*$py.class
+
+# jupyter notebooks stuff to be ignored
+.ipynb_checkpoints/
+
+# vscode stuff
+.vscode/
+
+# MacOS stuff to be ignored
+.DS_Store
+
+
+# build files
+build/
+dist/
+wheels/
+*.egg-info
+
+# Test 
+src/mgplot/zz-test-charts/**
+src/mgplot/zz-unused-code-snippets/**
+
+# Virtual environments
+.venv

mgplot-0.1.5/CHANGELOG.md

@@ -0,0 +1,49 @@
+Version 0.1.4 - released 01-Jun-2025 (Canberra, Australia)
+
+* minor changes
+     - changed the build-system
+     - added dynamic version numbering to __init__.py
+     - reworked annotations in the growth_plot.py module
+       and the utilities module,
+     - reworked kwargs validation in plot_then_finalise() 
+     - typo in kw_type_checking.py
+     - tightened up function chaining in the multi-plot modules
+     - moved some default arguments from the finalisers module
+       to the line_plot module.
+     
+---
+
+Version 0.1.3 - released 31-May-2025 (Canberra, Australia)
+
+* minor changes
+     - changed defaults for postcovid_plot() to annotate series
+     - changed line_plot() to bail early if nothing to plot
+     - added a test to ignore empty axes objects in finalise_plot()
+     - reduced the text size for runs in run_plot()
+     - added "legend" to line_plot() and the growth plots.
+     - if the plot function and the finalise_plot() function have
+       kwargs in common, they will be handled by plot() and not
+       sent to finalise plot (done by plot_then_finalise())
+---
+
+Version 0.1.2 - released 30-May-2025 (Canberra, Australia)
+
+* minor changes
+     - fixed an incorrect typing-gate in run_plot()
+     - removed repeated version code in __init__.py
+     - added "numpy-typing" to pyproject.toml
+     - added a warning if ylabel set in series_growth_plot_finalise()
+     - added legend=True default argument to raw_growth_plot()
+---
+
+Version 0.1.1 - released 29-May-2025 (Canberra, Australia)
+
+* minor changes
+     - added additional documentation
+     - disclosed additional variables in the API
+     - standardised the naming of the internal ExpectedTypeDicts
+---
+
+Version 0.1.0 - released 28-May-2025 (Canberra, Australia)
+
+---

{mgplot-0.1.3/src/mgplot.egg-info → mgplot-0.1.5}/PKG-INFO

@@ -1,29 +1,18 @@
 Metadata-Version: 2.4
 Name: mgplot
-Version: 0.1.3
+Version: 0.1.5
 Summary: mgplot is a time-series/PeriodIndex frontend for matplotlib
+Project-URL: Repository, https://github.com/bpalmer4/mgplot
 Project-URL: Homepage, https://github.com/bpalmer4/mgplot
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: typing
-Requires-Dist: pathlib
+Requires-Python: >=3.12
 Requires-Dist: matplotlib
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: pathlib
 Requires-Dist: tabulate
-Requires-Dist: black
-Requires-Dist: mypy
-Requires-Dist: pdoc
-Requires-Dist: pylint
-Requires-Dist: ruff
-Requires-Dist: pandas-stubs
-Requires-Dist: numpy-typing
-Requires-Dist: types-tabulate
-Provides-Extra: build
-Requires-Dist: setuptools; extra == "build"
-Requires-Dist: cython; extra == "build"
-Dynamic: license-file
+Requires-Dist: typing
+Description-Content-Type: text/markdown
 
 mgplot
 ======

mgplot-0.1.5/build-docs.sh

@@ -0,0 +1,6 @@
+echo " "
+echo "About to build the documentation ..."
+cd ~/mgplot
+rm -rf ./docs
+pdoc ./src/mgplot -o ./docs 
+

mgplot-0.1.5/build-test.sh

@@ -0,0 +1,33 @@
+#!/bin/zsh
+# make sure the version number is correct:
+# ~/mgplot/pyproject.toml
+
+# --- cd mgplot home and get ready
+cd ~/mgplot
+uv pip uninstall mgplot
+deactivate
+
+# --- clean out the dist folder
+if [ ! -d ./dist ]; then
+    mkdir dist
+fi
+if [ -n "$(ls -A ./dist 2>/dev/null)" ]; then
+  rm ./dist/*
+fi
+
+# --- sync and build
+uv lock --upgrade  # --upgrade to get the latest dependencies
+uv sync --no-dev  # --no-dev to avoid installing dev dependencies
+uv build
+
+# --- install new mgplot locally
+uv sync  # install with the development dependencies
+uv pip install dist/mgplot*gz  # add in the new package
+
+# --- build documentation
+~/mgplot/build-docs.sh
+
+# --- if everything is good publish and git
+echo "\nAnd if everything is okay ..."
+echo "uv publish --token MY_TOKEN_HERE"
+echo "And don't forget to upload to github"

{mgplot-0.1.3 → mgplot-0.1.5}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "mgplot"
-version = "0.1.3"
+version = "0.1.5"
 description = "mgplot is a time-series/PeriodIndex frontend for matplotlib"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 
 dependencies = [
     # - system
@@ -15,24 +15,27 @@ dependencies = [
     "numpy",
     "pandas",
     "tabulate",
+]
 
-    # - development environment
+[dependency-groups]
+dev = [
+    # - tools
     "black",
     "mypy",
     "pdoc",
     "pylint",
     "ruff",
-
+    
     # - typing
     "pandas-stubs",
     "numpy-typing",
     "types-tabulate",
 ]
 
-[project.optional-dependencies]
-build = ["setuptools", "cython"]
-
 [project.urls]
+Repository = "https://github.com/bpalmer4/mgplot"
 Homepage = "https://github.com/bpalmer4/mgplot"
 
-
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

{mgplot-0.1.3 → mgplot-0.1.5}/src/mgplot/__init__.py

@@ -7,14 +7,10 @@ with timeseries data that is indexed with a PeriodIndex.
 """
 
 # --- version and author
-# NOTE: update version number here (below) and in pyproject.toml
-__version__ = "0.1.3"
-__author__ = "Bryan Palmer"
-
+import importlib.metadata
 
 # --- local imports
 #    Do not import the utilities, test nor type-checking modules here.
-from mgplot.kw_type_checking import ExpectedTypeDict  # typing for the kwarg types
 from mgplot.finalise_plot import finalise_plot, FINALISE_KW_TYPES
 from mgplot.bar_plot import bar_plot, BAR_KW_TYPES
 from mgplot.line_plot import line_plot, LINE_KW_TYPES
@@ -63,6 +59,14 @@ from mgplot.finalisers import (
 )
 
 
+# --- version and author
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+__author__ = "Bryan Palmer"
+
+
 # --- public API
 __all__ = (
     "__version__",
@@ -115,7 +119,6 @@ __all__ = (
     "series_growth_plot_finalise",
     "run_plot_finalise",
     # --- typing information
-    "ExpectedTypeDict",
     "FINALISE_KW_TYPES",
     "BAR_KW_TYPES",
     "LINE_KW_TYPES",

{mgplot-0.1.3 → mgplot-0.1.5}/src/mgplot/finalisers.py

@@ -46,15 +46,6 @@ def line_plot_finalise(
     wraps calls to line_plot() and finalise_plot().
     """
 
-    if isinstance(data, DataFrame):
-        if len(data.columns) > 1:
-            # default to displaying a legend
-            kwargs["legend"] = kwargs.get("legend", True)
-        if len(data.columns) > 4:
-            # default to using a style for the lines
-            kwargs["style"] = kwargs.get(
-                "style", ["solid", "dashed", "dashdot", "dotted"]
-            )
     plot_then_finalise(
         data,
         function=line_plot,
@@ -249,6 +240,7 @@ if __name__ == "__main__":
             data=test_frame,
             title="Test Line Plot",
             ylabel="Value",
+            annotate=True,
             xlabel=None,
         )
 
@@ -306,7 +298,6 @@ if __name__ == "__main__":
             function=series_growth_plot_finalise,
             starts=[0, -19],
             title="Test Multi Start Series Growth Plot: ",
-            ylabel="Per cent Growth",
             xlabel=None,
         )
 

{mgplot-0.1.3 → mgplot-0.1.5}/src/mgplot/growth_plot.py

@@ -18,7 +18,7 @@ from mgplot.finalise_plot import make_legend
 from mgplot.test import prepare_for_test
 from mgplot.settings import get_setting, DataT
 from mgplot.date_utils import set_labels
-from mgplot.utilities import annotate_series, check_clean_timeseries
+from mgplot.utilities import annotate_series, check_clean_timeseries, default_rounding
 from mgplot.kw_type_checking import (
     validate_kwargs,
     report_kwargs,
@@ -31,15 +31,22 @@ from mgplot.kw_type_checking import (
 ANNUAL = "annual"
 PERIODIC = "periodic"
 
+ANNOTATE_BAR = "annotate_bar"
+ANNOTATE_LINE = "annotate_line"
+BAR_ROUNDING = "bar_rounding"
+ROUNDING = "rounding"
+
+
 RAW_GROWTH_KW_TYPES: Final[ExpectedTypeDict] = {
     "line_width": (float, int),
     "line_color": str,
     "line_style": str,
-    "annotate_line": (type(None), int, str),
+    ANNOTATE_LINE: (type(None), bool, int, str),  # None, True or fontsize
+    ROUNDING: (type(None), bool, int),  # None, True or rounding
     "bar_width": float,
     "bar_color": str,
-    "annotate_bar": (type(None), int, str),
-    "annotation_rounding": int,
+    ANNOTATE_BAR: (type(None), bool, int, str),  # None, True or fontsize
+    BAR_ROUNDING: (type(None), bool, int),  # None, True or rounding
     "plot_from": (type(None), Period, int),
     "max_ticks": int,
     "legend": (type(None), bool, dict, (str, object)),
@@ -108,44 +115,45 @@ def _annotations(
 ) -> None:
     """Apply annotations the annual and periodic growth series."""
 
-    annotate_line = kwargs.get("annotate_line", "small")
-    if annotate_line is not None:
-        annotate_series(
-            annual,
-            axes,
-            rounding=kwargs.get("annotation_rounding", True),
-            fontsize=annotate_line,
-            color=kwargs.get("line_color", "darkblue"),
+    # --- annotate the end of the line
+    annotate_line = kwargs.get(ANNOTATE_LINE, True)  #
+    if annotate_line is not None and annotate_line is not False:
+        fontsize = kwargs.pop("fontsize", annotate_line)
+        annotate_series(annual, axes, fontsize=fontsize, **kwargs)
+
+    # --- annotate each bar
+    annotate_bar = kwargs.get(ANNOTATE_BAR, True)  # really fontsize
+    if annotate_bar is None or annotate_bar is False:
+        return
+    if annotate_bar is True:
+        annotate_bar = "small"
+    max_annotations = 25
+    if len(periodic) > max_annotations:
+        return
+
+    rounding = kwargs.get(BAR_ROUNDING, True)
+    if rounding is None or isinstance(rounding, bool):
+        value = periodic.abs().max()
+        rounding = default_rounding(value)
+    annotate_style = {
+        "fontsize": annotate_bar,
+        "fontname": "Helvetica",
+    }
+    adjustment = (periodic.max() - periodic.min()) * 0.01
+    for i, value in enumerate(periodic):
+        va = "bottom" if value >= 0 else "top"
+        text = axes.text(
+            periodic.index[i],
+            adjustment if value >= 0 else -adjustment,
+            f"{value:.{rounding}f}",
+            ha="center",
+            va=va,
+            **annotate_style,
+            color="white",
+        )
+        text.set_path_effects(
+            [pe.withStroke(linewidth=2, foreground=kwargs.get("bar_color", "#dd0000"))]
         )
-
-    annotate_bar = kwargs.get("annotate_bar", "small")
-    max_annotations = 30
-    if annotate_bar is not None and len(periodic) < max_annotations:
-        annotation_rounding = kwargs.get("annotation_rounding", 1)
-        annotate_style = {
-            "fontsize": annotate_bar,
-            "fontname": "Helvetica",
-        }
-        adjustment = (periodic.max() - periodic.min()) * 0.005
-        for i, value in enumerate(periodic):
-            va = "bottom" if value >= 0 else "top"
-            text = axes.text(
-                periodic.index[i],
-                adjustment if value >= 0 else -adjustment,
-                f"{value:.{annotation_rounding}f}",
-                ha="center",
-                va=va,
-                **annotate_style,
-                fontdict=None,
-                color="white",
-            )
-            text.set_path_effects(
-                [
-                    pe.withStroke(
-                        linewidth=2, foreground=kwargs.get("bar_color", "indianred")
-                    )
-                ]
-            )
 
 
 def raw_growth_plot(
@@ -162,15 +170,17 @@ def raw_growth_plot(
         -   line_width: The width of the line (default is 2).
         -   line_color: The color of the line (default is "darkblue").
         -   line_style: The style of the line (default is "-").
-        -   annotate_line: None | int | str - fontsize to annotate the line
-            (default is "small", which means the line is annotated with
+        -   annotate_line: None | bool | int | str - fontsize to annotate
+            the line (default is "small", which means the line is annotated with
             small text).
+        -   rounding: None | bool | int - the number of decimal places to round
+            the line (default is 0).
         -   bar_width: The width of the bars (default is 0.8).
         -   bar_color: The color of the bars (default is "indianred").
         -   annotate_bar: None | int | str - fontsize to annotate the bars
             (default is "small", which means the bars are annotated with
             small text).
-        -   annotation_rounding: The number of decimal places to round the
+        -   bar_rounding: The number of decimal places to round the
             annotations to (default is 1).
         -   plot_from: None | Period | int -- if:
             -   None: the entire series is plotted
@@ -217,8 +227,10 @@ def raw_growth_plot(
     periodic.name = {"M": "Monthly", "Q": "Quarterly", "D": "Daily"}[
         PeriodIndex(save_index).freqstr[:1]
     ] + " Growth"
+    color = kwargs.get("bar_color", "#dd0000")
+    kwargs["bar_color"] = color  # for annotations
     axes = periodic.plot.bar(
-        color=kwargs.get("bar_color", "indianred"),
+        color=color,
         width=kwargs.get("bar_width}", 0.8),
     )
     thin_threshold = 180

{mgplot-0.1.3 → mgplot-0.1.5}/src/mgplot/kw_type_checking.py

@@ -379,7 +379,7 @@ def validate_kwargs(
             continue
         if key not in expected:
             problems += (
-                f"{key}: unexpected keyword argument with {value=}in {called_from}.\n"
+                f"{key}: keyword not recognised. Has {value=} " + f"in {called_from}.\n"
             )
             continue
         if not _type_check_kwargs(value, expected[key]):

{mgplot-0.1.3 → mgplot-0.1.5}/src/mgplot/line_plot.py

@@ -130,6 +130,14 @@ def line_plot(data: DataT, **kwargs) -> plt.Axes:
     df = DataFrame(data)  # really we are only plotting DataFrames
     df, kwargs = constrain_data(df, **kwargs)
 
+    # --- some special defaults
+    if len(df.columns) > 1:
+        # default to displaying a legend
+        kwargs["legend"] = kwargs.get("legend", True)
+    if len(df.columns) > 4:
+        # default to using a style for the lines
+        kwargs["style"] = kwargs.get("style", ["solid", "dashed", "dashdot", "dotted"])
+
     # --- Let's plot
     axes, kwargs = get_axes(**kwargs)  # get the axes to plot on
     if df.empty or df.isna().all().all():

mgplot-0.1.5/src/mgplot/lint-all.sh

@@ -0,0 +1,19 @@
+echo "black"
+black *.py
+
+echo "pylint"
+pylint *.py
+
+echo "mypy"
+mypy *.py
+
+echo "ruff"
+ruff check *.py
+
+# report any lint overrides
+echo " "
+echo "Check linting overrides ..."
+grep "# type" *.py
+grep "# pylint" *.py
+grep --regexp="from typing import .*cast" *.py
+grep "cast(" *.py

{mgplot-0.1.3 → mgplot-0.1.5}/src/mgplot/multi_plot.py

@@ -36,7 +36,7 @@ Note: rather than pass the kwargs dict directly, we will re-pack-it
 """
 
 # --- imports
-from typing import Any, Callable, Final
+from typing import Callable, Final
 from collections.abc import Iterable
 from pandas import Period, DataFrame, Series, period_range
 from numpy import random
@@ -85,8 +85,7 @@ EXPECTED_CALLABLES: Final[dict[Callable, ExpectedTypeDict]] = {
 # --- private functions
 def first_unchain(
     function: Callable | list[Callable],
-    **kwargs,
-) -> tuple[Callable, dict[str, Any]]:
+) -> tuple[Callable, list[Callable]]:
     """
     Extract the first Callable from function (which may be
     a stand alone Callable or a nonr-empty list of Callables).
@@ -94,12 +93,10 @@ def first_unchain(
     This allows for chaining multiple functions together.
 
     Parameters
-    - kwargs - keyword arguments
+    - function - a Callable or a non-empty list of Callables
 
-    Returns a tuple containing the first function and the updated kwargs.
-    if function is a list of Callables, the first function will be removed
-    from the the list, and the remaining functions will be stored in a
-    list under the key "function" in kwargs.
+    Returns a tuple containing the first function and a list of the remaining
+    functions (which may be empty if there are no remaining functions).
 
     Raises ValueError if function is an empty list.
 
@@ -117,10 +114,7 @@ def first_unchain(
     else:
         raise ValueError(error_msg)
 
-    if rest:
-        kwargs["function"] = rest
-
-    return first, kwargs
+    return first, rest
 
 
 # --- public functions
@@ -151,8 +145,17 @@ def plot_then_finalise(
     # data is not checked here, assume it is checked by the called
     # plot function.
 
-    # --- check the function argument
-    first, kwargs_ = first_unchain(function, **kwargs)
+    first, kwargs["function"] = first_unchain(function)
+    if not kwargs["function"]:
+        del kwargs["function"]  # remove the function key if it is empty
+
+    bad_next = (multi_start, multi_column)
+    if first in bad_next:
+        # these functions should not be called by plot_then_finalise()
+        raise ValueError(
+            f"[{', '.join(k.__name__ for k in bad_next)}] should not be called by {me}. "
+            "Call them before calling {me}. "
+        )
 
     if first in EXPECTED_CALLABLES:
         expected = EXPECTED_CALLABLES[first]
@@ -161,10 +164,12 @@ def plot_then_finalise(
         # this is an unexpected Callable, so we will give it a try
         print(f"Unknown proposed function: {first}; nonetheless, will give it a try.")
         expected = {}
-        plot_kwargs = kwargs_
-    validate_kwargs(expected | FINALISE_KW_TYPES, me, **plot_kwargs)
+        plot_kwargs = kwargs.copy()
 
-    # --- call the first function with the data and kwargs
+    # --- validate the original kwargs (could not do before now)
+    validate_kwargs(FINALISE_KW_TYPES | expected, me, **kwargs)
+
+    # --- call the first function with the data and selected plot kwargs
     axes = first(data, **plot_kwargs)
 
     # --- remove potentially overlapping kwargs
@@ -215,7 +220,9 @@ def multi_start(
 
     # --- check the function argument
     original_tag: Final[str] = kwargs.get("tag", "")
-    first, kwargs = first_unchain(function, **kwargs)
+    first, kwargs["function"] = first_unchain(function)
+    if not kwargs["function"]:
+        del kwargs["function"]  # remove the function key if it is empty
 
     # --- iterate over the starts
     for i, start in enumerate(starts):
@@ -255,7 +262,9 @@ def multi_column(
     # --- check the function argument
     title_stem = kwargs.get("title", "")
     tag: Final[str] = kwargs.get("tag", "")
-    first, kwargs = first_unchain(function, **kwargs)
+    first, kwargs["function"] = first_unchain(function)
+    if not kwargs["function"]:
+        del kwargs["function"]  # remove the function key if it is empty
 
     # --- iterate over the columns
     for i, col in enumerate(data.columns):
@@ -304,7 +313,8 @@ if __name__ == "__main__":
         [multi_start, plot_then_finalise, line_plot],
         title="Test Multi Column / Multi start: ",
         starts=[None, 180],
-        verbose=False,
+        garbage=True,  # this is an unexpected argument - should trigger a warning
+        annotate=True,  # this is an expected argument
     )
 
     # bar plot
@@ -327,10 +337,6 @@ if __name__ == "__main__":
         ylabel="Y-axis Label",
     )
 
-
-# --- test
-if __name__ == "__main__":
-
     # --- check that this fails
     try:
         multi_start(
@@ -341,7 +347,7 @@ if __name__ == "__main__":
     except (ValueError, TypeError) as e:
         print(f"Expected error: {e}")
 
-    # --- check that tjis fails
+    # --- check that this fails
     try:
         multi_column(
             data=Series([1, 2, 3]),  # type: ignore # Series is not a DataFrame
@@ -358,3 +364,16 @@ if __name__ == "__main__":
         )
     except (ValueError, TypeError) as e:
         print(f"Expected error: {e}")
+
+    # --- check this fails
+    try:
+        plot_then_finalise(
+            data=Series([1, 2, 3]),
+            function=[multi_start, bar_plot],
+            starts=[0, 1],
+            title="Test Multi Start with Bar Plot",
+            xlabel="X-axis Label",
+            ylabel="Y-axis Label",
+        )
+    except (ValueError, TypeError) as e:
+        print(f"Expected error: {e}")