Merge branch 'master' into patch-1

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Share about things that are not working as expected
+labels: kind/bug
+
+---
+
+**What happened (please include outputs or screenshots)**:
+
+**What you expected to happen**:
+
+**How to reproduce it (as minimally and precisely as possible)**:
+
+**Anything else we need to know?**:
+
+**Environment**:
+- Kubernetes version (`kubectl version`):
+- OS (e.g., MacOS 10.13.6):
+- Python version (`python --version`)
+- Python client version (`pip list | grep kubernetes`)

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,10 @@
+---
+name: Documentation
+about: Report any mistakes or missing information from the documentation or the examples
+labels: kind/documentation
+
+---
+
+**Link to the issue (please include a link to the specific documentation or example)**:
+
+**Description of the issue (please include outputs or screenshots if possible)**:

.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,10 @@
+---
+name: Feature request
+about: Suggest a new feature for the project
+labels: kind/feature
+
+---
+
+**What is the feature and why do you need it**:
+
+**Describe the solution you'd like to see**:

.gitignore

@@ -67,3 +67,7 @@ target/
 .idea/*
 *.iml
 .vscode
+
+# created by sphinx documentation build
+doc/source/README.md
+doc/_build

.travis.yml

@@ -1,7 +1,6 @@
 # ref: https://docs.travis-ci.com/user/languages/python
 language: python
 dist: xenial
-sudo: true
 services:
   - docker
 
@@ -13,12 +12,10 @@ matrix:
        env: TOXENV=py27-functional
      - python: 2.7
        env: TOXENV=update-pycodestyle
-     - python: 2.7
+     - python: 3.7
        env: TOXENV=docs
      - python: 2.7
        env: TOXENV=coverage,codecov
-     - python: 3.4
-       env: TOXENV=py34
      - python: 3.5
        env: TOXENV=py35
      - python: 3.5
@@ -31,6 +28,10 @@ matrix:
        env: TOXENV=py37
      - python: 3.7
        env: TOXENV=py37-functional
+     - python: 3.8
+       env: TOXENV=py38
+     - python: 3.8
+       env: TOXENV=py38-functional
 
 install:
   - pip install tox

CHANGELOG.md

@@ -25,6 +25,7 @@
 - Introduce RuntimeClass to NodeV1alpha1Api and NodeV1beta1Api [kubernetes/kubernetes#74433](https://github.com/kubernetes/kubernetes/pull/74433)
 - Graduate PriorityClass API to GA SchedulingV1Api [kubernetes/kubernetes#73555](https://github.com/kubernetes/kubernetes/pull/73555)
 - Introduce CSINodeInfo and CSIDriver to StorageV1beta1Api [kubernetes/kubernetes#74283](https://github.com/kubernetes/kubernetes/pull/74283)
+- The alpha Initializers feature, `admissionregistration.k8s.io/v1alpha1` API version, `Initializers` admission plugin, and use of the `metadata.initializers` API field have been removed. Discontinue use of the alpha feature and delete any existing `InitializerConfiguration` API objects before upgrading. The `metadata.initializers` field will be removed in a future release. The parameter `include_uninitialized` has been removed. [kubernetes/kubernetes#72972](https://github.com/kubernetes/kubernetes/pull/72972)
 
 # v9.0.0
 **Bug Fix:**

OWNERS

@@ -1,8 +1,11 @@
 # See the OWNERS docs at https://go.k8s.io/owners
 
 approvers:
-  - mbohlool
+  - roycaihw
+  - yliaog
+emeritus_approvers:
   - caesarxuchao
   - lavalamp
-  - yliaog
-  - roycaihw
+  - mbohlool
+reviewers:
+  - micw523

README.md

@@ -25,7 +25,7 @@ From [PyPi](https://pypi.python.org/pypi/kubernetes/) directly:
 pip install kubernetes
 ```
 
-## Example
+## Examples
 
 list all pods:
 
@@ -68,7 +68,7 @@ More examples can be found in [examples](examples/) folder. To run examples, run
 python -m examples.example1
 ```
 
-(replace example1 with the example base filename)
+(replace example1 with one of the filenames in the examples folder)
 
 ## Documentation
 
@@ -77,24 +77,20 @@ All APIs and Models' documentation can be found at the [Generated client's READM
 ## Compatibility
 
 `client-python` follows [semver](http://semver.org/), so until the major version of
-client-python gets increased, your code will continue to work with explicitly 
+client-python gets increased, your code will continue to work with explicitly
 supported versions of Kubernetes clusters.
 
 #### Compatibility matrix
 
-|                    | Kubernetes 1.5 | Kubernetes 1.6 | Kubernetes 1.7 | Kubernetes 1.8 | Kubernetes 1.9 | Kubernetes 1.10 | Kubernetes 1.11 | Kubernetes 1.12 | Kubernetes 1.13 | Kubernetes 1.14 |
-|--------------------|----------------|----------------|----------------|----------------|----------------|-----------------|-----------------|-----------------|-----------------|-----------------|
-| client-python 1.0  | ✓              | -              | -              |-               |-               |-                |-                |-                |-                |-                |
-| client-python 2.0  | +              | ✓              | -              |-               |-               |-                |-                |-                |-                |-                |
-| client-python 3.0  | +              | +              | ✓              |-               |-               |-                |-                |-                |-                |-                |
-| client-python 4.0  | +              | +              | +              |✓               |-               |-                |-                |-                |-                |-                |
-| client-python 5.0  | +              | +              | +              |+               |✓               |-                |-                |-                |-                |-                |
-| client-python 6.0  | +              | +              | +              |+               |+               |✓                |-                |-                |-                |-                |
-| client-python 7.0  | +              | +              | +              |+               |+               |+                |✓                |-                |-                |-                |
-| client-python 8.0  | +              | +              | +              |+               |+               |+                |+                |✓                |-                |-                |
-| client-python 9.0  | +              | +              | +              |+               |+               |+                |+                |+                |✓                |-                |
-| client-python 10.0 | +              | +              | +              |+               |+               |+                |+                |+                |+                |✓                |
-| client-python HEAD | +              | +              | +              |+               |+               |+                |+                |+                |+                |✓                |
+|                    | Kubernetes 1.9 | Kubernetes 1.10 | Kubernetes 1.11 | Kubernetes 1.12 | Kubernetes 1.13 | Kubernetes 1.14 |
+|--------------------|----------------|-----------------|-----------------|-----------------|-----------------|-----------------|
+| client-python 5.0  |✓               |-                |-                |-                |-                |-                |
+| client-python 6.0  |+               |✓                |-                |-                |-                |-                |
+| client-python 7.0  |+               |+                |✓                |-                |-                |-                |
+| client-python 8.0  |+               |+                |+                |✓                |-                |-                |
+| client-python 9.0  |+               |+                |+                |+                |✓                |-                |
+| client-python 10.0 |+               |+                |+                |+                |+                |✓                |
+| client-python HEAD |+               |+                |+                |+                |+                |✓                |
 
 Key:
 
@@ -110,14 +106,6 @@ between client-python versions.
 
 | Client version  | Canonical source for OpenAPI spec    | Maintenance status            |
 |-----------------|--------------------------------------|-------------------------------|
-| 1.0 Alpha/Beta  | Kubernetes main repo, 1.5 branch     | ✗                             |
-| 1.0.x           | Kubernetes main repo, 1.5 branch     | ✗                             |
-| 2.0 Alpha/Beta  | Kubernetes main repo, 1.6 branch     | ✗                             |
-| 2.0.x           | Kubernetes main repo, 1.6 branch     | ✗                             |
-| 3.0 Alpha/Beta  | Kubernetes main repo, 1.7 branch     | ✗                             |
-| 3.0             | Kubernetes main repo, 1.7 branch     | ✗                             |
-| 4.0 Alpha/Beta  | Kubernetes main repo, 1.8 branch     | ✗                             |
-| 4.0             | Kubernetes main repo, 1.8 branch     | ✗                             |
 | 5.0 Alpha/Beta  | Kubernetes main repo, 1.9 branch     | ✗                             |
 | 5.0             | Kubernetes main repo, 1.9 branch     | ✗                             |
 | 6.0 Alpha/Beta  | Kubernetes main repo, 1.10 branch    | ✗                             |
@@ -142,18 +130,12 @@ Note: There would be no maintenance for alpha/beta releases except the latest on
 
 ## Community, Support, Discussion
 
-If you have any problem on using the package or any suggestions, please start with reaching the [Kubernetes clients slack channel](https://kubernetes.slack.com/messages/C76GB48RK/), or filing an [issue](https://github.com/kubernetes-client/python/issues) to let us know. You can also reach the maintainers of this project at [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery).
+If you have any problem on using the package or any suggestions, please start with reaching the [Kubernetes clients slack channel](https://kubernetes.slack.com/messages/C76GB48RK/), or filing an [issue](https://github.com/kubernetes-client/python/issues) to let us know. You can also reach the maintainers of this project at [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery), where this project falls under.
 
 ### Code of Conduct
 
 Participation in the Kubernetes community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
 
-## Kubernetes Incubator
-
-This is a [Kubernetes Incubator project](https://github.com/kubernetes/community/blob/master/incubator.md).
-
-* [SIG: sig-api-machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery)
-
 ## Troubleshooting
 
 ### SSLError on macOS
@@ -184,9 +166,9 @@ Specifically check `ipaddress` and `urllib3` package versions to make sure they
 
 Starting from 4.0 release, we do not support directly calling exec or attach calls. you should use stream module to call them. so instead
 of `resp = api.connect_get_namespaced_pod_exec(name, ...` you should call `resp = stream(api.connect_get_namespaced_pod_exec, name, ...`.
-See more at [exec example](examples/exec.py).
 
 Using Stream will overwrite the requests protocol in _core_v1_api.CoreV1Api()_ 
 This will cause a failure in  non-exec/attach calls. If you reuse your api client object, you will need to 
 recreate it between api calls that use _stream_ and other api calls.
 
+See more at [exec example](examples/pod_exec.py).

RELEASE.md

@@ -3,7 +3,11 @@
 The Kubernetes Python client is released on an as-needed basis. The process is as follows:
 
 1. An issue is proposing a new release with a changelog since the last release
+1. Update the support matrix in README.md removing the oldest version and adding the
+   proposed release.
 1. All [OWNERS](OWNERS) must LGTM this release
-1. An OWNER runs `git tag -s $VERSION` and inserts the changelog and pushes the tag with `git push $VERSION`
+1. An OWNER runs `git tag -s $VERSION` and inserts the changelog and pushes
+   the tag with `git push $VERSION`
 1. The release issue is closed
-1. An announcement email is sent to `[email protected]` with the subject `[ANNOUNCE] kubernetes-python-client $VERSION is released`
+1. An announcement email is sent to `[email protected]`
+   with the subject `[ANNOUNCE] kubernetes-python-client $VERSION is released`

doc/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -c source
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = kubernetes-python
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+html:
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "\nDocs rendered successfully, open _/build/html/index.html to view"

doc/README.md

@@ -0,0 +1,11 @@
+Building the documentation
+==========================
+
+Install the test requirements with:
+
+```
+$ pip install -r ../test-requirements.txt
+```
+
+Use `make html` to build the docs in html format.
+

doc/requirements-docs.txt

@@ -0,0 +1,2 @@
+recommonmark
+sphinx_markdown_tables

doc/source/conf.py

@@ -13,22 +13,37 @@
 # limitations under the License.
 
 import os
+import re
+import shutil
 import sys
 
-from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
+
+# Work around https://github.com/readthedocs/recommonmark/issues/152
+new_readme = []
+
+with open("../../README.md", "r") as r:
+    lines = r.readlines()
+    for l in lines:
+        nl = re.sub("\[!\[[\w\s]+\]\(", "[![](", l)
+        new_readme.append(nl)
+
+with open("README.md", "w") as n:
+    n.writelines(new_readme)
+
+# apparently index.rst can't search for markdown not in the same directory
+shutil.copy("../../CONTRIBUTING.md", ".")
 
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
-source_parsers = {
-    '.md': CommonMarkParser,
-}
-
 source_suffix = ['.rst', '.md']
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'sphinx_markdown_tables',
+    'recommonmark',
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
 ]
@@ -80,3 +95,10 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'auto_toc_tree_section': 'Contents',
+            'enable_eval_rst': True,
+            }, True)
+    app.add_transform(AutoStructify)
+

doc/source/index.rst

@@ -11,11 +11,12 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   readme
+   README <README.md>
    installation
    usage
+   examples
    modules
-   contributing
+   contributing <CONTRIBUTING.md>
 
 Indices and tables
 ==================

doc/source/usage.rst

@@ -2,6 +2,19 @@
 Usage
 ========
 
-To use kubernetes-python-client in a project::
+The directory ``examples`` contains a few examples on how to use the client.
 
-    import kubernetes
+
+Deployments
+-----------
+
+Here is a simple usage of creating a deployment from a yaml file:
+
+
+.. literalinclude:: ../../examples/create_deployment.py
+
+
+The following example demostrates how to create, update and delete deployments
+without the need to read a file from the disk:
+
+.. literalinclude:: ../../examples/deployment_examples.py

examples/README.md

@@ -0,0 +1,17 @@
+# Python Client Examples
+
+This directory contains various examples of how to use the Python client.
+Please read the description at the top of each example for more information
+about what the script does and any prequisites. Most scripts also include
+comments throughout the code.
+
+## Setup
+
+These scripts require Python 2.7 or 3.5+ and the Kubernetes client which can be
+installed following the directions
+[here](https://github.com/kubernetes-client/python#installation).
+
+## Contributions
+
+If you find a problem please file an
+[issue](https://github.com/kubernetes-client/python/issues).

examples/__init__.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Empty init file to make examples folder a python module.
+# Empty init file to make examples folder a python module