Merge pull request #2585 from RolefH/develop

final changes for 1.16.0 release

com.ibm.streamsx.topology/CHANGELOG.md

@@ -1,7 +1,7 @@
 # Changes
 ==========
 
-## v1.16.0.beta
+## v1.16.0
 * [#1679](https://github.com/IBMStreams/streamsx.topology/issues/1679) Nested tuple: Support tuple as attribute type
 * [#2551](https://github.com/IBMStreams/streamsx.topology/issues/2551) Adapt streamsx for REST API changes
 * [#2527](https://github.com/IBMStreams/streamsx.topology/issues/2527) Python: Support tumbling window based on punctuation

com.ibm.streamsx.topology/info.xml

@@ -38,7 +38,7 @@ tuple processing using Python.
 See the documentation under [namespace:com.ibm.streamsx.topology.python|com.ibm.streamsx.topology.python] for details.
 
     </description>
-    <version>1.16.0.beta</version>
+    <version>1.16.0</version>
     <requiredProductVersion>4.2</requiredProductVersion>
     </identity>
   <dependencies/>

com.ibm.streamsx.topology/opt/python/packages/streamsx/_streams/_version.py

@@ -3,7 +3,7 @@
 # Copyright IBM Corp. 2018,2019
 
 ## Common PEP396 version for modules shipped with streamsx packages
-__version__='1.16.0b'
+__version__='1.16.0'
 
 import pkg_resources
 import sys

com.ibm.streamsx.topology/opt/python/packages/streamsx/topology/schema.py

@@ -34,17 +34,37 @@ class SensorReading(typing.NamedTuple):
     
 Python 3::
 
-    SensorReading = typing.NamedTuple('SensorReading',
-        [('sensor_id', int), ('ts', int), ('reading', float)]
+    sensors = raw_readings.map(parse_sensor,
+        schema='tuple<int64 sensor_id, int64 ts, float64 reading>')
 
-    sensors = raw_readings.map(parse_sensor, schema=SensorReading)
+The supported types are defined by IBM Streams and are listed in :py:class:`~StreamSchema`.
+
+*************************
+Nested structured schemas
+*************************
+
+A structured schema can contain nested structures that are defined separately.
+
+Python 3.6::
+
+    class Sensor(typing.NamedTuple):
+        manufacturer: str
+        sensor_id: int
 
+    class SensorReading(typing.NamedTuple):
+        sensor: Sensor
+        ts: int
+        reading: float
+
+    sensors = raw_readings.map(parse_sensor, schema=SensorReading)
+    
 Python 3::
 
     sensors = raw_readings.map(parse_sensor,
-        schema='tuple<int64 sensor_id, int64 ts, float64 reading>')
+        schema='tuple<tuple<rstring manufacturer, int64 sensor_id> sensor, int64 ts, float64 reading>')
+
+Both schema definitions are equivalent.
 
-The supported types are defined by IBM Streams and are listed in :py:class:`~StreamSchema`.
 
 Structured schemas provide type-safety and efficient network serialization when compared to passing a ``dict`` using :py:const:`~CommonSchema.Python` streams. 
 
@@ -365,9 +385,10 @@ class StreamSchema(object) :
             Tuples on a stream with a schema defined by a
             ``typing.NamedTuple`` instance are passed into callables
             as instance of a named tuple with the the correct field
-            names and types. This is not guaranteed to be the same class
+            names and types unless the named tuple contains nested
+            named tuples at any nesting depth. When passed as named tuple,
+            there is no guarantee to be the same class
             instance as the one used to declare the schema.
-            
 
     Tuple string:
 
@@ -415,7 +436,7 @@ class StreamSchema(object) :
     ``optional<T>``               Optional value of type `T`      Value of type `T`, or None                 Value of for type ``T``
     ``enum{id [,...]}``           Enumeration                     Not supported                              Not supported
     ``xml``                       XML value                       Not supported                              Not supported
-    ``tuple<type name [, ...]>``  Nested tuple                    ```dict```                                 ```dict``
+    ``tuple<type name [, ...]>``  Nested tuple                    ``dict``                                   ``dict``
     ============================  ==============================  =========================================  =======================================
 
     .. note::

python/sphinx/source/restrictions.rst

@@ -11,6 +11,8 @@ Restrictions and known bugs
 
   In this example, `set_parallel(3)` is ignored.
 
+* When tuples are nested within other tuples in a stream schema, the call style of instances of `StreamSchema` for a callable is always dict, whatever value the `style` property has. When the return value of a callable represents also a structured schema with nested tuples, the return type must also be a `dict`. Otherwise the behaviour is not defined.
+
 * No schema support for container types (list, map, set, and the like) with non-primitive value or element types as value or element types for other containers, also when encapsulated in a named tuple::
 
     class A_schema(typing.NamedTuple):

release-pom.xml

@@ -7,7 +7,7 @@
     <groupId>com.ibm.streams</groupId>
     <artifactId>streamsx.topology</artifactId>
     <packaging>jar</packaging>
-    <version>1.16-beta-0</version>
+    <version>1.16.0</version>
 
     <name>${project.groupId}:${project.artifactId}</name>
     <description>Java API to allow creation of streaming applications for IBM Streams</description>