├── docs ├── .nojekyll ├── _static │ ├── custom.css │ ├── up.png │ ├── down.png │ ├── file.png │ ├── minus.png │ ├── plus.png │ ├── comment.png │ ├── pyungo.jpg │ ├── up-pressed.png │ ├── ajax-loader.gif │ ├── down-pressed.png │ ├── comment-bright.png │ ├── comment-close.png │ ├── documentation_options.js │ ├── pygments.css │ ├── doctools.js │ ├── underscore.js │ ├── language_data.js │ ├── basic.css │ ├── alabaster.css │ └── searchtools.js ├── copydoc.sh ├── source │ ├── install.rst │ ├── developer.rst │ ├── gettingstarted.rst │ ├── whatsnew.rst │ ├── install.html │ ├── features.rst │ ├── gettingstarted.html │ ├── whatsnew.html │ └── developer.html ├── index.rst ├── Makefile ├── search.html ├── conf.py ├── index.html └── genindex.html ├── tests ├── __init__.py ├── test_utils.py ├── test_io.py └── test_core.py ├── examples ├── __init__.py ├── simple.py └── pvlib_ex.py ├── setup.cfg ├── pyungo ├── __init__.py ├── errors.py ├── utils.py ├── data.py └── io.py ├── .gitignore ├── .circleci └── config.yml ├── setup.py ├── LICENSE.txt └── README.rst /docs/.nojekyll: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /examples/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [bdist_wheel] 2 | universal=1 -------------------------------------------------------------------------------- /docs/_static/custom.css: -------------------------------------------------------------------------------- 1 | /* This file intentionally left blank. */ 2 | -------------------------------------------------------------------------------- /docs/_static/up.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/up.png -------------------------------------------------------------------------------- /docs/_static/down.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/down.png -------------------------------------------------------------------------------- /docs/_static/file.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/file.png -------------------------------------------------------------------------------- /docs/_static/minus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/minus.png -------------------------------------------------------------------------------- /docs/_static/plus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/plus.png -------------------------------------------------------------------------------- /docs/_static/comment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/comment.png -------------------------------------------------------------------------------- /docs/_static/pyungo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/pyungo.jpg -------------------------------------------------------------------------------- /pyungo/__init__.py: -------------------------------------------------------------------------------- 1 | """ init module """ 2 | from .core import * 3 | 4 | 5 | __version__ = "0.9.0" 6 | -------------------------------------------------------------------------------- /docs/_static/up-pressed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/up-pressed.png -------------------------------------------------------------------------------- /docs/_static/ajax-loader.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/ajax-loader.gif -------------------------------------------------------------------------------- /docs/_static/down-pressed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/down-pressed.png -------------------------------------------------------------------------------- /docs/_static/comment-bright.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/comment-bright.png -------------------------------------------------------------------------------- /docs/_static/comment-close.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cedricleroy/pyungo/HEAD/docs/_static/comment-close.png -------------------------------------------------------------------------------- /pyungo/errors.py: -------------------------------------------------------------------------------- 1 | """ errors module """ 2 | 3 | 4 | class PyungoError(Exception): 5 | """ pyungo custom exception """ 6 | 7 | pass 8 | -------------------------------------------------------------------------------- /docs/copydoc.sh: -------------------------------------------------------------------------------- 1 | cp _build/html/*.html . 2 | cp _build/html/_static/* _static/ 3 | cp _build/html/.nojekyll .nojekyll 4 | cp _build/html/source/*.html source/ 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build/ 2 | dist/ 3 | pyungo.egg-info/ 4 | venv*/ 5 | *.pyc 6 | *.vscode/ 7 | *.pytest_cache/ 8 | .DS_Store 9 | docs/_build/ 10 | .mypy_cache/ 11 | .idea 12 | -------------------------------------------------------------------------------- /docs/source/install.rst: -------------------------------------------------------------------------------- 1 | .. install: 2 | 3 | ************ 4 | Installation 5 | ************ 6 | 7 | For a standard installation of **pyungo**: 8 | 9 | >>> pip install pyungo 10 | 11 | If you wish to install all dependencies for all features (parallelism, contracts, etc.): 12 | 13 | >>> pip install pyungo[all] 14 | -------------------------------------------------------------------------------- /docs/source/developer.rst: -------------------------------------------------------------------------------- 1 | .. developer: 2 | 3 | *********************** 4 | Developer Documentation 5 | *********************** 6 | 7 | .. autofunction:: pyungo.core.topological_sort 8 | 9 | .. autoclass:: pyungo.core.Node 10 | 11 | .. autoclass:: pyungo.core.Graph 12 | :members: 13 | 14 | .. autoclass:: pyungo.io.Input 15 | 16 | .. autoclass:: pyungo.io.Output 17 | -------------------------------------------------------------------------------- /docs/_static/documentation_options.js: -------------------------------------------------------------------------------- 1 | var DOCUMENTATION_OPTIONS = { 2 | URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), 3 | VERSION: 'v0.7.0', 4 | LANGUAGE: 'None', 5 | COLLAPSE_INDEX: false, 6 | FILE_SUFFIX: '.html', 7 | HAS_SOURCE: true, 8 | SOURCELINK_SUFFIX: '.txt', 9 | NAVIGATION_WITH_KEYS: false, 10 | }; -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | 2 | Welcome to pyungo's documentation! 3 | ================================== 4 | 5 | .. toctree:: 6 | :maxdepth: 2 7 | :caption: Contents: 8 | 9 | source/install.rst 10 | source/gettingstarted.rst 11 | source/features.rst 12 | source/developer.rst 13 | source/whatsnew.rst 14 | 15 | 16 | Indices and tables 17 | ================== 18 | 19 | * :ref:`genindex` 20 | * :ref:`modindex` 21 | * :ref:`search` 22 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SOURCEDIR = . 8 | BUILDDIR = _build 9 | 10 | # Put it first so that "make" without argument is like "make help". 11 | help: 12 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 13 | 14 | .PHONY: help Makefile 15 | 16 | # Catch-all target: route all unknown targets to Sphinx using the new 17 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 18 | %: Makefile 19 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /examples/simple.py: -------------------------------------------------------------------------------- 1 | import os 2 | import sys 3 | 4 | PATH = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) 5 | sys.path.insert(0, PATH) 6 | 7 | from pyungo.core import Graph 8 | from pprint import pprint 9 | 10 | 11 | if __name__ == "__main__": 12 | graph = Graph() 13 | 14 | @graph.register() 15 | def f_my_function(a, b): 16 | c = a + b 17 | return c 18 | 19 | @graph.register(inputs=["d", "a"], outputs=["e"]) 20 | def f_my_function3(d, a): 21 | e = d - a 22 | return e 23 | 24 | @graph.register(outputs=["d"]) 25 | def f_my_function2(c): 26 | return c / 10.0 27 | 28 | res = graph.calculate(data={"a": 2, "b": 3}) 29 | print(res) 30 | -------------------------------------------------------------------------------- /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | # Python CircleCI 2.0 configuration file 2 | 3 | version: 2 4 | workflows: 5 | version: 2 6 | build-and-test: 7 | jobs: 8 | - build-3.6 9 | - build-3.7 10 | - build-3.8 11 | jobs: 12 | build-3.6: &build-template 13 | docker: 14 | - image: circleci/python:3.6-stretch 15 | working_directory: ~/repo 16 | steps: 17 | - checkout 18 | - run: 19 | name: install dependencies 20 | command: | 21 | pip install multiprocess --user 22 | pip install pycontracts --user 23 | pip install jsonschema --user 24 | - run: 25 | name: run tests 26 | command: | 27 | sudo pip install pytest 28 | pytest 29 | - store_artifacts: 30 | path: test-reports 31 | destination: test-reports 32 | build-3.7: 33 | <<: *build-template 34 | docker: 35 | - image: circleci/python:3.7-stretch 36 | build-3.8: 37 | <<: *build-template 38 | docker: 39 | - image: circleci/python:3.8-buster 40 | -------------------------------------------------------------------------------- /tests/test_utils.py: -------------------------------------------------------------------------------- 1 | import pytest 2 | 3 | from pyungo import PyungoError 4 | from pyungo.utils import get_function_return_names 5 | 6 | 7 | def test_get_function_return_names_simple(): 8 | def a(): 9 | b = 2 10 | return b 11 | 12 | assert get_function_return_names(a) == ["b"] 13 | 14 | 15 | def test_get_function_return_names_no_return(): 16 | def a(): 17 | pass 18 | 19 | with pytest.raises(PyungoError) as err: 20 | get_function_return_names(a) 21 | 22 | assert str(err.value) == "No return statement found in a" 23 | 24 | 25 | def test_get_function_return_names_tuple(): 26 | def a(): 27 | b = 2 28 | c = 3 29 | return (b, c) 30 | 31 | assert get_function_return_names(a) == ["b", "c"] 32 | 33 | 34 | def test_get_function_return_names_not_valid(): 35 | def a(): 36 | b = 2 37 | c = 3 38 | return b / c 39 | 40 | with pytest.raises(PyungoError) as err: 41 | get_function_return_names(a) 42 | 43 | msg = "Variable name or Tuple of variable names are expected, got BinOp" 44 | assert str(err.value) == msg 45 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup 2 | from os import path 3 | 4 | from pyungo import __version__ 5 | 6 | 7 | HERE = path.abspath(path.dirname(__file__)) 8 | 9 | 10 | with open(path.join(HERE, "README.rst")) as f: 11 | README = f.read() 12 | 13 | 14 | setup( 15 | name="pyungo", 16 | version=__version__, 17 | description="Function dependencies resolution and execution", 18 | long_description=README, 19 | url="https://github.com/cedricleroy/pyungo", 20 | author="Cedric Leroy", 21 | author_email="cedie73@hotmail.fr", 22 | license="MIT", 23 | extra_require={"all": ["multiprocess", "pycontracts", "jsonschema"]}, 24 | classifiers=[ 25 | "Development Status :: 3 - Alpha", 26 | "Intended Audience :: Developers", 27 | "License :: OSI Approved :: MIT License", 28 | "Programming Language :: Python :: 3", 29 | "Programming Language :: Python :: 3.6", 30 | "Programming Language :: Python :: 3.7", 31 | "Programming Language :: Python :: 3.8", 32 | ], 33 | keywords="dag workflow function dependency", 34 | packages=["pyungo"], 35 | ) 36 | -------------------------------------------------------------------------------- /LICENSE.txt: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Cedric Leroy 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /pyungo/utils.py: -------------------------------------------------------------------------------- 1 | import ast 2 | import inspect 3 | 4 | from .errors import PyungoError 5 | 6 | 7 | def get_function_return_names(fct): 8 | """ Return variable name(s) or return statement of the given function """ 9 | lines = inspect.getsourcelines(fct) 10 | outputs = None 11 | for line in lines[0][::-1]: 12 | stripped = line.strip() 13 | if "def" in stripped: 14 | # NOTE: This work as def is a reserved keyword which will trigger 15 | # invalid syntax if misused 16 | msg = "No return statement found in {}" 17 | raise PyungoError(msg.format(fct.__name__)) 18 | ast_tree = ast.parse(stripped) 19 | for ast_node in ast.walk(ast_tree): 20 | if isinstance(ast_node, ast.Return): 21 | if isinstance(ast_node.value, ast.Name): 22 | outputs = [ast_node.value.id] 23 | elif isinstance(ast_node.value, ast.Tuple): 24 | outputs = [ 25 | elt.id 26 | for elt in ast_node.value.elts 27 | if isinstance(elt, ast.Name) 28 | ] 29 | else: 30 | name = ast_node.value.__class__.__name__ 31 | msg = ( 32 | "Variable name or Tuple of variable names are " 33 | "expected, got {}".format(name) 34 | ) 35 | raise PyungoError(msg) 36 | break 37 | if outputs: 38 | break 39 | return outputs 40 | -------------------------------------------------------------------------------- /pyungo/data.py: -------------------------------------------------------------------------------- 1 | """ class abstracting data passed as inputs and saved as outputs """ 2 | from copy import deepcopy 3 | 4 | from .errors import PyungoError 5 | 6 | 7 | class Data: 8 | def __init__(self, inputs, do_deepcopy=True): 9 | if do_deepcopy: 10 | self._inputs = deepcopy(inputs) 11 | else: 12 | self._inputs = inputs 13 | self._outputs = {} 14 | 15 | @property 16 | def inputs(self): 17 | return self._inputs 18 | 19 | @property 20 | def outputs(self): 21 | return self._outputs 22 | 23 | def __getitem__(self, key): 24 | try: 25 | return self._inputs[key] 26 | except KeyError: 27 | return self._outputs[key] 28 | 29 | def __setitem__(self, key, val): 30 | self._outputs[key] = val 31 | 32 | def check_inputs(self, sim_inputs, sim_outputs, sim_kwargs): 33 | """ make sure data inputs provided are good enough """ 34 | data_inputs = set(self.inputs.keys()) 35 | diff = data_inputs - (data_inputs - set(sim_outputs)) 36 | if diff: 37 | msg = "The following inputs are already used in the model: {}" 38 | raise PyungoError(msg.format(list(diff))) 39 | inputs_to_provide = set(sim_inputs) - set(sim_outputs) 40 | diff = inputs_to_provide - data_inputs 41 | if diff: 42 | msg = "The following inputs are needed: {}".format(list(diff)) 43 | raise PyungoError(msg) 44 | diff = data_inputs - inputs_to_provide - set(sim_kwargs) 45 | if diff: 46 | msg = "The following inputs are not used by the model: {}" 47 | raise PyungoError(msg.format(list(diff))) 48 | -------------------------------------------------------------------------------- /tests/test_io.py: -------------------------------------------------------------------------------- 1 | from pyungo.io import Input, Output, get_if_exists 2 | 3 | 4 | def test_Input(): 5 | inp = Input(name="a") 6 | assert inp.name == "a" 7 | assert inp.value is None 8 | assert inp.is_arg is False 9 | assert inp.is_kwarg is False 10 | 11 | 12 | def test_Input_arg(): 13 | inp = Input.arg(name="a") 14 | assert inp.name == "a" 15 | assert inp.value is None 16 | assert inp.is_arg is True 17 | assert inp.is_kwarg is False 18 | 19 | 20 | def test_Input_kwarg(): 21 | inp = Input.kwarg(name="a") 22 | assert inp.name == "a" 23 | assert inp.value is None 24 | assert inp.is_arg is False 25 | assert inp.is_kwarg is True 26 | 27 | 28 | def test_Input_constant(): 29 | inp = Input.constant(name="a", value=2) 30 | assert inp.name == "a" 31 | assert inp.value == 2 32 | assert inp.is_arg is False 33 | assert inp.is_kwarg is False 34 | assert inp.is_constant is True 35 | 36 | 37 | def test_Output(): 38 | out = Output("a") 39 | assert out.name == "a" 40 | out.value = 2 41 | assert out._value == 2 42 | assert out.value == 2 43 | 44 | 45 | def test_get_if_exists_do_not_exists(): 46 | res = get_if_exists([1, 2, 3], []) 47 | assert res == [1, 2, 3] 48 | 49 | 50 | def test_get_if_exists_ok(): 51 | inputs = [Input("a"), Input("b"), Input("c")] 52 | existing = {i.name: i for i in inputs} 53 | res = get_if_exists(["a", "b", "c", {"d": 3}], existing) 54 | for i, j in zip(inputs, res): # skip the dict on purpose 55 | assert i == j 56 | 57 | 58 | def test_io_maps(): 59 | for Class in [Input, Output]: 60 | io = Class(name="a") 61 | assert io.map == "a" 62 | io = Class(name="a", map="b") 63 | assert io.map == "b" 64 | -------------------------------------------------------------------------------- /docs/source/gettingstarted.rst: -------------------------------------------------------------------------------- 1 | .. gettingstarted: 2 | 3 | *************** 4 | Getting Started 5 | *************** 6 | 7 | **pyungo** is a lightweight library to link a set of dependent functions together, 8 | and execute them in an ordered manner. 9 | 10 | **pyungo** is built around **Graphs** and **Nodes** used in a 11 | `DAG `_ (Directed Acyclic Graph). 12 | A :class:`~pyungo.core.Node` represent a function being run with a defined set of inputs 13 | and returning one or several outputs. A :class:`~pyungo.core.Graph` is a collection of 14 | **Nodes** where data can flow in an logical manner, the output of one node serving as 15 | input of another. 16 | 17 | Simple example 18 | ############## 19 | 20 | :: 21 | 22 | graph = Graph() 23 | 24 | @graph.register() 25 | def f_my_function_2(d, a): 26 | e = d - a 27 | return e 28 | 29 | @graph.register(outputs=['d']) 30 | def f_my_function_1(c): 31 | return c / 10. 32 | 33 | @graph.register() 34 | def f_my_function_3(a, b): 35 | c = a + b 36 | return c 37 | 38 | res = graph.calculate(data={'a': 2, 'b': 3}) 39 | print(res) 40 | 41 | 42 | **pyungo** is registering the functions at import time. It then resolve the DAG and figure out 43 | the sequence at which the functions have to be run per their inputs / outputs. In this case, 44 | it will be function 3 then 1 and finally 2. 45 | 46 | The ordered :class:`~pyungo.core.Graph` is run with calculate, with the given data. It returns 47 | the output of the last function being run (``e``), but all intermediate results are also 48 | available in the graph instance. 49 | 50 | The result will be `(a + b) / 10 - a = -1.5` 51 | 52 | .. note:: 53 | In the above example, most of the inputs / outputs are not explicitely defined when 54 | registering. **pyungo** inspects the function signature to get the names and extract the 55 | returned variable names automatically. For ``f_my_function_1``, there is no returned 56 | variable, so the output name needs to be explicitely provided. 57 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | pyungo 2 | ====== 3 | 4 | |pypi| |python-version| |build-status| |license| 5 | 6 | pyungo is a lightweight library to link a set of dependent 7 | functions together, and execute them in an ordered manner. 8 | 9 | pyungo is built around ``Graphs`` and ``Nodes`` used in a 10 | `DAG `_ 11 | (Directed Acyclic Graph). A `Node` represent a function being 12 | run with a defined set of inputs and returning one or several 13 | outputs. A ``Graph`` is a collection of ``Nodes`` where data 14 | can flow in an logical manner, the output of one node serving 15 | as input of another. 16 | 17 | installation 18 | ------------ 19 | 20 | .. code-block:: console 21 | 22 | >> pip install pyungo 23 | 24 | simple example 25 | -------------- 26 | 27 | .. code-block:: python 28 | 29 | graph = Graph() 30 | 31 | @graph.register() 32 | def f_my_function_2(d, a): 33 | e = d - a 34 | return e 35 | 36 | @graph.register() 37 | def f_my_function_1(c): 38 | d = c / 10 39 | return d 40 | 41 | @graph.register() 42 | def f_my_function_3(a, b): 43 | c = a + b 44 | return c 45 | 46 | res = graph.calculate(data={'a': 2, 'b': 3}) 47 | print(res) 48 | 49 | pyungo is registering the functions at import time. It then 50 | resolve the ``DAG`` and figure out the sequence at which the 51 | functions have to be run per their inputs / outputs. In this 52 | case, it will be function 3 then 1 and finally 2. 53 | 54 | The ordered ``Graph`` is run with ``calculate``, with the given 55 | data. It returns the output of the last function being 56 | run (e), but all intermediate results are also available 57 | in the ``graph`` instance. 58 | 59 | The result will be (a + b) / 10 - a = -1.5 60 | 61 | links 62 | ----- 63 | 64 | * Documentation: https://cedricleroy.github.io/pyungo/ 65 | * Releases: https://pypi.org/project/pyungo/ 66 | * Tests: https://circleci.com/gh/cedricleroy/pyungo/ 67 | 68 | 69 | .. |pypi| image:: https://img.shields.io/pypi/v/pyungo.svg 70 | :target: https://pypi.org/project/pyungo/ 71 | 72 | .. |build-status| image:: https://circleci.com/gh/cedricleroy/pyungo.svg?style=shield 73 | :target: https://circleci.com/gh/cedricleroy/pyungo 74 | 75 | .. |python-version| image:: https://img.shields.io/badge/python-3.6+-blue.svg 76 | :target: https://www.python.org/downloads/release/python-360/ 77 | 78 | .. |license| image:: https://img.shields.io/github/license/cedricleroy/pyungo.svg 79 | :target: https://github.com/cedricleroy/pyungo/blob/master/LICENSE.txt 80 | -------------------------------------------------------------------------------- /docs/source/whatsnew.rst: -------------------------------------------------------------------------------- 1 | .. whatsnew: 2 | 3 | ********** 4 | What's New 5 | ********** 6 | 7 | These are new features and improvements notes for each release. 8 | 9 | v0.9.0 (June 13, 2020) 10 | ====================== 11 | 12 | * Drop support / compatibility for Python 2.7. 13 | * inputs / outputs names are now optional.:: 14 | 15 | @graph.register() 16 | def f_my_function(a, b): 17 | c = a + b 18 | return c 19 | 20 | * Additional argument to ``Graph`` to prevent inputs deepcopy (`@Tosa95 `_). 21 | This is useful when having large inputs when the ``deepcopy`` might be slow, but remove inputs 22 | immutability. 23 | 24 | v0.8.1 (October 27, 2019) 25 | ========================= 26 | 27 | * Allow optional input data for kwargs (`@veronicaguo `_) 28 | 29 | v0.8.0 (March 17, 2019) 30 | ======================= 31 | 32 | * Can pass list of ``Input`` / ``Output`` to ``Graph``. 33 | 34 | * Names mapping. 35 | 36 | * Inputs validation with JSON Schema. 37 | 38 | * Some misc. refactoring and styling. 39 | 40 | v0.7.0 (February 10, 2019) 41 | ========================== 42 | 43 | * Refactoring, and introduction of ``Input`` and ``Output`` objects. 44 | 45 | * Contracts feature.:: 46 | 47 | graph.add_node( 48 | my_function, 49 | inputs=[Input(name='a', contract='>0'), Input(name='b', contract='float')], 50 | outputs=[Output(name='g', contract='float')] 51 | ) 52 | 53 | * Nodes IDs refactoring (now uses uuid). 54 | 55 | * Run topological sort only when needed. 56 | 57 | * Everything accessible from `pyungo` __init__ (`@nelsontodd `_) 58 | 59 | * Docstrings / Sphinx doc / GitHub page 60 | 61 | 62 | v0.6.0 (July 6, 2018) 63 | ===================== 64 | 65 | * Fix "false parallelism" implementation. This require an optional dependency (`multiprocess` 66 | module) which is more friendly to work with stateful objects and multiprocessing. 67 | 68 | * Ability to pass predefined inputs at the node definition:: 69 | 70 | @graph.register(inputs=['a', {'b': 2}], outputs=['c']) 71 | def f_my_function(a, b): 72 | return a + b 73 | 74 | 75 | v0.5.0 (April 3, 2018) 76 | ====================== 77 | 78 | * Nodes can be run in parallel using Python multiprocessing module:: 79 | 80 | graph = Graph(parallel=True, pool_size=3) 81 | 82 | * `inputs` and `outputs` parameters are mandatory and will raise an explicit error when missing. 83 | 84 | * Add a longer test using `pvlib` 85 | 86 | 87 | v0.4.0 (March 23, 2018) 88 | ======================= 89 | 90 | * Fix single output when dealing with iterables. Previously, returning one output 91 | with an iterable was resulting in taking the first element. 92 | 93 | * Args and kwargs can be used in functions:: 94 | 95 | @graph.register( 96 | inputs=['a', 'b'], 97 | args=['c'], 98 | kwargs=['d'], 99 | outputs=['e'] 100 | ) 101 | def f_my_function(a, b, *args, **kwargs): 102 | return a + b + args[0] + kwargs['d'] 103 | 104 | * Can create a Node without using the decorator:: 105 | 106 | graph.add_node(f_my_function, inputs=['a', 'b'], outputs=['c']) 107 | 108 | * DAG pretty print (`graph.dag`) 109 | 110 | 111 | v0.3.0 (March 18, 2018) 112 | ======================= 113 | 114 | First version in pypi 115 | -------------------------------------------------------------------------------- /docs/search.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Search — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 |
31 | 32 | 82 |
83 |
84 | 85 | 86 |
87 | 88 |

Search

89 |
90 | 91 |

92 | Please activate JavaScript to enable the search 93 | functionality. 94 |

95 |
96 |

97 | Searching for multiple words only shows matches that contain 98 | all words. 99 |

100 |
101 | 102 | 103 | 104 |
105 | 106 |
107 | 108 |
109 | 110 |
111 | 112 |
113 |
114 |
115 |
116 |
117 | ©2019, Cedric Leroy. 118 | 119 | | 120 | Powered by Sphinx 3.1.0 121 | & Alabaster 0.7.12 122 | 123 |
124 | 125 | 126 | 127 | Fork me on GitHub 128 | 129 | 130 | 131 | 132 | 133 | -------------------------------------------------------------------------------- /docs/_static/pygments.css: -------------------------------------------------------------------------------- 1 | .highlight .hll { background-color: #ffffcc } 2 | .highlight { background: #f8f8f8; } 3 | .highlight .c { color: #8f5902; font-style: italic } /* Comment */ 4 | .highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */ 5 | .highlight .g { color: #000000 } /* Generic */ 6 | .highlight .k { color: #004461; font-weight: bold } /* Keyword */ 7 | .highlight .l { color: #000000 } /* Literal */ 8 | .highlight .n { color: #000000 } /* Name */ 9 | .highlight .o { color: #582800 } /* Operator */ 10 | .highlight .x { color: #000000 } /* Other */ 11 | .highlight .p { color: #000000; font-weight: bold } /* Punctuation */ 12 | .highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */ 13 | .highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */ 14 | .highlight .cp { color: #8f5902 } /* Comment.Preproc */ 15 | .highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */ 16 | .highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */ 17 | .highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */ 18 | .highlight .gd { color: #a40000 } /* Generic.Deleted */ 19 | .highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */ 20 | .highlight .gr { color: #ef2929 } /* Generic.Error */ 21 | .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ 22 | .highlight .gi { color: #00A000 } /* Generic.Inserted */ 23 | .highlight .go { color: #888888 } /* Generic.Output */ 24 | .highlight .gp { color: #745334 } /* Generic.Prompt */ 25 | .highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */ 26 | .highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ 27 | .highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */ 28 | .highlight .kc { color: #004461; font-weight: bold } /* Keyword.Constant */ 29 | .highlight .kd { color: #004461; font-weight: bold } /* Keyword.Declaration */ 30 | .highlight .kn { color: #004461; font-weight: bold } /* Keyword.Namespace */ 31 | .highlight .kp { color: #004461; font-weight: bold } /* Keyword.Pseudo */ 32 | .highlight .kr { color: #004461; font-weight: bold } /* Keyword.Reserved */ 33 | .highlight .kt { color: #004461; font-weight: bold } /* Keyword.Type */ 34 | .highlight .ld { color: #000000 } /* Literal.Date */ 35 | .highlight .m { color: #990000 } /* Literal.Number */ 36 | .highlight .s { color: #4e9a06 } /* Literal.String */ 37 | .highlight .na { color: #c4a000 } /* Name.Attribute */ 38 | .highlight .nb { color: #004461 } /* Name.Builtin */ 39 | .highlight .nc { color: #000000 } /* Name.Class */ 40 | .highlight .no { color: #000000 } /* Name.Constant */ 41 | .highlight .nd { color: #888888 } /* Name.Decorator */ 42 | .highlight .ni { color: #ce5c00 } /* Name.Entity */ 43 | .highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */ 44 | .highlight .nf { color: #000000 } /* Name.Function */ 45 | .highlight .nl { color: #f57900 } /* Name.Label */ 46 | .highlight .nn { color: #000000 } /* Name.Namespace */ 47 | .highlight .nx { color: #000000 } /* Name.Other */ 48 | .highlight .py { color: #000000 } /* Name.Property */ 49 | .highlight .nt { color: #004461; font-weight: bold } /* Name.Tag */ 50 | .highlight .nv { color: #000000 } /* Name.Variable */ 51 | .highlight .ow { color: #004461; font-weight: bold } /* Operator.Word */ 52 | .highlight .w { color: #f8f8f8; text-decoration: underline } /* Text.Whitespace */ 53 | .highlight .mb { color: #990000 } /* Literal.Number.Bin */ 54 | .highlight .mf { color: #990000 } /* Literal.Number.Float */ 55 | .highlight .mh { color: #990000 } /* Literal.Number.Hex */ 56 | .highlight .mi { color: #990000 } /* Literal.Number.Integer */ 57 | .highlight .mo { color: #990000 } /* Literal.Number.Oct */ 58 | .highlight .sa { color: #4e9a06 } /* Literal.String.Affix */ 59 | .highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */ 60 | .highlight .sc { color: #4e9a06 } /* Literal.String.Char */ 61 | .highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */ 62 | .highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */ 63 | .highlight .s2 { color: #4e9a06 } /* Literal.String.Double */ 64 | .highlight .se { color: #4e9a06 } /* Literal.String.Escape */ 65 | .highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */ 66 | .highlight .si { color: #4e9a06 } /* Literal.String.Interpol */ 67 | .highlight .sx { color: #4e9a06 } /* Literal.String.Other */ 68 | .highlight .sr { color: #4e9a06 } /* Literal.String.Regex */ 69 | .highlight .s1 { color: #4e9a06 } /* Literal.String.Single */ 70 | .highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */ 71 | .highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */ 72 | .highlight .fm { color: #000000 } /* Name.Function.Magic */ 73 | .highlight .vc { color: #000000 } /* Name.Variable.Class */ 74 | .highlight .vg { color: #000000 } /* Name.Variable.Global */ 75 | .highlight .vi { color: #000000 } /* Name.Variable.Instance */ 76 | .highlight .vm { color: #000000 } /* Name.Variable.Magic */ 77 | .highlight .il { color: #990000 } /* Literal.Number.Integer.Long */ -------------------------------------------------------------------------------- /pyungo/io.py: -------------------------------------------------------------------------------- 1 | """ Input / Output module 2 | 3 | Inputs / Outputs objects used to represent functions inputs / outputs 4 | """ 5 | 6 | 7 | class _IO(object): 8 | """ IO Base class for inputs and outputs 9 | 10 | Args: 11 | name (str): The variable name of the input / output 12 | map (str): Optional mapping name. This is the name referenced 13 | in the data inputs / outputs 14 | meta (dict): Not used yet 15 | contract (str): Optional contract rule used by pycontracts 16 | """ 17 | 18 | def __init__(self, name, map=None, meta=None, contract=None): 19 | self._name = name 20 | self._meta = meta if meta is not None else {} 21 | self._value = None 22 | self._contract = None 23 | self._map = map if map else self._name 24 | if contract: 25 | try: 26 | from contracts.main import parse_contract_string 27 | except ImportError: 28 | raise ImportError("pycontracts is needed to use contracts") 29 | self._contract = parse_contract_string(contract) 30 | 31 | @property 32 | def name(self): 33 | return self._name 34 | 35 | @property 36 | def map(self): 37 | return self._map 38 | 39 | @property 40 | def contract(self): 41 | return self._contract 42 | 43 | @property 44 | def value(self): 45 | return self._value 46 | 47 | @value.setter 48 | def value(self, x): 49 | """ When setting a value, we check the contract when applicable """ 50 | if self._contract: 51 | self._contract.check(x) 52 | self._value = x 53 | 54 | 55 | class Input(_IO): 56 | """ Object representing a function input 57 | 58 | Args: 59 | name (str): The variable name of the input / output 60 | map (str): Optional mapping name. This is the name referenced 61 | in the data inputs / outputs 62 | meta (dict): Not used yet 63 | contract (str): Optional contract rule used by pycontracts 64 | """ 65 | 66 | def __init__(self, name, map=None, meta=None, contract=None): 67 | super(Input, self).__init__(name, map, meta, contract) 68 | self.is_arg = False 69 | self.is_kwarg = False 70 | self.is_constant = False 71 | 72 | def __repr__(self): 73 | return "<{} value={} is_arg: {} is_kwarg: {}>".format( 74 | self._name, self.value, self.is_arg, self.is_kwarg 75 | ) 76 | 77 | @classmethod 78 | def constant(cls, name, value, meta=None): 79 | """ Alternate constructor for inputs that are constant 80 | 81 | Args: 82 | name (str): The variable name of the input / output 83 | value: The defined constant value, can be anything 84 | meta (dict): Not used yet 85 | """ 86 | me = cls(name, meta) 87 | me.value = value 88 | me.is_constant = True 89 | return me 90 | 91 | @classmethod 92 | def arg(cls, name, meta=None): 93 | """ Alternate constructor for args 94 | 95 | Args: 96 | name (str): The variable name of the input / output 97 | meta (dict): Not used yet 98 | """ 99 | me = cls(name, meta) 100 | me.is_arg = True 101 | return me 102 | 103 | @classmethod 104 | def kwarg(cls, name, meta=None): 105 | """ Alternate constructor for kwargs 106 | 107 | Args: 108 | name (str): The variable name of the input / output 109 | meta (dict): Not used yet 110 | """ 111 | me = cls(name, meta) 112 | me.is_kwarg = True 113 | return me 114 | 115 | 116 | class Output(_IO): 117 | """ Object representing a function output 118 | 119 | Args: 120 | name (str): The variable name of the input / output 121 | map (str): Optional mapping name. This is the name referenced 122 | in the data inputs / outputs 123 | meta (dict): Not used yet 124 | contract (str): Optional contract rule used by pycontracts 125 | """ 126 | 127 | def __repr__(self): 128 | return "<{} value={}>".format(self._name, self.value) 129 | 130 | 131 | def get_if_exists(provided, existing): 132 | if not existing: 133 | return provided 134 | res = [] 135 | for p in provided: 136 | is_io = False 137 | if isinstance(p, str): 138 | name = p 139 | elif isinstance(p, Input) or isinstance(p, Output): 140 | name = p.name 141 | is_io = True 142 | else: 143 | res.append(p) 144 | continue 145 | exist = existing.get(name) 146 | if exist: 147 | if is_io: 148 | msg = "You cannot use Input / Output in a " "Node if already defined" 149 | raise TypeError(msg) 150 | res.append(exist) 151 | else: 152 | res.append(p) 153 | return res 154 | -------------------------------------------------------------------------------- /docs/source/install.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Installation — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
28 | 29 | 91 |
92 |
93 | 94 | 95 |
96 | 97 |
98 |

Installation

99 |

For a standard installation of pyungo:

100 | 
>>> pip install pyungo
101 |
102 |
103 |

If you wish to install all dependencies for all features (parallelism, contracts, etc.):

104 | 
>>> pip install pyungo[all]
105 |
106 |
107 |
108 | 109 | 110 |
111 | 112 |
113 |
114 |
115 |
116 |
117 | ©2019, Cedric Leroy. 118 | 119 | | 120 | Powered by Sphinx 3.1.0 121 | & Alabaster 0.7.12 122 | 123 | | 124 | Page source 126 |
127 | 128 | 129 | 130 | Fork me on GitHub 131 | 132 | 133 | 134 | 135 | 136 | -------------------------------------------------------------------------------- /examples/pvlib_ex.py: -------------------------------------------------------------------------------- 1 | """ Bigger example on solar PV modeling using PVLib 2 | 3 | https://github.com/pvlib/pvlib-python 4 | 5 | Example: https://github.com/pvlib/pvlib-python/blob/master/docs/tutorials/tmy_to_power.ipynb 6 | """ 7 | 8 | import inspect 9 | import os 10 | from pprint import pprint 11 | import warnings 12 | 13 | try: 14 | import pvlib 15 | except ImportError: 16 | raise ImportError("This example require pvlib") 17 | from pvlib import pvsystem 18 | from pyungo.core import Graph 19 | 20 | 21 | warnings.filterwarnings("ignore") 22 | 23 | 24 | pvlib_abspath = os.path.dirname(os.path.abspath(inspect.getfile(pvlib))) 25 | datapath = os.path.join(pvlib_abspath, "data", "703165TY.csv") 26 | tmy_data, meta = pvlib.tmy.readtmy3(datapath, coerce_year=2015) 27 | tmy_data.index.name = "Time" 28 | tmy_data = tmy_data.shift(freq="-30Min") 29 | sandia_modules = pvlib.pvsystem.retrieve_sam(name="SandiaMod") 30 | cec_modules = pvlib.pvsystem.retrieve_sam(name="CECMod") 31 | sapm_inverters = pvlib.pvsystem.retrieve_sam("sandiainverter") 32 | sapm_inverter = sapm_inverters["ABB__MICRO_0_25_I_OUTD_US_208_208V__CEC_2014_"] 33 | 34 | data = { 35 | "index": tmy_data.index, 36 | "surface_tilt": 30, 37 | "surface_azimuth": 180, 38 | "DHI": tmy_data["DHI"], 39 | "DNI": tmy_data["DNI"], 40 | "GHI": tmy_data["GHI"], 41 | "Wspd": tmy_data["Wspd"], 42 | "DryBulb": tmy_data["DryBulb"], 43 | "albedo": 0.2, 44 | "latitude": meta["latitude"], 45 | "longitude": meta["longitude"], 46 | "sandia_module": sandia_modules.Canadian_Solar_CS5P_220M___2009_, 47 | "cec_module": cec_modules.Canadian_Solar_CS5P_220M, 48 | "alpha_sc": cec_modules.Canadian_Solar_CS5P_220M["alpha_sc"], 49 | "EgRef": 1.121, 50 | "dEgdT": -0.0002677, 51 | "inverter": sapm_inverter, 52 | } 53 | 54 | 55 | def unpack_df(f): 56 | def wrap(*args, **kwargs): 57 | res = f(*args, **kwargs) 58 | return res.values.T 59 | 60 | return wrap 61 | 62 | 63 | def unpack_dict(f): # (ordered) 64 | def wrap(*args, **kwargs): 65 | res = f(*args, **kwargs) 66 | return [res[k] for k in res] 67 | 68 | return wrap 69 | 70 | 71 | # parallelism not needed for this example 72 | graph = Graph(parallel=False) 73 | 74 | graph.add_node( 75 | unpack_df(pvlib.solarposition.get_solarposition), 76 | inputs=["index", "latitude", "longitude"], 77 | outputs=[ 78 | "apparent_elevation", 79 | "apparent_zenith", 80 | "azimuth", 81 | "elevation", 82 | "equation_of_time", 83 | "zenith", 84 | ], 85 | ) 86 | graph.add_node(pvlib.irradiance.extraradiation, inputs=["index"], outputs=["dni_extra"]) 87 | graph.add_node( 88 | pvlib.atmosphere.relativeairmass, inputs=["apparent_zenith"], outputs=["airmass"] 89 | ) 90 | graph.add_node( 91 | pvlib.irradiance.haydavies, 92 | inputs=[ 93 | "surface_tilt", 94 | "surface_azimuth", 95 | "DHI", 96 | "DNI", 97 | "dni_extra", 98 | "apparent_zenith", 99 | "azimuth", 100 | ], 101 | outputs=["poa_sky_diffuse"], 102 | ) 103 | graph.add_node( 104 | pvlib.irradiance.grounddiffuse, 105 | inputs=["surface_tilt", "GHI", "albedo"], 106 | outputs=["poa_ground_diffuse"], 107 | ) 108 | graph.add_node( 109 | pvlib.irradiance.aoi, 110 | inputs=["surface_tilt", "surface_azimuth", "apparent_zenith", "azimuth"], 111 | outputs=["aoi"], 112 | ) 113 | graph.add_node( 114 | unpack_df(pvlib.irradiance.globalinplane), 115 | inputs=["aoi", "DNI", "poa_sky_diffuse", "poa_ground_diffuse"], 116 | outputs=["poa_global", "poa_direct", "poa_diffuse"], 117 | ) 118 | graph.add_node( 119 | unpack_df(pvlib.pvsystem.sapm_celltemp), 120 | inputs=["poa_global", "Wspd", "DryBulb"], 121 | outputs=["temp_cell", "temp_module"], 122 | ) 123 | graph.add_node( 124 | pvlib.pvsystem.sapm_effective_irradiance, 125 | inputs=["poa_direct", "poa_diffuse", "airmass", "aoi", "sandia_module"], 126 | outputs=["effective_irradiance"], 127 | ) 128 | graph.add_node( 129 | unpack_dict(pvlib.pvsystem.sapm), 130 | inputs=["effective_irradiance", "temp_cell", "sandia_module"], 131 | outputs=[ 132 | "i_sc_sapm", 133 | "i_mp_sapm", 134 | "v_oc_sapm", 135 | "v_mp_sapm", 136 | "p_mp_sapm", 137 | "i_x_sapm", 138 | "i_xx_sapm", 139 | ], 140 | ) 141 | graph.add_node( 142 | pvlib.pvsystem.calcparams_desoto, 143 | inputs=["poa_global", "temp_cell", "alpha_sc", "cec_module", "EgRef", "dEgdT"], 144 | outputs=[ 145 | "photocurrent", 146 | "saturation_current", 147 | "resistance_series", 148 | "resistance_shunt", 149 | "nNsVth", 150 | ], 151 | ) 152 | graph.add_node( 153 | unpack_dict(pvlib.pvsystem.singlediode), 154 | inputs=[ 155 | "photocurrent", 156 | "saturation_current", 157 | "resistance_series", 158 | "resistance_shunt", 159 | "nNsVth", 160 | ], 161 | outputs=[ 162 | "i_sc_sd", 163 | "i_mp_sd", 164 | "v_oc_sd", 165 | "v_mp_sd", 166 | "p_mp_sd", 167 | "i_x_sd", 168 | "i_xx_sd", 169 | ], 170 | ) 171 | graph.add_node( 172 | pvlib.pvsystem.snlinverter, 173 | inputs=["v_mp_sapm", "p_mp_sapm", "inverter"], 174 | outputs=["pac_sapm"], 175 | ) 176 | graph.add_node( 177 | pvlib.pvsystem.snlinverter, 178 | inputs=["v_mp_sd", "p_mp_sd", "inverter"], 179 | outputs=["pac_sd"], 180 | ) 181 | 182 | pprint(graph.dag) 183 | graph.calculate(data) 184 | print(sum(graph.data["pac_sd"])) 185 | print(sum(graph.data["pac_sapm"])) 186 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # Configuration file for the Sphinx documentation builder. 4 | # 5 | # This file does only contain a selection of the most common options. For a 6 | # full list see the documentation: 7 | # http://www.sphinx-doc.org/en/master/config 8 | 9 | # -- Path setup -------------------------------------------------------------- 10 | 11 | # If extensions (or modules to document with autodoc) are in another directory, 12 | # add these directories to sys.path here. If the directory is relative to the 13 | # documentation root, use os.path.abspath to make it absolute, like shown here. 14 | 15 | import os 16 | import sys 17 | sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath('.')), 'pyungo')) 18 | 19 | 20 | # -- Project information ----------------------------------------------------- 21 | 22 | project = u'pyungo' 23 | copyright = u'2019, Cedric Leroy' 24 | author = u'Cedric Leroy' 25 | 26 | # The short X.Y version 27 | version = u'' 28 | # The full version, including alpha/beta/rc tags 29 | release = u'v0.7.0' 30 | 31 | 32 | # -- General configuration --------------------------------------------------- 33 | 34 | # If your documentation needs a minimal Sphinx version, state it here. 35 | # 36 | # needs_sphinx = '1.0' 37 | 38 | # Add any Sphinx extension module names here, as strings. They can be 39 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 40 | # ones. 41 | extensions = [ 42 | 'sphinx.ext.napoleon', 43 | 'sphinx.ext.autodoc', 44 | 'sphinx.ext.githubpages', 45 | ] 46 | 47 | # Add any paths that contain templates here, relative to this directory. 48 | templates_path = ['_templates'] 49 | 50 | # The suffix(es) of source filenames. 51 | # You can specify multiple suffix as a list of string: 52 | # 53 | # source_suffix = ['.rst', '.md'] 54 | source_suffix = '.rst' 55 | 56 | # The master toctree document. 57 | master_doc = 'index' 58 | 59 | # The language for content autogenerated by Sphinx. Refer to documentation 60 | # for a list of supported languages. 61 | # 62 | # This is also used if you do content translation via gettext catalogs. 63 | # Usually you set "language" from the command line for these cases. 64 | language = None 65 | 66 | # List of patterns, relative to source directory, that match files and 67 | # directories to ignore when looking for source files. 68 | # This pattern also affects html_static_path and html_extra_path. 69 | exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] 70 | 71 | # The name of the Pygments (syntax highlighting) style to use. 72 | pygments_style = None 73 | 74 | 75 | # -- Options for HTML output ------------------------------------------------- 76 | 77 | # The theme to use for HTML and HTML Help pages. See the documentation for 78 | # a list of builtin themes. 79 | # 80 | html_theme = 'alabaster' 81 | 82 | # Theme options are theme-specific and customize the look and feel of a theme 83 | # further. For a list of options available for each theme, see the 84 | # documentation. 85 | 86 | html_theme_options = { 87 | "fixed_sidebar": True, 88 | "github_user": "cedricleroy", 89 | "github_repo": "pyungo", 90 | "github_banner": True, 91 | "github_type": "star", 92 | "logo": 'pyungo.jpg', 93 | } 94 | 95 | # Add any paths that contain custom static files (such as style sheets) here, 96 | # relative to this directory. They are copied after the builtin static files, 97 | # so a file named "default.css" will overwrite the builtin "default.css". 98 | html_static_path = ['_static'] 99 | 100 | # Custom sidebar templates, must be a dictionary that maps document names 101 | # to template names. 102 | # 103 | # The default sidebars (for documents that don't match any pattern) are 104 | # defined by theme itself. Builtin themes are using these templates by 105 | # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', 106 | # 'searchbox.html']``. 107 | # 108 | # html_sidebars = {} 109 | 110 | 111 | # -- Options for HTMLHelp output --------------------------------------------- 112 | 113 | # Output file base name for HTML help builder. 114 | htmlhelp_basename = 'pyungodoc' 115 | 116 | 117 | # -- Options for LaTeX output ------------------------------------------------ 118 | 119 | latex_elements = { 120 | # The paper size ('letterpaper' or 'a4paper'). 121 | # 122 | # 'papersize': 'letterpaper', 123 | 124 | # The font size ('10pt', '11pt' or '12pt'). 125 | # 126 | # 'pointsize': '10pt', 127 | 128 | # Additional stuff for the LaTeX preamble. 129 | # 130 | # 'preamble': '', 131 | 132 | # Latex figure (float) alignment 133 | # 134 | # 'figure_align': 'htbp', 135 | } 136 | 137 | # Grouping the document tree into LaTeX files. List of tuples 138 | # (source start file, target name, title, 139 | # author, documentclass [howto, manual, or own class]). 140 | latex_documents = [ 141 | (master_doc, 'pyungo.tex', u'pyungo Documentation', 142 | u'Cedric Leroy', 'manual'), 143 | ] 144 | 145 | 146 | # -- Options for manual page output ------------------------------------------ 147 | 148 | # One entry per manual page. List of tuples 149 | # (source start file, name, description, authors, manual section). 150 | man_pages = [ 151 | (master_doc, 'pyungo', u'pyungo Documentation', 152 | [author], 1) 153 | ] 154 | 155 | 156 | # -- Options for Texinfo output ---------------------------------------------- 157 | 158 | # Grouping the document tree into Texinfo files. List of tuples 159 | # (source start file, target name, title, author, 160 | # dir menu entry, description, category) 161 | texinfo_documents = [ 162 | (master_doc, 'pyungo', u'pyungo Documentation', 163 | author, 'pyungo', 'One line description of project.', 164 | 'Miscellaneous'), 165 | ] 166 | 167 | 168 | # -- Options for Epub output ------------------------------------------------- 169 | 170 | # Bibliographic Dublin Core info. 171 | epub_title = project 172 | 173 | # The unique identifier of the text. This can be a ISBN number 174 | # or the project homepage. 175 | # 176 | # epub_identifier = '' 177 | 178 | # A unique identification for the text. 179 | # 180 | # epub_uid = '' 181 | 182 | # A list of files that should not be packed into the epub file. 183 | epub_exclude_files = ['search.html'] 184 | 185 | 186 | # -- Extension configuration ------------------------------------------------- 187 | -------------------------------------------------------------------------------- /docs/source/features.rst: -------------------------------------------------------------------------------- 1 | .. features: 2 | 3 | ******** 4 | Features 5 | ******** 6 | 7 | Sanity Check 8 | ############ 9 | 10 | **pyungo** will raise an error in the following situations: 11 | 12 | * Circular dependencies: The :class:`~pyungo.core.Graph` need to be finite and cannot form a loop. 13 | * All inputs needed to run a :class:`~pyungo.core.Graph` are not provided. 14 | * Input collision: An input name provided as data in the :class:`~pyungo.core.Graph` has a 15 | conflict with at least of the output name. 16 | * Duplicated outputs: Several nodes are giving output(s) that have the same name. 17 | 18 | 19 | Add a :class:`~pyungo.core.Node` explicitely 20 | ############################################ 21 | 22 | While the simple example register nodes at import time with a decorator, it is possible to 23 | explicitely add a node a runtime. Here is the same example: 24 | 25 | :: 26 | 27 | from formulas import f_my_function_1, f_my_function_2, f_my_function_3 28 | 29 | graph = Graph() 30 | 31 | graph.add_node(f_my_function_1, inputs=['d', 'a'], outputs=['e']) 32 | graph.add_node(f_my_function_2, inputs=['c'], outputs=['d']) 33 | graph.add_node(f_my_function_3, inputs=['a', 'b'], outputs=['c']) 34 | 35 | res = graph.calculate(data={'a': 2, 'b': 3}) 36 | print(res) 37 | 38 | 39 | Parallelism 40 | ########### 41 | 42 | When resolving the dag, **pyungo** figure out nodes that can be run in parallel. 43 | When creating a graph, we can specify the option ``parallel=True`` for running calculations 44 | concurently when possible, using `multiprocess `_ 45 | module. This package is not automatically installed with **pyungo**, and will need to be 46 | installed manually if parallelism is used. We can specify the pool size when instantiating 47 | the :class:`~pyungo.core.Node`. This will set the maximum number of processes that will be 48 | launched. If 3 nodes can run in parallel and just 2 processes are used, **pyungo** will run 49 | calculation on the first 2 nodes first and will run the last one as soon as a process 50 | will be free. 51 | 52 | Instantiating a :class:`~pyungo.core.Graph` with a pool of 5 processes for running 53 | calculations in parralel: 54 | 55 | :: 56 | 57 | graph = Graph(parallel=True, pool_size=5) 58 | 59 | .. note:: 60 | Running functions in parallel has a cost. Python will spend time creating / deleting 61 | new processes. Parallelism is recommended when at least 2 concurrent nodes have heavy 62 | calculations which takes a significant amount of time. 63 | 64 | Args, Kwargs, Constants 65 | ####################### 66 | 67 | If a function registred in a :class:`~pyungo.core.Node` contains ``args`` or ``kwargs``, 68 | it is possible to define which data will be passed to them: 69 | 70 | :: 71 | 72 | graph.add_node( 73 | my_function, 74 | inputs=['a', 'b'], 75 | args=['c', 'd'], 76 | kwargs=['e', 'f'], 77 | outputs=['g'] 78 | ) 79 | 80 | Sometimes, we want one of the input to be defined as a constant: 81 | 82 | :: 83 | 84 | @graph.register(inputs=['a', {'b': 2}], outputs=['c']) 85 | def f_my_function(a, b): 86 | return a + b 87 | 88 | Then, only ``a`` and ``b`` will be needed when calling :class:`~pyungo.core.Graph.calculate`. 89 | 90 | :class:`~pyungo.io.Input` and :class:`~pyungo.io.Output` objects 91 | ################################################################ 92 | 93 | Inputs and outputs can be defined directly with their names, or with :class:`~pyungo.io.Input` 94 | / :class:`~pyungo.io.Output` objects. This come in handy when there is extra behavior to be 95 | attached to an input / output (e.g. ``Contracts``). 96 | 97 | :: 98 | 99 | from pyungo.io import Input, Output 100 | 101 | graph.add_node( 102 | my_function, 103 | inputs=[Input(name='a'), Input(name='b')], 104 | outputs=[Output(name='g')] 105 | ) 106 | 107 | Often, inputs are used multiple times across the nodes. In those cases, it is better to define 108 | inputs only once (with their special features if any). It is possible to pass a list of 109 | :class:`~pyungo.io.Input` / :class:`~pyungo.io.Output` objects a :class:`~pyungo.core.Graph`: 110 | 111 | :: 112 | 113 | from pyungo.io import Input, Output 114 | 115 | inputs = [Input(name='a'), Input(name='b')] 116 | outputs = [Output(name='c'), Output(name='d')] 117 | 118 | graph = Graph(inputs, outputs) 119 | 120 | graph.add_node( 121 | my_function, 122 | inputs=['a', 'b'], 123 | outputs=['c'] 124 | ) 125 | 126 | graph.add_node( 127 | my_other_function, 128 | inputs=['c', 'b'], 129 | outputs=['d'] 130 | ) 131 | 132 | .. note:: 133 | If inputs / outputs are explicitely provided to a graph, inputs / outputs defined 134 | in the nodes can only be strings. 135 | 136 | Schema 137 | ###### 138 | 139 | Inputs validation is an important step to run a model with confidence. pyungo uses the 140 | `JSON Schema specification `_ through a Python library: 141 | `jsonschema `_. The following is now possible: 142 | 143 | :: 144 | 145 | schema = { 146 | "type": "object", 147 | "properties": { 148 | "a": {"type": "number"}, 149 | "b": {"type": "number"} 150 | } 151 | } 152 | 153 | graph = Graph(schema=schema) 154 | 155 | @graph.register( 156 | inputs=['a', 'b'], 157 | outputs=['c'] 158 | ) 159 | def f_my_function(a, b): 160 | return a + b 161 | 162 | graph.calculate(data={'a': 1, 'b': '2'}) 163 | 164 | The calculation is going to fail as ``b`` is of type string. It is better to catch this problem 165 | early on before running the model. As we provided a schema saying we explicitely want ``b`` to 166 | be of type ``number``, the data validation against the schema will fail with the following error: 167 | ``'2' is not of type 'number'``. 168 | 169 | Name mapping 170 | ############ 171 | 172 | Often, the name of the data we get are different from the ones used in the functions / models / 173 | formulas. pyungo makes things easy providing a mapping feature. Here is an example: 174 | 175 | :: 176 | 177 | graph = Graph() 178 | 179 | @graph.register( 180 | inputs=[Input('a', map='q'), Input('b', map='w')], 181 | outputs=[Output('c', map='e')] 182 | ) 183 | def f_my_function(a, b): 184 | return a + b 185 | 186 | res = graph.calculate(data={'q': 2, 'w': 3}) 187 | assert res == 5 188 | assert graph.data['e'] == 5 189 | 190 | Contracts 191 | ######### 192 | 193 | Sometimes we want to make sure a value meet specific criteria before moving forward. 194 | **pyungo** uses `pycontracts `_ for attaching 195 | contracts to inputs or outputs. 196 | 197 | :: 198 | 199 | from pyungo.io import Input, Output 200 | 201 | graph.add_node( 202 | my_function, 203 | inputs=[Input(name='a', contract='>0'), Input(name='b', contract='float')], 204 | outputs=[Output(name='g', contract='float')] 205 | ) 206 | -------------------------------------------------------------------------------- /docs/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Welcome to pyungo’s documentation! — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 28 | 89 |
90 |
91 | 92 | 93 |
94 | 95 |
96 |

Welcome to pyungo’s documentation!

97 |
98 |

Contents:

99 | 129 |
130 |
131 |
132 |

Indices and tables

133 | 138 |
139 | 140 | 141 |
142 | 143 |
144 |
145 |
146 |
147 |
148 | ©2019, Cedric Leroy. 149 | 150 | | 151 | Powered by Sphinx 3.1.0 152 | & Alabaster 0.7.12 153 | 154 | | 155 | Page source 157 |
158 | 159 | 160 | 161 | Fork me on GitHub 162 | 163 | 164 | 165 | 166 | 167 | -------------------------------------------------------------------------------- /docs/genindex.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Index — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 |
26 | 27 | 87 |
88 |
89 | 90 | 91 |
92 | 93 | 94 |

Index

95 | 96 |
97 | A 98 | | C 99 | | D 100 | | G 101 | | I 102 | | N 103 | | O 104 | | R 105 | | S 106 | | T 107 | 108 |
109 |

A

110 | 111 | 115 |
116 | 117 |

C

118 | 119 | 123 |
124 | 125 |

D

126 | 127 | 131 | 135 |
136 | 137 |

G

138 | 139 | 143 |
144 | 145 |

I

146 | 147 | 151 |
152 | 153 |

N

154 | 155 | 159 |
160 | 161 |

O

162 | 163 | 167 |
168 | 169 |

R

170 | 171 | 175 | 179 |
180 | 181 |

S

182 | 183 | 187 | 193 |
194 | 195 |

T

196 | 197 | 201 |
202 | 203 | 204 | 205 |
206 | 207 |
208 |
209 |
210 |
211 |
212 | ©2019, Cedric Leroy. 213 | 214 | | 215 | Powered by Sphinx 3.1.0 216 | & Alabaster 0.7.12 217 | 218 |
219 | 220 | 221 | 222 | Fork me on GitHub 223 | 224 | 225 | 226 | 227 | 228 | -------------------------------------------------------------------------------- /docs/source/gettingstarted.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Getting Started — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
28 | 29 | 94 |
95 |
96 | 97 | 98 |
99 | 100 |
101 |

Getting Started

102 |

pyungo is a lightweight library to link a set of dependent functions together, 103 | and execute them in an ordered manner.

104 |

pyungo is built around Graphs and Nodes used in a 105 | DAG (Directed Acyclic Graph). 106 | A Node represent a function being run with a defined set of inputs 107 | and returning one or several outputs. A Graph is a collection of 108 | Nodes where data can flow in an logical manner, the output of one node serving as 109 | input of another.

110 |
111 |

Simple example

112 | 
graph = Graph()
113 | 
114 | @graph.register()
115 | def f_my_function_2(d, a):
116 |     e = d - a
117 |     return e
118 | 
119 | @graph.register(outputs=['d'])
120 | def f_my_function_1(c):
121 |     return c / 10.
122 | 
123 | @graph.register()
124 | def f_my_function_3(a, b):
125 |     c = a + b
126 |     return c
127 | 
128 | res = graph.calculate(data={'a': 2, 'b': 3})
129 | print(res)
130 |
131 |
132 |

pyungo is registering the functions at import time. It then resolve the DAG and figure out 133 | the sequence at which the functions have to be run per their inputs / outputs. In this case, 134 | it will be function 3 then 1 and finally 2.

135 |

The ordered Graph is run with calculate, with the given data. It returns 136 | the output of the last function being run (e), but all intermediate results are also 137 | available in the graph instance.

138 |

The result will be (a + b) / 10 - a = -1.5

139 |
140 |

Note

141 |

In the above example, most of the inputs / outputs are not explicitely defined when 142 | registering. pyungo inspects the function signature to get the names and extract the 143 | returned variable names automatically. For f_my_function_1, there is no returned 144 | variable, so the output name needs to be explicitely provided.

145 |
146 |
147 |
148 | 149 | 150 |
151 | 152 |
153 |
154 |
155 |
156 |
157 | ©2019, Cedric Leroy. 158 | 159 | | 160 | Powered by Sphinx 3.1.0 161 | & Alabaster 0.7.12 162 | 163 | | 164 | Page source 166 |
167 | 168 | 169 | 170 | Fork me on GitHub 171 | 172 | 173 | 174 | 175 | 176 | -------------------------------------------------------------------------------- /docs/_static/doctools.js: -------------------------------------------------------------------------------- 1 | /* 2 | * doctools.js 3 | * ~~~~~~~~~~~ 4 | * 5 | * Sphinx JavaScript utilities for all documentation. 6 | * 7 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | 12 | /** 13 | * select a different prefix for underscore 14 | */ 15 | $u = _.noConflict(); 16 | 17 | /** 18 | * make the code below compatible with browsers without 19 | * an installed firebug like debugger 20 | if (!window.console || !console.firebug) { 21 | var names = ["log", "debug", "info", "warn", "error", "assert", "dir", 22 | "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", 23 | "profile", "profileEnd"]; 24 | window.console = {}; 25 | for (var i = 0; i < names.length; ++i) 26 | window.console[names[i]] = function() {}; 27 | } 28 | */ 29 | 30 | /** 31 | * small helper function to urldecode strings 32 | */ 33 | jQuery.urldecode = function(x) { 34 | return decodeURIComponent(x).replace(/\+/g, ' '); 35 | }; 36 | 37 | /** 38 | * small helper function to urlencode strings 39 | */ 40 | jQuery.urlencode = encodeURIComponent; 41 | 42 | /** 43 | * This function returns the parsed url parameters of the 44 | * current request. Multiple values per key are supported, 45 | * it will always return arrays of strings for the value parts. 46 | */ 47 | jQuery.getQueryParameters = function(s) { 48 | if (typeof s === 'undefined') 49 | s = document.location.search; 50 | var parts = s.substr(s.indexOf('?') + 1).split('&'); 51 | var result = {}; 52 | for (var i = 0; i < parts.length; i++) { 53 | var tmp = parts[i].split('=', 2); 54 | var key = jQuery.urldecode(tmp[0]); 55 | var value = jQuery.urldecode(tmp[1]); 56 | if (key in result) 57 | result[key].push(value); 58 | else 59 | result[key] = [value]; 60 | } 61 | return result; 62 | }; 63 | 64 | /** 65 | * highlight a given string on a jquery object by wrapping it in 66 | * span elements with the given class name. 67 | */ 68 | jQuery.fn.highlightText = function(text, className) { 69 | function highlight(node, addItems) { 70 | if (node.nodeType === 3) { 71 | var val = node.nodeValue; 72 | var pos = val.toLowerCase().indexOf(text); 73 | if (pos >= 0 && 74 | !jQuery(node.parentNode).hasClass(className) && 75 | !jQuery(node.parentNode).hasClass("nohighlight")) { 76 | var span; 77 | var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); 78 | if (isInSVG) { 79 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); 80 | } else { 81 | span = document.createElement("span"); 82 | span.className = className; 83 | } 84 | span.appendChild(document.createTextNode(val.substr(pos, text.length))); 85 | node.parentNode.insertBefore(span, node.parentNode.insertBefore( 86 | document.createTextNode(val.substr(pos + text.length)), 87 | node.nextSibling)); 88 | node.nodeValue = val.substr(0, pos); 89 | if (isInSVG) { 90 | var bbox = span.getBBox(); 91 | var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); 92 | rect.x.baseVal.value = bbox.x; 93 | rect.y.baseVal.value = bbox.y; 94 | rect.width.baseVal.value = bbox.width; 95 | rect.height.baseVal.value = bbox.height; 96 | rect.setAttribute('class', className); 97 | var parentOfText = node.parentNode.parentNode; 98 | addItems.push({ 99 | "parent": node.parentNode, 100 | "target": rect}); 101 | } 102 | } 103 | } 104 | else if (!jQuery(node).is("button, select, textarea")) { 105 | jQuery.each(node.childNodes, function() { 106 | highlight(this, addItems); 107 | }); 108 | } 109 | } 110 | var addItems = []; 111 | var result = this.each(function() { 112 | highlight(this, addItems); 113 | }); 114 | for (var i = 0; i < addItems.length; ++i) { 115 | jQuery(addItems[i].parent).before(addItems[i].target); 116 | } 117 | return result; 118 | }; 119 | 120 | /* 121 | * backward compatibility for jQuery.browser 122 | * This will be supported until firefox bug is fixed. 123 | */ 124 | if (!jQuery.browser) { 125 | jQuery.uaMatch = function(ua) { 126 | ua = ua.toLowerCase(); 127 | 128 | var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || 129 | /(webkit)[ \/]([\w.]+)/.exec(ua) || 130 | /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || 131 | /(msie) ([\w.]+)/.exec(ua) || 132 | ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || 133 | []; 134 | 135 | return { 136 | browser: match[ 1 ] || "", 137 | version: match[ 2 ] || "0" 138 | }; 139 | }; 140 | jQuery.browser = {}; 141 | jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; 142 | } 143 | 144 | /** 145 | * Small JavaScript module for the documentation. 146 | */ 147 | var Documentation = { 148 | 149 | init : function() { 150 | this.fixFirefoxAnchorBug(); 151 | this.highlightSearchWords(); 152 | this.initIndexTable(); 153 | if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) { 154 | this.initOnKeyListeners(); 155 | } 156 | }, 157 | 158 | /** 159 | * i18n support 160 | */ 161 | TRANSLATIONS : {}, 162 | PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, 163 | LOCALE : 'unknown', 164 | 165 | // gettext and ngettext don't access this so that the functions 166 | // can safely bound to a different name (_ = Documentation.gettext) 167 | gettext : function(string) { 168 | var translated = Documentation.TRANSLATIONS[string]; 169 | if (typeof translated === 'undefined') 170 | return string; 171 | return (typeof translated === 'string') ? translated : translated[0]; 172 | }, 173 | 174 | ngettext : function(singular, plural, n) { 175 | var translated = Documentation.TRANSLATIONS[singular]; 176 | if (typeof translated === 'undefined') 177 | return (n == 1) ? singular : plural; 178 | return translated[Documentation.PLURALEXPR(n)]; 179 | }, 180 | 181 | addTranslations : function(catalog) { 182 | for (var key in catalog.messages) 183 | this.TRANSLATIONS[key] = catalog.messages[key]; 184 | this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); 185 | this.LOCALE = catalog.locale; 186 | }, 187 | 188 | /** 189 | * add context elements like header anchor links 190 | */ 191 | addContextElements : function() { 192 | $('div[id] > :header:first').each(function() { 193 | $('\u00B6'). 194 | attr('href', '#' + this.id). 195 | attr('title', _('Permalink to this headline')). 196 | appendTo(this); 197 | }); 198 | $('dt[id]').each(function() { 199 | $('\u00B6'). 200 | attr('href', '#' + this.id). 201 | attr('title', _('Permalink to this definition')). 202 | appendTo(this); 203 | }); 204 | }, 205 | 206 | /** 207 | * workaround a firefox stupidity 208 | * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 209 | */ 210 | fixFirefoxAnchorBug : function() { 211 | if (document.location.hash && $.browser.mozilla) 212 | window.setTimeout(function() { 213 | document.location.href += ''; 214 | }, 10); 215 | }, 216 | 217 | /** 218 | * highlight the search words provided in the url in the text 219 | */ 220 | highlightSearchWords : function() { 221 | var params = $.getQueryParameters(); 222 | var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; 223 | if (terms.length) { 224 | var body = $('div.body'); 225 | if (!body.length) { 226 | body = $('body'); 227 | } 228 | window.setTimeout(function() { 229 | $.each(terms, function() { 230 | body.highlightText(this.toLowerCase(), 'highlighted'); 231 | }); 232 | }, 10); 233 | $('

' + _('Hide Search Matches') + '

') 235 | .appendTo($('#searchbox')); 236 | } 237 | }, 238 | 239 | /** 240 | * init the domain index toggle buttons 241 | */ 242 | initIndexTable : function() { 243 | var togglers = $('img.toggler').click(function() { 244 | var src = $(this).attr('src'); 245 | var idnum = $(this).attr('id').substr(7); 246 | $('tr.cg-' + idnum).toggle(); 247 | if (src.substr(-9) === 'minus.png') 248 | $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); 249 | else 250 | $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); 251 | }).css('display', ''); 252 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { 253 | togglers.click(); 254 | } 255 | }, 256 | 257 | /** 258 | * helper function to hide the search marks again 259 | */ 260 | hideSearchWords : function() { 261 | $('#searchbox .highlight-link').fadeOut(300); 262 | $('span.highlighted').removeClass('highlighted'); 263 | }, 264 | 265 | /** 266 | * make the url absolute 267 | */ 268 | makeURL : function(relativeURL) { 269 | return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; 270 | }, 271 | 272 | /** 273 | * get the current relative url 274 | */ 275 | getCurrentURL : function() { 276 | var path = document.location.pathname; 277 | var parts = path.split(/\//); 278 | $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { 279 | if (this === '..') 280 | parts.pop(); 281 | }); 282 | var url = parts.join('/'); 283 | return path.substring(url.lastIndexOf('/') + 1, path.length - 1); 284 | }, 285 | 286 | initOnKeyListeners: function() { 287 | $(document).keyup(function(event) { 288 | var activeElementType = document.activeElement.tagName; 289 | // don't navigate when in search box or textarea 290 | if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') { 291 | switch (event.keyCode) { 292 | case 37: // left 293 | var prevHref = $('link[rel="prev"]').prop('href'); 294 | if (prevHref) { 295 | window.location.href = prevHref; 296 | return false; 297 | } 298 | case 39: // right 299 | var nextHref = $('link[rel="next"]').prop('href'); 300 | if (nextHref) { 301 | window.location.href = nextHref; 302 | return false; 303 | } 304 | } 305 | } 306 | }); 307 | } 308 | }; 309 | 310 | // quick alias for translations 311 | _ = Documentation.gettext; 312 | 313 | $(document).ready(function() { 314 | Documentation.init(); 315 | }); 316 | -------------------------------------------------------------------------------- /docs/_static/underscore.js: -------------------------------------------------------------------------------- 1 | // Underscore.js 1.3.1 2 | // (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc. 3 | // Underscore is freely distributable under the MIT license. 4 | // Portions of Underscore are inspired or borrowed from Prototype, 5 | // Oliver Steele's Functional, and John Resig's Micro-Templating. 6 | // For all details and documentation: 7 | // http://documentcloud.github.com/underscore 8 | (function(){function q(a,c,d){if(a===c)return a!==0||1/a==1/c;if(a==null||c==null)return a===c;if(a._chain)a=a._wrapped;if(c._chain)c=c._wrapped;if(a.isEqual&&b.isFunction(a.isEqual))return a.isEqual(c);if(c.isEqual&&b.isFunction(c.isEqual))return c.isEqual(a);var e=l.call(a);if(e!=l.call(c))return false;switch(e){case "[object String]":return a==String(c);case "[object Number]":return a!=+a?c!=+c:a==0?1/a==1/c:a==+c;case "[object Date]":case "[object Boolean]":return+a==+c;case "[object RegExp]":return a.source== 9 | c.source&&a.global==c.global&&a.multiline==c.multiline&&a.ignoreCase==c.ignoreCase}if(typeof a!="object"||typeof c!="object")return false;for(var f=d.length;f--;)if(d[f]==a)return true;d.push(a);var f=0,g=true;if(e=="[object Array]"){if(f=a.length,g=f==c.length)for(;f--;)if(!(g=f in a==f in c&&q(a[f],c[f],d)))break}else{if("constructor"in a!="constructor"in c||a.constructor!=c.constructor)return false;for(var h in a)if(b.has(a,h)&&(f++,!(g=b.has(c,h)&&q(a[h],c[h],d))))break;if(g){for(h in c)if(b.has(c, 10 | h)&&!f--)break;g=!f}}d.pop();return g}var r=this,G=r._,n={},k=Array.prototype,o=Object.prototype,i=k.slice,H=k.unshift,l=o.toString,I=o.hasOwnProperty,w=k.forEach,x=k.map,y=k.reduce,z=k.reduceRight,A=k.filter,B=k.every,C=k.some,p=k.indexOf,D=k.lastIndexOf,o=Array.isArray,J=Object.keys,s=Function.prototype.bind,b=function(a){return new m(a)};if(typeof exports!=="undefined"){if(typeof module!=="undefined"&&module.exports)exports=module.exports=b;exports._=b}else r._=b;b.VERSION="1.3.1";var j=b.each= 11 | b.forEach=function(a,c,d){if(a!=null)if(w&&a.forEach===w)a.forEach(c,d);else if(a.length===+a.length)for(var e=0,f=a.length;e2;a== 12 | null&&(a=[]);if(y&&a.reduce===y)return e&&(c=b.bind(c,e)),f?a.reduce(c,d):a.reduce(c);j(a,function(a,b,i){f?d=c.call(e,d,a,b,i):(d=a,f=true)});if(!f)throw new TypeError("Reduce of empty array with no initial value");return d};b.reduceRight=b.foldr=function(a,c,d,e){var f=arguments.length>2;a==null&&(a=[]);if(z&&a.reduceRight===z)return e&&(c=b.bind(c,e)),f?a.reduceRight(c,d):a.reduceRight(c);var g=b.toArray(a).reverse();e&&!f&&(c=b.bind(c,e));return f?b.reduce(g,c,d,e):b.reduce(g,c)};b.find=b.detect= 13 | function(a,c,b){var e;E(a,function(a,g,h){if(c.call(b,a,g,h))return e=a,true});return e};b.filter=b.select=function(a,c,b){var e=[];if(a==null)return e;if(A&&a.filter===A)return a.filter(c,b);j(a,function(a,g,h){c.call(b,a,g,h)&&(e[e.length]=a)});return e};b.reject=function(a,c,b){var e=[];if(a==null)return e;j(a,function(a,g,h){c.call(b,a,g,h)||(e[e.length]=a)});return e};b.every=b.all=function(a,c,b){var e=true;if(a==null)return e;if(B&&a.every===B)return a.every(c,b);j(a,function(a,g,h){if(!(e= 14 | e&&c.call(b,a,g,h)))return n});return e};var E=b.some=b.any=function(a,c,d){c||(c=b.identity);var e=false;if(a==null)return e;if(C&&a.some===C)return a.some(c,d);j(a,function(a,b,h){if(e||(e=c.call(d,a,b,h)))return n});return!!e};b.include=b.contains=function(a,c){var b=false;if(a==null)return b;return p&&a.indexOf===p?a.indexOf(c)!=-1:b=E(a,function(a){return a===c})};b.invoke=function(a,c){var d=i.call(arguments,2);return b.map(a,function(a){return(b.isFunction(c)?c||a:a[c]).apply(a,d)})};b.pluck= 15 | function(a,c){return b.map(a,function(a){return a[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);if(!c&&b.isEmpty(a))return-Infinity;var e={computed:-Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b>=e.computed&&(e={value:a,computed:b})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);if(!c&&b.isEmpty(a))return Infinity;var e={computed:Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;bd?1:0}),"value")};b.groupBy=function(a,c){var d={},e=b.isFunction(c)?c:function(a){return a[c]};j(a,function(a,b){var c=e(a,b);(d[c]||(d[c]=[])).push(a)});return d};b.sortedIndex=function(a, 17 | c,d){d||(d=b.identity);for(var e=0,f=a.length;e>1;d(a[g])=0})})};b.difference=function(a){var c=b.flatten(i.call(arguments,1));return b.filter(a,function(a){return!b.include(c,a)})};b.zip=function(){for(var a=i.call(arguments),c=b.max(b.pluck(a,"length")),d=Array(c),e=0;e=0;d--)b=[a[d].apply(this,b)];return b[0]}}; 24 | b.after=function(a,b){return a<=0?b():function(){if(--a<1)return b.apply(this,arguments)}};b.keys=J||function(a){if(a!==Object(a))throw new TypeError("Invalid object");var c=[],d;for(d in a)b.has(a,d)&&(c[c.length]=d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=b.methods=function(a){var c=[],d;for(d in a)b.isFunction(a[d])&&c.push(d);return c.sort()};b.extend=function(a){j(i.call(arguments,1),function(b){for(var d in b)a[d]=b[d]});return a};b.defaults=function(a){j(i.call(arguments, 25 | 1),function(b){for(var d in b)a[d]==null&&(a[d]=b[d])});return a};b.clone=function(a){return!b.isObject(a)?a:b.isArray(a)?a.slice():b.extend({},a)};b.tap=function(a,b){b(a);return a};b.isEqual=function(a,b){return q(a,b,[])};b.isEmpty=function(a){if(b.isArray(a)||b.isString(a))return a.length===0;for(var c in a)if(b.has(a,c))return false;return true};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=o||function(a){return l.call(a)=="[object Array]"};b.isObject=function(a){return a===Object(a)}; 26 | b.isArguments=function(a){return l.call(a)=="[object Arguments]"};if(!b.isArguments(arguments))b.isArguments=function(a){return!(!a||!b.has(a,"callee"))};b.isFunction=function(a){return l.call(a)=="[object Function]"};b.isString=function(a){return l.call(a)=="[object String]"};b.isNumber=function(a){return l.call(a)=="[object Number]"};b.isNaN=function(a){return a!==a};b.isBoolean=function(a){return a===true||a===false||l.call(a)=="[object Boolean]"};b.isDate=function(a){return l.call(a)=="[object Date]"}; 27 | b.isRegExp=function(a){return l.call(a)=="[object RegExp]"};b.isNull=function(a){return a===null};b.isUndefined=function(a){return a===void 0};b.has=function(a,b){return I.call(a,b)};b.noConflict=function(){r._=G;return this};b.identity=function(a){return a};b.times=function(a,b,d){for(var e=0;e/g,">").replace(/"/g,""").replace(/'/g,"'").replace(/\//g,"/")};b.mixin=function(a){j(b.functions(a), 28 | function(c){K(c,b[c]=a[c])})};var L=0;b.uniqueId=function(a){var b=L++;return a?a+b:b};b.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g};var t=/.^/,u=function(a){return a.replace(/\\\\/g,"\\").replace(/\\'/g,"'")};b.template=function(a,c){var d=b.templateSettings,d="var __p=[],print=function(){__p.push.apply(__p,arguments);};with(obj||{}){__p.push('"+a.replace(/\\/g,"\\\\").replace(/'/g,"\\'").replace(d.escape||t,function(a,b){return"',_.escape("+ 29 | u(b)+"),'"}).replace(d.interpolate||t,function(a,b){return"',"+u(b)+",'"}).replace(d.evaluate||t,function(a,b){return"');"+u(b).replace(/[\r\n\t]/g," ")+";__p.push('"}).replace(/\r/g,"\\r").replace(/\n/g,"\\n").replace(/\t/g,"\\t")+"');}return __p.join('');",e=new Function("obj","_",d);return c?e(c,b):function(a){return e.call(this,a,b)}};b.chain=function(a){return b(a).chain()};var m=function(a){this._wrapped=a};b.prototype=m.prototype;var v=function(a,c){return c?b(a).chain():a},K=function(a,c){m.prototype[a]= 30 | function(){var a=i.call(arguments);H.call(a,this._wrapped);return v(c.apply(b,a),this._chain)}};b.mixin(b);j("pop,push,reverse,shift,sort,splice,unshift".split(","),function(a){var b=k[a];m.prototype[a]=function(){var d=this._wrapped;b.apply(d,arguments);var e=d.length;(a=="shift"||a=="splice")&&e===0&&delete d[0];return v(d,this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];m.prototype[a]=function(){return v(b.apply(this._wrapped,arguments),this._chain)}});m.prototype.chain=function(){this._chain= 31 | true;return this};m.prototype.value=function(){return this._wrapped}}).call(this); 32 | -------------------------------------------------------------------------------- /docs/_static/language_data.js: -------------------------------------------------------------------------------- 1 | /* 2 | * language_data.js 3 | * ~~~~~~~~~~~~~~~~ 4 | * 5 | * This script contains the language-specific data used by searchtools.js, 6 | * namely the list of stopwords, stemmer, scorer and splitter. 7 | * 8 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 9 | * :license: BSD, see LICENSE for details. 10 | * 11 | */ 12 | 13 | var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"]; 14 | 15 | 16 | /* Non-minified version JS is _stemmer.js if file is provided */ 17 | /** 18 | * Porter Stemmer 19 | */ 20 | var Stemmer = function() { 21 | 22 | var step2list = { 23 | ational: 'ate', 24 | tional: 'tion', 25 | enci: 'ence', 26 | anci: 'ance', 27 | izer: 'ize', 28 | bli: 'ble', 29 | alli: 'al', 30 | entli: 'ent', 31 | eli: 'e', 32 | ousli: 'ous', 33 | ization: 'ize', 34 | ation: 'ate', 35 | ator: 'ate', 36 | alism: 'al', 37 | iveness: 'ive', 38 | fulness: 'ful', 39 | ousness: 'ous', 40 | aliti: 'al', 41 | iviti: 'ive', 42 | biliti: 'ble', 43 | logi: 'log' 44 | }; 45 | 46 | var step3list = { 47 | icate: 'ic', 48 | ative: '', 49 | alize: 'al', 50 | iciti: 'ic', 51 | ical: 'ic', 52 | ful: '', 53 | ness: '' 54 | }; 55 | 56 | var c = "[^aeiou]"; // consonant 57 | var v = "[aeiouy]"; // vowel 58 | var C = c + "[^aeiouy]*"; // consonant sequence 59 | var V = v + "[aeiou]*"; // vowel sequence 60 | 61 | var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 62 | var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 63 | var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 64 | var s_v = "^(" + C + ")?" + v; // vowel in stem 65 | 66 | this.stemWord = function (w) { 67 | var stem; 68 | var suffix; 69 | var firstch; 70 | var origword = w; 71 | 72 | if (w.length < 3) 73 | return w; 74 | 75 | var re; 76 | var re2; 77 | var re3; 78 | var re4; 79 | 80 | firstch = w.substr(0,1); 81 | if (firstch == "y") 82 | w = firstch.toUpperCase() + w.substr(1); 83 | 84 | // Step 1a 85 | re = /^(.+?)(ss|i)es$/; 86 | re2 = /^(.+?)([^s])s$/; 87 | 88 | if (re.test(w)) 89 | w = w.replace(re,"$1$2"); 90 | else if (re2.test(w)) 91 | w = w.replace(re2,"$1$2"); 92 | 93 | // Step 1b 94 | re = /^(.+?)eed$/; 95 | re2 = /^(.+?)(ed|ing)$/; 96 | if (re.test(w)) { 97 | var fp = re.exec(w); 98 | re = new RegExp(mgr0); 99 | if (re.test(fp[1])) { 100 | re = /.$/; 101 | w = w.replace(re,""); 102 | } 103 | } 104 | else if (re2.test(w)) { 105 | var fp = re2.exec(w); 106 | stem = fp[1]; 107 | re2 = new RegExp(s_v); 108 | if (re2.test(stem)) { 109 | w = stem; 110 | re2 = /(at|bl|iz)$/; 111 | re3 = new RegExp("([^aeiouylsz])\\1$"); 112 | re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 113 | if (re2.test(w)) 114 | w = w + "e"; 115 | else if (re3.test(w)) { 116 | re = /.$/; 117 | w = w.replace(re,""); 118 | } 119 | else if (re4.test(w)) 120 | w = w + "e"; 121 | } 122 | } 123 | 124 | // Step 1c 125 | re = /^(.+?)y$/; 126 | if (re.test(w)) { 127 | var fp = re.exec(w); 128 | stem = fp[1]; 129 | re = new RegExp(s_v); 130 | if (re.test(stem)) 131 | w = stem + "i"; 132 | } 133 | 134 | // Step 2 135 | re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; 136 | if (re.test(w)) { 137 | var fp = re.exec(w); 138 | stem = fp[1]; 139 | suffix = fp[2]; 140 | re = new RegExp(mgr0); 141 | if (re.test(stem)) 142 | w = stem + step2list[suffix]; 143 | } 144 | 145 | // Step 3 146 | re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; 147 | if (re.test(w)) { 148 | var fp = re.exec(w); 149 | stem = fp[1]; 150 | suffix = fp[2]; 151 | re = new RegExp(mgr0); 152 | if (re.test(stem)) 153 | w = stem + step3list[suffix]; 154 | } 155 | 156 | // Step 4 157 | re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; 158 | re2 = /^(.+?)(s|t)(ion)$/; 159 | if (re.test(w)) { 160 | var fp = re.exec(w); 161 | stem = fp[1]; 162 | re = new RegExp(mgr1); 163 | if (re.test(stem)) 164 | w = stem; 165 | } 166 | else if (re2.test(w)) { 167 | var fp = re2.exec(w); 168 | stem = fp[1] + fp[2]; 169 | re2 = new RegExp(mgr1); 170 | if (re2.test(stem)) 171 | w = stem; 172 | } 173 | 174 | // Step 5 175 | re = /^(.+?)e$/; 176 | if (re.test(w)) { 177 | var fp = re.exec(w); 178 | stem = fp[1]; 179 | re = new RegExp(mgr1); 180 | re2 = new RegExp(meq1); 181 | re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); 182 | if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) 183 | w = stem; 184 | } 185 | re = /ll$/; 186 | re2 = new RegExp(mgr1); 187 | if (re.test(w) && re2.test(w)) { 188 | re = /.$/; 189 | w = w.replace(re,""); 190 | } 191 | 192 | // and turn initial Y back to y 193 | if (firstch == "y") 194 | w = firstch.toLowerCase() + w.substr(1); 195 | return w; 196 | } 197 | } 198 | 199 | 200 | 201 | 202 | 203 | var splitChars = (function() { 204 | var result = {}; 205 | var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, 206 | 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, 207 | 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, 208 | 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, 209 | 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, 210 | 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, 211 | 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, 212 | 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, 213 | 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, 214 | 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; 215 | var i, j, start, end; 216 | for (i = 0; i < singles.length; i++) { 217 | result[singles[i]] = true; 218 | } 219 | var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], 220 | [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], 221 | [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], 222 | [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], 223 | [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], 224 | [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], 225 | [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], 226 | [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], 227 | [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], 228 | [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], 229 | [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], 230 | [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], 231 | [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], 232 | [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], 233 | [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], 234 | [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], 235 | [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], 236 | [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], 237 | [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], 238 | [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], 239 | [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], 240 | [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], 241 | [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], 242 | [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], 243 | [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], 244 | [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], 245 | [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], 246 | [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], 247 | [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], 248 | [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], 249 | [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], 250 | [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], 251 | [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], 252 | [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], 253 | [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], 254 | [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], 255 | [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], 256 | [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], 257 | [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], 258 | [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], 259 | [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], 260 | [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], 261 | [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], 262 | [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], 263 | [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], 264 | [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], 265 | [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], 266 | [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], 267 | [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; 268 | for (i = 0; i < ranges.length; i++) { 269 | start = ranges[i][0]; 270 | end = ranges[i][1]; 271 | for (j = start; j <= end; j++) { 272 | result[j] = true; 273 | } 274 | } 275 | return result; 276 | })(); 277 | 278 | function splitQuery(query) { 279 | var result = []; 280 | var start = -1; 281 | for (var i = 0; i < query.length; i++) { 282 | if (splitChars[query.charCodeAt(i)]) { 283 | if (start !== -1) { 284 | result.push(query.slice(start, i)); 285 | start = -1; 286 | } 287 | } else if (start === -1) { 288 | start = i; 289 | } 290 | } 291 | if (start !== -1) { 292 | result.push(query.slice(start)); 293 | } 294 | return result; 295 | } 296 | 297 | 298 | -------------------------------------------------------------------------------- /tests/test_core.py: -------------------------------------------------------------------------------- 1 | import pytest 2 | 3 | from pyungo.core import Graph, PyungoError 4 | from pyungo.io import Input, Output 5 | 6 | 7 | def test_simple(): 8 | graph = Graph() 9 | 10 | @graph.register(inputs=["a", "b"], outputs=["c"]) 11 | def f_my_function(a, b): 12 | return a + b 13 | 14 | @graph.register(inputs=["d", "a"], outputs=["e"]) 15 | def f_my_function3(d, a): 16 | return d - a 17 | 18 | @graph.register(inputs=["c"], outputs=["d"]) 19 | def f_my_function2(c): 20 | return c / 10.0 21 | 22 | res = graph.calculate(data={"a": 2, "b": 3}) 23 | assert res == -1.5 24 | assert graph.data["e"] == -1.5 25 | 26 | # make sure it is indepodent 27 | res = graph.calculate(data={"a": 2, "b": 3}) 28 | assert res == -1.5 29 | assert graph.data["e"] == -1.5 30 | 31 | 32 | def test_simple_without_decorator(): 33 | graph = Graph() 34 | 35 | def f_my_function(a, b): 36 | return a + b 37 | 38 | def f_my_function3(d, a): 39 | return d - a 40 | 41 | def f_my_function2(c): 42 | return c / 10.0 43 | 44 | graph.add_node(f_my_function, inputs=["a", "b"], outputs=["c"]) 45 | graph.add_node(f_my_function3, inputs=["d", "a"], outputs=["e"]) 46 | graph.add_node(f_my_function2, inputs=["c"], outputs=["d"]) 47 | 48 | res = graph.calculate(data={"a": 2, "b": 3}) 49 | 50 | assert res == -1.5 51 | assert graph.data["e"] == -1.5 52 | 53 | 54 | def test_simple_parallel(): 55 | """ TODO: We could mock and make sure things are called correctly """ 56 | 57 | graph = Graph(parallel=True) 58 | 59 | def f_my_function(a, b): 60 | return a + b 61 | 62 | def f_my_function3(d, a): 63 | return d - a 64 | 65 | def f_my_function2(c): 66 | return c / 10.0 67 | 68 | graph.add_node(f_my_function, inputs=["a", "b"], outputs=["c"]) 69 | graph.add_node(f_my_function3, inputs=["d", "a"], outputs=["e"]) 70 | graph.add_node(f_my_function2, inputs=["c"], outputs=["d"]) 71 | graph.add_node(f_my_function2, inputs=["c"], outputs=["f"]) 72 | graph.add_node(f_my_function2, inputs=["c"], outputs=["g"]) 73 | 74 | res = graph.calculate(data={"a": 2, "b": 3}) 75 | 76 | assert res == -1.5 77 | 78 | 79 | def test_multiple_outputs(): 80 | graph = Graph() 81 | 82 | @graph.register(inputs=["a", "b"], outputs=["c", "d"]) 83 | def f_my_function(a, b): 84 | return a + b, 2 * b 85 | 86 | @graph.register(inputs=["c", "d"], outputs=["e"]) 87 | def f_my_function2(c, d): 88 | return c + d 89 | 90 | res = graph.calculate(data={"a": 2, "b": 3}) 91 | 92 | assert res == 11 93 | assert graph.data["e"] == 11 94 | 95 | 96 | def test_same_output_names(): 97 | graph = Graph() 98 | 99 | @graph.register(inputs=["a", "b"], outputs=["c"]) 100 | def f_my_function(a, b): 101 | return a + b 102 | 103 | with pytest.raises(PyungoError) as err: 104 | 105 | @graph.register(inputs=["c"], outputs=["c"]) 106 | def f_my_function2(c): 107 | return c / 10 108 | 109 | assert "c output already exist" in str(err.value) 110 | 111 | 112 | def test_missing_input(): 113 | graph = Graph() 114 | 115 | @graph.register(inputs=["a", "b"], outputs=["c"]) 116 | def f_my_function(a, b): 117 | return a + b 118 | 119 | with pytest.raises(PyungoError) as err: 120 | graph.calculate(data={"a": 6}) 121 | 122 | assert "The following inputs are needed: ['b']" in str(err.value) 123 | 124 | 125 | def test_inputs_not_used(): 126 | graph = Graph() 127 | 128 | @graph.register(inputs=["a", "b"], outputs=["c"]) 129 | def f_my_function(a, b): 130 | return a + b 131 | 132 | with pytest.raises(PyungoError) as err: 133 | graph.calculate(data={"a": 6, "b": 4, "e": 7}) 134 | 135 | assert "The following inputs are not used by the model: ['e']" in str(err.value) 136 | 137 | 138 | def test_inputs_collision(): 139 | graph = Graph() 140 | 141 | @graph.register(inputs=["a", "b"], outputs=["c"]) 142 | def f_my_function(a, b): 143 | return a + b 144 | 145 | with pytest.raises(PyungoError) as err: 146 | graph.calculate(data={"a": 6, "b": 4, "c": 7}) 147 | 148 | assert "The following inputs are already used in the model: ['c']" in str(err.value) 149 | 150 | 151 | def test_circular_dependency(): 152 | graph = Graph() 153 | 154 | @graph.register(inputs=["a", "b", "d"], outputs=["c"]) 155 | def f_my_function(a, b): 156 | return a + b 157 | 158 | @graph.register(inputs=["c"], outputs=["d"]) 159 | def f_my_function2(c): 160 | return c / 2.0 161 | 162 | with pytest.raises(PyungoError) as err: 163 | graph.calculate(data={"a": 6, "b": 4}) 164 | 165 | assert "A cyclic dependency exists amongst" in str(err.value) 166 | 167 | 168 | def test_iterable_on_single_output(): 169 | graph = Graph() 170 | 171 | @graph.register(inputs=["a", "b"], outputs=["c"]) 172 | def f_my_function(a, b): 173 | return list(range(a)) + [b] 174 | 175 | res = graph.calculate(data={"a": 2, "b": 3}) 176 | 177 | assert res == [0, 1, 3] 178 | assert graph.data["c"] == [0, 1, 3] 179 | 180 | 181 | def test_multiple_outputs_with_iterable(): 182 | graph = Graph() 183 | 184 | @graph.register(inputs=["a", "b"], outputs=["c", "d"]) 185 | def f_my_function(a, b): 186 | return list(range(a)) + [b], b * 10 187 | 188 | res = graph.calculate(data={"a": 2, "b": 3}) 189 | 190 | assert isinstance(res, tuple) is True 191 | assert graph.data["c"] == [0, 1, 3] 192 | assert graph.data["d"] == 30 193 | assert res[0] == [0, 1, 3] 194 | assert res[1] == 30 195 | 196 | 197 | def test_args_kwargs(): 198 | graph = Graph() 199 | 200 | @graph.register(inputs=["a", "b"], args=["c"], kwargs=["d"], outputs=["e"]) 201 | def f_my_function(a, b, *args, **kwargs): 202 | return a + b + args[0] + kwargs["d"] 203 | 204 | res = graph.calculate(data={"a": 2, "b": 3, "c": 4, "d": 5}) 205 | 206 | assert res == 14 207 | assert graph.data["e"] == 14 208 | 209 | 210 | def test_dag_pretty_print(): 211 | graph = Graph() 212 | 213 | @graph.register(inputs=["a", "b"], outputs=["c"]) 214 | def f_my_function(a, b): 215 | return a + b 216 | 217 | @graph.register(inputs=["d", "a"], outputs=["e"]) 218 | def f_my_function3(d, a): 219 | return d - a 220 | 221 | @graph.register(inputs=["c"], outputs=["d"]) 222 | def f_my_function2(c): 223 | return c / 10.0 224 | 225 | expected = ["f_my_function", "f_my_function2", "f_my_function3"] 226 | dag = graph.dag 227 | for i, fct_name in enumerate(expected): 228 | assert dag[i][0].fct_name == fct_name 229 | 230 | 231 | def test_passing_data_to_node_definition(): 232 | graph = Graph() 233 | 234 | @graph.register(inputs=["a", {"b": 2}], outputs=["c"]) 235 | def f_my_function(a, b): 236 | return a + b 237 | 238 | res = graph.calculate(data={"a": 5}) 239 | assert res == 7 240 | 241 | 242 | def test_wrong_input_type(): 243 | graph = Graph() 244 | 245 | with pytest.raises(PyungoError) as err: 246 | 247 | @graph.register(inputs=["a", {"b"}], outputs=["c"]) 248 | def f_my_function(a, b): 249 | return a + b 250 | 251 | assert "inputs need to be of type Input, str or dict" in str(err.value) 252 | 253 | 254 | def test_empty_input_dict(): 255 | graph = Graph() 256 | 257 | with pytest.raises(PyungoError) as err: 258 | 259 | @graph.register(inputs=["a", {}], outputs=["c"]) 260 | def f_my_function(a, b): 261 | return a + b 262 | 263 | assert "dict inputs should have only one key and cannot be empty" in str(err.value) 264 | 265 | 266 | def test_multiple_keys_input_dict(): 267 | graph = Graph() 268 | 269 | with pytest.raises(PyungoError) as err: 270 | 271 | @graph.register(inputs=["a", {"b": 1, "c": 2}], outputs=["c"]) 272 | def f_my_function(a, b): 273 | return a + b 274 | 275 | assert "dict inputs should have only one key and cannot be empty" in str(err.value) 276 | 277 | 278 | def test_Input_type_input(): 279 | graph = Graph() 280 | 281 | @graph.register(inputs=[Input(name="a"), "b"], outputs=["c"]) 282 | def f_my_function(a, b): 283 | return a + b 284 | 285 | res = graph.calculate(data={"a": 2, "b": 3}) 286 | 287 | assert res == 5 288 | 289 | 290 | def test_contract_inputs(): 291 | from contracts import ContractNotRespected 292 | 293 | graph = Graph() 294 | 295 | @graph.register(inputs=[Input(name="a", contract="int,>0"), "b"], outputs=["c"]) 296 | def f_my_function(a, b): 297 | return a + b 298 | 299 | res = graph.calculate(data={"a": 2, "b": 3}) 300 | assert res == 5 301 | res = graph.calculate(data={"a": 2, "b": 3}) 302 | assert res == 5 303 | 304 | with pytest.raises(ContractNotRespected) as err: 305 | res = graph.calculate(data={"a": -2, "b": 3}) 306 | 307 | assert "Condition -2 > 0 not respected" in str(err.value) 308 | 309 | 310 | def test_contract_outputs(): 311 | from contracts import ContractNotRespected 312 | 313 | graph = Graph() 314 | 315 | @graph.register(inputs=["a", "b"], outputs=[Output("c", contract="int,>0")]) 316 | def f_my_function(a, b): 317 | return a + b 318 | 319 | res = graph.calculate(data={"a": 2, "b": 3}) 320 | assert res == 5 321 | 322 | with pytest.raises(ContractNotRespected) as err: 323 | res = graph.calculate(data={"a": -4, "b": 3}) 324 | 325 | assert "Condition -1 > 0 not respected" in str(err.value) 326 | 327 | 328 | def test_provide_inputs_outputs(): 329 | inputs = [Input("a"), Input("b")] 330 | outputs = [Output("c")] 331 | 332 | graph = Graph(inputs=inputs, outputs=outputs) 333 | 334 | @graph.register(inputs=["a", "b"], outputs=["c"]) 335 | def f_my_function(a, b): 336 | return a + b 337 | 338 | res = graph.calculate(data={"a": 2, "b": 3}) 339 | assert res == 5 340 | 341 | 342 | def test_provide_inputs_outputs_already_defined(): 343 | inputs = [Input("a"), Input("b")] 344 | outputs = [Output("c")] 345 | 346 | graph = Graph(inputs=inputs, outputs=outputs) 347 | 348 | with pytest.raises(TypeError) as err: 349 | 350 | @graph.register(inputs=["a", "b"], outputs=[Output("c")]) 351 | def f_my_function(a, b): 352 | return a + b 353 | 354 | msg = "You cannot use Input / Output in a Node if already defined" 355 | assert msg in str(err.value) 356 | 357 | 358 | def test_map(): 359 | graph = Graph() 360 | 361 | @graph.register( 362 | inputs=[Input("a", map="q"), Input("b", map="w")], 363 | outputs=[Output("c", map="e")], 364 | ) 365 | def f_my_function(a, b): 366 | return a + b 367 | 368 | res = graph.calculate(data={"q": 2, "w": 3}) 369 | assert res == 5 370 | assert graph.data["e"] == 5 371 | 372 | 373 | def test_schema(): 374 | from jsonschema import ValidationError 375 | 376 | schema = { 377 | "type": "object", 378 | "properties": {"a": {"type": "number"}, "b": {"type": "number"}}, 379 | } 380 | 381 | graph = Graph(schema=schema) 382 | 383 | @graph.register(inputs=["a", "b"], outputs=["c"]) 384 | def f_my_function(a, b): 385 | return a + b 386 | 387 | with pytest.raises(ValidationError) as err: 388 | graph.calculate(data={"a": 1, "b": "2"}) 389 | 390 | msg = "'2' is not of type 'number'" 391 | assert msg in str(err.value) 392 | 393 | res = graph.calculate(data={"a": 1, "b": 2}) 394 | assert res == 3 395 | 396 | 397 | def test_optional_kwargs(): 398 | graph = Graph() 399 | 400 | @graph.register(inputs=["a"], kwargs=["b"], outputs=["c"]) 401 | def f(a, b=2): 402 | return a + b 403 | 404 | res = graph.calculate(data={"a": 1}) 405 | 406 | assert res == 3 407 | assert graph.data["c"] == 3 408 | 409 | 410 | def test_no_explicit_inputs_outputs_simple(): 411 | graph = Graph() 412 | 413 | @graph.register() 414 | def f(a, b): 415 | c = a + b 416 | return c 417 | 418 | res = graph.calculate(data={"a": 1, "b": 2}) 419 | 420 | assert res == 3 421 | assert graph.data["c"] == 3 422 | 423 | 424 | def test_no_explicit_inputs_outputs_tuple(): 425 | graph = Graph() 426 | 427 | @graph.register() 428 | def f(a, b, c, d): 429 | e = a + b 430 | f = c - d 431 | return e, f 432 | 433 | res = graph.calculate(data={"a": 1, "b": 2, "c": 3, "d": 4}) 434 | 435 | assert res == (3, -1) 436 | assert graph.data["e"] == 3 437 | assert graph.data["f"] == -1 438 | 439 | 440 | def test_no_explicit_inputs_outputs_bad_return(): 441 | graph = Graph() 442 | 443 | with pytest.raises(PyungoError) as err: 444 | 445 | @graph.register() 446 | def f(a, b): 447 | return a + b 448 | 449 | expected = "Variable name or Tuple of variable " "names are expected, got BinOp" 450 | assert str(err.value) == expected 451 | 452 | 453 | def test_no_deepcopy_doesnt_copy(): 454 | graph = Graph(do_deepcopy=False) 455 | 456 | @graph.register() 457 | def f(c, e): 458 | c["a"] += 1 459 | f = c["a"] + e 460 | return f 461 | 462 | d = {"a": 1} 463 | res = graph.calculate(data={"c": d, "e": 2}) 464 | assert res == 4 465 | res = graph.calculate(data={"c": d, "e": 2}) 466 | assert res == 5 467 | 468 | 469 | def test_no_side_effects_if_deepcopy_enabled(): 470 | graph = Graph(do_deepcopy=True) 471 | 472 | @graph.register() 473 | def f(c, e): 474 | c["a"] += 1 475 | f = c["a"] + e 476 | return f 477 | 478 | d = {"a": 1} 479 | res = graph.calculate(data={"c": d, "e": 2}) 480 | assert res == 4 481 | res = graph.calculate(data={"c": d, "e": 2}) 482 | assert res == 4 483 | 484 | 485 | def test_no_side_effects_if_deepcopy_is_left_at_default(): 486 | graph = Graph() 487 | 488 | @graph.register() 489 | def f(c, e): 490 | c["a"] += 1 491 | f = c["a"] + e 492 | return f 493 | 494 | d = {"a": 1} 495 | res = graph.calculate(data={"c": d, "e": 2}) 496 | assert res == 4 497 | res = graph.calculate(data={"c": d, "e": 2}) 498 | assert res == 4 499 | -------------------------------------------------------------------------------- /docs/_static/basic.css: -------------------------------------------------------------------------------- 1 | /* 2 | * basic.css 3 | * ~~~~~~~~~ 4 | * 5 | * Sphinx stylesheet -- basic theme. 6 | * 7 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | 12 | /* -- main layout ----------------------------------------------------------- */ 13 | 14 | div.clearer { 15 | clear: both; 16 | } 17 | 18 | /* -- relbar ---------------------------------------------------------------- */ 19 | 20 | div.related { 21 | width: 100%; 22 | font-size: 90%; 23 | } 24 | 25 | div.related h3 { 26 | display: none; 27 | } 28 | 29 | div.related ul { 30 | margin: 0; 31 | padding: 0 0 0 10px; 32 | list-style: none; 33 | } 34 | 35 | div.related li { 36 | display: inline; 37 | } 38 | 39 | div.related li.right { 40 | float: right; 41 | margin-right: 5px; 42 | } 43 | 44 | /* -- sidebar --------------------------------------------------------------- */ 45 | 46 | div.sphinxsidebarwrapper { 47 | padding: 10px 5px 0 10px; 48 | } 49 | 50 | div.sphinxsidebar { 51 | float: left; 52 | width: 230px; 53 | margin-left: -100%; 54 | font-size: 90%; 55 | word-wrap: break-word; 56 | overflow-wrap : break-word; 57 | } 58 | 59 | div.sphinxsidebar ul { 60 | list-style: none; 61 | } 62 | 63 | div.sphinxsidebar ul ul, 64 | div.sphinxsidebar ul.want-points { 65 | margin-left: 20px; 66 | list-style: square; 67 | } 68 | 69 | div.sphinxsidebar ul ul { 70 | margin-top: 0; 71 | margin-bottom: 0; 72 | } 73 | 74 | div.sphinxsidebar form { 75 | margin-top: 10px; 76 | } 77 | 78 | div.sphinxsidebar input { 79 | border: 1px solid #98dbcc; 80 | font-family: sans-serif; 81 | font-size: 1em; 82 | } 83 | 84 | div.sphinxsidebar #searchbox form.search { 85 | overflow: hidden; 86 | } 87 | 88 | div.sphinxsidebar #searchbox input[type="text"] { 89 | float: left; 90 | width: 80%; 91 | padding: 0.25em; 92 | box-sizing: border-box; 93 | } 94 | 95 | div.sphinxsidebar #searchbox input[type="submit"] { 96 | float: left; 97 | width: 20%; 98 | border-left: none; 99 | padding: 0.25em; 100 | box-sizing: border-box; 101 | } 102 | 103 | 104 | img { 105 | border: 0; 106 | max-width: 100%; 107 | } 108 | 109 | /* -- search page ----------------------------------------------------------- */ 110 | 111 | ul.search { 112 | margin: 10px 0 0 20px; 113 | padding: 0; 114 | } 115 | 116 | ul.search li { 117 | padding: 5px 0 5px 20px; 118 | background-image: url(file.png); 119 | background-repeat: no-repeat; 120 | background-position: 0 7px; 121 | } 122 | 123 | ul.search li a { 124 | font-weight: bold; 125 | } 126 | 127 | ul.search li div.context { 128 | color: #888; 129 | margin: 2px 0 0 30px; 130 | text-align: left; 131 | } 132 | 133 | ul.keywordmatches li.goodmatch a { 134 | font-weight: bold; 135 | } 136 | 137 | /* -- index page ------------------------------------------------------------ */ 138 | 139 | table.contentstable { 140 | width: 90%; 141 | margin-left: auto; 142 | margin-right: auto; 143 | } 144 | 145 | table.contentstable p.biglink { 146 | line-height: 150%; 147 | } 148 | 149 | a.biglink { 150 | font-size: 1.3em; 151 | } 152 | 153 | span.linkdescr { 154 | font-style: italic; 155 | padding-top: 5px; 156 | font-size: 90%; 157 | } 158 | 159 | /* -- general index --------------------------------------------------------- */ 160 | 161 | table.indextable { 162 | width: 100%; 163 | } 164 | 165 | table.indextable td { 166 | text-align: left; 167 | vertical-align: top; 168 | } 169 | 170 | table.indextable ul { 171 | margin-top: 0; 172 | margin-bottom: 0; 173 | list-style-type: none; 174 | } 175 | 176 | table.indextable > tbody > tr > td > ul { 177 | padding-left: 0em; 178 | } 179 | 180 | table.indextable tr.pcap { 181 | height: 10px; 182 | } 183 | 184 | table.indextable tr.cap { 185 | margin-top: 10px; 186 | background-color: #f2f2f2; 187 | } 188 | 189 | img.toggler { 190 | margin-right: 3px; 191 | margin-top: 3px; 192 | cursor: pointer; 193 | } 194 | 195 | div.modindex-jumpbox { 196 | border-top: 1px solid #ddd; 197 | border-bottom: 1px solid #ddd; 198 | margin: 1em 0 1em 0; 199 | padding: 0.4em; 200 | } 201 | 202 | div.genindex-jumpbox { 203 | border-top: 1px solid #ddd; 204 | border-bottom: 1px solid #ddd; 205 | margin: 1em 0 1em 0; 206 | padding: 0.4em; 207 | } 208 | 209 | /* -- domain module index --------------------------------------------------- */ 210 | 211 | table.modindextable td { 212 | padding: 2px; 213 | border-collapse: collapse; 214 | } 215 | 216 | /* -- general body styles --------------------------------------------------- */ 217 | 218 | div.body { 219 | min-width: 450px; 220 | max-width: 800px; 221 | } 222 | 223 | div.body p, div.body dd, div.body li, div.body blockquote { 224 | -moz-hyphens: auto; 225 | -ms-hyphens: auto; 226 | -webkit-hyphens: auto; 227 | hyphens: auto; 228 | } 229 | 230 | a.headerlink { 231 | visibility: hidden; 232 | } 233 | 234 | h1:hover > a.headerlink, 235 | h2:hover > a.headerlink, 236 | h3:hover > a.headerlink, 237 | h4:hover > a.headerlink, 238 | h5:hover > a.headerlink, 239 | h6:hover > a.headerlink, 240 | dt:hover > a.headerlink, 241 | caption:hover > a.headerlink, 242 | p.caption:hover > a.headerlink, 243 | div.code-block-caption:hover > a.headerlink { 244 | visibility: visible; 245 | } 246 | 247 | div.body p.caption { 248 | text-align: inherit; 249 | } 250 | 251 | div.body td { 252 | text-align: left; 253 | } 254 | 255 | .first { 256 | margin-top: 0 !important; 257 | } 258 | 259 | p.rubric { 260 | margin-top: 30px; 261 | font-weight: bold; 262 | } 263 | 264 | img.align-left, .figure.align-left, object.align-left { 265 | clear: left; 266 | float: left; 267 | margin-right: 1em; 268 | } 269 | 270 | img.align-right, .figure.align-right, object.align-right { 271 | clear: right; 272 | float: right; 273 | margin-left: 1em; 274 | } 275 | 276 | img.align-center, .figure.align-center, object.align-center { 277 | display: block; 278 | margin-left: auto; 279 | margin-right: auto; 280 | } 281 | 282 | .align-left { 283 | text-align: left; 284 | } 285 | 286 | .align-center { 287 | text-align: center; 288 | } 289 | 290 | .align-right { 291 | text-align: right; 292 | } 293 | 294 | /* -- sidebars -------------------------------------------------------------- */ 295 | 296 | div.sidebar { 297 | margin: 0 0 0.5em 1em; 298 | border: 1px solid #ddb; 299 | padding: 7px 7px 0 7px; 300 | background-color: #ffe; 301 | width: 40%; 302 | float: right; 303 | } 304 | 305 | p.sidebar-title { 306 | font-weight: bold; 307 | } 308 | 309 | /* -- topics ---------------------------------------------------------------- */ 310 | 311 | div.topic { 312 | border: 1px solid #ccc; 313 | padding: 7px 7px 0 7px; 314 | margin: 10px 0 10px 0; 315 | } 316 | 317 | p.topic-title { 318 | font-size: 1.1em; 319 | font-weight: bold; 320 | margin-top: 10px; 321 | } 322 | 323 | /* -- admonitions ----------------------------------------------------------- */ 324 | 325 | div.admonition { 326 | margin-top: 10px; 327 | margin-bottom: 10px; 328 | padding: 7px; 329 | } 330 | 331 | div.admonition dt { 332 | font-weight: bold; 333 | } 334 | 335 | div.admonition dl { 336 | margin-bottom: 0; 337 | } 338 | 339 | p.admonition-title { 340 | margin: 0px 10px 5px 0px; 341 | font-weight: bold; 342 | } 343 | 344 | div.body p.centered { 345 | text-align: center; 346 | margin-top: 25px; 347 | } 348 | 349 | /* -- tables ---------------------------------------------------------------- */ 350 | 351 | table.docutils { 352 | border: 0; 353 | border-collapse: collapse; 354 | } 355 | 356 | table.align-center { 357 | margin-left: auto; 358 | margin-right: auto; 359 | } 360 | 361 | table caption span.caption-number { 362 | font-style: italic; 363 | } 364 | 365 | table caption span.caption-text { 366 | } 367 | 368 | table.docutils td, table.docutils th { 369 | padding: 1px 8px 1px 5px; 370 | border-top: 0; 371 | border-left: 0; 372 | border-right: 0; 373 | border-bottom: 1px solid #aaa; 374 | } 375 | 376 | table.footnote td, table.footnote th { 377 | border: 0 !important; 378 | } 379 | 380 | th { 381 | text-align: left; 382 | padding-right: 5px; 383 | } 384 | 385 | table.citation { 386 | border-left: solid 1px gray; 387 | margin-left: 1px; 388 | } 389 | 390 | table.citation td { 391 | border-bottom: none; 392 | } 393 | 394 | /* -- figures --------------------------------------------------------------- */ 395 | 396 | div.figure { 397 | margin: 0.5em; 398 | padding: 0.5em; 399 | } 400 | 401 | div.figure p.caption { 402 | padding: 0.3em; 403 | } 404 | 405 | div.figure p.caption span.caption-number { 406 | font-style: italic; 407 | } 408 | 409 | div.figure p.caption span.caption-text { 410 | } 411 | 412 | /* -- field list styles ----------------------------------------------------- */ 413 | 414 | table.field-list td, table.field-list th { 415 | border: 0 !important; 416 | } 417 | 418 | .field-list ul { 419 | margin: 0; 420 | padding-left: 1em; 421 | } 422 | 423 | .field-list p { 424 | margin: 0; 425 | } 426 | 427 | .field-name { 428 | -moz-hyphens: manual; 429 | -ms-hyphens: manual; 430 | -webkit-hyphens: manual; 431 | hyphens: manual; 432 | } 433 | 434 | /* -- hlist styles ---------------------------------------------------------- */ 435 | 436 | table.hlist td { 437 | vertical-align: top; 438 | } 439 | 440 | 441 | /* -- other body styles ----------------------------------------------------- */ 442 | 443 | ol.arabic { 444 | list-style: decimal; 445 | } 446 | 447 | ol.loweralpha { 448 | list-style: lower-alpha; 449 | } 450 | 451 | ol.upperalpha { 452 | list-style: upper-alpha; 453 | } 454 | 455 | ol.lowerroman { 456 | list-style: lower-roman; 457 | } 458 | 459 | ol.upperroman { 460 | list-style: upper-roman; 461 | } 462 | 463 | dl { 464 | margin-bottom: 15px; 465 | } 466 | 467 | dd p { 468 | margin-top: 0px; 469 | } 470 | 471 | dd ul, dd table { 472 | margin-bottom: 10px; 473 | } 474 | 475 | dd { 476 | margin-top: 3px; 477 | margin-bottom: 10px; 478 | margin-left: 30px; 479 | } 480 | 481 | dt:target, span.highlighted { 482 | background-color: #fbe54e; 483 | } 484 | 485 | rect.highlighted { 486 | fill: #fbe54e; 487 | } 488 | 489 | dl.glossary dt { 490 | font-weight: bold; 491 | font-size: 1.1em; 492 | } 493 | 494 | .optional { 495 | font-size: 1.3em; 496 | } 497 | 498 | .sig-paren { 499 | font-size: larger; 500 | } 501 | 502 | .versionmodified { 503 | font-style: italic; 504 | } 505 | 506 | .system-message { 507 | background-color: #fda; 508 | padding: 5px; 509 | border: 3px solid red; 510 | } 511 | 512 | .footnote:target { 513 | background-color: #ffa; 514 | } 515 | 516 | .line-block { 517 | display: block; 518 | margin-top: 1em; 519 | margin-bottom: 1em; 520 | } 521 | 522 | .line-block .line-block { 523 | margin-top: 0; 524 | margin-bottom: 0; 525 | margin-left: 1.5em; 526 | } 527 | 528 | .guilabel, .menuselection { 529 | font-family: sans-serif; 530 | } 531 | 532 | .accelerator { 533 | text-decoration: underline; 534 | } 535 | 536 | .classifier { 537 | font-style: oblique; 538 | } 539 | 540 | abbr, acronym { 541 | border-bottom: dotted 1px; 542 | cursor: help; 543 | } 544 | 545 | /* -- code displays --------------------------------------------------------- */ 546 | 547 | pre { 548 | overflow: auto; 549 | overflow-y: hidden; /* fixes display issues on Chrome browsers */ 550 | } 551 | 552 | span.pre { 553 | -moz-hyphens: none; 554 | -ms-hyphens: none; 555 | -webkit-hyphens: none; 556 | hyphens: none; 557 | } 558 | 559 | td.linenos pre { 560 | padding: 5px 0px; 561 | border: 0; 562 | background-color: transparent; 563 | color: #aaa; 564 | } 565 | 566 | table.highlighttable { 567 | margin-left: 0.5em; 568 | } 569 | 570 | table.highlighttable td { 571 | padding: 0 0.5em 0 0.5em; 572 | } 573 | 574 | div.code-block-caption { 575 | padding: 2px 5px; 576 | font-size: small; 577 | } 578 | 579 | div.code-block-caption code { 580 | background-color: transparent; 581 | } 582 | 583 | div.code-block-caption + div > div.highlight > pre { 584 | margin-top: 0; 585 | } 586 | 587 | div.code-block-caption span.caption-number { 588 | padding: 0.1em 0.3em; 589 | font-style: italic; 590 | } 591 | 592 | div.code-block-caption span.caption-text { 593 | } 594 | 595 | div.literal-block-wrapper { 596 | padding: 1em 1em 0; 597 | } 598 | 599 | div.literal-block-wrapper div.highlight { 600 | margin: 0; 601 | } 602 | 603 | code.descname { 604 | background-color: transparent; 605 | font-weight: bold; 606 | font-size: 1.2em; 607 | } 608 | 609 | code.descclassname { 610 | background-color: transparent; 611 | } 612 | 613 | code.xref, a code { 614 | background-color: transparent; 615 | font-weight: bold; 616 | } 617 | 618 | h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { 619 | background-color: transparent; 620 | } 621 | 622 | .viewcode-link { 623 | float: right; 624 | } 625 | 626 | .viewcode-back { 627 | float: right; 628 | font-family: sans-serif; 629 | } 630 | 631 | div.viewcode-block:target { 632 | margin: -1px -10px; 633 | padding: 0 10px; 634 | } 635 | 636 | /* -- math display ---------------------------------------------------------- */ 637 | 638 | img.math { 639 | vertical-align: middle; 640 | } 641 | 642 | div.body div.math p { 643 | text-align: center; 644 | } 645 | 646 | span.eqno { 647 | float: right; 648 | } 649 | 650 | span.eqno a.headerlink { 651 | position: relative; 652 | left: 0px; 653 | z-index: 1; 654 | } 655 | 656 | div.math:hover a.headerlink { 657 | visibility: visible; 658 | } 659 | 660 | /* -- printout stylesheet --------------------------------------------------- */ 661 | 662 | @media print { 663 | div.document, 664 | div.documentwrapper, 665 | div.bodywrapper { 666 | margin: 0 !important; 667 | width: 100%; 668 | } 669 | 670 | div.sphinxsidebar, 671 | div.related, 672 | div.footer, 673 | #top-link { 674 | display: none; 675 | } 676 | } -------------------------------------------------------------------------------- /docs/_static/alabaster.css: -------------------------------------------------------------------------------- 1 | @import url("basic.css"); 2 | 3 | /* -- page layout ----------------------------------------------------------- */ 4 | 5 | body { 6 | font-family: Georgia, serif; 7 | font-size: 17px; 8 | background-color: #fff; 9 | color: #000; 10 | margin: 0; 11 | padding: 0; 12 | } 13 | 14 | 15 | div.document { 16 | width: 940px; 17 | margin: 30px auto 0 auto; 18 | } 19 | 20 | div.documentwrapper { 21 | float: left; 22 | width: 100%; 23 | } 24 | 25 | div.bodywrapper { 26 | margin: 0 0 0 220px; 27 | } 28 | 29 | div.sphinxsidebar { 30 | width: 220px; 31 | font-size: 14px; 32 | line-height: 1.5; 33 | } 34 | 35 | hr { 36 | border: 1px solid #B1B4B6; 37 | } 38 | 39 | div.body { 40 | background-color: #fff; 41 | color: #3E4349; 42 | padding: 0 30px 0 30px; 43 | } 44 | 45 | div.body > .section { 46 | text-align: left; 47 | } 48 | 49 | div.footer { 50 | width: 940px; 51 | margin: 20px auto 30px auto; 52 | font-size: 14px; 53 | color: #888; 54 | text-align: right; 55 | } 56 | 57 | div.footer a { 58 | color: #888; 59 | } 60 | 61 | p.caption { 62 | font-family: inherit; 63 | font-size: inherit; 64 | } 65 | 66 | 67 | div.relations { 68 | display: none; 69 | } 70 | 71 | 72 | div.sphinxsidebar a { 73 | color: #444; 74 | text-decoration: none; 75 | border-bottom: 1px dotted #999; 76 | } 77 | 78 | div.sphinxsidebar a:hover { 79 | border-bottom: 1px solid #999; 80 | } 81 | 82 | div.sphinxsidebarwrapper { 83 | padding: 18px 10px; 84 | } 85 | 86 | div.sphinxsidebarwrapper p.logo { 87 | padding: 0; 88 | margin: -10px 0 0 0px; 89 | text-align: center; 90 | } 91 | 92 | div.sphinxsidebarwrapper h1.logo { 93 | margin-top: -10px; 94 | text-align: center; 95 | margin-bottom: 5px; 96 | text-align: left; 97 | } 98 | 99 | div.sphinxsidebarwrapper h1.logo-name { 100 | margin-top: 0px; 101 | } 102 | 103 | div.sphinxsidebarwrapper p.blurb { 104 | margin-top: 0; 105 | font-style: normal; 106 | } 107 | 108 | div.sphinxsidebar h3, 109 | div.sphinxsidebar h4 { 110 | font-family: Georgia, serif; 111 | color: #444; 112 | font-size: 24px; 113 | font-weight: normal; 114 | margin: 0 0 5px 0; 115 | padding: 0; 116 | } 117 | 118 | div.sphinxsidebar h4 { 119 | font-size: 20px; 120 | } 121 | 122 | div.sphinxsidebar h3 a { 123 | color: #444; 124 | } 125 | 126 | div.sphinxsidebar p.logo a, 127 | div.sphinxsidebar h3 a, 128 | div.sphinxsidebar p.logo a:hover, 129 | div.sphinxsidebar h3 a:hover { 130 | border: none; 131 | } 132 | 133 | div.sphinxsidebar p { 134 | color: #555; 135 | margin: 10px 0; 136 | } 137 | 138 | div.sphinxsidebar ul { 139 | margin: 10px 0; 140 | padding: 0; 141 | color: #000; 142 | } 143 | 144 | div.sphinxsidebar ul li.toctree-l1 > a { 145 | font-size: 120%; 146 | } 147 | 148 | div.sphinxsidebar ul li.toctree-l2 > a { 149 | font-size: 110%; 150 | } 151 | 152 | div.sphinxsidebar input { 153 | border: 1px solid #CCC; 154 | font-family: Georgia, serif; 155 | font-size: 1em; 156 | } 157 | 158 | div.sphinxsidebar hr { 159 | border: none; 160 | height: 1px; 161 | color: #AAA; 162 | background: #AAA; 163 | 164 | text-align: left; 165 | margin-left: 0; 166 | width: 50%; 167 | } 168 | 169 | div.sphinxsidebar .badge { 170 | border-bottom: none; 171 | } 172 | 173 | div.sphinxsidebar .badge:hover { 174 | border-bottom: none; 175 | } 176 | 177 | /* To address an issue with donation coming after search */ 178 | div.sphinxsidebar h3.donation { 179 | margin-top: 10px; 180 | } 181 | 182 | /* -- body styles ----------------------------------------------------------- */ 183 | 184 | a { 185 | color: #004B6B; 186 | text-decoration: underline; 187 | } 188 | 189 | a:hover { 190 | color: #6D4100; 191 | text-decoration: underline; 192 | } 193 | 194 | div.body h1, 195 | div.body h2, 196 | div.body h3, 197 | div.body h4, 198 | div.body h5, 199 | div.body h6 { 200 | font-family: Georgia, serif; 201 | font-weight: normal; 202 | margin: 30px 0px 10px 0px; 203 | padding: 0; 204 | } 205 | 206 | div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } 207 | div.body h2 { font-size: 180%; } 208 | div.body h3 { font-size: 150%; } 209 | div.body h4 { font-size: 130%; } 210 | div.body h5 { font-size: 100%; } 211 | div.body h6 { font-size: 100%; } 212 | 213 | a.headerlink { 214 | color: #DDD; 215 | padding: 0 4px; 216 | text-decoration: none; 217 | } 218 | 219 | a.headerlink:hover { 220 | color: #444; 221 | background: #EAEAEA; 222 | } 223 | 224 | div.body p, div.body dd, div.body li { 225 | line-height: 1.4em; 226 | } 227 | 228 | div.admonition { 229 | margin: 20px 0px; 230 | padding: 10px 30px; 231 | background-color: #EEE; 232 | border: 1px solid #CCC; 233 | } 234 | 235 | div.admonition tt.xref, div.admonition code.xref, div.admonition a tt { 236 | background-color: #FBFBFB; 237 | border-bottom: 1px solid #fafafa; 238 | } 239 | 240 | div.admonition p.admonition-title { 241 | font-family: Georgia, serif; 242 | font-weight: normal; 243 | font-size: 24px; 244 | margin: 0 0 10px 0; 245 | padding: 0; 246 | line-height: 1; 247 | } 248 | 249 | div.admonition p.last { 250 | margin-bottom: 0; 251 | } 252 | 253 | div.highlight { 254 | background-color: #fff; 255 | } 256 | 257 | dt:target, .highlight { 258 | background: #FAF3E8; 259 | } 260 | 261 | div.warning { 262 | background-color: #FCC; 263 | border: 1px solid #FAA; 264 | } 265 | 266 | div.danger { 267 | background-color: #FCC; 268 | border: 1px solid #FAA; 269 | -moz-box-shadow: 2px 2px 4px #D52C2C; 270 | -webkit-box-shadow: 2px 2px 4px #D52C2C; 271 | box-shadow: 2px 2px 4px #D52C2C; 272 | } 273 | 274 | div.error { 275 | background-color: #FCC; 276 | border: 1px solid #FAA; 277 | -moz-box-shadow: 2px 2px 4px #D52C2C; 278 | -webkit-box-shadow: 2px 2px 4px #D52C2C; 279 | box-shadow: 2px 2px 4px #D52C2C; 280 | } 281 | 282 | div.caution { 283 | background-color: #FCC; 284 | border: 1px solid #FAA; 285 | } 286 | 287 | div.attention { 288 | background-color: #FCC; 289 | border: 1px solid #FAA; 290 | } 291 | 292 | div.important { 293 | background-color: #EEE; 294 | border: 1px solid #CCC; 295 | } 296 | 297 | div.note { 298 | background-color: #EEE; 299 | border: 1px solid #CCC; 300 | } 301 | 302 | div.tip { 303 | background-color: #EEE; 304 | border: 1px solid #CCC; 305 | } 306 | 307 | div.hint { 308 | background-color: #EEE; 309 | border: 1px solid #CCC; 310 | } 311 | 312 | div.seealso { 313 | background-color: #EEE; 314 | border: 1px solid #CCC; 315 | } 316 | 317 | div.topic { 318 | background-color: #EEE; 319 | } 320 | 321 | p.admonition-title { 322 | display: inline; 323 | } 324 | 325 | p.admonition-title:after { 326 | content: ":"; 327 | } 328 | 329 | pre, tt, code { 330 | font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; 331 | font-size: 0.9em; 332 | } 333 | 334 | .hll { 335 | background-color: #FFC; 336 | margin: 0 -12px; 337 | padding: 0 12px; 338 | display: block; 339 | } 340 | 341 | img.screenshot { 342 | } 343 | 344 | tt.descname, tt.descclassname, code.descname, code.descclassname { 345 | font-size: 0.95em; 346 | } 347 | 348 | tt.descname, code.descname { 349 | padding-right: 0.08em; 350 | } 351 | 352 | img.screenshot { 353 | -moz-box-shadow: 2px 2px 4px #EEE; 354 | -webkit-box-shadow: 2px 2px 4px #EEE; 355 | box-shadow: 2px 2px 4px #EEE; 356 | } 357 | 358 | table.docutils { 359 | border: 1px solid #888; 360 | -moz-box-shadow: 2px 2px 4px #EEE; 361 | -webkit-box-shadow: 2px 2px 4px #EEE; 362 | box-shadow: 2px 2px 4px #EEE; 363 | } 364 | 365 | table.docutils td, table.docutils th { 366 | border: 1px solid #888; 367 | padding: 0.25em 0.7em; 368 | } 369 | 370 | table.field-list, table.footnote { 371 | border: none; 372 | -moz-box-shadow: none; 373 | -webkit-box-shadow: none; 374 | box-shadow: none; 375 | } 376 | 377 | table.footnote { 378 | margin: 15px 0; 379 | width: 100%; 380 | border: 1px solid #EEE; 381 | background: #FDFDFD; 382 | font-size: 0.9em; 383 | } 384 | 385 | table.footnote + table.footnote { 386 | margin-top: -15px; 387 | border-top: none; 388 | } 389 | 390 | table.field-list th { 391 | padding: 0 0.8em 0 0; 392 | } 393 | 394 | table.field-list td { 395 | padding: 0; 396 | } 397 | 398 | table.field-list p { 399 | margin-bottom: 0.8em; 400 | } 401 | 402 | /* Cloned from 403 | * https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68 404 | */ 405 | .field-name { 406 | -moz-hyphens: manual; 407 | -ms-hyphens: manual; 408 | -webkit-hyphens: manual; 409 | hyphens: manual; 410 | } 411 | 412 | table.footnote td.label { 413 | width: .1px; 414 | padding: 0.3em 0 0.3em 0.5em; 415 | } 416 | 417 | table.footnote td { 418 | padding: 0.3em 0.5em; 419 | } 420 | 421 | dl { 422 | margin: 0; 423 | padding: 0; 424 | } 425 | 426 | dl dd { 427 | margin-left: 30px; 428 | } 429 | 430 | blockquote { 431 | margin: 0 0 0 30px; 432 | padding: 0; 433 | } 434 | 435 | ul, ol { 436 | /* Matches the 30px from the narrow-screen "li > ul" selector below */ 437 | margin: 10px 0 10px 30px; 438 | padding: 0; 439 | } 440 | 441 | pre { 442 | background: #EEE; 443 | padding: 7px 30px; 444 | margin: 15px 0px; 445 | line-height: 1.3em; 446 | } 447 | 448 | div.viewcode-block:target { 449 | background: #ffd; 450 | } 451 | 452 | dl pre, blockquote pre, li pre { 453 | margin-left: 0; 454 | padding-left: 30px; 455 | } 456 | 457 | tt, code { 458 | background-color: #ecf0f3; 459 | color: #222; 460 | /* padding: 1px 2px; */ 461 | } 462 | 463 | tt.xref, code.xref, a tt { 464 | background-color: #FBFBFB; 465 | border-bottom: 1px solid #fff; 466 | } 467 | 468 | a.reference { 469 | text-decoration: none; 470 | border-bottom: 1px dotted #004B6B; 471 | } 472 | 473 | /* Don't put an underline on images */ 474 | a.image-reference, a.image-reference:hover { 475 | border-bottom: none; 476 | } 477 | 478 | a.reference:hover { 479 | border-bottom: 1px solid #6D4100; 480 | } 481 | 482 | a.footnote-reference { 483 | text-decoration: none; 484 | font-size: 0.7em; 485 | vertical-align: top; 486 | border-bottom: 1px dotted #004B6B; 487 | } 488 | 489 | a.footnote-reference:hover { 490 | border-bottom: 1px solid #6D4100; 491 | } 492 | 493 | a:hover tt, a:hover code { 494 | background: #EEE; 495 | } 496 | 497 | 498 | @media screen and (max-width: 870px) { 499 | 500 | div.sphinxsidebar { 501 | display: none; 502 | } 503 | 504 | div.document { 505 | width: 100%; 506 | 507 | } 508 | 509 | div.documentwrapper { 510 | margin-left: 0; 511 | margin-top: 0; 512 | margin-right: 0; 513 | margin-bottom: 0; 514 | } 515 | 516 | div.bodywrapper { 517 | margin-top: 0; 518 | margin-right: 0; 519 | margin-bottom: 0; 520 | margin-left: 0; 521 | } 522 | 523 | ul { 524 | margin-left: 0; 525 | } 526 | 527 | li > ul { 528 | /* Matches the 30px from the "ul, ol" selector above */ 529 | margin-left: 30px; 530 | } 531 | 532 | .document { 533 | width: auto; 534 | } 535 | 536 | .footer { 537 | width: auto; 538 | } 539 | 540 | .bodywrapper { 541 | margin: 0; 542 | } 543 | 544 | .footer { 545 | width: auto; 546 | } 547 | 548 | .github { 549 | display: none; 550 | } 551 | 552 | 553 | 554 | } 555 | 556 | 557 | 558 | @media screen and (max-width: 875px) { 559 | 560 | body { 561 | margin: 0; 562 | padding: 20px 30px; 563 | } 564 | 565 | div.documentwrapper { 566 | float: none; 567 | background: #fff; 568 | } 569 | 570 | div.sphinxsidebar { 571 | display: block; 572 | float: none; 573 | width: 102.5%; 574 | margin: -20px -30px 20px -30px; 575 | padding: 10px 20px; 576 | background: #333; 577 | color: #FFF; 578 | } 579 | 580 | div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, 581 | div.sphinxsidebar h3 a { 582 | color: #fff; 583 | } 584 | 585 | div.sphinxsidebar a { 586 | color: #AAA; 587 | } 588 | 589 | div.sphinxsidebar p.logo { 590 | display: none; 591 | } 592 | 593 | div.document { 594 | width: 100%; 595 | margin: 0; 596 | } 597 | 598 | div.footer { 599 | display: none; 600 | } 601 | 602 | div.bodywrapper { 603 | margin: 0; 604 | } 605 | 606 | div.body { 607 | min-height: 0; 608 | padding: 0; 609 | } 610 | 611 | .rtd_doc_footer { 612 | display: none; 613 | } 614 | 615 | .document { 616 | width: auto; 617 | } 618 | 619 | .footer { 620 | width: auto; 621 | } 622 | 623 | .footer { 624 | width: auto; 625 | } 626 | 627 | .github { 628 | display: none; 629 | } 630 | } 631 | @media screen and (min-width: 876px) { 632 | div.sphinxsidebar { 633 | position: fixed; 634 | margin-left: 0; 635 | } 636 | } 637 | 638 | 639 | /* misc. */ 640 | 641 | .revsys-inline { 642 | display: none!important; 643 | } 644 | 645 | /* Make nested-list/multi-paragraph items look better in Releases changelog 646 | * pages. Without this, docutils' magical list fuckery causes inconsistent 647 | * formatting between different release sub-lists. 648 | */ 649 | div#changelog > div.section > ul > li > p:only-child { 650 | margin-bottom: 0; 651 | } 652 | 653 | /* Hide fugly table cell borders in ..bibliography:: directive output */ 654 | table.docutils.citation, table.docutils.citation td, table.docutils.citation th { 655 | border: none; 656 | /* Below needed in some edge cases; if not applied, bottom shadows appear */ 657 | -moz-box-shadow: none; 658 | -webkit-box-shadow: none; 659 | box-shadow: none; 660 | } 661 | 662 | 663 | /* relbar */ 664 | 665 | .related { 666 | line-height: 30px; 667 | width: 100%; 668 | font-size: 0.9rem; 669 | } 670 | 671 | .related.top { 672 | border-bottom: 1px solid #EEE; 673 | margin-bottom: 20px; 674 | } 675 | 676 | .related.bottom { 677 | border-top: 1px solid #EEE; 678 | } 679 | 680 | .related ul { 681 | padding: 0; 682 | margin: 0; 683 | list-style: none; 684 | } 685 | 686 | .related li { 687 | display: inline; 688 | } 689 | 690 | nav#rellinks { 691 | float: right; 692 | } 693 | 694 | nav#rellinks li+li:before { 695 | content: "|"; 696 | } 697 | 698 | nav#breadcrumbs li+li:before { 699 | content: "\00BB"; 700 | } 701 | 702 | /* Hide certain items when printing */ 703 | @media print { 704 | div.related { 705 | display: none; 706 | } 707 | } -------------------------------------------------------------------------------- /docs/source/whatsnew.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | What’s New — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
27 | 28 | 99 |
100 |
101 | 102 | 103 |
104 | 105 |
106 |

What’s New

107 |

These are new features and improvements notes for each release.

108 |
109 |

v0.9.0 (June 13, 2020)

110 |
    111 |

  • Drop support / compatibility for Python 2.7.

    • 112 |

  • inputs / outputs names are now optional.:

    113 | 
    @graph.register()
114 | def f_my_function(a, b):
115 |     c = a + b
116 |     return c
117 |
    118 |
    119 |
    • 120 |

  • Additional argument to Graph to prevent inputs deepcopy (@Tosa95). 121 | This is useful when having large inputs when the deepcopy might be slow, but remove inputs 122 | immutability.

    • 123 |
124 |
125 |
126 |

v0.8.1 (October 27, 2019)

127 |
    128 |

  • Allow optional input data for kwargs (@veronicaguo)

    • 129 |
130 |
131 |
132 |

v0.8.0 (March 17, 2019)

133 |
    134 |

  • Can pass list of Input / Output to Graph.

    • 135 |

  • Names mapping.

    • 136 |

  • Inputs validation with JSON Schema.

    • 137 |

  • Some misc. refactoring and styling.

    • 138 |
139 |
140 |
141 |

v0.7.0 (February 10, 2019)

142 |
    143 |

  • Refactoring, and introduction of Input and Output objects.

    • 144 |

  • Contracts feature.:

    145 | 
    graph.add_node(
146 |     my_function,
147 |     inputs=[Input(name='a', contract='>0'), Input(name='b', contract='float')],
148 |     outputs=[Output(name='g', contract='float')]
149 | )
150 |
    151 |
    152 |
    • 153 |

  • Nodes IDs refactoring (now uses uuid).

    • 154 |

  • Run topological sort only when needed.

    • 155 |

  • Everything accessible from pyungo __init__ (@nelsontodd)

    • 156 |

  • Docstrings / Sphinx doc / GitHub page

    • 157 |
158 |
159 |
160 |

v0.6.0 (July 6, 2018)

161 |
    162 |

  • Fix “false parallelism” implementation. This require an optional dependency (multiprocess 163 | module) which is more friendly to work with stateful objects and multiprocessing.

    • 164 |

  • Ability to pass predefined inputs at the node definition:

    165 | 
    @graph.register(inputs=['a', {'b': 2}], outputs=['c'])
166 | def f_my_function(a, b):
167 |     return a + b
168 |
    169 |
    170 |
    • 171 |
172 |
173 |
174 |

v0.5.0 (April 3, 2018)

175 |
    176 |

  • Nodes can be run in parallel using Python multiprocessing module:

    177 | 
    graph = Graph(parallel=True, pool_size=3)
178 |
    179 |
    180 |
    • 181 |

  • inputs and outputs parameters are mandatory and will raise an explicit error when missing.

    • 182 |

  • Add a longer test using pvlib

    • 183 |
184 |
185 |
186 |

v0.4.0 (March 23, 2018)

187 |
    188 |

  • Fix single output when dealing with iterables. Previously, returning one output 189 | with an iterable was resulting in taking the first element.

    • 190 |

  • Args and kwargs can be used in functions:

    191 | 
    @graph.register(
192 |         inputs=['a', 'b'],
193 |         args=['c'],
194 |         kwargs=['d'],
195 |         outputs=['e']
196 |     )
197 | def f_my_function(a, b, *args, **kwargs):
198 |     return a + b + args[0] + kwargs['d']
199 |
    200 |
    201 |
    • 202 |

  • Can create a Node without using the decorator:

    203 | 
    graph.add_node(f_my_function, inputs=['a', 'b'], outputs=['c'])
204 |
    205 |
    206 |
    • 207 |

  • DAG pretty print (graph.dag)

    • 208 |
209 |
210 |
211 |

v0.3.0 (March 18, 2018)

212 |

First version in pypi

213 |
214 |
215 | 216 | 217 |
218 | 219 |
220 |
221 |
222 |
223 |
224 | ©2019, Cedric Leroy. 225 | 226 | | 227 | Powered by Sphinx 3.1.0 228 | & Alabaster 0.7.12 229 | 230 | | 231 | Page source 233 |
234 | 235 | 236 | 237 | Fork me on GitHub 238 | 239 | 240 | 241 | 242 | 243 | -------------------------------------------------------------------------------- /docs/source/developer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Developer Documentation — pyungo v0.7.0 documentation 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
28 | 29 | 91 |
92 |
93 | 94 | 95 |
96 | 97 |
98 |

Developer Documentation

99 |
100 |
101 | pyungo.core.topological_sort(data)
102 |

Topological sort algorithm

103 |
104 |
Parameters
105 |

data (dict) – dictionnary representing dependencies 106 | Example: {‘a’: [‘b’, ‘c’]} node id ‘a’ depends on 107 | node id ‘b’ and ‘c’

108 |
109 |
Returns
110 |

111 |
list of list of node ids

Example: [[‘a’], [‘b’, ‘c’], [‘d’]] 112 | The sequence is representing the order to be run. 113 | The nested lists are node ids that can be run in parallel

114 |
115 |
116 |

117 |
118 |
Return type
119 |

ordered (list)

120 |
121 |
Raises
122 |

PyungoError – In case a cyclic dependency exists

123 |
124 |
125 |
126 | 127 |
128 |
129 | class pyungo.core.Node(fct, inputs, outputs, args=None, kwargs=None)
130 |

Node object (aka vertex in graph theory)

131 |
132 |
Parameters
133 |
    134 |

  • fct (function) – The Python function attached to the node

    • 135 |

  • inputs (list) – List of inputs (which can be Input, str or dict)

    • 136 |

  • outputs (list) – List of outputs (Output or str)

    • 137 |

  • args (list) – Optional list of args

    • 138 |

  • kwargs (list) – Optional list of kwargs

    • 139 |
140 |
141 |
Raises
142 |

PyungoError – In case inputs have the wrong type

143 |
144 |
145 |
146 | 147 |
148 |
149 | class pyungo.core.Graph(inputs=None, outputs=None, parallel=False, pool_size=2, schema=None)
150 |

Graph object, collection of related nodes

151 |
152 |
Parameters
153 |
    154 |

  • inputs (list) – List of optional Input if defined separately

    • 155 |

  • outputs (list) – List of optional Output if defined separately

    • 156 |

  • parallel (bool) – Parallelism flag

    • 157 |

  • pool_size (int) – Size of the pool in case parallelism is enabled

    • 158 |

  • schema (dict) – Optional JSON schema to validate inputs data

    • 159 |
160 |
161 |
Raises
162 |

ImportError will raise in case parallelism is chosen and multiprocess – not installed

163 |
164 |
165 |
166 |
167 | add_node(function, **kwargs)
168 |

explicit method to add a node to the graph

169 |
170 |
Parameters
171 |
    172 |

  • function (function) – Python function attached to the node

    • 173 |

  • inputs (list) – List of inputs (Input, str, or dict)

    • 174 |

  • outputs (list) – List of outputs (Output or str)

    • 175 |

  • args (list) – List of optional args

    • 176 |

  • kwargs (list) – List of optional kwargs

    • 177 |
178 |
179 |
180 |
181 | 182 |
183 |
184 | calculate(data)
185 |

run graph calculations

186 |
187 | 188 |
189 |
190 | property dag
191 |

return the ordered nodes graph

192 |
193 | 194 |
195 |
196 | property data
197 |

return the data of the graph (inputs + outputs)

198 |
199 | 200 |
201 |
202 | register(**kwargs)
203 |

register decorator

204 |
205 | 206 |
207 |
208 | static run_node(node)
209 |

run the node

210 |
211 |
Parameters
212 |

node (Node) – The node to run

213 |
214 |
Returns
215 |

node id, node output values

216 |
217 |
Return type
218 |

results (tuple)

219 |
220 |
221 |
222 | 223 |
224 |
225 | property sim_inputs
226 |

return input names (mapped) of every nodes

227 |
228 | 229 |
230 |
231 | property sim_kwargs
232 |

return kwarg names (mapped) of every nodes

233 |
234 | 235 |
236 |
237 | property sim_outputs
238 |

return output names (mapped) of every nodes

239 |
240 | 241 |
242 | 243 |
244 |
245 | class pyungo.io.Input(name, map=None, meta=None, contract=None)
246 |

Object representing a function input

247 |
248 |
Parameters
249 |
    250 |

  • name (str) – The variable name of the input / output

    • 251 |

  • map (str) – Optional mapping name. This is the name referenced 252 | in the data inputs / outputs

    • 253 |

  • meta (dict) – Not used yet

    • 254 |

  • contract (str) – Optional contract rule used by pycontracts

    • 255 |
256 |
257 |
258 |
259 | 260 |
261 |
262 | class pyungo.io.Output(name, map=None, meta=None, contract=None)
263 |

Object representing a function output

264 |
265 |
Parameters
266 |
    267 |

  • name (str) – The variable name of the input / output

    • 268 |

  • map (str) – Optional mapping name. This is the name referenced 269 | in the data inputs / outputs

    • 270 |

  • meta (dict) – Not used yet

    • 271 |

  • contract (str) – Optional contract rule used by pycontracts

    • 272 |
273 |
274 |
275 |
276 | 277 |
278 | 279 | 280 |
281 | 282 |
283 |
284 |
285 |
286 |
287 | ©2019, Cedric Leroy. 288 | 289 | | 290 | Powered by Sphinx 3.1.0 291 | & Alabaster 0.7.12 292 | 293 | | 294 | Page source 296 |
297 | 298 | 299 | 300 | Fork me on GitHub 301 | 302 | 303 | 304 | 305 | 306 | -------------------------------------------------------------------------------- /docs/_static/searchtools.js: -------------------------------------------------------------------------------- 1 | /* 2 | * searchtools.js 3 | * ~~~~~~~~~~~~~~~~ 4 | * 5 | * Sphinx JavaScript utilities for the full-text search. 6 | * 7 | * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS. 8 | * :license: BSD, see LICENSE for details. 9 | * 10 | */ 11 | 12 | if (!Scorer) { 13 | /** 14 | * Simple result scoring code. 15 | */ 16 | var Scorer = { 17 | // Implement the following function to further tweak the score for each result 18 | // The function takes a result array [filename, title, anchor, descr, score] 19 | // and returns the new score. 20 | /* 21 | score: function(result) { 22 | return result[4]; 23 | }, 24 | */ 25 | 26 | // query matches the full name of an object 27 | objNameMatch: 11, 28 | // or matches in the last dotted part of the object name 29 | objPartialMatch: 6, 30 | // Additive scores depending on the priority of the object 31 | objPrio: {0: 15, // used to be importantResults 32 | 1: 5, // used to be objectResults 33 | 2: -5}, // used to be unimportantResults 34 | // Used when the priority is not in the mapping. 35 | objPrioDefault: 0, 36 | 37 | // query found in title 38 | title: 15, 39 | // query found in terms 40 | term: 5 41 | }; 42 | } 43 | 44 | if (!splitQuery) { 45 | function splitQuery(query) { 46 | return query.split(/\s+/); 47 | } 48 | } 49 | 50 | /** 51 | * Search Module 52 | */ 53 | var Search = { 54 | 55 | _index : null, 56 | _queued_query : null, 57 | _pulse_status : -1, 58 | 59 | init : function() { 60 | var params = $.getQueryParameters(); 61 | if (params.q) { 62 | var query = params.q[0]; 63 | $('input[name="q"]')[0].value = query; 64 | this.performSearch(query); 65 | } 66 | }, 67 | 68 | loadIndex : function(url) { 69 | $.ajax({type: "GET", url: url, data: null, 70 | dataType: "script", cache: true, 71 | complete: function(jqxhr, textstatus) { 72 | if (textstatus != "success") { 73 | document.getElementById("searchindexloader").src = url; 74 | } 75 | }}); 76 | }, 77 | 78 | setIndex : function(index) { 79 | var q; 80 | this._index = index; 81 | if ((q = this._queued_query) !== null) { 82 | this._queued_query = null; 83 | Search.query(q); 84 | } 85 | }, 86 | 87 | hasIndex : function() { 88 | return this._index !== null; 89 | }, 90 | 91 | deferQuery : function(query) { 92 | this._queued_query = query; 93 | }, 94 | 95 | stopPulse : function() { 96 | this._pulse_status = 0; 97 | }, 98 | 99 | startPulse : function() { 100 | if (this._pulse_status >= 0) 101 | return; 102 | function pulse() { 103 | var i; 104 | Search._pulse_status = (Search._pulse_status + 1) % 4; 105 | var dotString = ''; 106 | for (i = 0; i < Search._pulse_status; i++) 107 | dotString += '.'; 108 | Search.dots.text(dotString); 109 | if (Search._pulse_status > -1) 110 | window.setTimeout(pulse, 500); 111 | } 112 | pulse(); 113 | }, 114 | 115 | /** 116 | * perform a search for something (or wait until index is loaded) 117 | */ 118 | performSearch : function(query) { 119 | // create the required interface elements 120 | this.out = $('#search-results'); 121 | this.title = $('

' + _('Searching') + '

').appendTo(this.out); 122 | this.dots = $('').appendTo(this.title); 123 | this.status = $('

').appendTo(this.out); 124 | this.output = $('