diff --git a/.gitignore b/.gitignore index f7aa02f4..2ef18313 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,7 @@ target/ # virtualenv venv/ ENV/ +.venv/ # OS X .DS_Store diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..efbb4724 --- /dev/null +++ b/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 `_ 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 `_ +#. Clone forked repo and set upstream + + .. code-block:: bash + + git clone git@github.com:/pypika.git + cd pypika + git remote add upstream git@github.com: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 `_. The latest builds are displayed on their site `here `_. + +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 `_ or `Sphinx `_ format. + +Automations +----------- + +We use `pre-commit `_ 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. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..aec52ac1 --- /dev/null +++ b/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) diff --git a/README.rst b/README.rst index 534d76d5..f36f34b5 100644 --- a/README.rst +++ b/README.rst @@ -1370,9 +1370,17 @@ This produces: .. _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 ------- diff --git a/docs/6_contributing.rst b/docs/6_contributing.rst new file mode 100644 index 00000000..3bdd7dc2 --- /dev/null +++ b/docs/6_contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst \ No newline at end of file diff --git a/docs/api/pypika.analytics.rst b/docs/api/pypika.analytics.rst new file mode 100644 index 00000000..36ae82ed --- /dev/null +++ b/docs/api/pypika.analytics.rst @@ -0,0 +1,7 @@ +pypika.analytics module +======================= + +.. automodule:: pypika.analytics + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/api/pypika.dialects.rst b/docs/api/pypika.dialects.rst new file mode 100644 index 00000000..0c10e70a --- /dev/null +++ b/docs/api/pypika.dialects.rst @@ -0,0 +1,7 @@ +pypika.dialects module +====================== + +.. automodule:: pypika.dialects + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/api/pypika.pseudocolumns.rst b/docs/api/pypika.pseudocolumns.rst new file mode 100644 index 00000000..dc578333 --- /dev/null +++ b/docs/api/pypika.pseudocolumns.rst @@ -0,0 +1,7 @@ +pypika.pseudocolumns module +=========================== + +.. automodule:: pypika.pseudocolumns + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/api/pypika.rst b/docs/api/pypika.rst index bff77c90..26282846 100644 --- a/docs/api/pypika.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 9f49b4fa..57f8d39d 100644 --- a/docs/conf.py +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 9d7a3c45..72e39ea1 100644 --- a/docs/index.rst +++ b/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 ------------------ diff --git a/pypika/__init__.py b/pypika/__init__.py index 538bdfbd..a875ae00 100644 --- a/pypika/__init__.py +++ b/pypika/__init__.py @@ -1,35 +1,49 @@ """ PyPika is divided into a couple of modules, primarily the ``queries`` and ``terms`` modules. -pypika.queries --------------- +pypika.analytics +---------------- -This is where the ``Query`` class can be found which is the core class in PyPika. Also, other top level classes such -as ``Table`` can be found here. ``Query`` is a container that holds all of the ``Term`` types together and also -serializes the builder to a string. +Wrappers for SQL analytic functions -pypika.terms +pypika.dialects +--------------- + +This contains all of the dialect specific implementations of the ``Query`` class. + +pypika.enums ------------ -This module contains the classes which represent individual parts of queries that extend the ``Term`` base class. +Enumerated values are kept in this package which are used as options for Queries and Terms. pypika.functions ---------------- Wrappers for common SQL functions are stored in this package. -pypika.enums ------------- +pypika.pseudocolumns +-------------------- -Enumerated values are kept in this package which are used as options for Queries and Terms. +Wrappers for common SQL pseudocolumns are stored in this package. + +pypika.queries +-------------- + +This is where the ``Query`` class can be found which is the core class in PyPika. Also, other top level classes such +as ``Table`` can be found here. ``Query`` is a container that holds all of the ``Term`` types together and also +serializes the builder to a string. +pypika.terms +------------ + +This module contains the classes which represent individual parts of queries that extend the ``Term`` base class. pypika.utils ------------ This contains all of the utility classes such as exceptions and decorators. - """ + # noinspection PyUnresolvedReferences from pypika.dialects import ( ClickHouseQuery, diff --git a/pypika/queries.py b/pypika/queries.py index 76eeea25..223c3c95 100644 --- a/pypika/queries.py +++ b/pypika/queries.py @@ -350,6 +350,15 @@ class Query: pattern. This class is immutable. + + Examples + -------- + Simple query + + .. code-block:: python + + from pypika import Query, Field + q = Query.from_('customers').select('*').where(Field("id") == 1) """ @classmethod @@ -367,7 +376,7 @@ def from_(cls, table: Union[Selectable, str], **kwargs: Any) -> "QueryBuilder": An instance of a Table object or a string table name. - :returns QueryBuilder + :return: QueryBuilder """ return cls._builder(**kwargs).from_(table) @@ -458,7 +467,7 @@ def into(cls, table: Union[Table, str], **kwargs: Any) -> "QueryBuilder": An instance of a Table object or a string table name. - :returns QueryBuilder + :return QueryBuilder """ return cls._builder(**kwargs).into(table) @@ -478,7 +487,7 @@ def select(cls, *terms: Union[int, float, str, bool, Term], **kwargs: Any) -> "Q A list of terms to select. These can be any type of int, float, str, bool, or Term. They cannot be a Field unless the function ``Query.from_`` is called first. - :returns QueryBuilder + :return: QueryBuilder """ return cls._builder(**kwargs).select(*terms) @@ -493,7 +502,7 @@ def update(cls, table: Union[str, Table], **kwargs) -> "QueryBuilder": An instance of a Table object or a string table name. - :returns QueryBuilder + :return: QueryBuilder """ return cls._builder(**kwargs).update(table) @@ -507,7 +516,7 @@ def Table(cls, table_name: str, **kwargs) -> _TableClass: A string table name. - :returns Table + :return: Table """ kwargs["query_cls"] = cls return Table(table_name, **kwargs) @@ -523,7 +532,7 @@ def Tables(cls, *names: Union[TypedTuple[str, str], str], **kwargs: Any) -> List A list of string table names, or name and alias tuples. - :returns Table + :return: Table """ kwargs["query_cls"] = cls return make_tables(*names, **kwargs) diff --git a/requirements-dev.txt b/requirements-dev.txt index 3926afa7..e8f8d7fa 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -2,6 +2,8 @@ Sphinx==1.6.5 sphinx-rtd-theme==0.2.4 bumpversion==0.5.3 +jinja2==3.0.3 +numpydoc==1.1.0 # Testing parameterized==0.7.0