Merge branch 'kayak:master' into feature/support-fetch-first-oracle

.gitignore

@@ -70,6 +70,7 @@ target/
 # virtualenv
 venv/
 ENV/
+.venv/
 
 # OS X
 .DS_Store

CONTRIBUTING.rst

@@ -0,0 +1,101 @@
+Guidelines for Contributing
+===========================
+
+PyPika welcomes contributions in all forms. These may be bugs, feature requests, documentation, or examples. Please feel free to:
+
+#. Submitting an issue
+#. Opening a pull request
+#. Helping with outstanding issues and pull requests 
+
+Open an issue
+-------------
+
+If you find a bug or have a feature request, please `open an issue <https://github.com/kayak/pypika/issues>`_ on GitHub. Please just check that the issue doesn't already exist before opening a new one.
+
+Local development steps
+-----------------------
+
+Create a forked branch of the repo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Do this once but keep it up to date
+
+#. `Fork the kayak/PyPika repo GitHub <https://github.com/kayak/pypika/fork>`_
+#. Clone forked repo and set upstream
+
+    .. code-block:: bash
+
+        git clone [email protected]:<your-username>/pypika.git
+        cd pypika
+        git remote add upstream [email protected]:kayak/pypika.git
+
+Setup local development environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Setup up python virtual environment
+
+    Create and activate the environment. Here is an example using ``venv`` from the standard library:
+
+    .. code-block:: bash
+
+        python -m venv .venv
+        source .venv/bin/activate
+
+#. Install python dependencies for development
+
+    With the virtual environment activated, install the development requirements, pre-commit, and the package itself:
+
+    .. code-block:: bash
+
+        make install
+
+#. Run the tests
+
+    The unit tests are run with ``unittest`` via ``tox``. To run the tests locally:
+
+    .. code-block:: bash 
+
+        make test
+
+    These tests will also run on GitHub Actions when you open a pull request.
+
+#. Build the docs locally
+
+    Our docs are built with Sphinx. To build the docs locally:
+
+    .. code-block:: bash 
+
+        make docs.build
+
+    Open the docs in your browser. For instance, on macOS:
+
+    .. code-block:: bash
+
+        open docs/_build/index.html
+
+Pull Request checklist
+----------------------
+
+Please check that your pull request meets the following criteria:
+
+- Unit tests pass
+- pre-commit hooks pass
+- Docstring and examples and checking for correct render in the docs
+
+Documentation
+-------------
+
+Documentation is built with Sphinx and hosted on `Read the Docs <https://pypika.readthedocs.io/en/latest/>`_. The latest builds are displayed on their site `here <https://readthedocs.org/projects/pypika/builds/>`_.
+
+The code documentation is to be written in the docstrings of the code itself or in the various ``.rst`` files in project root or the ``docs/`` directory.
+
+The docstrings can be in either `Numpy <https://numpydoc.readthedocs.io/en/latest/format.html>`_ or `Sphinx <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_ format.
+
+Automations
+-----------
+
+We use `pre-commit <https://pre-commit.com/>`_ to automate format checks. Install the pre-commit hooks with the ``make install`` command described above.
+
+GitHub Actions runs both format checks and unit tests on every pull request.
+
+**NOTE:** The hosted documentation is built separately from the GitHub Actions workflow. To build the docs locally, use the ``make docs.build`` command described above.

Makefile

@@ -0,0 +1,23 @@
+# You can set these variables from the command line.
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = docs
+BUILDDIR      = docs/_build
+
+
+help:            ## Show this help.
+	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
+
+install:         ## Install development dependencies
+	pip install -r requirements-dev.txt pre-commit -e . 
+	pre-commit install
+
+test:            ## Run tests
+	tox
+
+docs.build:      ## Build the documentation
+	$(SPHINXBUILD) $(SOURCEDIR) $(BUILDDIR) -b html -E
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
+
+docs.clean:      ## Remove the generated documentation
+	rm -rf $(BUILDDIR)

README.rst

@@ -510,7 +510,7 @@ Example of a correlated subquery in the `SELECT`
 Unions
 """"""
 
-Both ``UNION`` and ``UNION ALL`` are supported. ``UNION DISTINCT`` is synonomous with "UNION`` so |Brand| does not
+Both ``UNION`` and ``UNION ALL`` are supported. ``UNION DISTINCT`` is synonymous with "UNION`` so |Brand| does not
 provide a separate function for it.  Unions require that queries have the same number of ``SELECT`` clauses so
 trying to cast a unioned query to string will throw a ``SetOperationException`` if the column sizes are mismatched.
 
@@ -1274,12 +1274,166 @@ This produces:
 
         CREATE TABLE "names" AS (SELECT "last_name","first_name" FROM "person")
 
+Managing Table Indices
+^^^^^^^^^^^^^^^^^^^^^^
+
+Create Indices
+""""""""""""""""
+
+The entry point for creating indices is ``pypika.Query.create_index``.
+An index name (as ``str``) or a ``pypika.terms.Index`` a table (as ``str`` or ``pypika.Table``) and
+columns (as ``pypika.Column``) must be specified.
+
+.. code-block:: python
+
+    my_index = Index("my_index")
+    person = Table("person")
+    stmt = Query \
+        .create_index(my_index) \
+        .on(person) \
+        .columns(person.first_name, person.last_name)
+
+This produces:
+
+.. code-block:: sql
+
+    CREATE INDEX my_index
+    ON person (first_name, last_name)
+
+It is also possible to create a unique index
+
+.. code-block:: python
+
+    my_index = Index("my_index")
+    person = Table("person")
+    stmt = Query \
+        .create_index(my_index) \
+        .on(person) \
+        .columns(person.first_name, person.last_name) \
+        .unique()
+
+This produces:
+
+.. code-block:: sql
+
+        CREATE UNIQUE INDEX my_index
+        ON person (first_name, last_name)
+
+It is also possible to create an index if it does not exist
+
+.. code-block:: python
+
+    my_index = Index("my_index")
+    person = Table("person")
+    stmt = Query \
+        .create_index(my_index) \
+        .on(person) \
+        .columns(person.first_name, person.last_name) \
+        .if_not_exists()
+
+This produces:
+
+.. code-block:: sql
+
+        CREATE INDEX IF NOT EXISTS my_index
+        ON person (first_name, last_name)
+
+Drop Indices
+""""""""""""""""
+
+Then entry point for dropping indices is ``pypika.Query.drop_index``.
+It takes either ``str`` or ``pypika.terms.Index`` as an argument.
+
+.. code-block:: python
+
+    my_index = Index("my_index")
+    stmt = Query.drop_index(my_index)
+
+This produces:
+
+.. code-block:: sql
+
+    DROP INDEX my_index
+
+It is also possible to drop an index if it exists
+
+.. code-block:: python
+
+    my_index = Index("my_index")
+    stmt = Query.drop_index(my_index).if_exists()
+
+This produces:
+
+.. code-block:: sql
+
+    DROP INDEX IF EXISTS my_index
+
+
+Chaining Functions
+^^^^^^^^^^^^^^^^^^
+
+The ``QueryBuilder.pipe`` method gives a more readable alternative while chaining functions.
+
+.. code-block:: python 
+
+    # This 
+    (
+        query
+        .pipe(func1, *args)
+        .pipe(func2, **kwargs)
+        .pipe(func3)
+    )
+
+    # Is equivalent to this
+    func3(func2(func1(query, *args), **kwargs))
+
+Or for a more concrete example:
+
+.. code-block:: python 
+
+    from pypika import Field, Query, functions as fn
+    from pypika.queries import QueryBuilder
+
+    def filter_days(query: QueryBuilder, col, num_days: int) -> QueryBuilder: 
+        if isinstance(col, str): 
+            col = Field(col)
+
+        return query.where(col > fn.Now() - num_days)
+
+    def count_groups(query: QueryBuilder, *groups) -> QueryBuilder: 
+        return query.groupby(*groups).select(*groups, fn.Count("*").as_("n_rows"))
+
+    base_query = Query.from_("table")
+
+    query = (
+        base_query
+        .pipe(filter_days, "date", num_days=7)
+        .pipe(count_groups, "col1", "col2")
+    )
+
+This produces: 
+
+.. code-block:: sql
+
+    SELECT "col1","col2",COUNT(*) n_rows 
+    FROM "table" 
+    WHERE "date">NOW()-7 
+    GROUP BY "col1","col2"
+
 .. _tutorial_end:
 
+.. _contributing_start: 
 
-.. _license_start:
+Contributing
+------------
+
+We welcome community contributions to |Brand|. Please see the `contributing guide <6_contributing.html>`_ to more info.
+
+.. _contributing_end:
 
 
+.. _license_start:
+
 License
 -------
 

docs/3_advanced.rst

@@ -51,7 +51,8 @@ The pseudo-column can change from database to database, so here it's possible to
 
 .. code-block:: python
 
-    from pypika import Query, PseudoColumn
+    from pypika import Query
+    from pypika.terms import PseudoColumn
 
     CurrentDate = PseudoColumn('current_date')
 

docs/6_contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst

docs/api/pypika.analytics.rst

@@ -0,0 +1,7 @@
+pypika.analytics module
+=======================
+
+.. automodule:: pypika.analytics
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pypika.dialects.rst

@@ -0,0 +1,7 @@
+pypika.dialects module
+======================
+
+.. automodule:: pypika.dialects
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pypika.pseudocolumns.rst

@@ -0,0 +1,7 @@
+pypika.pseudocolumns module
+===========================
+
+.. automodule:: pypika.pseudocolumns
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/pypika.rst

@@ -3,9 +3,11 @@ pypika package
 
 .. toctree::
 
-
+   pypika.analytics
+   pypika.dialects
    pypika.enums
    pypika.functions
+   pypika.pseudocolumns
    pypika.queries
    pypika.terms
    pypika.utils

docs/conf.py

@@ -39,6 +39,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.imgmath',
     'sphinx.ext.viewcode',
+    'numpydoc',  
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -9,6 +9,10 @@ PyPika - Python Query Builder
    :start-after: _appendix_start:
    :end-before:  _appendix_end:
 
+.. include:: ../README.rst
+   :start-after: _contributing_start:
+   :end-before:  _contributing_end:
+
 Contents
 --------
 
@@ -20,6 +24,7 @@ Contents
     3_advanced
     4_extending
     5_reference
+    6_contributing
 
 Indices and tables
 ------------------