Deprecate port and ping methods in Network proxy

The Network proxy contains two methods that are mostly there for example
purposes: security_group_allow_ping and security_group_open_port.
They haven't been included in documentation due to missing docstrings,
and they aren't used anywhere in the SDK or within OSC. They're better
off as actual examples in our documentation than being within code that
we need to support throughout the future.

Change-Id: I4c6b47860b0c2b952e50d4b564451780008b631a

doc/source/users/guides/network.rst

@@ -101,6 +101,29 @@ same project network.
 
 Full example: `network resource create`_
 
+Open a Port
+-----------
+
+When creating a security group for a network, you will need to open certain
+ports to allow communication via them. For example, you may need to enable
+HTTPS access on port 443.
+
+.. literalinclude:: ../examples/network/security_group_rules.py
+   :pyobject: open_port
+
+Full example: `network security group create`_
+
+Accept Pings
+------------
+
+In order to ping a machine on your network within a security group,
+you will need to create a rule to allow inbound ICMP packets.
+
+.. literalinclude:: ../examples/network/security_group_rules.py
+   :pyobject: allow_ping
+
+Full example: `network security group create`_
+
 Delete Network
 --------------
 
@@ -114,3 +137,4 @@ Full example: `network resource delete`_
 .. _network resource create: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/create.py
 .. _network resource delete: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/delete.py
 .. _network resource list: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/list.py
+.. _network security group create: http://git.openstack.org/cgit/openstack/python-openstacksdk/tree/examples/network/security_group_rules.py

examples/network/security_group_rules.py

@@ -0,0 +1,57 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+"""
+Create resources with the Network service.
+
+For a full guide see TODO(etoews):link to docs on developer.openstack.org
+"""
+
+
+def open_port(conn):
+    print("Open a port:")
+
+    example_sec_group = conn.network.create_security_group(
+        name='openstacksdk-example-security-group')
+
+    print(example_sec_group)
+
+    example_rule = conn.network.create_security_group_rule(
+        security_group_id=example_sec_group.id,
+        direction='ingress',
+        remote_ip_prefix='0.0.0.0/0',
+        protocol='HTTPS',
+        port_range_max='443',
+        port_range_min='443',
+        ethertype='IPv4')
+
+    print(example_rule)
+
+
+def allow_ping(conn):
+    print("Allow pings:")
+
+    example_sec_group = conn.network.create_security_group(
+        name='openstacksdk-example-security-group2')
+
+    print(example_sec_group)
+
+    example_rule = conn.network.create_security_group_rule(
+        security_group_id=example_sec_group.id,
+        direction='ingress',
+        remote_ip_prefix='0.0.0.0/0',
+        protocol='icmp',
+        port_range_max=None,
+        port_range_min=None,
+        ethertype='IPv4')
+
+    print(example_rule)

openstack/network/v2/_proxy.py

@@ -48,6 +48,7 @@ from openstack.network.v2 import subnet as _subnet
 from openstack.network.v2 import subnet_pool as _subnet_pool
 from openstack.network.v2 import vpn_service as _vpn_service
 from openstack import proxy2
+from openstack import utils
 
 
 class Proxy(proxy2.BaseProxy):
@@ -2400,6 +2401,8 @@ class Proxy(proxy2.BaseProxy):
         return self._update(_security_group.SecurityGroup, security_group,
                             **attrs)
 
+    @utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
+                      details="See the Network user guide for an example")
     def security_group_open_port(self, sgid, port, protocol='tcp'):
         rule = {
             'direction': 'ingress',
@@ -2412,6 +2415,8 @@ class Proxy(proxy2.BaseProxy):
         }
         return self.create_security_group_rule(**rule)
 
+    @utils.deprecated(deprecated_in="0.9.14", removed_in="1.0",
+                      details="See the Network user guide for an example")
     def security_group_allow_ping(self, sgid):
         rule = {
             'direction': 'ingress',

openstack/tests/unit/network/v2/test_proxy.py

@@ -10,6 +10,7 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+import deprecation
 import mock
 import uuid
 
@@ -788,6 +789,7 @@ class TestNetworkProxy(test_proxy_base2.TestProxyBase):
         self.verify_update(self.proxy.update_security_group,
                            security_group.SecurityGroup)
 
+    @deprecation.fail_if_not_removed
     def test_security_group_open_port(self):
         mock_class = 'openstack.network.v2._proxy.Proxy'
         mock_method = mock_class + '.create_security_group_rule'
@@ -809,6 +811,7 @@ class TestNetworkProxy(test_proxy_base2.TestProxyBase):
             }
             mocked.assert_called_with(**expected_args)
 
+    @deprecation.fail_if_not_removed
     def test_security_group_allow_ping(self):
         mock_class = 'openstack.network.v2._proxy.Proxy'
         mock_method = mock_class + '.create_security_group_rule'