Merge pull request #29 from alkemics/groupby_pnt

documentation update / flake8 ci fix

.github/CODEOWNERS

@@ -0,0 +1 @@
+*  @alk-lbinet

.github/workflows/python-package.yml → .github/workflows/python-2-tests.yml

@@ -1,7 +1,7 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
-name: Python package
+name: Python 2 Tests
 
 on:
   push:
@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
+        python-version: [2.7]
 
     steps:
     - uses: actions/checkout@v2
@@ -26,14 +26,14 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
+        pip install -r requirements-test-2.txt
         python setup.py develop
     - name: Lint with flake8
       run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        # ignore "line break before binary operator", and "invalid escape sequence '\_'" useful for doc
+        flake8 --count --ignore=W503,W605 --show-source --statistics pandagg
+        # on tests, more laxist: allow "missing whitespace after ','" and "line too long"
+        flake8 --count --ignore=W503,W605,E231,E501 --show-source --statistics tests
     - name: Test with pytest
       run: |
         pytest

.github/workflows/python-3-tests.yml

@@ -0,0 +1,39 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python 3 Tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.5, 3.6, 3.7, 3.8]
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements-test.txt
+        python setup.py develop
+    - name: Lint with flake8
+      run: |
+        # ignore "line break before binary operator", and "invalid escape sequence '\_'" useful for doc
+        flake8 --count --ignore=W503,W605 --show-source --statistics pandagg
+        # on tests, more laxist: allow "missing whitespace after ','" and "line too long"
+        flake8 --count --ignore=W503,W605,E231,E501 --show-source --statistics tests
+    - name: Test with pytest
+      run: |
+        pytest

Makefile

@@ -1,4 +1,4 @@
-.PHONY : develop check clean clean_pyc doc lint-diff black doc-references coverage
+.PHONY : develop check clean clean_pyc doc lint lint-diff black doc-references coverage
 
 clean:
 	-python setup.py clean
@@ -10,6 +10,12 @@ clean_pyc:
 lint-diff:
 	git diff upstream/master --name-only -- "*.py" | xargs flake8
 
+lint:
+	# ignore "line break before binary operator", and "invalid escape sequence '\_'" useful for doc
+	flake8 --count --ignore=W503,W605 --show-source --statistics pandagg
+	# on tests, more laxist: allow "missing whitespace after ','" and "line too long"
+	flake8 --count --ignore=W503,W605,E231,E501 --show-source --statistics tests
+
 black:
 	black examples docs pandagg tests setup.py
 

README.md

@@ -1,3 +1,8 @@
+[![PyPI Latest Release](https://img.shields.io/pypi/v/pandagg.svg)](https://pypi.org/project/pandagg/)
+[![License](https://img.shields.io/pypi/l/pandagg.svg)](https://github.com/alkemics/pandagg/blob/master/LICENSE)
+![Python package](https://github.com/alkemics/pandagg/workflows/Python%20package/badge.svg)
+
+
 ## What is it?
 
 **pandagg** is a Python package providing a simple interface to manipulate ElasticSearch queries and aggregations. Its goal is to make it
@@ -50,7 +55,7 @@ All contributions, bug reports, bug fixes, documentation improvements, enhanceme
 
 ## Roadmap
 
-- implement CI workflow: python2/3 tests, coverage
+- improve CI workflow with coverage report
 - on aggregation `nodes`, ensure all allowed `fields` are listed
 - expand functionalities: proper ORM similar to elasticsearch-dsl Document classes, index managing operations
 - package versions for different ElasticSearch versions

docs/requirements.txt

@@ -1 +1,3 @@
-pandas
+pandas
+sphinx_rtd_theme
+recommonmark

docs/source/user-guide.rst

@@ -124,12 +124,10 @@ In the flattened syntax, the query clause type is used as first argument:
 Query enrichment
 ================
 
-query() method
---------------
+All methods described below return a new :class:`~pandagg.tree.query.abstract.Query` instance, and keep unchanged the
+initial query.
 
-The base method to enrich a :class:`~pandagg.tree.query.abstract.Query` is :func:`~pandagg.tree.query.abstract.Query.query`.
-
-It returns a new instance, and keep unchanged the initial query:
+For instance:
 
     >>> from pandagg.query import Query
     >>> initial_q = Query()
@@ -150,8 +148,11 @@ It returns a new instance, and keep unchanged the initial query:
         None
 
 
-Available syntaxes
-^^^^^^^^^^^^^^^^^^
+query() method
+--------------
+
+The base method to enrich a :class:`~pandagg.tree.query.abstract.Query` is :func:`~pandagg.tree.query.abstract.Query.query`.
+
 
 Considering this query:
 
@@ -160,23 +161,18 @@ Considering this query:
 
 :func:`~pandagg.tree.query.abstract.Query.query` accepts following syntaxes:
 
-from dictionnary
-""""""""""""""""
+from dictionnary::
 
 
     >>> q.query({"terms": {"genres": ['Comedy', 'Short']})
 
-flattened syntax
-""""""""""""""""
+flattened syntax::
 
 
     >>> q.query("terms", genres=['Comedy', 'Short'])
 
 
-from Query instance
-"""""""""""""""""""
-
-This includes DSL classes:
+from Query instance (this includes DSL classes)::
 
     >>> from pandagg.query import Terms
     >>> q.query(Terms(genres=['Action', 'Thriller']))

pandagg/_decorators.py

@@ -0,0 +1,95 @@
+from textwrap import dedent
+
+
+# Substitution and Appender are copied from pandas.util._decorators
+# https://github.com/pandas-dev/pandas/blob/master/LICENSE
+
+
+class Substitution:
+    """
+    A decorator to take a function's docstring and perform string
+    substitution on it.
+
+    This decorator should be robust even if func.__doc__ is None
+    (for example, if -OO was passed to the interpreter)
+
+    Usage: construct a docstring.Substitution with a sequence or
+    dictionary suitable for performing substitution; then
+    decorate a suitable function with the constructed object. e.g.
+
+    sub_author_name = Substitution(author='Jason')
+
+    @sub_author_name
+    def some_function(x):
+        "%(author)s wrote this function"
+
+    # note that some_function.__doc__ is now "Jason wrote this function"
+
+    One can also use positional arguments.
+
+    sub_first_last_names = Substitution('Edgar Allen', 'Poe')
+
+    @sub_first_last_names
+    def some_function(x):
+        "%s %s wrote the Raven"
+    """
+
+    def __init__(self, *args, **kwargs):
+        if args and kwargs:
+            raise AssertionError("Only positional or keyword args are allowed")
+
+        self.params = args or kwargs
+
+    def __call__(self, func):
+        func.__doc__ = func.__doc__ and func.__doc__ % self.params
+        return func
+
+    def update(self, *args, **kwargs):
+        """
+        Update self.params with supplied args.
+        """
+
+        if isinstance(self.params, dict):
+            self.params.update(*args, **kwargs)
+
+
+class Appender:
+    """
+    A function decorator that will append an addendum to the docstring
+    of the target function.
+
+    This decorator should be robust even if func.__doc__ is None
+    (for example, if -OO was passed to the interpreter).
+
+    Usage: construct a docstring.Appender with a string to be joined to
+    the original docstring. An optional 'join' parameter may be supplied
+    which will be used to join the docstring and addendum. e.g.
+
+    add_copyright = Appender("Copyright (c) 2009", join='\n')
+
+    @add_copyright
+    def my_dog(has='fleas'):
+        "This docstring will have a copyright below"
+        pass
+    """
+
+    def __init__(self, addendum, join="", indents=0):
+        if indents > 0:
+            self.addendum = indent(addendum, indents=indents)
+        else:
+            self.addendum = addendum
+        self.join = join
+
+    def __call__(self, func):
+        func.__doc__ = func.__doc__ if func.__doc__ else ""
+        self.addendum = self.addendum if self.addendum else ""
+        docitems = [func.__doc__, self.addendum]
+        func.__doc__ = dedent(self.join.join(docitems))
+        return func
+
+
+def indent(text, indents=1):
+    if not text or not isinstance(text, str):
+        return ""
+    jointext = "".join(["\n"] + ["    "] * indents)
+    return jointext.join(text.split("\n"))

pandagg/node/query/compound.py

@@ -2,14 +2,17 @@
 
 
 class CompoundClause(QueryClause):
-    """Compound clauses can encapsulate other query clauses::
+    """Compound clauses can encapsulate other query clauses:
+
+    .. code-block::
 
         {
             "<query_type>" : {
                 <query_body>
                 <children_clauses>
             }
         }
+
     """
 
     _default_operator = None

pandagg/response.py

@@ -363,7 +363,7 @@ def to_dataframe(
             index = (None,) * len(index)
         else:
             index = pd.MultiIndex.from_tuples(index, names=index_names)
-        return pd.DataFrame(index=index, data=values)
+        return pd.DataFrame(index=index, data=list(values))
 
     def to_normalized(self):
         children = []