Initial commit.

Author: christian-oreilly

README.rst

@@ -0,0 +1,103 @@
+.. -*- mode: rst -*-
+
+Pickler2
+===================================
+
+Small package allowing to decorate a function so that it automatically pickle its results
+and load it the next time it is called.
+
+Example of usage
+===================================
+
+With the following code, the first time long_function() will be called, it will execute and
+save the pickle processed_data. Next time it is run, it will load the pickled object without
+running the function.
+
+.. code-block:: python
+
+    from pickler2 import pickled
+
+    @pickled("some_file_name.pck")
+    def long_function():
+        ... long time to process data ...
+        return processed_data
+
+To explicitly re-run the function, you can call
+
+.. code-block:: python
+
+    long_function(run=True)
+
+When using this functionality at different places, within a project, you might want to save
+all the pickles at a same place. This can be done by given full name to the decorator
+
+.. code-block:: python
+
+    @pickled("/some/long/path/some_file_name.pck")
+    def long_function():
+        ... long time to process data ...
+        return processed_data
+
+Alternatively, the project pickling path can be registered as follow
+
+.. code-block:: python
+
+    from pickler2 import register_project_path
+
+    register_project_path("/some/long/path/", "my_project")
+
+and then use provide the project name to the constructor:
+
+.. code-block:: python
+
+    @pickled("some_file_name.pck", project_name="my_project")
+    def long_function():
+        ... long time to process data ...
+        return processed_data
+
+The registered pickled path are saved in "~/.pickler_conf.yaml". This allow to run the same code
+on different systems with differents path, as long as the corresponding path have been registered
+in their respective configuration path.
+
+
+Why the 2 in Piclker2?
+===================================
+Because Pickler was already taken on PyPi!
+
+Licensing
+^^^^^^^^^
+
+Pickler2 is **BSD-licenced** (3 clause):
+
+    This software is OSI Certified Open Source Software.
+    OSI Certified is a certification mark of the Open Source Initiative.
+
+    Copyright (c) 2011-2019, authors of MNE-Python.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+    * 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.
+
+    * Neither the names of MNE-Python authors nor the names of any
+      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
+    owner 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.**

pickler2/__init__.py

@@ -0,0 +1 @@
+from .pickler import pickled, register_project_path

pickler2/pickler.py

@@ -0,0 +1,69 @@
+import functools
+import pickle
+from pathlib import Path
+from warnings import warn
+from yaml import load, dump
+try:
+    from yaml import CLoader as Loader, CDumper as Dumper
+except ImportError:
+    from yaml import Loader, Dumper
+
+
+config_path = Path.home() / ".pickler_conf.yaml"
+
+
+def register_project_path(project_name, pickling_path):
+    config = load_config()
+
+    Path(pickling_path).mkdir(parents=True, exist_ok=True)
+    config[project_name] = str(pickling_path)
+
+    with config_path.open("w") as stream:
+        dump(config, stream, Dumper=Dumper)
+
+
+def load_config():
+    if config_path.exists():
+        with config_path.open("r") as stream:
+            return load(stream, Loader=Loader)
+    return {}
+
+
+def pickled(file_name, run=None, load=None, project_name=None):
+    def pickler_decorator(func):
+        @functools.wraps(func)
+        def wrapper(file_name, *args, run=run, load=load, project_name=project_name, **kwargs):
+
+            if project_name is not None:
+                config = load_config()
+                if project_name not in config:
+                    raise ValueError("This project is unknown. Please register it first using " +
+                                     "register_project_path(project_name, pickling_path).")
+
+                pickling_path = Path(config[project_name])
+            else:
+                pickling_path = None
+
+            if isinstance(file_name, str):
+                file_name = Path(file_name)
+            elif not isinstance(file_name, Path):
+                raise TypeError("Unrecognized type ({}).".format(type(file_name)))
+
+            if not file_name.is_absolute():
+                if pickling_path is not None:
+                    file_name = pickling_path / file_name
+            else:
+                if pickling_path is not None:
+                    warn("The file_name passed is absolute. The project pickling path has been ignored.")
+
+            if run or not file_name.exists():
+                data = func(*args, **kwargs)
+                with file_name.open("wb") as pickle_stream:
+                    pickle.dump(data, pickle_stream)
+                return data
+
+            with file_name.open("rb") as pickle_stream:
+                return pickle.load(pickle_stream)
+
+        return functools.partial(wrapper, file_name)
+    return pickler_decorator

pickler2/tests/test_pickler.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+from pickler2 import pickled, register_project_path
+
+
+def test_pickler(project_name=None, pickling_path=None):
+
+    if project_name is not None:
+        register_project_path(project_name, pickling_path)
+
+    file_name = Path("test_pickler.pck")
+    if pickling_path is None:
+        if file_name.exists():
+            file_name.unlink()
+    else:
+        if (Path(pickling_path) / file_name).exists():
+            (Path(pickling_path) / file_name).unlink()
+
+    @pickled(file_name, project_name=project_name)
+    def dummy_func1():
+        return 1
+
+    dummy_func1()
+    if pickling_path is None:
+        assert(file_name.exists())
+    else:
+        assert((Path(pickling_path) / file_name).exists())
+
+    @pickled(file_name, project_name=project_name)
+    def dummy_func2():
+        return 2
+
+    assert(dummy_func2() == 1)
+
+    dummy_func2(run=True)
+    assert(dummy_func2() == 2)
+
+
+def test_pickler_with_registration():
+    test_pickler("test_project", str(Path(__file__).parent / "test"))

setup.py

@@ -0,0 +1,13 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='pickler',
+    version='0.0.1',
+    url='https://github.com/christian-oreilly/pickler.git',
+    author="Christian O'Reilly",
+    author_email='[email protected]',
+    description="Small package allowing to decorate a function so that it automatically pickle its results" +
+                " and load it the next time it is called.",
+    packages=find_packages(),    
+    install_requires=["numpy"],
+)