├── .gitignore
├── .travis.yml
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.md
├── doc
├── Makefile
├── code.rst
├── conf.py
├── design
│ ├── client_design_doc.md
│ └── magic_design_doc.md
└── index.rst
├── index.html
├── proto
└── sqlflow
│ └── proto
│ └── sqlflow.proto
├── setup.cfg
├── setup.py
├── sqlflow
├── __init__.py
├── __main__.py
├── _version.py
├── client.py
├── compound_message.py
├── env_expand.py
├── magic.py
└── rows.py
└── tests
├── __init__.py
├── mock_servicer.py
├── test_client.py
├── test_env_expand.py
└── test_version.py
/.gitignore:
--------------------------------------------------------------------------------
1 | sqlflow/proto
2 |
3 | venv/
4 | build/
5 | dist/
6 |
7 | .eggs/
8 | *.egg-info/
9 | .pytest_cache
10 | __pycache__/
11 |
12 | .idea/
13 |
14 | *.swp
15 | *.vim
16 | *.pyc
17 | *.log
18 |
19 | .DS_Store
20 | .vscode
21 |
--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | dist: xenial
2 | cache: pip
3 | branches:
4 | only:
5 | - master
6 | - develop
7 | # https://docs.travis-ci.com/user/customizing-the-build/#safelisting-or-blocklisting-branches
8 | # safe list can prevent tag building, add rexp to detect tag
9 | - "/^v\\d+\\.\\d+(\\.\\d+)?(-\\S*)?$/"
10 |
11 | language: python
12 | python:
13 | - 3.6
14 | - 3.7
15 |
16 | install:
17 | - python setup.py -q install
18 |
19 | script:
20 | - make protoc
21 | - python setup.py -q test
22 |
23 | deploy:
24 | provider: pypi
25 | user: tonyyang
26 | password:
27 | # secure token: `echo -n "password" | travis encrypt --add deploy.password -r sql-machine-learning/pysqlflow`
28 | secure: u8hoMuMukUcD6D+y+61w93yczgcixTgj8wQadv0VrI7aEsIOkMi508FXhsj4gmgN95O7fUApi6oXWhmOllVGFy2wJ+zZH1M8WDZi6Gq23meWTs7K+f9m6dADN0+/Y87Nc/UIOQLO8bU38hqophDRbC5Utn5bY5/lkMZzg8ypG9luZ+div+6DmZ3+kxh8o7jByiql0JjBeVLfycVW+LUpu6Fqx0XIp+tyWx99osT9LxDoZyPOmN4yXiyhEWNaK9BHi2X+qxxymjZvEJ0nSKeyQmfxBoKFW0PXh1t6r2yP5h1FzeuvZ3jB4hyvYAplKJbWJ6RLNISpBitB4PeeIVTFBPEzjc5gtDPvc5oy/OoLtmtbxGpAYh/J+DOA5T9S3vfM38xLByGMgA/Tpj0521RVd/UeyLgOrw7yPR1ZdyfDILoJ+TdupSNBpF5uMemuQGoGprGuMMHhZC+9Yv3+pUitnugDBHCx/A5uWSh699fv7UQBH0AgG5tFroQLZO6M1UVWyhkY1+LJZTuW8N4Xgq3d5dh6KdTaAJ7HZrAjow1Vc9U0S6RlWyhRgnuDwcVs3O2sPjufRSo1NK+P8Y78Gy10L1vtIr8MJRtTkTqcztrBZWAwjcvCHlgNfOPpPW1wR6klfBYN2/0MFFUYlo2ZTbsQSIgSLcVvR9d+TZkWaCsImPg=
29 | distributions: sdist bdist_wheel
30 | skip_existing: true
31 | skip_cleanup: true
32 | on:
33 | tags: true
34 | repo: sql-machine-learning/pysqlflow
35 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 |
2 | Apache License
3 | Version 2.0, January 2004
4 | http://www.apache.org/licenses/
5 |
6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7 |
8 | 1. Definitions.
9 |
10 | "License" shall mean the terms and conditions for use, reproduction,
11 | and distribution as defined by Sections 1 through 9 of this document.
12 |
13 | "Licensor" shall mean the copyright owner or entity authorized by
14 | the copyright owner that is granting the License.
15 |
16 | "Legal Entity" shall mean the union of the acting entity and all
17 | other entities that control, are controlled by, or are under common
18 | control with that entity. For the purposes of this definition,
19 | "control" means (i) the power, direct or indirect, to cause the
20 | direction or management of such entity, whether by contract or
21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
22 | outstanding shares, or (iii) beneficial ownership of such entity.
23 |
24 | "You" (or "Your") shall mean an individual or Legal Entity
25 | exercising permissions granted by this License.
26 |
27 | "Source" form shall mean the preferred form for making modifications,
28 | including but not limited to software source code, documentation
29 | source, and configuration files.
30 |
31 | "Object" form shall mean any form resulting from mechanical
32 | transformation or translation of a Source form, including but
33 | not limited to compiled object code, generated documentation,
34 | and conversions to other media types.
35 |
36 | "Work" shall mean the work of authorship, whether in Source or
37 | Object form, made available under the License, as indicated by a
38 | copyright notice that is included in or attached to the work
39 | (an example is provided in the Appendix below).
40 |
41 | "Derivative Works" shall mean any work, whether in Source or Object
42 | form, that is based on (or derived from) the Work and for which the
43 | editorial revisions, annotations, elaborations, or other modifications
44 | represent, as a whole, an original work of authorship. For the purposes
45 | of this License, Derivative Works shall not include works that remain
46 | separable from, or merely link (or bind by name) to the interfaces of,
47 | the Work and Derivative Works thereof.
48 |
49 | "Contribution" shall mean any work of authorship, including
50 | the original version of the Work and any modifications or additions
51 | to that Work or Derivative Works thereof, that is intentionally
52 | submitted to Licensor for inclusion in the Work by the copyright owner
53 | or by an individual or Legal Entity authorized to submit on behalf of
54 | the copyright owner. For the purposes of this definition, "submitted"
55 | means any form of electronic, verbal, or written communication sent
56 | to the Licensor or its representatives, including but not limited to
57 | communication on electronic mailing lists, source code control systems,
58 | and issue tracking systems that are managed by, or on behalf of, the
59 | Licensor for the purpose of discussing and improving the Work, but
60 | excluding communication that is conspicuously marked or otherwise
61 | designated in writing by the copyright owner as "Not a Contribution."
62 |
63 | "Contributor" shall mean Licensor and any individual or Legal Entity
64 | on behalf of whom a Contribution has been received by Licensor and
65 | subsequently incorporated within the Work.
66 |
67 | 2. Grant of Copyright License. Subject to the terms and conditions of
68 | this License, each Contributor hereby grants to You a perpetual,
69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70 | copyright license to reproduce, prepare Derivative Works of,
71 | publicly display, publicly perform, sublicense, and distribute the
72 | Work and such Derivative Works in Source or Object form.
73 |
74 | 3. Grant of Patent License. Subject to the terms and conditions of
75 | this License, each Contributor hereby grants to You a perpetual,
76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77 | (except as stated in this section) patent license to make, have made,
78 | use, offer to sell, sell, import, and otherwise transfer the Work,
79 | where such license applies only to those patent claims licensable
80 | by such Contributor that are necessarily infringed by their
81 | Contribution(s) alone or by combination of their Contribution(s)
82 | with the Work to which such Contribution(s) was submitted. If You
83 | institute patent litigation against any entity (including a
84 | cross-claim or counterclaim in a lawsuit) alleging that the Work
85 | or a Contribution incorporated within the Work constitutes direct
86 | or contributory patent infringement, then any patent licenses
87 | granted to You under this License for that Work shall terminate
88 | as of the date such litigation is filed.
89 |
90 | 4. Redistribution. You may reproduce and distribute copies of the
91 | Work or Derivative Works thereof in any medium, with or without
92 | modifications, and in Source or Object form, provided that You
93 | meet the following conditions:
94 |
95 | (a) You must give any other recipients of the Work or
96 | Derivative Works a copy of this License; and
97 |
98 | (b) You must cause any modified files to carry prominent notices
99 | stating that You changed the files; and
100 |
101 | (c) You must retain, in the Source form of any Derivative Works
102 | that You distribute, all copyright, patent, trademark, and
103 | attribution notices from the Source form of the Work,
104 | excluding those notices that do not pertain to any part of
105 | the Derivative Works; and
106 |
107 | (d) If the Work includes a "NOTICE" text file as part of its
108 | distribution, then any Derivative Works that You distribute must
109 | include a readable copy of the attribution notices contained
110 | within such NOTICE file, excluding those notices that do not
111 | pertain to any part of the Derivative Works, in at least one
112 | of the following places: within a NOTICE text file distributed
113 | as part of the Derivative Works; within the Source form or
114 | documentation, if provided along with the Derivative Works; or,
115 | within a display generated by the Derivative Works, if and
116 | wherever such third-party notices normally appear. The contents
117 | of the NOTICE file are for informational purposes only and
118 | do not modify the License. You may add Your own attribution
119 | notices within Derivative Works that You distribute, alongside
120 | or as an addendum to the NOTICE text from the Work, provided
121 | that such additional attribution notices cannot be construed
122 | as modifying the License.
123 |
124 | You may add Your own copyright statement to Your modifications and
125 | may provide additional or different license terms and conditions
126 | for use, reproduction, or distribution of Your modifications, or
127 | for any such Derivative Works as a whole, provided Your use,
128 | reproduction, and distribution of the Work otherwise complies with
129 | the conditions stated in this License.
130 |
131 | 5. Submission of Contributions. Unless You explicitly state otherwise,
132 | any Contribution intentionally submitted for inclusion in the Work
133 | by You to the Licensor shall be under the terms and conditions of
134 | this License, without any additional terms or conditions.
135 | Notwithstanding the above, nothing herein shall supersede or modify
136 | the terms of any separate license agreement you may have executed
137 | with Licensor regarding such Contributions.
138 |
139 | 6. Trademarks. This License does not grant permission to use the trade
140 | names, trademarks, service marks, or product names of the Licensor,
141 | except as required for reasonable and customary use in describing the
142 | origin of the Work and reproducing the content of the NOTICE file.
143 |
144 | 7. Disclaimer of Warranty. Unless required by applicable law or
145 | agreed to in writing, Licensor provides the Work (and each
146 | Contributor provides its Contributions) on an "AS IS" BASIS,
147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148 | implied, including, without limitation, any warranties or conditions
149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150 | PARTICULAR PURPOSE. You are solely responsible for determining the
151 | appropriateness of using or redistributing the Work and assume any
152 | risks associated with Your exercise of permissions under this License.
153 |
154 | 8. Limitation of Liability. In no event and under no legal theory,
155 | whether in tort (including negligence), contract, or otherwise,
156 | unless required by applicable law (such as deliberate and grossly
157 | negligent acts) or agreed to in writing, shall any Contributor be
158 | liable to You for damages, including any direct, indirect, special,
159 | incidental, or consequential damages of any character arising as a
160 | result of this License or out of the use or inability to use the
161 | Work (including but not limited to damages for loss of goodwill,
162 | work stoppage, computer failure or malfunction, or any and all
163 | other commercial damages or losses), even if such Contributor
164 | has been advised of the possibility of such damages.
165 |
166 | 9. Accepting Warranty or Additional Liability. While redistributing
167 | the Work or Derivative Works thereof, You may choose to offer,
168 | and charge a fee for, acceptance of support, warranty, indemnity,
169 | or other liability obligations and/or rights consistent with this
170 | License. However, in accepting such obligations, You may act only
171 | on Your own behalf and on Your sole responsibility, not on behalf
172 | of any other Contributor, and only if You agree to indemnify,
173 | defend, and hold each Contributor harmless for any liability
174 | incurred by, or claims asserted against, such Contributor by reason
175 | of your accepting any such warranty or additional liability.
176 |
177 | END OF TERMS AND CONDITIONS
178 |
179 | APPENDIX: How to apply the Apache License to your work.
180 |
181 | To apply the Apache License to your work, attach the following
182 | boilerplate notice, with the fields enclosed by brackets "[]"
183 | replaced with your own identifying information. (Don't include
184 | the brackets!) The text should be enclosed in the appropriate
185 | comment syntax for the file format. We also recommend that a
186 | file or class name and description of purpose be included on the
187 | same "printed page" as the copyright notice for easier
188 | identification within third-party archives.
189 |
190 | Copyright [yyyy] [name of copyright owner]
191 |
192 | Licensed under the Apache License, Version 2.0 (the "License");
193 | you may not use this file except in compliance with the License.
194 | You may obtain a copy of the License at
195 |
196 | http://www.apache.org/licenses/LICENSE-2.0
197 |
198 | Unless required by applicable law or agreed to in writing, software
199 | distributed under the License is distributed on an "AS IS" BASIS,
200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201 | See the License for the specific language governing permissions and
202 | limitations under the License.
203 |
--------------------------------------------------------------------------------
/MANIFEST.in:
--------------------------------------------------------------------------------
1 | include README.md LICENSE
2 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | SQLFLOW_VERSION := develop
2 | VERSION_FILE := sqlflow/_version.py
3 | SHELL := /bin/bash
4 |
5 | setup: ## Setup virtual environment for local development
6 | python3 -m venv venv
7 | source venv/bin/activate \
8 | && $(MAKE) install-requirements protoc
9 |
10 | install-requirements:
11 | pip install -e .
12 |
13 | test: ## Run tests
14 | python3 setup.py test
15 |
16 | clean: ## Clean up temporary folders
17 | rm -rf build dist .eggs *.egg-info .pytest_cache sqlflow/proto
18 |
19 | # NOTE(typhoonzero): grpcio-tools >= 1.29.0 breaks the tests like:
20 | # AttributeError: module 'google.protobuf.descriptor' has no attribute '_internal_create_key'
21 | protoc: ## Generate python client from proto file
22 | python3 -m venv build/grpc
23 | source build/grpc/bin/activate \
24 | && pip install grpcio-tools==1.29.0 \
25 | && mkdir -p build/grpc/sqlflow/proto \
26 | && python -m grpc_tools.protoc -Iproto --python_out=. \
27 | --grpc_python_out=. proto/sqlflow/proto/sqlflow.proto
28 |
29 | release: ## Release new version
30 | $(if $(shell git status -s), $(error "Please commit your changes or stash them before you release."))
31 |
32 | # Make sure local develop branch is up-to-date
33 | git fetch origin
34 | git checkout develop
35 | git merge origin/develop
36 |
37 | # Remove dev from version number
38 | $(eval VERSION := $(subst .dev,,$(shell python -c "exec(open('$(VERSION_FILE)').read());print(__version__)")))
39 | $(info release $(VERSION)...)
40 | sed -i '' "s/, 'dev'//" $(VERSION_FILE)
41 | git commit -a -m "release $(VERSION)"
42 |
43 | # Tag it
44 | git tag v$(VERSION)
45 |
46 | # Bump version for development
47 | $(eval NEXT_VERSION := $(shell echo $(VERSION) | awk -F. '{print $$1"."($$2+1)".0"}'))
48 | $(eval VERSION_CODE := $(shell echo $(NEXT_VERSION) | sed 's/\./, /g'))
49 | sed -i '' -E "s/[0-9]+, [0-9]+, [0-9]+/$(VERSION_CODE), 'dev'/" $(VERSION_FILE)
50 | git commit -a -m "start $(NEXT_VERSION)"
51 | git push origin develop
52 |
53 | # Push the tag, release the package to pypi
54 | git push --tags
55 |
56 | doc:
57 | $(MAKE) setup \
58 | && source venv/bin/activate \
59 | && pip install sphinx \
60 | && cd doc \
61 | && make clean && make html
62 |
63 | help:
64 | @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
65 |
66 | .PHONY: help doc
67 | .DEFAULT_GOAL := help
68 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # sqlflow [](https://travis-ci.org/sql-machine-learning/pysqlflow) [](https://pypi.python.org/pypi/sqlflow)
2 |
3 | [SQLFlow](https://github.com/sql-machine-learning/sqlflow) client library for Python.
4 |
5 | ## Installation
6 |
7 | This package is available on PyPI as `pysqlflow`. So you can install it by running the following command:
8 |
9 | pip install sqlflow
10 |
11 | ## Documentation
12 |
13 | You can read the Sphinx generated docs at:
14 | [http://sql-machine-learning.github.io/pysqlflow/](http://sql-machine-learning.github.io/pysqlflow/)
15 |
16 | ## Development
17 |
18 | ## Prerequisite
19 | ### Python 3
20 | `brew install python`
21 |
22 | ### Setup Environment
23 | `make setup`
24 |
25 | ### Test
26 | `make test`
27 |
28 | ### Release
29 | `make release`
30 |
31 | ### Generate Documentation
32 | `make doc`
33 |
34 | ### Generate GRPC client
35 | GRPC client code has been generated when you setup environment.
36 | If you would like to regenerate it, please run `make protoc`.
37 |
--------------------------------------------------------------------------------
/doc/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)
--------------------------------------------------------------------------------
/doc/code.rst:
--------------------------------------------------------------------------------
1 | Python Client for SQLFlow Server
2 | ================================
3 |
4 | .. automodule:: sqlflow.client
5 | :members:
6 | :undoc-members:
7 | :show-inheritance:
8 |
9 | .. automodule:: sqlflow.magic
10 | :members:
11 | :undoc-members:
12 | :show-inheritance:
13 |
14 |
--------------------------------------------------------------------------------
/doc/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.abspath('../'))
18 |
19 | # enable auto generate doc on __init__
20 | autoclass_content = 'both'
21 |
22 |
23 |
24 | # -- Project information -----------------------------------------------------
25 |
26 | # TODO(tony): read project, author, version, release from setup.py
27 | project = 'pysqlflow'
28 | copyright = '2019, Yang Yang'
29 | author = 'Yang Yang'
30 |
31 | # The short X.Y version
32 | version = ''
33 | # The full version, including alpha/beta/rc tags
34 | release = ''
35 |
36 |
37 | # -- General configuration ---------------------------------------------------
38 |
39 | # If your documentation needs a minimal Sphinx version, state it here.
40 | #
41 | # needs_sphinx = '1.0'
42 |
43 | # Add any Sphinx extension module names here, as strings. They can be
44 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
45 | # ones.
46 | extensions = [
47 | 'sphinx.ext.autodoc',
48 | 'sphinx.ext.githubpages',
49 | ]
50 |
51 | # Add any paths that contain templates here, relative to this directory.
52 | templates_path = ['_templates']
53 |
54 | # The suffix(es) of source filenames.
55 | # You can specify multiple suffix as a list of string:
56 | #
57 | # source_suffix = ['.rst', '.md']
58 | source_suffix = '.rst'
59 |
60 | # The master toctree document.
61 | master_doc = 'index'
62 |
63 | # The language for content autogenerated by Sphinx. Refer to documentation
64 | # for a list of supported languages.
65 | #
66 | # This is also used if you do content translation via gettext catalogs.
67 | # Usually you set "language" from the command line for these cases.
68 | language = None
69 |
70 | # List of patterns, relative to source directory, that match files and
71 | # directories to ignore when looking for source files.
72 | # This pattern also affects html_static_path and html_extra_path.
73 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
74 |
75 | # The name of the Pygments (syntax highlighting) style to use.
76 | pygments_style = None
77 |
78 |
79 | # -- Options for HTML output -------------------------------------------------
80 |
81 | # The theme to use for HTML and HTML Help pages. See the documentation for
82 | # a list of builtin themes.
83 | #
84 | html_theme = 'alabaster'
85 |
86 | # Theme options are theme-specific and customize the look and feel of a theme
87 | # further. For a list of options available for each theme, see the
88 | # documentation.
89 | #
90 | # html_theme_options = {}
91 |
92 | # Add any paths that contain custom static files (such as style sheets) here,
93 | # relative to this directory. They are copied after the builtin static files,
94 | # so a file named "default.css" will overwrite the builtin "default.css".
95 | html_static_path = ['_static']
96 |
97 | # Custom sidebar templates, must be a dictionary that maps document names
98 | # to template names.
99 | #
100 | # The default sidebars (for documents that don't match any pattern) are
101 | # defined by theme itself. Builtin themes are using these templates by
102 | # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
103 | # 'searchbox.html']``.
104 | #
105 | # html_sidebars = {}
106 |
107 |
108 | # -- Options for HTMLHelp output ---------------------------------------------
109 |
110 | # Output file base name for HTML help builder.
111 | htmlhelp_basename = 'pysqlflowdoc'
112 |
113 |
114 | # -- Options for LaTeX output ------------------------------------------------
115 |
116 | latex_elements = {
117 | # The paper size ('letterpaper' or 'a4paper').
118 | #
119 | # 'papersize': 'letterpaper',
120 |
121 | # The font size ('10pt', '11pt' or '12pt').
122 | #
123 | # 'pointsize': '10pt',
124 |
125 | # Additional stuff for the LaTeX preamble.
126 | #
127 | # 'preamble': '',
128 |
129 | # Latex figure (float) alignment
130 | #
131 | # 'figure_align': 'htbp',
132 | }
133 |
134 | # Grouping the document tree into LaTeX files. List of tuples
135 | # (source start file, target name, title,
136 | # author, documentclass [howto, manual, or own class]).
137 | latex_documents = [
138 | (master_doc, 'pysqlflow.tex', 'pysqlflow Documentation',
139 | 'Yang Yang', 'manual'),
140 | ]
141 |
142 |
143 | # -- Options for manual page output ------------------------------------------
144 |
145 | # One entry per manual page. List of tuples
146 | # (source start file, name, description, authors, manual section).
147 | man_pages = [
148 | (master_doc, 'pysqlflow', 'pysqlflow Documentation',
149 | [author], 1)
150 | ]
151 |
152 |
153 | # -- Options for Texinfo output ----------------------------------------------
154 |
155 | # Grouping the document tree into Texinfo files. List of tuples
156 | # (source start file, target name, title, author,
157 | # dir menu entry, description, category)
158 | texinfo_documents = [
159 | (master_doc, 'pysqlflow', 'pysqlflow Documentation',
160 | author, 'pysqlflow', 'One line description of project.',
161 | 'Miscellaneous'),
162 | ]
163 |
164 |
165 | # -- Options for Epub output -------------------------------------------------
166 |
167 | # Bibliographic Dublin Core info.
168 | epub_title = project
169 |
170 | # The unique identifier of the text. This can be a ISBN number
171 | # or the project homepage.
172 | #
173 | # epub_identifier = ''
174 |
175 | # A unique identification for the text.
176 | #
177 | # epub_uid = ''
178 |
179 | # A list of files that should not be packed into the epub file.
180 | epub_exclude_files = ['search.html']
181 |
182 |
183 | # -- Extension configuration -------------------------------------------------
184 |
--------------------------------------------------------------------------------
/doc/design/client_design_doc.md:
--------------------------------------------------------------------------------
1 | # SQLFlow Client Design Doc
2 |
3 | ## Overview
4 |
5 | SQLFlow Client connects [sqlflowserver](https://github.com/sql-machine-learning/sqlflowserver).
6 | It only one method `Run` which takes a SQL statement and returns a `RowSet` object.
7 |
8 | ## Example
9 |
10 | ```python
11 | import sqlflow
12 |
13 | client = sqlflow.Client(server_url='localhost:50051')
14 |
15 | # Query SQL
16 | rowset = client.run('SELECT ... FROM ...')
17 | for row in rowset:
18 | print(row) # [1, 1]
19 |
20 | # Execution SQL, prints
21 | # Query OK, ... row affected (... sec)
22 | client.run('DELETE FROM ... WHERE ...')
23 |
24 | # ML SQL, prints
25 | # epoch = 0, loss = ...
26 | # epoch = 1, loss = ...
27 | # ...
28 | client.run('SELECT ... TRAIN ...')
29 | ```
30 |
31 | ## Service Protocol
32 |
33 | `sqlflow.Client` uses grpc to contact the `sqlflowserver`. The service protocol
34 | is defined [here](sqlfow/proto/sqlflow.proto)
35 |
36 | ## Implementaion
37 |
38 | `sqlflow.Client.__init__` establishes a grpc stub/channel based on `server_url`.
39 |
40 | `sqlflow.Client.run` takes a sql statement and returns a `RowSet` object.
41 | ```python
42 | class Client:
43 | def __init__(self, host):
44 | channel = grpc.insecure_channel(host)
45 | self._stub = sqlflow_pb2_grpc.SQLFlowStub(channel)
46 |
47 | def _decode_protobuf(self, proto):
48 | '''decode rowset'''
49 |
50 | def run(self, operation):
51 | def rowset_gen():
52 | for res in self._stub.Run(sqlflow_pb2.Request(sql=operation)):
53 | if res.is_message():
54 | log(res)
55 | else:
56 | yield self._decode_protobuf(res)
57 |
58 | return RowSet(rowset_gen=rowset_gen)
59 |
60 | class RowSet:
61 | def __init__(self, rowset_gen):
62 | res = [r for r in rowset_gen]
63 | if res:
64 | self._head = res[0]
65 | self._rows = res[1:]
66 | else:
67 | self._head, self._rows = None, None
68 |
69 | def __repr__(self):
70 | '''used for IPython: pretty prints self'''
71 |
72 | def rows(self):
73 | return self._rows
74 |
75 | def to_dataframe(self):
76 | '''convert to dataframes'''
77 | ```
78 |
79 | ## Pagination
80 |
81 | Currently sqlflow server doesn't support pagination, neither does the client.
82 | If we want to support it in the future, it can be implemented through passing
83 | pageTokens. For example, the following code snippet from
84 | [google-api-go-client](https://github.com/googleapis/google-api-go-client/blob/master/iterator/iterator.go#L68)
85 |
86 | ```go
87 | // Function that fetches a page from the underlying service. It should pass
88 | // the pageSize and pageToken arguments to the service, fill the buffer
89 | // with the results from the call, and return the next-page token returned
90 | // by the service. The function must not remove any existing items from the
91 | // buffer. If the underlying RPC takes an int32 page size, pageSize should
92 | // be silently truncated.
93 | fetch func(pageSize int, pageToken string) (nextPageToken string, err error)
94 | ```
95 |
96 | ## Credential
97 |
98 | The authorization between the client and the server should be independent
99 | with authorization between the server and the database. A client should never
100 | store any sensitive data such as DB username and password.
101 |
--------------------------------------------------------------------------------
/doc/design/magic_design_doc.md:
--------------------------------------------------------------------------------
1 | # Magic Command Design Doc
2 |
3 | ## Overview
4 |
5 | Magic command wraps a pysqlflow client. It pretty prints the logs and tables.
6 |
7 | ## Example
8 |
9 | Magic command can be invoked through `%%sqlflow`.
10 |
11 | ```
12 | In [1]: %load_ext sqlflow
13 |
14 | In [2]: %%sqlflow select * from iris.iris limit 1;
15 | Out[2]: executing query 100% [========================================]
16 | +--------------+-------------+--------------+-------------+-------+
17 | | sepal_length | sepal_width | petal_length | petal_width | class |
18 | +--------------+-------------+--------------+-------------+-------+
19 | | 6.4 | 2.8 | 5.6 | 2.2 | 2 |
20 | +--------------+-------------+--------------+-------------+-------+
21 |
22 | In [3]: %%sqlflow select *
23 | ...: from iris.iris limit 1;
24 | ...:
25 | Out[3]: executing query 100% [========================================]
26 | +--------------+-------------+--------------+-------------+-------+
27 | | sepal_length | sepal_width | petal_length | petal_width | class |
28 | +--------------+-------------+--------------+-------------+-------+
29 | | 6.4 | 2.8 | 5.6 | 2.2 | 2 |
30 | +--------------+-------------+--------------+-------------+-------+
31 |
32 | In [4]: %%sqlflow SELECT *
33 | ...: FROM iris.iris limit 1
34 | ...: TRAIN DNNClassifier
35 | ...: WITH
36 | ...: n_classes = 3,
37 | ...: hidden_units = [10, 20]
38 | ...: COLUMN sepal_length, sepal_width, petal_length, petal_width
39 | ...: LABEL class
40 | ...: INTO my_dnn_model;
41 | Out[4]:
42 | Epoch 0: Training Accuracy ... Validation Accuracy ...
43 | Epoch 1: Training Accuracy ... Validation Accuracy ...
44 | Epoch 2: Training Accuracy ... Validation Accuracy ...
45 | ...
46 | Train Finished. Model saved at my_dnn_model
47 | ```
48 |
49 | ## Implementation
50 |
51 | ### Pretty print
52 |
53 | #### Table
54 |
55 | Some off-the-shelf library: https://stackoverflow.com/a/26937531/6794675
56 |
57 | ```
58 | >>> from prettytable import PrettyTable
59 | >>> t = PrettyTable(['Name', 'Age'])
60 | >>> t.add_row(['Alice', 24])
61 | >>> t.add_row(['Bob', 19])
62 | >>> print t
63 | +-------+-----+
64 | | Name | Age |
65 | +-------+-----+
66 | | Alice | 24 |
67 | | Bob | 19 |
68 | +-------+-----+
69 | ```
70 |
71 | #### Log
72 |
73 | Progress bar: https://stackoverflow.com/questions/3002085/python-to-print-out-status-bar-and-percentage
74 |
75 | ```text
76 | [================ ] 60%
77 | ```
78 |
--------------------------------------------------------------------------------
/doc/index.rst:
--------------------------------------------------------------------------------
1 | .. pysqlflow documentation master file, created by
2 | sphinx-quickstart on Mon Feb 25 15:53:09 2019.
3 | You can adapt this file completely to your liking, but it should at least
4 | contain the root `toctree` directive.
5 |
6 | Welcome to pysqlflow's documentation!
7 | =====================================
8 |
9 | .. toctree::
10 | :maxdepth: 2
11 | :caption: Contents:
12 |
13 | code
14 |
15 | Indices and tables
16 | ==================
17 |
18 | * :ref:`genindex`
19 | * :ref:`modindex`
20 | * :ref:`search`
21 |
--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
1 |
2 |