plotis 0.1.6.2__py3-none-any.whl

plotis/__init__.py

@@ -0,0 +1 @@
+from .plotis import *

plotis/plotis.py

@@ -0,0 +1,334 @@
+# Standard lib imports
+import os
+import inspect
+import re
+
+# Dependencies imports
+import pandas as pd
+
+# Specified imports
+from contextlib import AbstractContextManager
+from typing import Any, List
+from types import TracebackType
+
+class PlotIs(AbstractContextManager):
+    """A context manager for isolating, and packaging everything
+    needed to independently reproduce plots.
+
+    The plotting logic placed in this context may only rely on 
+    matplotlib.pyplot imported as `import matplotlib,pyplot as plt`.
+
+    The plotting logic in this context may only produce a single figure.
+
+    Every `.show()` and `.savefig()` call will be removed from the plotting 
+    logic before being saved to `run.py`.
+
+    This class can only be used in compination with the keywork `with`.
+
+    Attributes 
+    ----------
+    figpath : str 
+        Path of the folder in which `data.csv` and `run.py` will be saved.
+    data : pandas.DataFrame 
+        Data used in plotting logic.
+    calling_filename : str 
+        Name of the file calling the contructor. This will be set 
+        during runtime.
+    calling_context_line_start : int 
+        Line number + 1 of the constructor call. This will be set during 
+        runtime.
+    calling_line_end : int 
+        Last line of context related to the call of this constructor. 
+        This will be set during runtime.
+    context_source_lines : List[str]
+        Lines of code contain in the context related to the call to 
+        the constructor, i.e. the lines 
+        [calling_context_line_start, calling_context_line_end].
+    """
+
+    def __init__(self, figpath: str, data: pd.DataFrame) -> None:
+        self.figpath = figpath
+        self.data = data
+
+        # Information about the calling file
+        self.calling_filename = "" 
+        self.calling_context_line_start = -1  # This is set to calling line + 1
+        self.calling_line_end = -1
+        self.constructing_line = "" # Line of code conaining the constructor call
+        self.context_source_lines = []
+
+    def __enter__(self) -> Any:
+        calling_frame = inspect.stack()[1]
+        
+        # Ensuring we have calling code context
+        if calling_frame.code_context is None:
+            raise Exception("Could not find code context")
+        self.constructing_line = calling_frame.code_context[0]
+       
+        # Ensuring that this function is called 
+        # as part of a with statement
+        regex_str = r"(\s{1,}|)with PlotIs[(](\s|\S|){1,}[)] as \S{1,}:[\n]|(\s{1,}|)with PlotIs[(](\s|\S|){1,}[)]:[\n]" 
+        with_context_pattern = re.compile(regex_str)
+        if with_context_pattern.fullmatch(self.constructing_line) is None :
+            raise Exception(f"PlotIs must be called by `with`: {calling_frame.code_context[0]}")
+       
+        # Parsing calling frame to set up attributes
+        self.calling_filename = calling_frame.filename
+        self.calling_context_line_start = calling_frame.lineno + 1 # Exclude calling line
+        self.calling_context_line_end = self._get_last_lineno_of_context(
+            self.calling_filename,
+            self.calling_context_line_start,
+            include_calling_line=False
+        )
+
+        # Extacting source lines
+        lines = []
+        with open(self.calling_filename, "r") as fp:
+            # Colleting the source lines of our context.
+            # Note that code lines start counting at 1 while 
+            # list index starts at 0.
+            lbnd_inclusive = self.calling_context_line_start - 1 
+            ubnd_exclusive = self.calling_context_line_end
+            lines = fp.readlines()[lbnd_inclusive:ubnd_exclusive]
+
+        # Ensuring that there is not more than one plot in the context
+        # NOTE: this method is very yanky, see _has_multiple_plots().
+        if PlotIs._has_multiple_plots(lines) is True:
+            raise Exception("Multiple figures are not supported. You cannot have more than one savefig or show calls in context")
+
+        # Formats and cleans source code and save it in attribute
+        self.context_source_lines = self._clean_context_source(lines) 
+
+        # Ensuring that there are no nested with contexts using PlotIs 
+        line_match_list = [with_context_pattern.match(line) is not None for line in self.context_source_lines]
+        if True in line_match_list:
+            raise Exception("PlotIs does not support nested `with` contexts using PlotIs")
+
+    def __exit__(
+        self, 
+        __exc_type: type[BaseException] | None, 
+        __exc_value: BaseException | None, 
+        __traceback: TracebackType | None
+    ) -> bool | None:
+        calling_frame = inspect.stack()[1]
+        self.calling_line_end = calling_frame.lineno
+
+        # Creates the folder in which to write the data and code
+        if not os.path.exists(self.figpath):
+            os.makedirs(self.figpath)
+
+        # Writing data to figpath
+        data_file_path = self.figpath + f"/data.csv"
+        print(f"Writing data to: {data_file_path}")
+        with open(data_file_path, "w+") as fp:
+            self.data.to_csv(fp)
+
+        # Writing concatinating data load code with 
+        # context source and writing it to file
+        code_file_path = self.figpath + "/run.py" 
+        print(f"Writing context code to: {code_file_path}")
+        with open(code_file_path, "w+") as fp:
+            code_to_write = self._get_import_code()
+            code_to_write += self._get_data_load_code()
+            code_to_write += self.context_source_lines
+            code_to_write += self._get_savefig_code("png")
+            fp.writelines(code_to_write)
+
+    def _get_last_lineno_of_context(
+        self,
+        calling_filename: str,
+        calling_line_no: int,
+        include_calling_line: bool = False
+    ) -> int:
+        """Returns the last line number of the calling context specified in 
+        `calling_frame`.
+        """
+        with open(calling_filename, "r") as fp:
+            lines = fp.readlines()
+
+        # Initiates the returning variable as the base case 
+        last_lineno_context = len(lines)
+
+        # Specifies the line to start analysing our context from.
+        # The number is dependent on if we want to include the calling 
+        # line. The reason for this is that in a for caluse, or with 
+        # clause, the calling line has a different indentation than 
+        # the context we are trying to analyse.
+        starting_line_no = None 
+        if include_calling_line is True:
+            starting_line_no = calling_line_no
+        else:
+            starting_line_no = calling_line_no + 1
+
+        # Iterate over each line of code in starting at calling frame 
+        # (or one line after it) until indentation becomes less than 
+        # the initial one, i.e. stepping out of the context.
+        context_indent_base = None
+        for lineno in range(starting_line_no, len(lines)+1):
+            line = lines[lineno-1]
+            current_indent = self._get_indentation(line)
+
+            # For the first iteration we save the number 
+            # of indentation defining the calling context 
+            if lineno == starting_line_no:
+                context_indent_base = current_indent
+                continue
+
+            # The first time at which the number of 
+            # indentations are less than the context base 
+            # defines beginning of the next context.
+            #
+            # Note: that we do not consider a new line. If we do not do this 
+            # code in same context but separated by new line will be 
+            # incorrecly excluded.
+            any_white_space = re.compile(r"\s")
+            if current_indent < context_indent_base and not any_white_space.fullmatch(line):
+                # When current indent is less than base indent 
+                # for the first time we are at first line in next
+                # context. Therefore we subtract one to get last 
+                # line in context we are analysing 
+                last_lineno_context = lineno - 1
+                break
+
+        return last_lineno_context
+
+    @staticmethod
+    def _get_indentation(line: str) -> int:
+        """Gets the number of indentation charachters used in `line`.
+
+        Parameters
+        ----------
+        line : str 
+            Code line for which to get the number of indentations.
+
+        Returns
+        -------
+        int
+            Number of whitespace characters used for indentation in `line`.
+        """
+        leading_spaces = len(line) - len(line.lstrip())
+        return leading_spaces
+
+
+    def _get_data_load_code(self) -> List[str]:
+        """Returns the strings of code needed to load the data, which is saved in 
+        data.csv, into a variable of the same name as was supplied to the data argument
+        in the PlotIs constructor.
+
+        Returns
+        -------
+        List[str]
+            List of strings. Each entry is one line of pyhton code.
+        """
+        # Checking if the contructor call is using PlotIs(data=xxx, xxx)
+        # or PlotIs(some_file_path, some_pd_df)
+        variable_name = ""
+        regex_str = r"data=[\S\s]+"
+        data_pattern_match = re.search(regex_str, self.constructing_line)
+        if data_pattern_match is not None:
+            # Extracts the name of the variable storing the data
+            variable_name = self.constructing_line.split("data=")[1].strip()
+            variable_name = variable_name.replace(")", "").replace(":", "")
+            variable_name = variable_name.strip()
+        else:
+            # Extracts the name of the variable storgin the data 
+            variable_name = self.constructing_line.split(",")[1].strip()
+            variable_name = variable_name.replace(")", "").replace(":", "")
+            variable_name = variable_name.strip()
+
+        # Ensuring that something was catpured by above logic
+        if variable_name == "":
+            raise ValueError("Something went wrong. Could not parse varable name containing data")
+
+        # Constructing line of code to load data from data.csv into variable 
+        data_file_path = self.figpath + f"/data.csv"
+        data_load_code = [
+            f"{variable_name} = pd.read_csv(\"{data_file_path}\")\n\n"
+        ]
+
+        return data_load_code
+
+    def _get_savefig_code(self, format: str) -> List[str]:
+        """Returns lines of code needed to save 
+        the most recently created figure.
+        """
+        save_path = self.figpath + "/figure." + format
+        return [f"plt.savefig(\"{save_path}\")"]
+
+    def _get_import_code(self) -> List[str]:
+        """Returns lines of code with neccessary imports.
+        """
+        code = [
+            "import pandas as pd\n",
+            "import matplotlib.pyplot as plt\n",
+            "\n"
+        ]
+
+        return code
+
+    def _clean_context_source(self, code: List[str]) -> List[str]:
+        """Cleans and formats the input code such that it can be writen 
+        to independent pyhton file without any unexpected behaviour.
+
+        Parameters
+        ----------
+        code : List[str]
+            List of code lines to be cleaned and formated.
+
+        Returns
+        -------
+        List[str]
+            Input list where each string element has been formated and 
+            cleaned.
+        """
+        # Removing indentation
+        code = [line.lstrip() for line in code]
+
+        # Translating empty lines to blank rows
+        for ix, line in enumerate(code):
+            if len(line) == 0:
+                code[ix] = "\n"
+
+        # Ensuring that last element in each code line is a line break
+        for ix, line in enumerate(code):
+            if line[len(line)-1] != "\n":
+                line = line + "\n"
+                code[ix] = line
+
+        # Removing any lines containing savefig 
+        code = [line for line in code if ".savefig" not in line]
+
+        # Removing any lines containing plt.show()
+        code = [line for line in code if "plt.show(" not in line]
+
+        # Removes all in line comments
+        code = [line for line in code if line[0] != "#"]
+
+        return code
+
+    @staticmethod
+    def _has_multiple_plots(code: List[str]) -> bool:
+        """Returns false if there are more than one 
+        savefig() and or plt.show() call in `code`,
+        otherwise true.
+
+        Parameters 
+        ----------
+        code : List[str]
+            List of code lines in which to check if there are 
+            more than one figure.
+
+        Returns
+        -------
+        bool 
+            False if there are more than one savefig() and or 
+            plt.show() call in `code`, otherwise it returns True.
+        """
+        n_show = 0
+        n_savefig = 0
+        for line in code:
+            n_show += 1 if ".show()" in line else 0
+            n_savefig += 1 if "savefig(" in line else 0
+
+        return n_show > 1 or n_savefig > 1
+

plotis-0.1.6.2.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.3
+Name: plotis
+Version: 0.1.6.2
+Summary: Plot isolation tool for pyhton
+Project-URL: Homepage, https://github.com/victorbrun/plotis
+Project-URL: Issues, https://github.com/victorbrun/plotis/issues
+Author-email: Victor Brun <me@victorbrun.com>
+License-File: LICENCE
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Description-Content-Type: text/markdown
+
+# `plotis`
+`plotis` is a plot isolation tool for python. It saves the data and python code needed to independently reproduce plots using a pythonic interface.
+
+This project was initiated to address the issue of repository size ballooning in documentation projects where images are frequently updated. Since the most common image formats are not plain text, Git cannot version control them effectively, resulting in the storage of every version of every image. Instead of converting images to a plain text format or pruning the Git history, I chose to overengineer this solution. This solution uses Python context managers to extract the necessary code and data, enabling the independent reproduction of plots.
+
+# Installation
+```bash
+pip install plotis
+```
+
+# Usage
+## Simple example
+`plotis` relies on the context manager `PlotIs`. By placing the plotting logic inside the `PlotIs` context and providing the data used for plotting, as shown below, a folder will be created in the working directory. This folder contains the data (`<figfoldername>/data.csv`) and code (`<figfoldername>/run.py`) needed to reproduce the plot independently.
+```python
+# Import base dependencies
+import pandas as pd 
+import matplotlib.pyplot as plt
+
+# Imports PlotIs context manager from plotis package
+from plotis import PlotIs 
+
+# Generates sample data
+x = np.linspace(0, 4*math.pi)
+y = np.sin(x)
+sample_data = pd.DataFrame(data={"x": x, "y": y})
+
+# Specify the name of the folder which will contain 
+# code and data needed to independently reproduce the plot.
+figure_folder = "fig1"
+
+# Creates plot inside PlotIs context
+with PlotIs(figure_folder, sample_data):
+	# Plots data 
+	sample_data.plot(x="x", y="y")
+	plt.title("Sin function")
+	plt.xlabel("x")
+	plt.ylabel("sin(x)")
+
+	# Shows plot 
+	plt.show()
+```
+
+## LaTeX project example
+As this package was motivate by large documentation projects, this example will showcase how to "highjack" the compilation process of a LaTeX document to insert the figure produced by above example.
+
+Consider a LaTeX document containing the following content:
+```latex
+\documentclass[12pt]{article}
+\usepackage{graphicx}
+\usepackage{hyperref}
+
+\title{PlotIs example one}
+\author{Victor Brun\\ \href{https://victorbrun.com}{victorbrun.com}}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{The sinus function}
+The sinus function is a trigonometric function which we denote by $\sin{x}$. In figure \ref{fig:sin} we can see that it looks like a wave.
+
+\begin{figure}[h]
+	\centering
+	\includegraphics[width=8cm]{figures/sinus_curve.png}
+	\caption{The sinus function plotted on the interval $[0, 4\pi]$.}
+	\label{fig:sin}
+\end{figure}
+
+\end{document}
+```
+
+Since you want to version control the figures in this huge LaTeX project, `figures/sinus_curve.png` does not exist in the repository (as it is a non-plain text image format). Fortunately, you have already written the logic using `plotis` (the code in the above example) needed to produce the figure `sinus_curve.png`. The result produced by running the `plotis` code, `fig1/data.csv`, and `fig1/run.py`, is sufficient to recreate the figure. You can create a Makefile to run the plotting script `fig1/run.py` and subsequently move the produced image to the appropriate folder in your LaTeX project. The Makefile is as follows:
+```make
+all: | plotgen move pdflatex
+	# Executes below targets in the following order
+	# 1. plotget
+	# 2. move
+	# 3. pdflatex
+
+plotgen: sinus_curve/run.py sinus_curve/data.csv
+	# Runs the automatically generated pyhton
+	# script to create the plot
+	python3 fig1/run.py 
+
+move: sinus_curve/figure.png 
+	@echo "\nCreating folder figures if it does not exist"
+	mkdir -p figures 
+
+	@echo "\nCopying produced fiure to figures/"
+	cp fig1/figure.png figures/sinus_curve.png
+
+pdflatex: main.tex
+	# Runs pdflatex twice to make sure
+	# references are created correctly
+	pdflatex main.tex
+	pdflatex main.tex
+```
+
+This can be found as a working example in `examples/ex1`.

plotis-0.1.6.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+plotis/__init__.py,sha256=8iupCzp5AV4mIRN1ir5GOGiLKpcU4PbcZDP4g_UBCgE,22
+plotis/plotis.py,sha256=AblIIVylWg_fIy2wHoO7VXxn9x1DlE0wNMFOZcETvkk,12831
+plotis-0.1.6.2.dist-info/METADATA,sha256=DMJWa_qxbO3Cs3SKaIdMgkpzwvmgSn37zHZdwpoERdY,4523
+plotis-0.1.6.2.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+plotis-0.1.6.2.dist-info/licenses/LICENCE,sha256=GjwAED6oFuY0O8Hpmq8JTEqsPLMY596DuBSNh46Irq8,1498
+plotis-0.1.6.2.dist-info/RECORD,,

plotis-0.1.6.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plotis-0.1.6.2.dist-info/licenses/LICENCE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Victor Brun
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.